Prelude

Prelude

Project memory and a code map for AI agents: where to look, why the code is the way it is, and what a change will touch.

An agent with grep can find where a word appears. It cannot find out why the code is shaped the way it is, which tests cover a file, how many other files depend on it, or what the last session learned. That knowledge isn't in the source.

Prelude keeps it in the repo. It scans the project once and writes a small set of JSON files to .context/: the stack, the architecture, the constraints, the decisions, and a code map of every module, its exports, and what imports what. You commit those files, and agents add to them as they work. Every later session starts from them, through an MCP server, a generated CLAUDE.md / AGENTS.md, or plain stdout.

No embeddings, no server to host, no network calls. Regex heuristics over TypeScript/JavaScript, Python, Go, and Rust.

Quick start

cd your-project

npx prelude-context init # writes .context/

Or install it, which gives you the prelude command used in the rest of this README:

npm install -g prelude-context

prelude init

Then give it a task phrase:

prelude locate preserve manual edits during update --limit 2

1. src/core/merger.ts  ·  src/core (Core business logic)  ·  score 32

exports: MergeResult, MergeChange, ContextMerger, trackMapFields why: decision: Manual edits are sacred, content preserve×25, manual×31, edit×9, update×6, matches all terms impact: imported by 4 files · tests: tests/map-merge.test.ts, tests/mcp-server.test.ts, tests/merge-preserve.test.ts decisions: Manual edits are sacred

1. src/core/state-manager.ts · src/core (Core business logic) · score 26 exports: StateManager why: decision: Manual edits are sacred, content manual×9, edit×4, update×6, matches all terms impact: imported by 7 files · tests: tests/map-merge.test.ts, tests/mcp-server.test.ts, tests/merge-preserve.test.ts decisions: Manual edits are sacred

One call returns the files to read, why each was picked, what depends on them, the tests to run afterwards, and the recorded decision that constrains the change. That is real output from this repository, which keeps its own .context/ committed. Browse it to see what Prelude writes.

Requires Node.js >= 20.19.

What you get

your-project/

└── .context/ ├── project.json what the project is ├── stack.json language, runtime, frameworks, tooling ├── architecture.json type, patterns, directories, entry points, routes ├── constraints.json rules and preferences ├── decisions.json architecture decisions and their rationale ├── map.json modules, exports, import graph, hub files ├── changelog.md project timeline └── .prelude/ state: which fields were inferred, which you edited

Commit .context/. Gitignore .context/*.session.json.

prelude compact prints the whole thing as one dense line per section, sized for a system prompt (a few hundred tokens for this repo):

[project] prelude-context | The open standard for expressing and maintaining machine-readable context about a codebase

[stack] TypeScript/JavaScript Node.js >=20.19.0 | pnpm | testing: Vitest [arch] type=cli | patterns: Utility modules | entry: bin/prelude.ts | dirs: bin (Executable entry points), src/commands (Command handlers), src/core (Core business logic), src/mcp (MCP server), ... [decisions] Manual edits are sacred (accepted); Regex heuristics, not AST parsers (accepted); Schemas are the contract (accepted); ... [map] hubs: src/utils/fs.ts(25), src/runtime/context.ts(20), src/schema/index.ts(18), ... | src/core (Core business logic): state-manager.ts, infer.ts, map-scanner.ts +15 | ...

What grep can't tell an agent

prelude locate attaches the first four to every file it returns. On a freshly initialised project the decisions and notes are empty; the import graph and tests are there from the first run, and the rest accumulates as people and agents record it.

How well does locate find files?

bench/locate-bench.ts replays a repository's git history: each commit subject is a query, the files that commit changed are the answer, and the repo is checked out at the parent commit so nothing sees the change itself. The baseline is a grep for each query term over the same files, ranked by distinct terms matched. Share of queries with a correct file in the top 8:

The top result is correct 48% of the time, against 39% for grep. Up to 100 commits per repo. The scoring weights were chosen using these same six repositories, so treat the numbers as in-sample; run the script on your own repo to check (see CONTRIBUTING.md). File-finding is the baseline here, not the point: the table above is.

Why not just write a CLAUDE.md or AGENTS.md?

Keep them. Prelude generates both (prelude export --format claude-md, --format agents-md) and can bootstrap from one you already have (prelude init --from-claude-md). The difference is what sits underneath:

• It doesn't rot silently. A hand-written context file is correct on the day it is written. prelude diff --check exits 1 when the committed context no longer matches the code, so CI catches the drift.
• It is structured. JSON with a published schema, so tools can query one section, one directory, or one module instead of loading a whole markdown file.
• It answers "where" and "what else". prelude locate turns a task phrase into a short list of files with the reason each was picked, the tests that cover it, and the decisions that apply. A prose file can't do that.
• Your edits survive. Prelude tracks which fields it inferred and which you wrote. prelude update refreshes the first kind and never touches the second.
• It spans projects. Register several repos once and a single MCP server answers for all of them, including how they relate.
• It isn't tied to one tool. The same files feed Claude Code, Cursor, Codex, Claude Desktop, or anything that reads JSON.

How it relates to other approaches

• In-session repo maps (Aider's, for example) are computed when the session starts and discarded when it ends. Prelude's map is a file: diffable in a pull request, correctable by hand, shared by the whole team.
• Hosted code search and indexing services are more powerful retrieval, and they are a service to run or pay for. Prelude is static files and a local CLI.
• Embedding-based retrieval finds semantic matches that Prelude's term matching will miss. Prelude's results are deterministic and explain themselves, and they cost nothing to produce.

Use it from an agent (MCP)

Prelude runs as an MCP server over stdio.

One project

From a project that has a .context/ directory, register the server with Claude Code:

claude mcp add prelude-context -- npx -y prelude-context serve

For any other client, the server command is npx -y prelude-context serve --root /path/to/project:

{

"mcpServers": { "prelude-context": { "command": "npx", "args": ["-y", "prelude-context", "serve", "--root", "/path/to/project"] } } }

prelude mcp-config --client claude-code | cursor | codex | claude-desktop prints the exact snippet for your machine and client. The read tools are annotated read-only, so clients that honour tool annotations can run them without asking.

Resources: prelude://context/full, prelude://context/compact, prelude://context/map, and prelude://context/{type} for a single file.

Every project on the machine

Register each codebase once, register Prelude once in your agent harness, and every session can see all of your projects: what each one is, how they relate, and where to look inside any of them.

# once per repo

cd ~/code/backend && prelude init && prelude workspace add . cd ~/code/frontend && prelude init && prelude workspace add .

once per machine

prelude mcp-config --workspace --client claude-code

prints: claude mcp add --scope user prelude -- prelude serve --workspace

In workspace mode every tool takes an optional project, and three more tools appear:

prelude workspace list | index | status | remove manage the registry at ~/.prelude/ (override with PRELUDE_HOME).

Keep it honest in CI

The GitHub Action has two modes. Guard (check: "true") runs prelude diff --check and fails the job when the committed .context/ has drifted from the code. Update (the default) runs prelude update and opens a pull request when .context/ changed. Use both: guard pull requests, update on main.

# .github/workflows/prelude.yml

name: Prelude Context on: pull_request: push: branches: [main] paths: [package.json, pyproject.toml, Cargo.toml, go.mod, "src/**"]

jobs: check: if: github.event_name == 'pull_request' runs-on: ubuntu-latest steps:

• uses: actions/c