ctxd

A context firewall for AI coding agents.

Local-first engineering memory that gives Claude Code, Cursor and friends the minimum useful context for a task — and explains every token it sent.

The problem

You paste your repo into an AI agent. It gets 60,000 tokens, most of it irrelevant, and still misses the one architectural rule that mattered. Next session you explain the same project again. And again.

Meanwhile the agent "helpfully" reformats a file you asked it to change one line in.

Related MCP server: junto-memory

What ctxd does

$ ctxd context --task "Fix Stripe webhook idempotency" --budget 10000

CONTEXT RECEIPT 87f27bbb

Candidate: 76,182 estimated tokens
Final:     4,547 estimated tokens
Estimated context avoided: 71,635

Included (16):
  ✓ docs/rules.md                       [P0]  reason: mandatory (P0)
  ✓ src/payment/webhook.ts              [P2]  reason: direct task relevance
  ✓ src/payment/idempotency.ts          [P2]  reason: direct task relevance
  ✓ memory/decision/idempotency-key.md  [P1]  reason: project memory (accepted_decision)
  …

Excluded (61):
  × src/camera/stream.ts           — no task relevance
  × docs/architecture-overview.md  — duplicate of docs/architecture.md
  × .ctxd/sessions/session-2.md    — low priority

76k tokens of candidate context became 4.5k — and every inclusion and exclusion has a stated reason. Not compression: selection you can audit.

Storage is cheap. Model context is expensive. Every token sent to a model should have a reason to exist.

Principles

• Local-first. No cloud, no accounts, no telemetry. Your repository, memory and decisions never leave your machine.

• Deterministic. No embeddings, no LLM in the core. The same inputs produce byte-identical output, which is why it can be benchmarked.

• Auditable. Every context build produces a receipt. Nothing is included without a reason, and nothing is dropped silently.

• Provider-independent. Claude, Cursor and whatever comes next are workers. They are replaceable; your memory is not.

• Honest. Token counts are labelled estimates, never dollar figures. Unavailable signals read as zero rather than being invented.

Install

Requires Node.js 24+ and pnpm.

git clone https://github.com/g0GobliN/ctxd.git
cd ctxd
pnpm install
pnpm build

node packages/cli/dist/index.js doctor

doctor verifies Node, SQLite, FTS5, storage, config, the database, logging and Git. Every check actually runs — none reports success without executing.

Quickstart

# 1. Register your project. Detection reads real manifest files,
#    never guesses from directory names.
ctxd init --dir .

# 2. Build context for a task
ctxd context --task "Fix the webhook retry logic" --budget 10000

# 3. Record what a future session could not infer from the code
ctxd memory add --type DECISION --source accepted_decision \
  --title "Retry with exponential backoff" \
  --content "Fixed intervals caused a thundering herd under load."

# 4. Keep work across interruptions
ctxd session start --worker claude
ctxd checkpoint --next "Fix the 409 path then rerun tests"
ctxd resume
ctxd handoff --to cursor

Connect an AI worker

claude mcp add ctxd -- ctxd mcp --dir /path/to/project

Claude Code and Cursor then share one project memory — neither owns it. The agent asks ctxd for context instead of reading your whole repository, and records what it learns.

Crucially: a worker cannot overwrite what you told it. Agent conclusions are stored as worker_statement with visible confidence. If one contradicts a rule you stated, the write is refused and the conflict reported.

How it works

task ──► signals ──► candidates ──► dedup ──► rank ──► budget ──► receipt
                          ▲                              │
                     memory + git                  compression

Two rules do most of the work:

• Leftover budget is not a reason to send a file. An item with no connection to the task is excluded even when there is room. This is why a 10k budget often returns 4.5k.

• Search decides what is relevant; it does not decide what is mandatory. Every P0 rule is retrieved whether or not it shares vocabulary with the task.

Deep dive: docs/context-engine.md.

Commands

Every command supports --help.

Project status

Early but real. Phases 1–6 of the specification are built, tested and documented — 212 tests, including a golden benchmark that turns a 76k-token fixture repository into 4.5k while keeping everything the task needs.

Not built yet: worker verification, the diff firewall, the web UI. Nothing in this repository calls a network service or an AI model.

APIs may change before 1.0.

Documentation

Contributing

Contributions are very welcome — especially benchmark scenarios, which is how retrieval quality gets measured rather than argued about.

Start with CONTRIBUTING.md.

pnpm install && pnpm build && pnpm test

By participating you agree to the Code of Conduct. Security issues: see SECURITY.md.

Licence

MIT © the ctxd authors.