memoryledger

memoryledger is an auditable long-term project memory ledger and deterministic AGENTS.md renderer.

AGENTS.md is a generated entry point. Canonical durable memory lives in .ledger/memoryledger/data/; rendered previews live in the resolved Ledgercore artifacts cache mount.

Quick start

memoryledger init
cat <<'EOF' | memoryledger --json memory create --kind rule --title "Use plans" --scope repo --stdin
Always plan before implementation.
EOF
memoryledger --json review accept memory-0001 --reason "User approved project rule."
memoryledger preview
memoryledger --json export

The short alias memledger exposes the same CLI.

New projects use the shared Ledgercore schema-3 manifest at .ledger/ledger.toml, with tool config at .ledger/memoryledger/config.toml and durable records under .ledger/memoryledger/data/. Initialization creates exact data=project and artifacts=cache mounts and binding markers; the artifacts cache is initialized only when a preview is written.

Inspect layout without creating state with:

memoryledger storage where
memoryledger storage validate --strict

Existing legacy projects migrate explicitly and copy-first:

memoryledger --json migrate plan storage-layout --adopt-project-uuid --output .ledger/migrations/storage-layout.json
memoryledger --json migrate apply storage-layout --plan-file .ledger/migrations/storage-layout.json --adopt-project-uuid
memoryledger --json migrate recover storage-layout --journal .ledger/migrations/<migration-id>.toml --policy auto
memoryledger --json migrate cleanup storage-layout --dry-run

Migration preserves the legacy config and data until an explicitly confirmed cleanup. It rejects unsafe files and conflicting project identity or mount registrations, verifies copied regular files with SHA-256, and writes the shared manifest last.

To build or update AGENTS.md, update memory records first, then render and export. Do not edit generated AGENTS.md files directly.

Rendered targets are owned only when configured and marked with <!-- Generated by memoryledger. Do not edit directly. -->. Do not edit those files directly. Files under agent_docs/ without the marker may be manual. Export refuses to overwrite any manual target, including when --backup is passed. Use memoryledger --json agents adopt AGENTS.md for a read-only preview that reports source hash, headings, proposed memories, placement, and root shrink expectations. After user approval, run memoryledger --json agents adopt AGENTS.md --apply --backup --accept --reason "...", then read result.backup and verify with memoryledger --json agents verify-adoption --source "<exact backup path>". Adoption preserves the full original source as generated linked memory and the root links to it.

For multiline or shell-sensitive content, prefer --stdin with a single-quoted heredoc instead of --text. Use memoryledger schema values to list valid kinds, scopes, render targets, statuses, and evidence kinds.

Example:

cat <<'EOF' | memoryledger --json memory create --kind rule --title "Use memoryledger for AGENTS" --scope repo --stdin
Do not edit AGENTS.md directly; update memoryledger records and export.
EOF
memoryledger --json review accept memory-0001 --reason "User approved project memory workflow."
memoryledger --json finalize --accept-all --reason "User approved project memory workflow." --export

Additional intake commands are template list/show/apply/sync/remove, evidence scan, and import run-html. All producer output remains candidate memory until explicit review. Structured evidence is managed with memory evidence list/add. Both memoryledger and memledger expose the same commands.

Storage v2 compatibility reads legacy records, while canonical records live at .ledger/memoryledger/data/memories/memory-NNNN.md with YAML front matter. Legacy sidecar storage can be normalized with memoryledger --json migrate plan storage-v2 --output .ledger/migrations/storage-v2.json and memoryledger --json migrate apply storage-v2 --plan-file .ledger/migrations/storage-v2.json. Generated linked documents now default to agent_docs/; migrate generated files only with memoryledger --json migrate plan linked-docs-dir --output .ledger/migrations/linked-docs-dir.json then memoryledger --json migrate apply linked-docs-dir --plan-file .ledger/migrations/linked-docs-dir.json.