Why each agent starts from zero

Each tool keeps its own context and none of it travels:

• Claude Code's auto memory is stored on one machine.
• Cursor's user rules are per person.
• Chat histories stay in the tool and with the person who had them.
• Pull request descriptions and Slack threads hold the reasons, but agents don't read them before a change.

So the lesson one person's agent learned on Tuesday is learned again by someone else's on Thursday.

Layer 1: one instruction file for every agent

Commit an AGENTS.md at the repository root. Who reads it:

Keep it short and stable: build and test commands, layout, conventions, and the name of the project's shared memory.

Layer 2: one memory every agent reads and writes

RepoMemory keeps a ledger per project with five kinds of entry:

Every agent uses the same tools: brief at the start of a session (every guardrail, the open tasks, the newest decisions), recall before a change, record_entry when something is worth keeping, and claim_task before starting a task. A claim is refused with already_claimed if another agent has the task, and runs out after two hours unless renewed, so two people's agents don't do the same job and a crashed one doesn't hold it.

Each entry records which key and which agent wrote it. Entries are shown to agents as notes, not instructions, and one worded like a prompt injection is flagged.

Set it up for a team

1. Put the team on one account. On the Team plan, every API key on the account reads and writes the same ledgers. Invite teammates from the dashboard.

2. Each person creates their own key on the API keys page and sets it as REPOMEMORY_KEY.

3. Each person connects their agent:

   # Claude Code
   claude mcp add --transport http repomemory https://api.repomemory.dev/mcp \
     --header "X-API-Key: $REPOMEMORY_KEY"
   # Codex
   codex mcp add repomemory --url https://api.repomemory.dev/mcp \
     --bearer-token-env-var REPOMEMORY_KEY
   

   For Cursor and VS Code, the docs have the JSON.

4. Commit the project-memory section to AGENTS.md once, for everyone:

   ## Project memory (RepoMemory, project "acme/shop")
   - At the start of a session, call `brief` for the project: it returns every guardrail, the open tasks and the latest decisions. Never break a guardrail. If a guardrail contradicts the repository's rules or what you were asked, don't pick one quietly: say so and ask.
   - Before planning a change, removing code that looks unneeded or retrying an approach, call `recall` with words about the change. Follow what it returns.
   - When a change is reverted, a fix took real digging, or you choose one approach over another, call `record_entry` (kind lesson or decision) saying what happened, why, and what to do instead, with your name in `agent`.
   - Claim a task with `claim_task` before starting it and keep the `claim_token` it returns; `retire_entry` it with the token when done, or call `claim_task` with `release` and the token if you stop without finishing.
   

   npx @plexsicity/repomemory init writes this section and adds the server to Claude Code and Cursor in one step.

Keep it healthy

• When a decision changes, record the new one with supersedes; the old one is retired with a pointer, and recall stops returning it.
• If someone's agent records a secret, delete the entry from the dashboard's Ledger page; deleting is free.

Limits to know

Recall matches words, not meaning. Agents record only what AGENTS.md tells them to. RepoMemory is hosted only, with no self-hosted version. The Team plan is $50 a month; see pricing.

The four kinds of Cursor rules

From Cursor's rules docs, checked on 30 October 2026:

When rules disagree, Team Rules come first, then project rules, then user rules.

A project rule the whole team gets

Project rules must use the .mdc extension; a plain .md file in .cursor/rules is ignored. The front matter decides when a rule applies:

---
description: Conventions for the checkout service
globs: src/checkout/**/*.ts
alwaysApply: false
---
- Validate every request body with zod at the route.
- Prices are integers in cents; never use floats for money.
- Read @src/checkout/README.md before changing the payment flow.

• alwaysApply: true: in every chat.
• globs only: when a matching file is in context.
• description only: when the agent judges it relevant.
• Neither: only when someone @-mentions the rule.

If your team doesn't all use Cursor

