# 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:

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

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

```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:

```markdown
## 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