# Append-only Memory Model

MCP17 adds the maintenance model for long-lived `project.ithz` memory:

```text
Append-only is the audit layer.
Indexes are the working memory layer.
Snapshots are the performance layer.
```

Inside `project.ithz`:

- `events/events.jsonl` stores immutable memory events.
- `indexes/current_index.json` is a deterministic searchable view derived from the events.
- `indexes/search_index.json`, `indexes/gate_index.json`, `indexes/risk_index.json` and `indexes/prompt_summary_index.json` provide focused working views.
- `indexes/memory_synthesis.json` compiles the current working-memory view: recent decisions, gates, risks, must-not-break rules, forbidden claims, next steps and stale/superseded items.
- `claims/claim_log.jsonl`, `claims/blocked_claim_log.jsonl`, `replication/replication_pack_log.jsonl` and `review/reviewer_notes.jsonl` are first-class project ledger projections.
- `indexes/claim_index.json` and `ledger/project_ledger_summary.json` summarize the claim/blocked-claim/replication/reviewer-note ledger view.
- `context-commits/ctx_*.json` and `context-commits/commit_index.json` provide the Git-like memory timeline derived from append-only events.
- `decisions/decision_log.jsonl` is a decision-specific projection.
- `refs/HEAD`, `refs/main` and `branches/main.json` identify the active memory state.
- `snapshots/snapshot_index.json` records available snapshots.
- `snapshots/snapshot_*.json` stores compact point-in-time summaries.

Historical events are not edited. If a decision changes, a later event supersedes or clarifies the earlier event. Derived indexes can be rebuilt from the append-only log, and snapshots speed up future reads without removing audit history.

Commands:

```powershell
python -m ithz_mcp archive-append-event --project . --kind decision --text "Decision: keep the archive writer explicit."
python -m ithz_mcp archive-append-event --project . --kind gate --text "Gate: run-ci-fast passed." --include-git
python -m ithz_mcp archive-memory-index-status --project .
python -m ithz_mcp archive-rebuild-derived-indexes --project .
python -m ithz_mcp archive-compile-memory-synthesis --project .
python -m ithz_mcp archive-create-snapshot --project . --label "after sprint" --mode auto
python -m ithz_mcp ithz-can-i-claim --project . --query "Can I claim this result?"
```

Use `--include-git` when the event should remember the current Git branch, commit hash, short hash, ref names and human-readable commit subject/title. This is read-only Git metadata capture; ITHZ-MCP does not create or alter Git commits.

Safety:

- secret-like event text is blocked before write;
- write lock and archive hash precondition still apply, and lock contention fails quickly with metadata;
- index rebuild does not invent new history;
- snapshots do not replace the append-only audit log, and auto snapshots can be deferred for large archives;
- no Git replacement, cloud-sync or general token-saving claim is made.
