agent-context-mcp

Persistent, harness-agnostic project memory for AI coding agents.

A stateless MCP server that gives any agent — Claude Code, Codex, Kilo Code, OpenCode, Cursor — structured read/write access to a per-project ai_context/ folder of plain markdown. Decisions, plans, constraints and notes live in the repo, sync via git, and stay readable by agents that do not have the server installed.

The agent decides when and what to record. The server decides format and location. That opinionation is the point: give an agent free-form writes and the folder degrades into sludge.

What it is not

No code retrieval, no semantic search, no embeddings, no database, no daemon state. Pure file I/O. It composes with a code-search tool rather than competing with one.

Install

Needs Node ≥ 18. Nothing to install globally — every harness below runs it through npx.

npx agent-context-mcp init

init creates the ai_context/ skeleton, stubs project.md and constraints.md, appends the activation snippet to AGENTS.md, and prints the registration block for your harness. It never overwrites an existing file.

Register with your harness

Claude Code, from the project root:

claude mcp add agent-context -- npx -y agent-context-mcp .

Or commit a .mcp.json so the whole team gets it:

{
  "mcpServers": {
    "agent-context": {
      "command": "npx",
      "args": ["-y", "agent-context-mcp", "."]
    }
  }
}

Codex, in ~/.codex/config.toml:

[mcp_servers.agent-context]
command = "npx"
args = ["-y", "agent-context-mcp", "."]

Kilo Code, OpenCode, Cursor, Windsurf and other MCP clients take the same mcpServers JSON block in their own settings file.

The trailing . makes the server treat the harness's working directory as the project root. Pass an absolute path instead if your harness starts elsewhere. Transport is stdio only.

AGENTS.md snippet

init appends this; add it by hand if you would rather not run init. It is what actually makes agents use the tools:

## Persistent project context

This project uses the agent-context MCP server. At session start, call
`get_context` (no arguments) to orient yourself. When you make or the user
confirms a significant architectural/technical decision, call
`record_decision`. Persist gotchas and conventions with `record_note`.
Human-curated ground truth lives in ai_context/project.md and
ai_context/constraints.md — read them, never contradict them.

The folder

<project-root>/
  AGENTS.md                 entry point — yours, never written except by `init`
  ai_context/
    INDEX.md                auto-maintained table of contents (server-owned)
    project.md              what this project is (yours; server reads, never writes)
    constraints.md          hard rules and good practices (yours; read-only to the server)
    memory.md               notes, written via record_note
    decisions/
      0001-use-postgres.md  ADRs, written via record_decision
    plans/
      auth-refactor.md      mutable plans, written via update_plan

• ai_context/ is created lazily on the first write, or up front by init.
• INDEX.md is regenerated after every write and re-scanned from disk each time. Never hand-edit it.
• Decisions are append-only. Superseding one means recording a new one that references it; the only edit ever made to an existing ADR is a - Superseded-by: NNNN metadata line.
• Plans are mutable — update_plan overwrites.
• project.md and constraints.md are human ground truth. The server reads them and never writes them.

Tools

Tool	Input	What it does
get_context	topic?	Reads the index (default), project, constraints, memory, decisions or plans lists, a decision ID like 0003, or a plan slug.
record_decision	title, context, decision, consequences, supersedes?	Writes decisions/NNNN-<slug>.md as an ADR and links the superseded one both ways.
record_note	category, content	Appends a dated bullet to memory.md under Gotchas / Conventions / Learnings / Todos. Identical notes are deduplicated.
update_plan	name, content	Creates or fully overwrites plans/<slug>.md.
list_context	—	Lists every file under ai_context/ with size and last-modified date.

Length caps are deliberate anti-sludge discipline, not storage limits: title 80 chars, ADR sections 1200 each, notes 500, plans 8000. Exceeding one returns a message stating the actual length and the limit so the agent can summarize and retry.

There is no search_context. Grep over a small markdown folder is enough, and agents already have it.

Safety

• Every path is resolved through a single guard; nothing outside ai_context/ is ever read or written, and traversal in a slug or topic is rejected rather than quietly sanitized into something else.
• Writes go to a temp file and are renamed into place, so a crash cannot leave a half-written file.
• No state between calls, no caches. Edits from a human, a git pull or another agent are picked up on the next call.

Development

npm install
npm test          # unit + stdio integration tests
npm run typecheck # sources and tests
npm run build

License

MIT