Metadata-Version: 2.4
Name: memoryledger
Version: 0.2.1
Summary: Auditable long-term project memory ledger and AGENTS.md renderer
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Requires-Dist: click
Requires-Dist: ledgercore<0.7.0,>=0.6.0
Requires-Dist: PyYAML
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: sphinx>=7.0.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "dev"
Requires-Dist: myst-parser>=2.0.0; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Dynamic: license-file

# 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

```bash
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:

```bash
memoryledger storage where
memoryledger storage validate --strict
```

Existing legacy projects migrate explicitly and copy-first:

```bash
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:

```bash
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`.
