Memory for coding agents

This page shows how a development team can give every developer and coding agent the decisions that still apply to its code, and the reasons behind them, across people, repositories and sessions.

The problem

A payments team learns that its provider can deliver the same callback more than once. It decides to deduplicate callbacks by provider event ID before creating orders, first with an in-memory check. A month later, a process restart loses that check’s state and an order is created twice, so the team replaces it with a durable database constraint.

Three weeks on, a developer new to the team sees the constraint and a leftover helper from the old check and asks a coding agent to “remove the duplicate deduplication”. The agent starts a fresh session. Nothing in the code says which approach replaced which, or why either exists.

Why the usual approach falls short

Teams keep this knowledge in pull requests, chat threads, design documents and people’s heads. An agent can search some of them, but a search for “callback deduplication” returns the original plan and its replacement as equally good matches, and the agent has to decide which one still applies. Someone who was not there cannot tell from the text alone.

Alvia with CLAUDE.md, AGENTS.md and agent memory

Instruction files, built-in agent memory and Alvia each hold a different kind of knowledge (as of October 2026):

CLAUDE.md and AGENTS.md are files people write and review. Codex reads AGENTS.md before any work. Claude Code loads the CLAUDE.md files in the working directory and above at the start of every session; files in subdirectories and rules scoped to paths load when it works with matching files. They are the right place for conventions, commands and rules that must always apply. See Claude Code memory and Codex AGENTS.md.
Claude Code’s auto memory and Codex memories are notes the agent writes for itself, stored on one developer’s machine (Claude Code keeps them per repository and loads the first 200 lines or 25 KB of their index each session). They help that developer’s next session.
Alvia holds the team’s decisions and their reasons, shared across people, repositories and agents, and keeps each decision current as it changes.

How each handles a team’s decisions:

Question	Instruction files and local agent memory	Alvia
Who keeps it current?	A person edits the file, or one agent edits its own notes	Each decision is sent once; Alvia relates it to what it holds
What happens when a decision changes?	Someone edits the file or the notes to match	The new decision becomes the next version of the one it replaces
Who can read it?	Everyone with the repository, or one machine	Every person, repository and agent with a key to the project
What reaches the agent?	The instruction files for where it works, in full, and the notes it opens	One to three sentences that answer the question the agent asks

They work together: AGENTS.md or CLAUDE.md holds the instructions, including when to ask Alvia, as in the example below, and Alvia holds the decisions themselves.

How Alvia changes the design

The team records each decision once, with the reason and the date it was made. A later decision that Alvia classifies as replacing an earlier one becomes that decision’s next version. Before an agent changes the code that a decision governs, it asks Alvia why the code is the way it is and gets the decision that applies now.

Your team or an integration sends each decision, and Alvia returns the rationale. Tests and the source code establish what the implementation does, and your review decides whether a change is safe.

Set up

Project. Use one project for the team’s shared decisions, with a separate key for each person or service. Use a separate project for a repository or customer whose decisions must not be readable by the rest of the team: a team_id is not an access boundary.
Scope. Send the same scope on every write and read, such as organization_id: acme, team_id: payments and application_id: acme/checkout. Alvia relates a new decision only to memories with the same scope, so a developer whose agent leaves out team_id writes beside the team’s decisions instead of updating them. See Projects and scope.
Memory policy. Before anyone connects an agent, set the project’s policy in the dashboard to exclude credentials, access tokens, personnel information and customer payloads. Store the decision and its reason, not the logs or source that led to it. See Filter memories.

Connect each developer’s agent with Connect a coding agent with MCP. The MCP setting holds the key and stays out of the repository.

Example

Record the first decision

The agent stores the decision with the remember tool:

{
  "content": "Deduplicate payment callbacks by provider event ID before creating orders because the provider can deliver the same callback more than once. The initial implementation uses an in-memory duplicate check.",
  "occurred_at": "2026-08-20T11:00:00Z",
  "organization_id": "acme",
  "team_id": "payments",
  "application_id": "acme/checkout"
}

A decision log or developer portal sends the same content to POST /v1/memories, with the scope fields inside scope. See Store memories.

Record the decision that replaces it

After the restart incident, the team records what replaced the check and why:

{
  "content": "Use a durable database constraint on provider event ID for payment callback deduplication. This replaces the in-memory duplicate check, which can lose its state during a process restart. The requirement to prevent duplicate orders still applies.",
  "occurred_at": "2026-09-22T16:00:00Z",
  "organization_id": "acme",
  "team_id": "payments",
  "application_id": "acme/checkout"
}

Saying what the decision replaces helps Alvia relate the two.

Ask before changing the code

Before removing anything, the agent asks:

{
  "query": "Why does checkout deduplicate payment callbacks durably, and which approach replaced the in-memory check?",
  "organization_id": "acme",
  "team_id": "payments",
  "application_id": "acme/checkout"
}

An illustrative result:

{
  "status": "available",
  "context": "Checkout uses a durable constraint on provider event ID to prevent duplicate orders from repeated callbacks. It replaced the in-memory check because that state can be lost during a process restart."
}

The result arrives in the agent’s context like any other tool result. The agent can now keep the constraint, remove the leftover helper from the old check and tell the developer why. When Alvia has nothing for the question, the result is { "status": "not_found" }, and the agent should read the design records or ask the team rather than invent a reason.

Tell the agent when to ask

Commit a short instruction to the repository’s agent file:

Before changing checkout behavior, ask Alvia for the relevant decisions
using organization_id "acme", team_id "payments" and
application_id "acme/checkout". When the team changes a decision, store
what replaced it and why. Exclude secrets, customer payloads and logs.

The file stays short and rarely changes; the decisions it points to change in Alvia.

What Alvia does here

Formation turns each submitted decision into a memory and compares it with the team’s decisions in the same scope
Supersession makes the durable constraint the next version of the deduplication decision in this example
Contradiction keeps two developers’ conflicting decisions and links them, so context reports both and the team can settle it
Occurrence dates keep the date each decision was made, including decisions imported from older discussions
Scope keeps the payments team’s decisions together for every person and agent that sends the same IDs
Memory policies keep secrets and customer data out of the shared memory
Resolved context answers the agent’s question from the decision that applies now
Forget removes a decision recorded by mistake

Your application reads each memory’s history, versions and relationships through the API, and the dashboard shows each version, how it was classified and why, and the memory’s related and contradicting memories. See See the history in Change over time.

Design notes

Formation is asynchronous. The agent that stores a decision already has it in that step; formation finishes in less than a minute, so other agents and later sessions read it shortly after it is sent.
Alvia holds the decisions your team records. Record each decision when it is made, from the agent, a decision log or a developer portal.
Execution status stays in the tracker. “We decided to migrate” is not “the migration has finished”. Store completion when it becomes a fact, and check the code before acting on an old plan.
Where Alvia fits. Keep conventions, commands and rules that always apply in AGENTS.md or CLAUDE.md, and one developer’s working notes in the agent’s own memory. Alvia holds the team’s decisions as they change, shared across people, repositories and agents. See Alvia compared with other approaches.

Build it with a coding assistant

Give a coding assistant this brief together with Build with an AI assistant:

Help our team share current architecture decisions and their reasons.
Use consistent organization, team and repository application IDs across
people and agents. Retain explicit design decisions, not raw production
logs, credentials or customer payloads. Configure the project policy
and test it before importing permitted discussions. Show a decision
changing from an in-memory callback check to durable deduplication.