Module memory_reconcile 

Reconcile an agent’s memory record with the provider folder its spawn is about to use (SPEC_MEMORY_FOLLOWS_THE_AGENT_2026_09_24.md §2.1.3, M3b).

Runs before the provider process starts, so a new account, working directory or channel starts its first session WITH the agent’s memory. Only a directory proven exclusive (memory_dir_claims) is touched.

Per file, comparing disk, the record’s head, and the version last projected into this directory:

• disk equals the head → record the projection, nothing else (rule 0: covers a crash between a write and its record);
• the record changed, disk didn’t → write the head to disk (or, for a deletion, remove the file — only if it still holds what was projected);
• disk changed, the record didn’t → capture it as a new version;
• both changed → conflict: disk’s version becomes the head, marked conflicts_with the record’s, which is written beside it as <stem>__conflict_<short>.md and recorded, so it follows the agent;
• the first time the record meets an exclusive directory, its files are adopted together as the baseline.

Safety rules, each from a data-loss review of the first version:

• A file that can’t be read is left alone — never taken for deleted, and never overwritten. A folder that can’t be listed skips the pass. A folder that doesn’t exist, or holds none of the files projected into it, has its projections forgotten first and is refilled — never tombstoned, even if the refill stops part-way.
• MEMORY.md is reconciled first, and every file is decided against a fresh read of the record, never a snapshot from the start of the pass.
• MEMORY.md is edited (to index a conflict file) only when disk, the head and this directory’s projection all agree on it; otherwise a later pass adds the line.
• A deletion re-reads the file and removes it only if it still holds the projected content, and only in a pass that finished everything else.
• The pass has a time budget; exclusivity that can’t be proven in time counts as shared.
• The folder is the one the CLI really uses: keyed by the repository’s main checkout, not the working directory (crate::backend::claude_layout::memory_project_root). A folder the spawn or a settings file may redirect is left alone.
• Each file is read again when its turn comes, and again right before it is overwritten; a provider write in between wins, and is captured next pass.
• One pass per agent at a time, across AgentMux processes (a lease in the global store); a second one skips.

Structs

Budget 🔒

The pass’s time budget. files_left lets tests stop a pass part-way.

Deletion 🔒

A queued deletion: remove name if it still holds expected_sha.

PassLease 🔒

PendingCapture 🔒

A file the provider changed in dir since it was last projected there, with the head it will be recorded on.

Report 🔒

ShaCache 🔒

Versions’ content hashes for one pass, read from the log once — not once per file, which made a pass quadratic in the log’s length. A version appended during the pass is found by reading it again.

SpawnMemory 🔒

What a spawn’s memory directory is.

Enums

OnDisk 🔒

A memory file as read from disk.

Constants

CAPTURE_SETTLE 🔒

How long a memory file must go unchanged before a capture while the agent runs takes it.

CONFLICT_MARK 🔒

INDEX_FILE 🔒

PASS_LEASE_FILE 🔒

A lease on uid’s reconcile, across every AgentMux process on this machine: two passes for one agent at once — two spawns of it, in one process or two — each act on a view of the folder the other is changing. The second one skips; its spawn goes ahead.

RECONCILE_BUDGET 🔒

The whole pass, before the spawn proceeds without it.

Functions

adopt_baseline 🔒

The first time the record meets this agent’s own exclusive directory: every file in it, index and topics together, becomes the baseline.

capture_while_running 🔒

Record what the provider wrote to dir while the agent runs — the drift detector’s hook (SPEC_MEMORY_FOLLOWS_THE_AGENT_2026_09_24.md §2.1.3). Capture only: nothing is written to the folder. Only a folder a spawn has already reconciled (it holds projections), whose claim uid still holds alone, and only files unchanged for settle (CAPTURE_SETTLE). Returns how many versions were recorded.

conflict_file_name 🔒

<stem>__conflict_<short>.md, the stem cut so the whole name stays within validate_filename’s 200-character stem.

delete_if_unchanged 🔒

Remove a file the record deleted, if it still holds what was projected.

disk_still_holds 🔒

Whether name still holds content sha (None: still absent), read again immediately before overwriting it — the provider may have written it since this pass decided. What it wrote is captured next pass.

held_here 🔒

index_conflict_files 🔒

Index every conflict copy in MEMORY.md — Claude loads only the index, so an unindexed file would never be seen. Only when disk, the head and this directory’s projection all agree on MEMORY.md; otherwise a later pass.

keep_conflict_copy 🔒

Write the other version of a conflicted file beside it and record it, so it follows the agent to its other folders (and a deletion of it, once merged, does too).

pass_zone 🔒

pending_captures 🔒

What capture_while_running would record now: files whose content differs from what was projected here, while the record hasn’t moved on since (the head is still that projection). Files the record changed elsewhere meanwhile are left for the next spawn’s reconcile, which raises the conflict; deletions too, with its missing-folder guards.

projected_version 🔒

read_disk 🔒

The folder’s memory files, or None when the folder doesn’t exist. Any other listing error fails the pass rather than read as “no files”.

read_one 🔒

One memory file as it is on disk now; None when it doesn’t exist.

reconcile_before_spawn 🔒

Reconcile before a spawn. Never fails the spawn: every error is logged and reported as skipped.

reconcile_dir 🔒

reconcile_file 🔒

reconcile_inner 🔒

record_agentmux_write 🔒

An AgentMux write to an agent’s memory — MemoryWrite, the Memory editor, a revert, a bundle import — recorded before the file is written (SPEC_MEMORY_FOLLOWS_THE_AGENT_2026_09_24.md §2.1.1), so the next spawn doesn’t take it for the provider’s, and it follows the agent at once.

record_agentmux_write_in 🔒

record_agentmux_write against fs. Returns whether it was recorded.

release_pass_lease 🔒

run 🔒

settings_override_memory_dir 🔒

Whether a settings file the CLI reads mentions autoMemoryDirectory, which moves its memory folder. Any mention counts, parsed or not. Remote managed settings can’t be seen from here.

spawn_overrides_memory_dir 🔒

Whether a spawn’s environment or arguments may move the CLI’s memory folder away from projects/<root>/memory: an override variable, or a settings file passed on the command line (it could set autoMemoryDirectory).

take_pass_lease 🔒

Take the lease until until; None while another pass holds it.

write_atomic 🔒