Architecture note
Shared memory for AI coding agents: a portable architecture
How canonical knowledge, AGENTS.md, CLAUDE.md, MCP and human review can preserve useful context across coding agents without confusing memory with authority.
Two coding agents can both produce good work and still disagree about the project. One remembers a rejected design. Another reads an old instruction. A third receives a perfect summary that quietly drops the reason a decision was made. More context is useful only when the system can tell which context is current, relevant and permitted.
A portable memory architecture therefore needs an owner, a source, a state and a scope for important knowledge. It also needs a way to correct that knowledge without pretending the earlier version never existed. This note proposes that architecture; it does not certify every Starlight adapter or claim a new hosted memory service.
Separate the durable record from the session.
The durable record should survive the tool that created it. A plain file, append-only record or database row can hold a decision and its provenance. An agent's context window is a selected view of those records for a particular task.
This creates an important design choice: keep one canonical record and generate the views the tools need. Do not make several manually maintained instruction files competing authorities. A change to a decision should flow into each relevant view through a repeatable process.
Give each layer one responsibility.
| Layer | Responsibility | Evidence to ask for |
|---|---|---|
| Knowledge record | Retain the fact, decision, source, scope and current state. | A versioned record that can be corrected and exported. |
| Retrieval | Select relevant records the task is allowed to access. | The records returned and the reasons for their selection. |
| Host instructions | Explain how this coding agent should use the project. | The effective instructions loaded by the current session. |
| Tool interface | Expose bounded reads and explicitly permitted writes. | Declared schemas, authentication and observed tool responses. |
| Review | Decide which proposed changes become accepted knowledge. | A decision owner, revision and acceptance result. |
AGENTS.md and CLAUDE.md are projections.
Codex documents how it discovers AGENTS.md instructions. Claude Code documents its memory and instruction mechanisms. Each host has its own loading rules. A shared source does not make those rules identical.
Keep the host-specific file small: where the canonical knowledge lives, how to select the project's scope, which checks matter and what requires a person's decision. Test the effective session. The presence of a file on disk is weaker evidence than a fresh session correctly applying the decision it contains.
For example, change a synthetic project rule from “use fixture A” to “use fixture B.” Start a clean session in each intended host. Ask it to name the current rule and its source, then complete the small task. Record failures and interventions. That tests continuity more directly than asking whether an agent “has memory.”
MCP connects the tools; the project defines the meaning.
Model Context Protocol specifies interfaces through which hosts exchange context and call tools. Your application still decides what a memory record means, who can read it, which changes count as accepted and how conflicting records are resolved.
A useful design exposes a narrow read operation first. A write operation should validate the record's shape, enforce scope and retain the source of the proposal. An agent returning a confident statement is evidence of its output, not evidence that the statement is true or that the agent has authority to promote it.
A small record with explicit limits
This is an illustrative record shape, not a Starlight API schema. It shows the information a maintainer needs to judge the record:
{
"id": "decision-example-01",
"kind": "architecture-decision",
"project": "sample-app",
"statement": "Public examples use synthetic input.",
"state": "accepted",
"source": {
"type": "human-decision",
"reference": "sample-project/decisions/01"
},
"owner": "project-maintainer",
"visibility": "project",
"recordedAt": "2026-10-06",
"reviewAfter": "2026-11-06"
}The source reference must resolve inside the real project. The owner must exist. “Accepted” must result from the project's actual review process. The visibility field must be enforced by the reader; writing a label does not create access control.
Test correction, isolation and recovery.
- Correction: supersede a decision and verify that a fresh session uses the current one while retaining the earlier history.
- Isolation: put a distinctive synthetic record in another project and verify that an unauthorized task cannot retrieve it.
- Recovery: interrupt a write or export, resume the process and verify that records are neither lost nor silently duplicated.
- Portability: export the records, reconstruct the usable view in a clean environment and complete the same task.
Record the source revision, host version, inputs, expected result, actual output and repair effort. A successful demonstration is bounded evidence for that configuration. Keep broader compatibility claims tied to a published test matrix.
Where Starlight fits
The Starlight Intelligence System reference repository and Starlight Intelligence Protocol are the public starting points for the project's memory, provenance and responsibility conventions. Memory Studio lets you shape portable context files. Each surface states its own operational boundary.
Start with one project decision and two sessions. Make the continuity, correction and export work. That small result creates a foundation for a larger fleet—and gives the next builder something they can actually check.