vnem

Read-only AI booster and perception layer for coding agents.

vnem is a read-only AI booster for coding agents. It gives agents a local perception layer so they optimize performance, visuals, playability, safety, and maintainability before touching code.

It also ships an LLM-readable knowledge pack and registry for agentic tools: MCP servers, skills, frameworks, evals, safety utilities, memory systems, payment rails, identity tools, and workflow patterns.

It helps a coding agent answer: what should I use, what is stale, what is risky, what quality domains matter, and what is the current better option? before it edits a repo.

Live overview: vnem.pages.dev

Quick Start

Use the read-only pack when you only want repo-local AI guidance:

curl -fsSL https://raw.githubusercontent.com/Ovvuhy/vnem/main/public/install.tgz | tar -xz

Use the checkout when you want the CLI installer, doctor checks, or MCP server:

git clone https://github.com/Ovvuhy/vnem.git
cd vnem
npm install
npm run install:project -- /path/to/my-project
npm run doctor -- /path/to/my-project
node scripts/vnem-cli.mjs mcp-config

The VNEM Standard

VNEM is built around one rule: an AI agent should not satisfy one requirement by silently damaging another.

• Holistic Excellence: performance, visuals, playability, accessibility, maintainability, and safety are all part of done.
• Proactive Enhancement: the agent should infer the stronger product the user actually wants, not only the smallest literal interpretation of the prompt.
• Intelligent Trade-offs: when constraints conflict, the agent must engineer alternatives such as quality profiles, settings toggles, progressive enhancement, reduced-motion paths, asset optimization, or scoped fallbacks before lowering product quality.

If a user asks for extreme performance, VNEM should not let the agent quietly remove visual quality or game feel. The better answer is to optimize the system and expose control: fast defaults, high-quality modes, adaptive effects, and honest verification evidence.

Prompt pressure	Standard agent failure	With VNEM
"Make it faster."	Removes animation, sound, texture, or visual polish and calls the job done.	Optimizes the render path, keeps the high-quality path, and adds quality/profile controls when needed.
"Build a game."	Ships a technically working but ugly canvas with weak controls and no interaction evidence.	Checks playability, visual fit, reward feedback, responsive sizing, and screenshot or browser evidence.
"Make it production-ready."	Runs a build and ignores user-facing quality gaps.	Applies a quality gate across behavior, performance, visuals, accessibility, maintainability, safety, and verification.

What Vnem Improves

vnem is meant to improve the judgment of coding agents, not replace maintainer review.

• Holistic quality gates: agents run a Triple-Check Workflow: Analyze the real goal, Architect performance and visuals/playability together, then Review that no important domain was sacrificed.
• Better recommendations: agents compare current MCP servers, coding agents, frameworks, evals, memory systems, and workflows before proposing a stack change.
• Safer adoption: each entry tracks source links, licenses, permissions, risk flags, trust tier, and install notes.
• Coding execution playbooks: agents pick a task-specific loop for feature slices, root-cause bug fixes, test-first work, refactors, rendered web apps, API/data changes, large changes, reviews, and failure recovery.
• Universal task contracts: the operating protocol, coding protocol, playbooks, and broad rubrics steer agents through sensing the repo, choosing small capabilities, constraining risk, verifying, and reporting evidence.
• Shared research layer: source radar maps official docs, registries, MCP sources, evals, and verification sources so agents know where to research before burning context from scratch.
• Gateway-ready security guidance: vnem routes pre-execution gateway, tool pinning, package firewall, and AST-indexer ideas into a phased zero-trust review instead of a risky runtime rewrite.
• Clearer prompts: the install pack includes prompt-engineering guidance and reusable prompt patterns for Codex-style implementation, review, debugging, research, eval, and MCP-selection tasks.

How It Works

1. Install the read-only pack into a project.
2. Ask a coding agent to read .vnem/AGENTS.md.
3. The agent follows .vnem/operating-protocol.md, .vnem/quality-contract.md, .vnem/coding-protocol.md, and .vnem/coding-playbooks.json, then selects a broad rubric from .vnem/task-rubrics.json.
4. The agent uses .vnem/search-index.json, .vnem/best-practices.md, .vnem/agent-workspace.md, and .vnem/prompt-* files only when routed there.
5. For current docs, MCP discovery, or benchmark claims, the agent checks .vnem/source-radar.json before broad web search.
6. The agent recommends options and asks before changing code, installing packages, using secrets, or touching external systems.

Install The Pack

From any project root:

curl -fsSL https://raw.githubusercontent.com/Ovvuhy/vnem/main/public/install.tgz | tar -xz

