# Native Archive Memory

MCP13 adds an explicit native archive memory workflow.

Definition:

```text
An ITHZ file is an Information-Theoretic Hashed Zone for deterministic project memory.
Markdown is the bootstrap. ITHZ is the memory zone.
```

Slovensky:

```text
ITHZ subor je Informacno-Teoreticka Hashovana Zona pre deterministicku projektovu pamat.
Markdown je bootstrap. ITHZ je pamatova zona.
```

Target repository shape:

- `project.md`: small human bootstrap manifest.
- `project.ithz`: native ITHZ archive containing project memory, index data, prompt summaries, decisions, gates and selected source snapshot metadata.

New thread bootstrap:

```text
read project.md
ask ITHZ-MCP for status
ask ITHZ-MCP for a context pack
read selected source files only after the pack identifies them
```

Generated MCP configs carry this as `agent_policy.memory_first=true` with `agent_policy.bootstrap_file=project.md`. Hosts that support staged tool permissions should expose ITHZ-MCP read tools first and broad filesystem/codebase tools only after the context pack step.

The extension is `.ithz`. If a prompt says `.ihtz`, treat that as a typo unless the user explicitly asks for a different extension.

The archive is built and verified through `ithz-native.exe`:

```powershell
python -m ithz_mcp init-native-archive-memory --project C:\path\to\project
python -m ithz_mcp archive-memory-status --project C:\path\to\project
python -m ithz_mcp archive-search-context --project C:\path\to\project --query "gates risks"
python -m ithz_mcp archive-get-context-pack --project C:\path\to\project --query "next task" --out native_pack.md
```

Context-pack layout is intentionally evidence-first:

1. selected evidence rows;
2. candidate files;
3. evidence gaps, including uncovered specific query terms;
4. task-relevant current-memory synthesis.

This keeps small packs useful for agents. If the archive does not contain enough evidence for a query, the pack should say that clearly and direct the agent to inspect candidate files instead of treating broad memory as authoritative.

Memory-zone discovery:

- Default discovery is `nearest`: starting at `--project`, ITHZ-MCP walks upward and uses the nearest `project.ithz`.
- `archive-memory-status` reports `active_memory_zone`, plus detected `parent_zones`, `child_zones` and `sibling_zones`.
- Nested `project.ithz` files are child memory zones. A parent archive ignores child-zone contents by default.
- Child-zone discovery is bounded for large repositories. The default scan cap is `ITHZ_MCP_CHILD_ZONE_SCAN_MAX_DIRS=1500`; raise it only for projects that intentionally contain many nested memory zones.
- Use `init-native-archive-memory --include-child-zones` only when a parent archive must intentionally snapshot child-zone contents.
- Use `--memory-zone parent` from a nested project to read or write the parent `project.ithz`.
- Use `--memory-zone-path <dir-or-project.ithz>` to read or write an explicit parent, sibling or manually selected memory zone.

Examples:

```powershell
# Work in the nearest nested memory zone.
python -m ithz_mcp archive-search-context --project C:\repo\subproject --query "next gate"

# Search the parent zone while currently inside a subproject.
python -m ithz_mcp archive-search-context --project C:\repo\subproject --memory-zone parent --query "repo decision"

# Search a sibling project zone explicitly.
python -m ithz_mcp archive-get-context-pack --project C:\repo\subproject --memory-zone-path C:\repo\sibling --query "shared api" --out sibling_pack.md
```

Cross-zone registry:

```powershell
python -m ithz_mcp archive-link-zone --project C:\work\ITHKOR\ithz_mcp --zone native_ithz --path C:\work\ITHKOR\native_ithz
python -m ithz_mcp archive-zone-status --project C:\work\ITHKOR\ithz_mcp
python -m ithz_mcp archive-cross-zone-context-pack --project C:\work\ITHKOR\ithz_mcp --query "native update-files API" --out cross_zone_pack.md
python -m ithz_mcp archive-record-cross-zone-event --project C:\work\ITHKOR\ithz_mcp --target-zone native_ithz --event "MCP task referenced sibling native_ithz transport changes."
```

- Linked zones are stored inside the active archive as `zones/linked_zones.json`.
- Cross-zone task notes are stored inside the active archive as `zones/cross_zone_events.jsonl`.
- This models a task with one active zone and one or more referenced zones, such as `ithz_mcp` work that also changes sibling `native_ithz`.
- Read access can be combined into a deterministic cross-zone context pack.
- Write access to any parent or sibling zone remains explicit through `--memory-zone parent` or `--memory-zone-path`.

Append/index/snapshot model:

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

Logical files:

- `events/events.jsonl`: append-only memory events.
- `indexes/current_index.json`: deterministic current searchable view derived from events.
- `indexes/search_index.json`: broad deterministic search projection.
- `indexes/gate_index.json`: gate/test evidence projection.
- `indexes/risk_index.json`: risk and must-not-break projection.
- `indexes/prompt_summary_index.json`: prompt/response summary projection.
- `indexes/memory_synthesis.json`: deterministic current working-memory synthesis for decisions, gates, risks, forbidden claims, next steps and stale/superseded items.
- `claims/claim_log.jsonl`: scoped allowed claim projection.
- `claims/blocked_claim_log.jsonl`: blocked claim projection with reasons and blocking gates.
- `replication/replication_pack_log.jsonl`: replication pack ledger records.
- `review/reviewer_notes.jsonl`: reviewer guidance linked to phases, files or claims.
- `ledger/project_ledger_summary.json` and `indexes/claim_index.json`: current project-ledger summary and claim lookup.
- `context-commits/ctx_*.json` and `context-commits/commit_index.json`: derived context timeline.
- `decisions/decision_log.jsonl`: decision projection.
- `refs/HEAD`, `refs/main` and `branches/main.json`: active memory state.
- `snapshots/snapshot_index.json`: list of compact snapshots.
- `snapshots/snapshot_*.json`: point-in-time compact memory summaries.

