Persistent memory for AI coding agents

Persistent memory for an AI coding agent carries decisions, constraints, failed approaches, and project history across separate sessions. It complements repository instructions rather than replacing them. Stable rules belong in version control; evolving observations belong in memory; the current diff and plan belong in the active context.

Why coding agents forget#

Coding sessions are full of details that matter later but do not become code:

• why one database client was chosen;
• which migration failed and under what condition;
• what the team deliberately left out;
• which deployment quirk consumed an afternoon;
• who owns a decision that still needs review.

Compaction or a new session can remove this context. The next agent sees the current files but not the reasoning that shaped them.

Put each kind of context in the right place#

Context	Best home
Build commands and permanent conventions	AGENTS.md, CLAUDE.md, or repository docs
Code and configuration	Version control
Current task plan and tool output	Active context
Decisions, discoveries, and changing constraints	Persistent memory
External product documentation	RAG or direct retrieval

This separation keeps memory from becoming a second, stale README.

What a coding agent should remember#

Decisions with rationale#

“Use port 6543” is useful. “Use port 6543 because the serverless client connects through the transaction pooler” is durable.

Failed approaches#

A failed approach can save more time than a successful one, provided the memory records the conditions and not just the conclusion.

Operational constraints#

Deployment roots, migration order, authentication boundaries, and environment-specific behavior often live outside the type system.

Open threads#

Record what remains uncertain, who must decide, and what evidence would resolve it. Do not convert a question into a fact.

Corrections#

When the user corrects the agent, preserve the correction as a durable rule or decision. Repeated mistakes are often memory failures before they are model failures.

What not to remember#

Do not copy the whole repository into memory. Do not save secrets. Do not store every test log or transient thought. Avoid claims the source code can answer more accurately.

Memory should point back to durable sources where possible: a file, commit, issue, or decision record.

A practical capture pattern#

With OceanDB, a coding agent can write a decision through MCP:

insert into entries (title, content, entry_type, source)
values (
  'Next.js request interception',
  'This project uses proxy.ts under Next 16. Do not add middleware.ts.',
  'decision',
  '{"kind":"repository","ref":"CLAUDE.md"}'::jsonb
);

The write is cheap and append-only. Later, the Dreamer can consolidate related entries into a project page while keeping citations to the originals.

Recall before asking#

The highest-value behavior is simple: check memory before asking the user to repeat a project fact.

A standing instruction can establish the loop:

Before asking for project context that may already exist, recall it.
As you work, remember durable decisions, corrections, and constraints.

OceanDB provides a complete master prompt for this behavior.

Sharing context between coding agents#

Repository files already travel between agents that open the same checkout. Personal preferences and cross-project knowledge do not. A remote MCP memory can serve Claude Code, Cursor, Codex, and other clients from one identity-scoped store.

That makes switching models less costly. The new agent still reads the repository, but it no longer begins with no history of the person or project.

Keep memory reviewable#

Coding agents can act on incorrect context quickly. The memory surface should therefore be inspectable, sourced, and correctable. OceanDB exposes the raw log, maintained pages, links, and review proposals in the dashboard. Human edits become the new truth and are protected from automatic overwrite.

Persistent coding memory is valuable when it removes repeated explanation without becoming a hidden authority. The repository remains the source for code. Memory preserves why the code became what it is.