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 memory create --kind rule --title "Use plans" --scope repo --stdin
Always plan before implementation.
EOF
memoryledger review accept memory-0001 --reason "User approved project rule."
memoryledger render --print
memoryledger 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 migrate plan storage-layout
memoryledger migrate apply storage-layout --dry-run
memoryledger migrate recover --journal .ledger/migrations/<migration-id>.toml
memoryledger 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 agents adopt AGENTS.md --json for a read-only preview that reports source hash, headings, proposed memories, placement, and root shrink expectations. After user approval, run memoryledger agents adopt AGENTS.md --apply --backup --accept --reason "...", then verify with memoryledger agents verify-adoption --source AGENTS.md.memoryledger-adopt-1.bak. 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 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 review accept memory-0001 --reason "User approved project memory workflow."
memoryledger finalize --accept-all --reason "User approved project memory workflow." --export

Additional intake commands are templates 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 migrate plan storage-v2 and memoryledger migrate apply storage-v2. Generated linked documents now default to agent_docs/; migrate generated files only with memoryledger migrate plan linked-docs-dir then memoryledger migrate apply linked-docs-dir.