Until vnem.ai is live, the generated install command uses the GitHub-hosted archive. To generate artifacts for a different host later, run VNEM_BASE_URL=https://vnem.ai npm run generate.

In a clean project folder, this extracts:

• AGENTS.md
• .vnem/AGENTS.md
• .vnem/install-guide.md
• .vnem/operating-protocol.md
• .vnem/quality-contract.md
• .vnem/coding-protocol.md
• .vnem/coding-playbooks.json
• .vnem/task-rubrics.json
• .vnem/search-index.json
• .vnem/source-radar.json
• .vnem/best-practices.md
• .vnem/agent-workspace.md
• .vnem/prompt-engineering.md
• .vnem/prompt-patterns.json

AGENTS.md points coding agents to .vnem/AGENTS.md, the full agent entrypoint, plus .vnem/quality-contract.md, .vnem/coding-protocol.md, and .vnem/coding-playbooks.json for implementation work and .vnem/agent-workspace.md for autonomous developer environment guidance. Once an agent has read it, the user should not need special use vnem prompts: vnem auto-activates for build, code, debug, review, optimization, research, benchmark, and stack/tool decision tasks.

For existing repos with their own AGENTS.md, prefer the CLI installer below because it updates a managed vnem block instead of replacing the whole file.

PowerShell users can avoid pipe behavior entirely:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/Ovvuhy/vnem/main/public/install.tgz" -OutFile "vnem-install.tgz"
tar -xzf vnem-install.tgz
Remove-Item vnem-install.tgz

Make A Repo vnem-Aware

For the easiest local workflow, install vnem from this checkout into any clean project folder:

npm run install:project -- /path/to/my-project

This writes the read-only .vnem/ pack and creates or updates /path/to/my-project/AGENTS.md with a tiny managed pointer. After that, coding agents that read AGENTS.md should automatically consult vnem before choosing tools, MCP servers, skills, prompt patterns, evals, memory layers, search tools, or upgrade paths.

Check a project:

npm run doctor -- /path/to/my-project

Claude-style projects can also get a CLAUDE.md pointer:

npm run install:project -- /path/to/my-project --claude

Use As An MCP Server

vnem also ships an opt-in, read-only MCP server over stdio. It exposes the generated registry and install-pack guidance as tools, resources, and a prompt; it does not install packages, edit files, call upstream services, or collect secrets.

From this repo:

npm run mcp

Generate an absolute-path MCP client config from your checkout:

node scripts/vnem-cli.mjs mcp-config
node scripts/vnem-cli.mjs mcp-config --server-json

Example full MCP client config:

{
  "mcpServers": {
    "vnem": {
      "command": "node",
      "args": ["/path/to/vnem/scripts/vnem-mcp-server.mjs"],
      "env": {
        "VNEM_ROOT": "/path/to/vnem"
      }
    }
  }
}

For Claude Code, the server-object form from node scripts/vnem-cli.mjs mcp-config --server-json can be passed to claude mcp add-json vnem '<json>'. For generic MCP clients, use the full mcpServers object.

Main tools:

• vnem_status: show loaded data paths, generated timestamps, counts, MCP tools/resources/prompts, and read-only safety posture.
• vnem_overview: explain the usable vnem surfaces for newcomers, maintainers, or agents.
• vnem_route_intent: resolve a task or phrase into intent routing, read-first guidance, comparison options, rubrics, approval gates, and verification criteria.
• vnem_get_source: fetch one source-radar entry by ID or title.
• vnem_search: search registry entries, best-practice notes, prompt patterns, source radar, rubrics, and playbooks.
• vnem_recommend: run a recommendation pass for an agentic tooling or stack decision and return a compact task contract.
• vnem_quality_gate: apply VNEM's Triple-Check Workflow to a task or proposed approach and flag silent performance/visual/playability trade-offs.
• vnem_get_entry: fetch one registry entry with provenance, install notes, permissions, and risks.
• vnem_compare: compare two or more registry entries.
• vnem_best_practices: find matching best-practice and prompt-pattern notes.
• vnem_sources: find source-radar entries for upstream docs, registries, MCP sources, and benchmark evidence.

Main resources:

• vnem://install/search-index
• vnem://install/source-radar
• vnem://api/index
• vnem://install/install-guide
• vnem://install/operating-protocol
• vnem://install/quality-contract
• vnem://install/coding-protocol
• vnem://install/coding-playbooks
• vnem://install/task-rubrics
• vnem://install/design-architecture
• vnem://install/visual-qa-protocol
• vnem://install/best-practices
• vnem://install/agent-workspace
• vnem://install/prompt-engineering
• vnem://install/prompt-patterns
• vnem://discovery/daily-digest
• vnem://repo/readme
• vnem://repo/product
• vnem://repo/security-roadmap
• vnem://repo/hermes
• vnem://repo/contributing
• vnem://entries/{slug}