Commands:

```powershell
python -m ithz_mcp archive-append-event --project C:\path\to\project --kind decision --text "Decision: keep p9-v4 experimental."
python -m ithz_mcp archive-append-event --project C:\path\to\project --kind gate --text "Gate: package smoke passed." --include-git
python -m ithz_mcp archive-memory-index-status --project C:\path\to\project
python -m ithz_mcp archive-rebuild-derived-indexes --project C:\path\to\project
python -m ithz_mcp archive-compile-memory-synthesis --project C:\path\to\project
python -m ithz_mcp archive-create-snapshot --project C:\path\to\project --label "after sprint" --mode auto
```

Historical events are immutable. If a decision changes, add a new event rather than editing an old one. The current working memory is the deterministic index and synthesis layer derived from the append-only history. Search and context packs include these derived layers, so appended gates/risks/decisions and stale/superseded notes are searchable. With `--include-git`, the event also stores read-only Git metadata including the current commit subject/title, and that metadata is included in the derived search index.

Context-pack retrieval:

- Selected evidence is emitted before broad current-memory synthesis so small packs remain useful.
- File-navigation queries such as “which files should I inspect before changing scoring” prefer concrete source file summaries and suppress broad synthesis.
- Compound query terms such as `native_archive` and `context_pack` are derived deterministically from short user queries.
- Platform-sensitive queries avoid ranking opposite-platform installer evidence first, for example Ubuntu/Linux queries should not start from Windows shell files unless no better evidence exists.

Native executable selection:

- `--native-exe <path>` wins when a command exposes it.
- `ITHZ_NATIVE_EXE=<path>` wins next.
- Otherwise ITHZ-MCP detects AVX2 support at runtime and selects the AVX2 binary only when supported.
- If AVX2 is not supported and `native/ithz-native-scalar.exe` exists, scalar is selected.
- `archive-memory-status` reports `native_selected_build`, `native_selection_reason`, `native_cpu_avx2_supported`, `native_exe` and `native_version`.

Prompt/response capture can update logical files inside the archive:

```powershell
python -m ithz_mcp archive-record-prompt-response --project C:\path\to\project --prompt prompt.md --response response.md --task "task label" --mode summary
```

Project workflow intake and end-of-task checkpoints:

```powershell
python -m ithz_mcp archive-ingest-project-memory --project C:\path\to\project --source AI_PROJECT_BRIEF.md --source WORKFLOW_RULES.md --source DECISIONS_LOG.md
python -m ithz_mcp archive-finalize-task --project C:\path\to\project --task "task label" --summary task_summary.md --docs-impact updated --memory-impact handoff-created --snapshot --snapshot-mode auto
python -m ithz_mcp ithz-can-i-claim --project C:\path\to\project --query "ITHKOR proves gravity?"
```

- Intake mines durable workflow, decision, gate, deployment and risk facts from project docs.
- End-of-task checkpoints append a summary, decisions, gates, risks, next steps, documentation impact and memory impact.
- Read-only MCP profiles do not expose these write tools. Use an explicit write-enabled profile for checkpointing.
- Project ledger write tools are also explicit write-enabled operations. Read-only profiles can inspect claims and call `ithz_can_i_claim`.

Safety rules:

- `project.ithz` is the preferred project-memory data source.
- `project.md` stays short and human readable.
- Secrets, `.env`, private keys, binaries, build outputs and existing `.ithz` files are excluded from the source snapshot.
- Raw prompt/response capture remains explicit and redaction-gated.
- ITHZ-MCP still does not replace Git, a production database or cloud sync.
- For MCP host configs, prefer `--storage-profile native-archive`; this exposes archive-backed tools for `project.ithz` instead of the legacy sidecar profile.
- Prompt-memory writes use the native `--update-files` batch API: existing archive files are decoded to memory once, `prompts/prompt_log.jsonl` and `manifest.json` are replaced together, and the archive is safely rewritten once. This avoids full restored-tree staging on disk and avoids two separate archive rewrites.
- Writes to `project.ithz` acquire `project.ithz.lock` and check the archive hash precondition before rewriting. Lock contention fails quickly with PID/phase metadata; if another host changes the archive between read and write, the append path retries once from the fresh archive state or fails instead of silently overwriting it.

Compatibility:

- Existing `.ithz-context` and `.ithz_mcp` stores remain readable.
- MCP13 does not delete or migrate existing Markdown files automatically.
- Native archive read/search loads `manifest.json`, `index.json` and `scan.json` through `ithz-native --extract-file ... --output -`, so normal search avoids full restored-tree disk extraction.
- Native prompt-memory writes now update `prompts/prompt_log.jsonl` and `manifest.json` through `ithz-native --update-files ... --input -`. The archive is still rewritten as a whole file; this is not yet an in-place or zero-copy database engine.
