Your agent forgets everything between sessions.

ctxkeeper is a local-first MCP server that gives AI coding agents durable project memory and token-budgeted context packs. One brief, the right 30 lines, decisions that survive the session.

local-first zero API keys no vector DB 11 e2e tests MIT Node ≥ 20.11 TensorBlock MCP Index

The missing layer is context, not connectors

The MCP ecosystem has plenty of tools. What it lacks is a way to remember a project and read less of it.

PROBLEM 01

Every session starts cold

Architecture decisions, constraints, and the command that actually runs tests get re-explained every day.

PROBLEM 02

Whole files for 30 lines

Agents grep, then read hundreds of lines to find one function. The context window pays for it.

PROBLEM 03

Handoffs are manual

Switch clients or close the laptop, and the next session has no idea what changed or what comes next.

What a session looks like

Two calls replace exploratory reads. Memory writes are one line each.

ctxkeeper — demo
$ project_brief
stack · commands · files to read first · git · TODOs · decisions · gotchas
✓ 1.2k tokens

$ context_pack("where is the OAuth token refreshed?")
src/auth/refresh.ts:42-78
+ the decision that explains the 60s early-refresh rule
✓ 1.0k tokens

$ remember(type="gotcha", title="refresh must happen 60s early")
✓ saved to .ctxkeeper/events.jsonl

$ log_work(summary="...", files=[...], next_steps=[...])
✓ handoff ready for tomorrow

Eight tools, one loop

Enter the project, locate code, record decisions, hand off. No 60-tool surface to pollute the prompt.

READ

project_brief · context_pack · recall · status

Onboarding, cited code windows under a token budget, memory search, and diagnostics.

WRITE

remember · todo · log_work · forget

Durable decisions, gotchas, commands, TODOs, and work logs. Archive is reversible.

Install in a minute

Node.js ≥ 20.11. One process, one append-only file, no services to run.

# clone and verify git clone https://github.com/Coisini-cyber/ctxkeeper-mcp.git cd ctxkeeper-mcp npm install npm test # inspect output without a client node dist/index.js --brief node dist/index.js --pack "where is auth?"

No clone: npx -y github:Coisini-cyber/ctxkeeper-mcp (builds on first run).

// ~/.config/opencode/opencode.json { "mcp": { "ctxkeeper": { "type": "local", "command": ["node", "/abs/path/dist/index.js"] } } }

Omit cwd. The server detects the project root from the workspace, so one entry works in every repository.

Built like a tool you can audit

  • Append-only JSONL — replayable, crash-tolerant, reversible archive.
  • No network — no API keys, accounts, telemetry, or cloud storage.
  • Read-only code access — the only subprocess is fixed-argument git.
  • Sensitive files skipped — .env, keys, credentials; tokens redacted.
  • Token-aware — every context tool has a budget and degrades gracefully.
  • No mid-code truncation — best window or skip, never half a function.

Measured, not promised

On this repository: 17 files, ~2.9k LOC, Windows 11, Node 22.23.

PROJECT_BRIEF

~10 ms

0.5–1.2k tokens

CONTEXT_PACK

~8–10 ms

~1.0k tokens, 2–4 windows

READING STORE.TS

3.5–4k

tokens for 430 lines

TESTS

11/11

real stdio, Node 20/22

Give your agent a memory

If it saves you a few thousand tokens today, a star helps other developers find it.