Correcting memory atoms: versioned updates instead of duplicate saves

The problem with “save again”

Agents that only know memory_save_atom tend to duplicate facts when a retrieved atom is slightly wrong: billing day changed, a bug fix superseded an old root cause, a decision was reversed. Search then returns two conflicting atoms and the model has to guess which one is current.

Correction keeps one atom id, updates the body in place, and archives the previous revision. Retrieval stays anchored to a single canonical record instead of a pile of near-duplicates.

Version field and optimistic concurrency

Every atom now carries a monotonic version counter (starts at 1). It is stored in YAML frontmatter and archive metadata.json. Legacy atoms without the field are treated as version 1.

When correcting, pass expectedVersion from search or list_atoms. If another writer bumped the version first, the API returns 409 version_conflict with actualVersion — re-fetch and retry. Omit expectedVersion only when you accept last-write-wins.

REST: PATCH an atom

Authenticated writes use PATCH /api/v1/memory/atoms/{atomId} with memoryLibraryId in the query string. Body fields: • document — full corrected markdown body • expectedVersion — optional optimistic lock • scope / topic / tags — optional metadata updates

A successful response includes corrected: true and atom.version incremented. The engine re-embeds the staging vector so L3 search reflects the new text without a separate re-ingest job.

MCP: memory_correct_atom

IDE agents should call memory_correct_atom with the same fields: memoryLibraryId, atomId, document, and expectedVersion when available. It requires memory:write, like memory_save_atom.

Workflow: memory_search or memory_recall → identify outdated hit → memory_correct_atom with the fixed body. Do not memory_save_atom a second atom on the same fact unless you intentionally want parallel notes.

Per-library auto-correct policy

In the dashboard, open a library’s settings and enable “MCP auto-correct.” When that library is the MCP default, the server injects a CORRECT MEMORY POLICY into agent instructions: proactively fix outdated atoms during the session instead of duplicating them.

memory_list_libraries exposes autoCorrectEnabled per library so agents can check policy even without a team default. Team-level save policy (proactive / session_end / off) is unchanged — correction is a separate, library-scoped toggle.

Where revisions are stored

Before bumping version, the prior body is archived under the atom folder at revisions/v{N}.md and revisions/v{N}.json. The live markdown and metadata.json remain the source of truth for retrieval; revisions are for audit and rollback review, not separate search hits.

Contract version

REST, MCP, and the published engra-memory Skill ship at integration version 1.4.0 for async write defaults (MCP 1.4.0). Query GET /api/v1/memory/version for api / mcp / skill / engine pins in your CI.