.cursor/rules is read only by Cursor. If some of the team use Claude Code, Codex or another agent, put the shared rules in AGENTS.md: Cursor reads it (including nested ones in subfolders), Codex reads it, and Claude Code reads it when the repository has no CLAUDE.md. Keep Cursor-specific, file-scoped rules in .cursor/rules.

What rules don't do well

Rules are static text that someone has to edit. They're a poor fit for:

• Why a decision was made. The rule says "no captcha on checkout"; the reason, and the numbers behind it, don't fit in a rule.
• What was tried and reverted. Writing every lesson into a rule makes it long and less likely to be followed.
• Work in progress. Which tasks are open, and which agent has taken one.
• Things learned today. A teammate's agent finds out the staging database is read-only; until someone edits a rule, nobody else's agent knows.

Add a shared ledger to every teammate's Cursor

RepoMemory is an MCP server with one ledger per project. On the Team plan, every key on the account reads and writes the same ledgers. Add it to the project's .cursor/mcp.json, with each person's key coming from their own environment so no key is committed:

{
  "mcpServers": {
    "repomemory": {
      "url": "https://api.repomemory.dev/mcp",
      "headers": {
        "X-API-Key": "${env:REPOMEMORY_KEY}"
      }
    }
  }
}

Cursor fills in ${env:NAME} in url and headers from the environment. Then add an always-applied rule, .cursor/rules/project-memory.mdc:

---
alwaysApply: true
---
## Project memory (RepoMemory, project "acme/shop")
- At the start of a session, call `brief` for the project: it returns every guardrail, the open tasks and the latest decisions. Never break a guardrail. If a guardrail contradicts the repository's rules or what you were asked, don't pick one quietly: say so and ask.
- Before planning a change, removing code that looks unneeded or retrying an approach, call `recall` with words about the change. Follow what it returns.
- When a change is reverted, a fix took real digging, or you choose one approach over another, call `record_entry` (kind lesson or decision) saying what happened, why, and what to do instead, with your name in `agent`.

Now a lesson one teammate's agent records reaches everyone's next session, and a rule nobody should break can be a guardrail, which brief hands every agent at the start of a session.

When a guardrail and a rule disagree

RepoMemory doesn't read your rules, so brief can't spot a clash. The agent sees both; ledger entries come back as notes the user's instructions outrank. The rule above has the agent name the clash and ask; a person then edits the rule or supersedes the guardrail.

Limits to know

RepoMemory's recall matches words, not meaning, so agents should recall with the words of the change ("captcha checkout"). It's hosted only. The Team plan is $50 a month for 20,000 new entries; recall is free. See pricing and the docs.

First published on repomemory.dev. I build RepoMemory, so weigh my take on it accordingly.

The difference in one table

The CLAUDE.md column is from Anthropic's memory docs, checked on 30 October 2026.

What belongs in CLAUDE.md

Things that are true in every session and short to state:

## Build
- `npm test` before committing; `npm run lint -- --fix` for style.
## Layout
- API handlers in src/api/handlers/, one file per route.
## Project memory (RepoMemory, project "acme/shop")
- At the start of a session, call `brief` for the project. Never break a guardrail.
- Before planning a change, call `recall` with words about the change.
- When a change is reverted or you choose one approach over another, call `record_entry`.

If a line only matters when someone touches one part of the code, it's a candidate for a path-scoped rule (.claude/rules/ in Claude Code, .cursor/rules/ in Cursor) or for the ledger.

What belongs in shared memory

Things that matter for one change, and stories that explain a rule:

• Lesson: "Captcha on checkout cut completed orders 5%. Reverted after two weeks; bots only spike on release days."
• Decision: "Chose Postgres full-text search over embeddings: same query, same results, no model to run."
• Guardrail: "Never run migrations on deploy; the release job runs them first." brief returns every guardrail at the start of a session, so rules like this don't depend on a search matching them.
• Task: "Move image uploads to R2", which an agent claims before starting so no other agent starts the same job.

