Module memory_archive 

Multi-store, lossless memory archive (#995 Phase 1).

Every memory store — facts, history, patterns — archives the items it evicts here before dropping them, so capacity management is never lossy and anything reclaimed can be restored. This is the single archive subsystem behind the memory-capacity module and the recall-miss rehydrate path.

On-disk layout

• Facts live under memory/archive/facts/<project hash>/archive-*.json; the partition is always the request project’s. Releases before 3.11.5 kept unprotected facts in one installation-wide memory/archive/archive-*.json without a provable project: those files are left in place, unread, and are never listed, rehydrated or restored into any project.
• Every other store lives under memory/archive/<store>/<scope>/archive-*.json, where <scope> is the per-project hash so a restore lands in the right project.

Format

A single envelope (ArchiveEnvelope) is used for all stores. The item collection serializes as items; the facts alias keeps legacy facts archives (which used that key) deserializable.

Structs

ArchiveConfig

Tunable archive bounds. rehydrate_reach is how many of the newest archives the recall-miss path scans; it defaults to max_files so every retained archive is actually reachable (closing the pre-#995 16-retained / 4-reachable gap). Both are overridable via env for ops tuning.

ArchiveEnvelope

Unified archive envelope for reading every store. The collection is keyed items; the facts alias keeps legacy facts archives (which used that key) deserializable.

Enums

MemoryStore

Which memory store an archive belongs to. Drives the on-disk path only — the archive is generic over the item type, so this stays decoupled from the concrete fact/insight/pattern structs.

Constants

RETIRED_PROCEDURES_STORE_NOTICE

Reply to a restore that names store=procedures: that archive belonged to the procedure memory retired in 3.13.0 (DEPRECATIONS.toml mcp-ctx-session-episodes-procedures). Nothing is restored; archived procedure files stay on disk untouched.

Functions

adopt_legacy_facts

Copy legacy archived facts into the facts partition of project_root (an explicit, canonical root) through the admission of a normal facts archive write. Each fact is admitted on its own; the admitted ones are archived together. Returns one flag per fact: true adopted, false withheld. A fact the partition already holds is not archived again, so a rerun after an interrupted adoption (copied, not yet journaled) leaves exactly one copy.

archive_items

Archive items for store/scope, then prune the directory to cfg.max_files newest. Returns the written path, or None when there was nothing to archive. Ordering must be inspectable before writing; removal of old files remains best-effort.

legacy_facts_archives

The installation-wide facts archives of releases before 3.11.5, as (path, envelope). They are served to no project; only the explicit lean-ctx migrate legacy-context adoption reads them.

list_archives

All archive files for store/scope, sorted by their recorded archive time. Uninspectable files remain listed, but prevent retention from deleting files.

orphaned_facts_archives

Facts archives left in a partition that is no longer the current one of the root they recorded: that project’s identity (remote, package name) changed since. Served to no project until adopted.

reachable_archives

The newest cfg.rehydrate_reach archives for store/scope — the set a recall miss should scan. Aligned with retention so nothing retained is unreachable.

restore_items

Restore the items from a single archive file.

restore_knowledge_items