Cards and context for a task

An agent does not remember the last session, and after its context is compacted it does not remember the start of this one. Cards are two short notes that come with every session without a search: how you work, and how this project works. They live in memory, so every agent gets the same ones, and every change is a version that cannot erase someone else’s.

Every session starts from zero

The rules of a project (“database migrations only go forward: back up first”, “no file over 500 lines”) and the habits of a person (“commit and push only when I say so”, “before a long run: a short probe and how long it will take”) have to be told to the agent again, every time.

The usual answer is a file in the repo: CLAUDE.md, AGENTS.md, .cursorrules. It works while there is one tool and one repo. Then:

• each tool reads its own file, and the rules are copied into three files that drift apart;
• an agent on another machine, in the cloud or in a chat does not see the file;
• there is no history: who changed a rule, and when, is not visible;
• two people who edit it at the same time erase each other’s changes.

What cards are

Two short notes, at most 2 KB each, that come with every session without a search:

• the user card: how you work, in every project: language, style, what the agent should not do. Each person has their own;
• the project card: one per workspace: the stack, the rules, the current goals.

They are not part of the graph. They are what you would tell a new colleague on the first day.

Every change is a new version, and the old ones stay. A save says which version it was edited from. If someone else saved in between, nothing is overwritten: the latest version comes back, to merge the two.

Example: a compaction in the middle of a session

On November 7, the session in which this page was drafted went through a compaction of its context: everything before it became a short summary. The plugin for Claude Code put the two cards back at the top at once, before the next turn:

## post-cortex cards

### User card (v1)
## Preferences
- Talk to me in Bulgarian, informally.
- Short questions get short answers.
...
### Project card (v5)
## Conventions
- ... Commits without Co-Authored-By.

After the compaction the agent went on in Bulgarian and made its commits without a Co-Authored-By line, although the tool’s own instructions asked it to add one. The rule was not in the summary; it was in the card.

The cards are in memory, not in the repo, so the same two notes reach every client: Claude Code gets them at the start of a session and after a compaction, Hermes and other agents read them over MCP, and the context for a task (below) starts with them.

The limit: a card is as true as its last version

Our project card said where this project’s memory is kept. Two weeks later the memory had moved to another server, and nobody had updated the card.

On November 7 the agent checked a search fix and reported that it worked. It had checked it in the wrong place, where the old code still ran. The mistake came out when a tool’s description turned out to be older than the code: the agent looked at where its plugin really points, said so, and updated the card.

Two things follow from it:

• A card does not keep itself current. Whoever learns something new writes it: the person or the agent. That is why the agent that reads a card can also write it.
• The history shows when it went stale. Every version keeps its author and date. The version the agent read was 16 days old, and its “current goals” were work finished long before.

Two writers at once

The app had a project card open, and a line was being added to its goals. Meanwhile the agent saved a new version of the same card. Then the app saved. Nothing was overwritten; the app showed both versions:

The agent saved while the card was being edited in the app. The app shows the latest and yours side by side; saving yours over it is a choice, never an accident.

An agent gets the same answer when its save comes second: the card is at a newer version now, here is its text, merge your change and save again. In our case the line was added to the latest text and saved as the next version, which holds both changes. The history keeps each step with its author.

Everything for one task in one call

Cards say how the work is done. A concrete task also needs the facts: what was decided, what broke, what depends on what. One call gathers them, within a token budget, in this order:

1. the two cards;
2. the graph around the names in the request: the things themselves, their neighbours and what depends on them, at most half of what is left after the cards (when it does not fit, the neighbours go first, then the dependents);
3. the records search ranks highest for the request, only those that still hold, each as its passage around the words of the request;
4. excerpts of the conversation, when asked for.

The budget is a limit on the text the model reads: it never goes past it, unless the cards alone are larger. The same answer also carries those parts as data for a program (the things with their relations, the records with their ids), and those are not counted in the budget.

Example: why our cloud stopped

The memory of this project, on November 8, the afternoon after a morning outage of our cloud was fixed. One call, a budget of 4,000 tokens, asking why every call hung during the outage and how the database connection is kept alive now. The answer: 11 items, 3,975 tokens.

What came in:

• the two cards;
• the graph around the database and its connection: what fixed the reconnect, what depends on the connection, and what depends on the database;
• 11 records, on top what is still open and the cause (a call in flight on a replaced connection now fails at once instead of waiting), then the firewall rule that reset the connection, the tests that reproduce it, and the release with the fix.

The old way, that is four calls (the two cards, a search, the graph around the database), and the agent decides alone what to cut so that it fits.

The same answer shows where it is still weak: the last records are about other work of the same day (a release that stopped at one step, a module turned on), because they share its words. Search ranks them low, and they come in because there was still room in the budget.

What it solves

• Rules survive a compaction and a new session. They do not depend on the summary and are not repeated by hand.
• The same rules for every agent. Claude Code, Hermes, an agent in the cloud or in the chat get the same two notes, without copies in three files.
• Nobody erases another’s change. A save says which version it starts from; if that is old, it gets the latest, to merge it.
• Who changed what is visible. Every version stays, with its author and date.
• One task, one call. The cards, the graph and the records come together, in the size the model can read.

For agents and scripts: the cards in the tools reference and the REST API.