A useful memory system needs to explain more than what a record says now. It needs to preserve how the record changed, and prevent an outdated edit from silently replacing a newer decision.

Consider a fictional architecture note loaded by two readers at version 1. One changes the deployment procedure and saves version 2. The other submits an edit based on the original note. If that second write silently succeeds, the first change can disappear from the current record.

Revision history and stale-write protection address different parts of this problem. History preserves earlier states for inspection. A version precondition can reject a change based on an outdated state before it overwrites the current one.

This article examines both mechanisms in the accepted MB-001 foundation of METABOLIQ Brain, scoped to one owner on a trusted local machine. It also describes a specific difference between updates and archiving that limits how broadly we can state the guarantee.

Current state and history serve different purposes

Brain stores a current memory record and separate revision snapshots. Creating a memory produces version 1 and its initial snapshot. Successful updates and archiving advance the version and preserve another snapshot.

Snapshots include the title, content, memory type, status, visibility and sensitivity labels, tags, source fields and validity dates. Revision metadata records the memory identifier, version, change type, actor and time. They capture the configured memory fields; they are not a copy of every database table or every part of an agent's execution.

A revision is a saved state rather than a textual diff. An owner can compare earlier snapshots to understand what changed. Content, metadata and status changes can all produce revisions; changing a record's status can advance its version even when its prose stays the same.

History is owner-only in this foundation. Preserving it does not grant agents access to old content that may have been corrected or restricted. The access behavior of proposed agent edits is examined in Article 002.

An expected version is a precondition

Memory updates require the version the client last saw. The service locks the current record for the update and compares that stored version with the submitted value.

Two edits based on the same fictional starting version
ActionExpected versionResult
First writer saves a change1Success; current version becomes 2
Second writer submits an older edit1Conflict; current version stays 2
Second writer reloads and submits a considered change2Eligible for validation as a new update

A stale update returns HTTP 409 with a version-conflict error. The client needs to reload and decide how to reconcile its intention with the newer record. The service does not automatically merge the competing text.

The precondition does not establish that an edit is sensible. A client that reloads and submits a destructive replacement with the current version may still satisfy the version check. Authorization, field validation and content review remain separate concerns.

Testing a real write race

A sequential conflict test is useful, but it does not exercise two database sessions competing for the same row. For this article, we added a controlled two-writer check against PostgreSQL.

The first writer changed the memory and paused before committing, while retaining its row lock. A second writer attempted an update using the same original version. An observer connection confirmed that the second database session was waiting on a lock.

After the first writer was released and committed, the second writer encountered a version conflict. The current record contained the first writer's text at version 2. History contained versions 1 and 2, with no snapshot of the rejected competing text and one successful update audit event.

We repeated this controlled scenario three times. That supports the specific lock-and-version behavior exercised here. It is not a throughput benchmark, a stress test across arbitrary schedules or a claim that all concurrency problems are solved.

Commit the change and its evidence together

Saving a memory while losing its revision or successful mutation audit event would leave an incomplete explanation of the change. In the accepted create, update and archive service paths, these writes share one database transaction.

We tested that boundary by injecting failures when the service attempted to insert either a revision row or an audit row. We exercised both failure points for creation, updating and archiving: six cases in total.

Each injected failure rolled back the mutation. Failed creation left no new memory behind. Failed updates and archives left the original record at version 1 with its original content and active status. The counts of memory, revision and audit rows were unchanged.

These were controlled test failures in an isolated database. They support the transaction claim; they do not substitute for crash-recovery, disk-failure, backup or restore testing.

Rejected stale, invalid and no-change updates also left the version and revision history unchanged in our focused checks. This does not mean every rejected request is absent from the audit log: access denials have a separate audit path designed to preserve denial evidence.

Archiving has a different precondition

Archiving preserves content and history while marking the current memory archived. The owner can still inspect that record and its revisions. Agents cannot retrieve it through direct lookup, listings or full-text search, and subsequent edits are rejected.

There is an important qualification: the archive endpoint accepts an optional version. If the owner supplies one, a stale value is rejected. If the owner omits it, the service archives the current record without checking the version the owner previously saw.

We exercised both paths after advancing a record to version 2. An archive request carrying version 1 failed. A request carrying version 2 succeeded. In a separate case, an archive request with no version also succeeded and produced version 3.

A row lock serializes the operation, but it cannot supply a missing client precondition. The precise claim is therefore that updates require expected-version protection, while archive requests use it when a version is provided.

Archiving is also not deletion or erasure. Earlier content remains stored, which matters when deciding what information belongs in a persistent vault.

Append-only is a bounded guarantee

Database triggers reject ordinary update, delete and truncate attempts against revision and audit tables. Existing regressions exercised update and delete protections; our focused checks also verified truncate rejection for both tables.

Those protections help prevent ordinary application operations from rewriting history. They do not create an external tamper-evident log. A sufficiently privileged database operator remains outside that guarantee.

Actor attribution records which authenticated owner or agent credential made a change. It does not prove which human controlled that credential, independently validate the content, or show that the recorded decision was correct.

An owner-visible history is useful evidence of stored changes. It is not factual verification.

What we verified—and what remains

We ran 84 existing backend regressions covering updates, agent authorization, credential lifecycle, sensitivity restrictions and the route access matrix. All passed. We also ran 15 focused editorial verification cases; all passed.

The additional cases covered six injected transaction failures, three controlled concurrent-write scenarios, content/metadata/status snapshots, rejected-update history stability, versioned and unversioned archiving, and truncate protections.

Testing used Python 3.12 and PostgreSQL 17 with fictional records in a separate accepted-source snapshot. API test-client checks were combined with direct service and database checks for failure injection and lock contention. The active Brain development checkout and existing memory databases were not modified.

This was targeted verification, not a full Brain acceptance run or production security assessment. Newer retrieval experiments are outside this article's scope.

The accepted operating scope remains one owner on a trusted local machine. TLS and tested backup and restore procedures are separate requirements for wider or valuable-data use. Revision snapshots in the same database cannot replace a recovery plan if that database is lost.

The engineering lesson

History and stale-write protection complement one another. Snapshots preserve earlier states; a version precondition can stop an outdated update before it replaces the current state. A transaction keeps the successful change and its recorded evidence together.

The useful guarantee is the one we can state precisely: which operations require a version, which writes commit together, who can inspect history and which failures the tests actually exercised.

A memory's latest edit should remain explainable. Building that property requires both preserving the past and being explicit about when a new write is allowed to replace the present.

← All engineering articles