The quickest way to understand a running vnem MCP server is to call vnem_status, then vnem_overview, then vnem_route_intent for the task you care about.

You can also install the bundled Codex skill from this checkout:

npm run vnem -- install-skill

Safety Model

V1 is intentionally boring and safe:

• no auto-install of discovered third-party tools
• no daemon
• optional MCP server is local, read-only, and stdio-only
• no package installs from the MCP server or install pack
• no remote code execution
• no network calls from MCP tools
• no secrets collection
• no edits unless the user explicitly approves them

The pack is guidance and search data. It does not run the tools it recommends.

What This Repo Contains

Path	Purpose
registry/entries/{slug}/entry.yaml	Canonical machine-readable registry entry.
registry/entries/{slug}/profile.md	Short human/LLM-readable profile.
schemas/entry.schema.json	Entry schema used by validation.
scripts/	Validation, generation, curated knowledge upserts, discovery, digest, and install-pack tests.
public/api/index.json	Static API generated from registry data.
public/install/*	Hosted read-only install-pack files.
public/install.tgz	Tiny archive used by the one-line install command.
.vnem/	Generated local pack for dogfooding this repo.
.vnem/install-guide.md	Generated setup guide for archive install, managed repo install, MCP config, and verification.
landing/	Static public landing page and blog bundle for the website.
dashboard/	Vite/React source for the Hermes owner dashboard surface.
PRODUCT.md	Product direction, public-site clarity goals, and non-regression bar.
SECURITY-ROADMAP.md	Advisory-first roadmap for zero-trust gateway and runtime-security ideas.
llms.txt	Compact LLM entrypoint.
llms-full.txt	Full generated registry context for LLMs.
HERMES.md	Operating contract for recurring agentic discovery and daily ecosystem checks.

This repo is the open registry, generation system, install pack, MCP server, and static public site source.

For product direction, public-site clarity, and future commercial boundaries, see PRODUCT.md.

For LLMs

If you are working inside this repository, start with AGENTS.md.

If you are using vnem inside another project, read .vnem/AGENTS.md after installing the pack. It tells agents to automatically search .vnem/search-index.json, check intent_routes, compare relevant best-practice notes, and report vnem knowledge gaps before choosing a stack or recommendation.

To improve a prompt, say use vnem to enhance this prompt and include your rough prompt. The installed pack will route the agent to .vnem/prompt-engineering.md and .vnem/prompt-patterns.json.

If the agent has read .vnem/AGENTS.md, this can also happen automatically: requests to write, rewrite, optimize, critique, or template a prompt should use the prompt-enhancement protocol even when the user does not say use vnem.

To compare AI tools or research sources, ask for a vnem-backed review such as codex vs claude, ai model selection, source radar, source intake, or zero trust gateway. The installed pack routes those intents to the operating protocol, broad rubrics, source radar, best-practice notes, and relevant registry entries.

Trust Tiers

Tier	Meaning
verified	Install/docs manually reviewed.
promising	Official or high-signal source, not fully tested.
unreviewed	Discovered but not validated.
watchlist	Useful-looking, but quality/license/security is uncertain.
deprecated	Stale, broken, or superseded.

Local Development

npm install
npm run curate
npm run validate
npm run generate
npm test

Useful commands:

npm run check:links
npm run curate
npm run discover:dry-run
npm run digest

Add Or Update An Entry

1. Add or edit registry/entries/{slug}/entry.yaml.
2. Add or edit registry/entries/{slug}/profile.md.
3. Keep summaries original. Do not paste long upstream README/docs excerpts.
4. Preserve upstream source URLs, copyright owner, and SPDX license data when known.
5. Run npm test.
6. Open a PR with source links and a conservative trust-tier suggestion.

Discovery automation and Hermes may propose candidates, but maintainers approve what reaches main.

Token / Community

CA: M2DvKKrQiKu8Ux9pz3cKgdudmLqUUQLVbB9Vy9zEASY

EasyA Kickstart: https://kickstart.easya.io/token/M2DvKKrQiKu8Ux9pz3cKgdudmLqUUQLVbB9Vy9zEASY

License

Code and scripts are MIT licensed. Original registry metadata and profiles are CC0-1.0. Third-party names, trademarks, copyrights, packages, and licenses remain with their respective owners and are preserved through each entry's provenance fields.