Module memory_record 

AgentMux’s own record of an agent’s memory (SPEC_MEMORY_FOLLOWS_THE_AGENT_2026_09_24.md §2.1.1, phase M3).

An agent’s memory files follow its provider account and working directory — $CLAUDE_CONFIG_DIR/projects/<cwd>/memory — so an account switch or a new working directory used to leave them behind. The record lives in the global transcript store, keyed by the agent’s UID (db_agents.id), and is the source of truth the provider folder is reconciled against.

Zone agent-uid:<uid>:memory:

• log.jsonl — append-only events: a file version (a body by hash, or a tombstone) or a projection (which version a directory holds);
• blob/<sha256> — one file per distinct body, written before the log line that names it, in the same transaction;
• heads.json — per file, the head version; per directory, the version last projected there. Rewritten with every append, so current state is one small read and no tail window has to hold a rarely edited file.

Every write is one zone_txn — a conditional append against the head the caller expects — so srv processes sharing the store never fork a file’s chain. Nothing here touches the provider folder; reconciliation does (phase M3b).

Structs

Head 🔒

A file’s head.

Heads 🔒

ImportedVersion 🔒

A version from the per-channel history tables, to import.

NewVersion 🔒

A version to append.

Version 🔒

Enums

AppendOutcome 🔒

Event 🔒

One line of log.jsonl.

Constants

HEADS_FILE 🔒

LOG_FILE 🔒

MAX_BODY_BYTES 🔒

Same cap as a memory file today (app_api memory write).

Functions

add_history 🔒

Add rows to the agent’s history — no head changes, content the record already has for that file skipped. For versions kept beside a head the caller doesn’t replace (adoption of earlier accounts’ memory, §2.1.4). Returns how many were added.

append_version 🔒

Append a version if the file’s head is still expected_parent.

body 🔒

A body by hash.

heads 🔒

The agent’s current heads, read as one snapshot sized from the database.

held_by_other_records 🔒

Which of shas another agent’s record holds (a blob in its zone).

hold_for_adoption 🔒

Keep files (name, content hash) found in dir_id out of the record, for the adoption list. One transaction.

import_history 🔒

Import the agent’s earlier history, once: every version goes into the log, oldest first and chained per file, keeping its source and time. History only — no head changes, so a file deleted long ago is never written back; heads still come from the folder. A version whose content the record already has for that file is skipped. Returns how many were imported; None if the record already imported its history.

log_history 🔒

Log rows as history-only versions, oldest first and chained per file, skipping content the log already has for that file.

log_line 🔒

mark_conflicts_indexed 🔒

Remember that MEMORY.md has had a line for each of files.

read_heads 🔒

heads.json, or empty when the record has none yet. A file that exists but doesn’t parse is an error — never silently empty, or the next write would replace every head and projection with just its own.

record_projected 🔒

Record that dir_id now holds version of file, if its projection is still expected_previous (None: never projected there). Appended only after the file write it describes succeeded. Returns false, writing nothing, when another srv projected meanwhile — the caller re-reads.

release_held 🔒

Stop holding files in dir_id — a human adopted them (§2.1.4).

reset_projections 🔒

Forget every projection into dir_id: the folder no longer holds what was written there (it was removed or emptied), so each file must read as never projected — to be written back — not as deleted.

set_projected 🔒

Point dir_id’s projection of file at version and log it (the caller writes heads.json, or it is written here when nothing else changes).

sha256_hex 🔒

validate_file 🔒

A memory file name: one path component of safe characters.

validate_sha 🔒

version_shas 🔒

Every version’s content hash (None for a tombstone), by version id — read once, for a caller asking about many versions (a reconcile pass).

write_heads 🔒

zone_for 🔒

agent-uid:<uid>:memory, or None for a UID outside the safe zone-name character set.

zone_or_err 🔒