我们如何不再向 Claude Code、Codex 和 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: 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. 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. 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: calls brain_sync with its intent and the files it expects to touch, and gets task-relevant context back asks brain_ask for earlier decisions and their correction history runs brain_challenge to surface conflicting prior decisions or standing rules 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. Enter fullscreen mode Exit fullscreen mode 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 Enter fullscreen mode Exit fullscreen mode 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 Enter fullscreen mode Exit fullscreen mode 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