Here's a lesson being recorded, as an agent would through the record_entry tool:

curl -s https://api.repomemory.dev/v1/record \
  -H "X-API-Key: $REPOMEMORY_KEY" -H "Content-Type: application/json" \
  -d '{"project":"acme/shop","kind":"lesson",
       "title":"Captcha on checkout cut completed orders 5%",
       "body":"Shipped a captcha on the checkout page in March and reverted it after two weeks: completed orders fell 5%. Bots only spike on release days.",
       "tags":["checkout","captcha"],"agent":"claude-code"}'

Six months later, an agent asked to "add a captcha to checkout" recalls with those words and finds it before writing any code.

Signs you've put something in the wrong place

• Your CLAUDE.md has a "history" or "don't do X again" section that keeps growing. Move the stories to the ledger and leave one-line rules.
• Agents repeat a reverted change. The lesson was in a PR description or a chat nobody's agent reads.
• Two lines in CLAUDE.md contradict each other because a decision changed. In a ledger, recording the new decision with supersedes retires the old one.
• A rule is ignored by Cursor or Codex because it lives in Claude Code's machine-local auto memory.

Set it up

Create a free key on the API keys page, then in the repository:

export REPOMEMORY_KEY=sk_live_...
npx @plexsicity/repomemory init

It adds the MCP server to Claude Code and Cursor and writes the project-memory section into AGENTS.md or CLAUDE.md. The docs show the setup for Codex, VS Code and Claude.ai.

First published on repomemory.dev. I build RepoMemory, so weigh my take on it accordingly.

What Claude Code carries over by itself

Anthropic's memory docs (checked on 30 October 2026) describe two mechanisms, both loaded at the start of every session:

Both are context, not enforced rules. The docs suggest keeping each CLAUDE.md under about 200 lines, because longer files cost context and are followed less reliably.

Where they stop

• Auto memory stays on one machine. It isn't shared across machines, cloud sessions or teammates. A lesson Claude learned on your laptop doesn't reach the CI agent or a colleague's Cursor.
• CLAUDE.md is for rules, not history. "We reverted the checkout captcha because orders fell 5%" is worth knowing before anyone touches checkout, but a file loaded whole into every session can't hold every such story without growing past the size where it is followed.
• Nothing is retired. When a decision changes, someone has to find and edit the old line, or the file says both things.
• Only Claude Code reads auto memory. Codex, Cursor and other agents working on the same repository don't see it.

Add a shared ledger over MCP

RepoMemory is an MCP server that keeps a project's decisions, lessons, guardrails, notes and tasks. Claude Code calls brief at the start of a session, recall before a change, and record_entry when something is worth keeping. Recall searches, so only the entries about the change at hand come back, and the ledger can grow without filling the context.

1. Create a free key on the API keys page and add the server:

   claude mcp add --transport http repomemory https://api.repomemory.dev/mcp \
     --header "X-API-Key: $REPOMEMORY_KEY"
   

2. Add this to the repository's CLAUDE.md or AGENTS.md, so every session knows the project's ledger and when to use it:

   ## Project memory (RepoMemory, project "acme/shop")
   - At the start of a session, call `brief` for the project: it returns every guardrail, the open tasks and the latest decisions. Never break a guardrail.
   - Before planning a change, removing code that looks unneeded or retrying an approach, call `recall` with words about the change. Follow what it returns.
   - When a change is reverted, a fix took real digging, or you choose one approach over another, call `record_entry` (kind lesson or decision) saying what happened, why, and what to do instead, with your name in `agent`.
   

3. Or do both at once in the repository with the command line tool (Node.js 22 or newer):

   export REPOMEMORY_KEY=sk_live_...
   npx @plexsicity/repomemory init
   

The next session starts with a call like this one, made for you by Claude:

curl -s https://api.repomemory.dev/v1/brief \
  -H "X-API-Key: $REPOMEMORY_KEY" -H "Content-Type: application/json" \
  -d '{"project":"acme/shop"}'

