| name | dynamic-memory-cli |
| description | Operate a dynamic, UT-backed agent memory with atomic Pending publication, merged Pending/Built search, Memory Snapshot and history cursor state, Built-only validation, and exact-content migration. Use when an agent Harness must extract memory asynchronously while foreground work continues, publish immediately searchable Pending UTs, build them into a stable index, or inspect and recover an eternal-conversation memory project. |
Dynamic Memory CLI
Use scripts/dynamic_memory_cli.py as the deterministic boundary between a conversation Harness and its memory state. Keep semantic selection in the extraction Agent; keep validation, revisions, cursors, publication, search, and migration in this CLI.
Required workflow
- Run
init --path <session-memory-dir> once.
- Let the extraction Agent read the old Snapshot, frozen Working Memory, published UTs, and Raw History evidence.
- Submit one proposal with
publish-pending --file <proposal.json>. Never expose an Agent's scratch buffer directly.
- Use
search immediately. Published Pending UTs participate through lexical matching and are marked pending in results.
- Run
freeze-pending --output <batch.json> for a stable exact-content batch.
- Let the builder Agent review that batch, then run
build-pending --file <batch.json>.
- Treat a successful build as an atomic representation migration. It does not advance semantic memory revision, Snapshot revision, or history cursor.
Read references/dynamic-memory-contract.md before creating proposals or integrating a Harness.
Command contract
Run from the memory project directory unless init --path is used:
python scripts/dynamic_memory_cli.py init --path <dir>
python scripts/dynamic_memory_cli.py search <query> [query...]
python scripts/dynamic_memory_cli.py list [--full]
python scripts/dynamic_memory_cli.py show <id>
python scripts/dynamic_memory_cli.py check-conflicts --file <candidate.json>
python scripts/dynamic_memory_cli.py add --file <ut.json> [--force]
python scripts/dynamic_memory_cli.py update <id> --file <updates.json>
python scripts/dynamic_memory_cli.py retire <id> [--reason <text>]
python scripts/dynamic_memory_cli.py get-state
python scripts/dynamic_memory_cli.py publish-pending --file <proposal.json>
python scripts/dynamic_memory_cli.py freeze-pending --output <batch.json>
python scripts/dynamic_memory_cli.py build-pending --file <batch.json>
python scripts/dynamic_memory_cli.py test [--built-only]
python scripts/dynamic_memory_cli.py bench
Use the global --root <session-memory-dir> option before the subcommand when the caller cannot change its working directory.
Do not edit memory.sqlite3 manually. Preserve stable UT IDs. Modifying a Built UT must republish it as Pending. Do not advance a cursor unless Snapshot and UT changes are committed in the same publish-pending transaction.
Agent boundaries
- Extraction Agent: decide what to remember, resolve semantic conflicts, author UTs, and produce Snapshot content.
- Builder Agent: review a frozen Pending batch and request deterministic construction and Built-only validation.
- Harness: verify identity/range/version inputs and invoke atomic commands.
- CLI: enforce schemas, continuity, exact-content comparison, transactions, search merging, and test gates.
Save each foreground, extractor, and builder transcript outside the database in the session's Raw History or agent-history area. Store evidence references on every changed UT and on empty-UT proposals.
