How we stopped re-explaining decisions to Claude Code, Codex and Cursor

On Saturday a Codex session did our search-visibility work: it wrote a guide, submitted the sitemap to Google and Bing, and recorded what it did and what was still open in our project brain. On Monday I opened Claude Code (a different tool, a different session) and asked it to continue. It started from Codex's record: it knew the guide existed, that the PR had been merged after an earlier note said "not merged", and that Bing hadn't indexed it yet. It extended the guide instead of writing a second one. Before we had this, that handoff was me re-explaining Saturday to Monday's tool, and usually forgetting one thing.

Each tool remembers its own sessions. None of them knows what the others decided.

The short answer: keep stable conventions in a rules file like AGENTS.md, and keep changing decisions, corrections, evidence and open questions in one project brain that the tools you already use reach over MCP (Aider through the CLI). It is automatic in Claude Code; in Cursor and similar hosts the model has to call the tools.

Where a rules file stops working

AGENTS.md or CLAUDE.md is the right place for conventions: plain text, in Git, free. We keep ours. It stops being enough at three specific moments, and we hit the first one within a week:

1. A decision changes. The file still says the old thing until someone remembers to edit it, and a session that started from the file has no way to know it's stale.
2. A second session starts — same tool or a different one — and re-investigates what the last one already found, because the finding lived in a chat that ended.
3. Two sessions touch the same files and nobody finds out until review.

None of those is a conventions problem. They're a current state problem, and a file you edit by hand can't reliably hold current state.

The common approaches

Approach	What it keeps	Portability	Main limitation
Rules files (AGENTS.md, CLAUDE.md, Cursor rules)	Stable conventions	Plain text in Git	Edited by hand; no history of why a decision changed
A tool's own memory (e.g. Claude Code's auto-memory)	Notes one tool writes for itself	Outside the repo, per user and machine	Codex, Cursor and teammates never see it
Specs and decision records	Agreed designs and rationale	Plain text in Git	Agents consult them only when told to
Agent task trackers	Work items and handoff status	Varies	Centred on tasks, not decisions and evidence
Memory MCP servers	Facts or conversation memory	Local database or hosted service	Often scoped to a user or machine, not the project
Shared project brain	Decisions, corrections, evidence, open questions	One file committed with the code	Starts with what you capture

What we built

klypix-mcp is an open-source (Apache-2.0) MCP server that keeps a brain.klypix file in your repo. A session:

1. calls brain_sync with its intent and the files it expects to touch, and gets task-relevant context back
2. asks brain_ask for earlier decisions and their correction history
3. runs brain_challenge to surface conflicting prior decisions or standing rules
4. records findings or explicit corrections with brain_note

A correction supersedes the stale decision and keeps its history. A decision can also cite the code it was made against; when that code changes, the next Claude Code session flags the card for re-verification (it detects that the code changed, not that the decision became wrong). And a person can open the same file as a map in the Klypix desktop app (Windows) and correct any card by hand — that correction is what the next session reads. All of it is local: the MCP server is a process on your machine and the brain is a file in your repo — nothing is uploaded unless you explicitly share it. This is what a session actually sees at the start of a task — real output from our own project brain, trimmed:

# Relevant prior decisions from this project's brain
- Website: GEO improvements prepared in PR #219:
  shared-project-memory guide, bilingual FAQ, guide in
  sitemap/llms.txt. Vercel preview Ready. Not merged.
- Website: CORRECTION — GEO PR #219 is now APPROVED, MERGED
  and LIVE (2026-09-12), replacing its earlier
  pending-preview status.  [recorded by Codex, 2026-09-12]
- Website: Bing ownership verified 2026-09-12; sitemap and
  guide submissions accepted.

The second line is the point. The first card was true on Saturday morning and stale by the afternoon; the correction supersedes it, and a session that starts on Monday gets the current state without anyone editing a rules file.

It also argues back. Ask the brain to challenge a proposal and it answers with the cards that contradict it — here, a stale proposal made on Monday against Saturday's record, real output, trimmed:

⚔️ Challenge: "Keep the guide (PR #219) as a Vercel preview
and wait for review before merging."

Prior decisions that dispute this (1)
[Website] 2026-09-12 · via codex-mcp-client
  CORRECTION — GEO PR #219 is now APPROVED, MERGED and LIVE
  (2026-09-12), replacing its earlier pending-preview status.
  ⚠ A prior CORRECTION disputes this claim.
  ⚠ Captured by ANOTHER agent (codex-mcp-client) —
    coordinate before overriding.

checked 1891 live cards, 87 corrections, 74 open questions

An empty result is not proof the change is correct; it means no recorded contradiction was found.

And this is two real sessions on one project, not a mockup — session B declares a file session A already declared and gets the overlap warning; session A then records a correction that supersedes its stale card:

Per-tool behaviour — start with Claude Code

• Claude Code: lifecycle hooks: context arrives at session start automatically, and at turn end the hook harvests the lines the agent marked as decisions (plus brain_note calls). If the model marks nothing, nothing is captured. Try it here first.
• Codex: native MCP tools and the brain_sync gateway. Capture is explicit (brain_note).
• Cursor, Cline, VS Code / Copilot, Gemini CLI: MCP config plus an always-on rules file. The model has to call the tools, and sometimes it won't. This is the weakest path today.

What the hook captures

Only lines the agent explicitly marks as a decision, plus explicit brain_note calls — it reads the transcript to find those marks and takes nothing else. In Git repos a commit hook also records commits as cards (npx klypix-mcp git-hook remove turns that off). The file it writes is in your repo, so you can open it and delete anything.

Sharing the brain across a team

npx klypix-mcp install   # inside the project, on each machine

This wires the editors it detects and registers a .klypix merge driver in Git repositories. When two people change the brain, Git merges it card by card: a card edited differently on both sides keeps both versions instead of silently overwriting one.

The binary-file question

brain.klypix is a ZIP (cards plus any attached evidence), so a PR diff shows "Bin N → M bytes". For review, npx klypix-mcp diff main lists the cards added, updated and removed, and npx klypix-mcp pr-brief origin/main lists the cards that reference the files a PR changed. If you need the brain readable inside the PR itself, that is a fair ask, and the honest answer today is that you use the commands.

Limits

• A new brain knows only what has been captured.
• Live session presence and file-overlap warnings are per machine and advisory.
• Without the merge driver, a clone gets an ordinary binary conflict.
• The desktop app that shows the brain as a map is Windows-only. The MCP server runs anywhere Node runs.
• Your AI provider still receives whatever context its agent is given.

Full guide with the handoff example: https://klypix.com/guides/shared-project-memory

Comments

[Jo Do]

The correction chain is the part that makes this more useful than another memory dump. I would avoid returning only the winning card, though. Give the next agent the current decision plus a compact supersession trail and the evidence timestamp. That lets it distinguish "settled after new evidence" from "latest writer won," which matters when the next action is expensive or hard to undo.