It returns every active guardrail in full, the open tasks and the newest decisions and lessons, so the session begins where the last one stopped.

What to keep where

• CLAUDE.md: how to build and test, conventions, the project's ledger name.
• Auto memory: your own preferences, which nobody else needs.
• The ledger: why something is the way it is, what was tried and reverted, rules nobody should break, and tasks other agents may pick up.

Limits to know

Recall matches words, not meaning: "captcha checkout" finds a lesson titled "Captcha on checkout", while "why did orders drop" may not. Agents only record what they are told to, which is what the CLAUDE.md lines are for. RepoMemory is hosted only. The free plan allows 300 new entries a month; recall, claims and retires are free. See pricing and the docs for other clients.

First published on repomemory.dev. I build RepoMemory, so weigh my take on it accordingly.

Why it happens

Say someone added a captcha to checkout in March, and completed orders fell 5%, so it was reverted. In October someone asks an agent to "stop bots on checkout". The agent sees a checkout with no captcha and adds one. The lesson is still around, but the agent doesn't see it:

• the revert commit says "Revert 'Add captcha'", with no reason;
• the reason is in a PR comment, a Slack thread or someone's head;
• a "don't add a captcha" line in CLAUDE.md might be there, but a file that collects every such story stops being followed once it's long.

Record the lesson when you revert

The agent that does the revert, or you, records what happened and what to do instead:

curl -s https://api.repomemory.dev/v1/record \
  -H "X-API-Key: $REPOMEMORY_KEY" -H "Content-Type: application/json" \
  -d '{"project":"acme/shop","kind":"lesson",
       "title":"Captcha on checkout cut completed orders 5%",
       "body":"Shipped a captcha on the checkout page in March and reverted it after two weeks: completed orders fell 5%. Bots only spike on release days.",
       "tags":["checkout","captcha"],"agent":"claude-code"}'

Put the words someone would use for the change in the title and tags ("captcha", "checkout"). Recall matches words, so a title in the change's own words is what makes it findable.

Recall before the next change

Before planning, the agent searches with words about the change:

curl -s https://api.repomemory.dev/v1/recall \
  -H "X-API-Key: $REPOMEMORY_KEY" -H "Content-Type: application/json" \
  -d '{"project":"acme/shop","query":"add a captcha to checkout"}'

The lesson comes back, and the agent can propose rate limiting on release days instead. Recall is free and unmetered on every plan, so agents can do it before every change.

Make it automatic

Agents use the same operations as MCP tools. Connect the server (the docs cover Claude Code, Cursor, Codex, VS Code and Claude.ai) and add this to AGENTS.md or CLAUDE.md:

## Project memory (RepoMemory, project "acme/shop")
- At the start of a session, call `brief` for the project: it returns every guardrail, the open tasks and the latest decisions. Never break a guardrail.
- Before planning a change, removing code that looks unneeded or retrying an approach, call `recall` with words about the change. Follow what it returns.
- When a change is reverted, a fix took real digging, or you choose one approach over another, call `record_entry` (kind lesson or decision) saying what happened, why, and what to do instead, with your name in `agent`.

"Removing code that looks unneeded" is in there on purpose: agents also undo fixes by tidying away a line that looks pointless. A lesson recorded when the line was added stops that too.

For rules that must never be broken

If a lesson has become a rule, record it as a guardrail instead. brief returns every active guardrail at the start of each session, whatever the agent is about to do, so the rule doesn't depend on a search matching it.

When the lesson stops being true

If bots are later blocked at the CDN and a captcha is no longer the question, retire the lesson with a reason, or record a new decision with supersedes set to its id. Recall then leaves the old one out, and an agent won't refuse a change the team has agreed to.

Try it

The free plan has 300 new entries a month and needs no card. Create a key on the API keys page, then run npx @plexsicity/repomemory init in the repository.

First published on repomemory.dev. I build RepoMemory, so weigh my take on it accordingly.