Giving Claude Code a persistent memory with MCP

Claude Code is a phenomenal pair programmer with one embarrassing flaw: it wakes up every morning with total amnesia. You spend twenty minutes explaining that database access always goes through repository classes, that the billing domain uses idempotency keys on every mutation, that you migrated off moment.js last quarter — and the moment the session ends, all of it evaporates. Tomorrow you explain it again. Or worse, you don't, and the agent cheerfully reintroduces the exact pattern you banned in March.

The context window is working memory, not long-term memory. Closing a session is a hard reset. CLAUDE.md helps, but it doesn't scale: it's one flat file, it gets stale, every line gets loaded into every session whether relevant or not, and it's awkward to share nuanced knowledge across a dozen repos and a team of humans-plus-agents.

What you actually want is persistent memory for your AI coding agent: a store the agent queries before it plans, and writes back to after it learns something. The Model Context Protocol makes this straightforward — memory becomes just another MCP server the agent can call. That's what Knowit is: an open-source MCP memory server and CLI that gives Claude Code (and Cursor, Codex, Windsurf, and anything else that speaks MCP) shared, structured, persistent memory.

Install it in two minutes

One command, run from your project root:

$ npx knowit install

The wizard initializes a local memory store, registers the MCP server with your client (for Claude Code it just runs claude mcp add under the hood), and updates your agent instruction file so the agent knows the memory exists and when to use it. It can even import your existing ARCHITECTURE.md and ADR files into structured memory as a starting point.

There's no server to host and no account to create. Project memory lives in .knowit/knowledge.jsonl — a line-delimited JSON file sitting in your repo. Local-first, MIT licensed, readable with cat.

The store/retrieve loop

Knowit's memory isn't a pile of chat transcripts. Every entry is typed — rule, architecture, pattern, decision, convention, or note — and scoped to global, team, repo, or domain, with tags and confidence scores on top. Structure is what makes retrieval precise instead of vibes-based.

Seed it from the CLI:

$ knowit add rule "No direct DB access from controllers" \
  "All database access goes through repository classes." \
  --scope repo --repo api-gateway --tags architecture,layers

Now the loop. When you ask Claude Code to, say, "add webhook retry handling to the billing service," the agent first calls the resolve_context MCP tool with the task, repo, and domain. Knowit returns the titles and summaries of the most relevant entries — the retry decision from last month, the billing idempotency rule, the queue conventions. The agent then calls get_knowledge for just the entries that matter, pulling full content without flooding its context window.

The write side is the part that compounds. At the end of a session, the agent calls capture_session_learnings with the durable things it figured out:

capture_session_learnings {
  learnings: [{
    type: "decision",
    title: "Webhook retries use exponential backoff with jitter",
    content: "Max 5 attempts, base 2s, full jitter. Dead-letter
              after that. Chosen over fixed intervals to avoid
              thundering-herd on provider recovery.",
    scope: "repo", repo: "api-gateway", domain: "billing"
  }]
}

Deduplication is built in — an entry with the same title, type, scope, repo, and domain gets updated, not duplicated. Tomorrow's session (or your teammate's session, or a completely different agent's session) starts with that decision already in memory. You explained it zero times.

Team memory through git

Here's the quietly great part of JSONL-in-the-repo: memory changes ride the same rails as code changes. When an agent stores a new decision, it shows up as a one-line diff in .knowit/knowledge.jsonl. It goes into the same branch and the same pull request as the code it explains. Reviewers see "here's the retry implementation, and here's the recorded decision about why" side by side — and can veto a bad rule before it starts steering every future agent session.

On git pull, everyone's agents sync memory automatically. No hosted service, no sync protocol, no per-seat pricing. Just a file. And if your team wants shared memory outside any single repo, point everyone at one SQLite database instead: KNOWIT_DB_PATH=/shared/team/knowit.db — same tools, same loop.

What changes in practice

Concretely, after a few weeks of running this loop:

• New sessions stop asking questions the team answered months ago — the agent resolves them from memory before planning.
• Banned patterns stay banned. A rule entry outlives every context window.
• Onboarding flips: a new teammate's agent knows the architecture on day one, because the memory came with the clone.
• Your CLAUDE.md shrinks to a pointer: "call resolve_context before you plan, capture_session_learnings when you finish."

Session amnesia isn't an inherent property of AI coding agents — it's just a missing layer. MCP gives agents a standard way to call out to a memory server, and a memory server with structure gives them something worth recalling.

If you want to try it: npx knowit install, then read the Quick Start. The whole thing is open source — star it on GitHub or open an issue if your agent still forgets something it shouldn't.