# ITHZ-MCP

<!-- mcp-name: dev.ithz/ithz-mcp -->

ITHZ-MCP is a standalone local project for ITHZ ContextDB and agent work memory.

Product vision:

```text
Git shares code history.
ITHZ-MCP shares agent work memory.
Markdown is the bootstrap.
ITHZ is the memory zone.
```

An ITHZ file is an Information-Theoretic Hashed Zone for deterministic project memory.

The current project implements a local deterministic context archive first. Later stages add a read-only MCP server, explicit write-back checkpoints, local context timeline, Git metadata integration, team memory sync and a tester package.

ITHZ-MCP does not replace Git. It does not replace a production database. It is not a universal RAG replacement and does not guarantee lower token use for every task.

Current hardening status: MCP8 added a stricter read-only stdio JSON-RPC shim, expanded deterministic beta fixtures, context corruption tests, team sync conflict/redaction checks and an RC2 tester package.

MCP9/MCP10 pivot the project toward a deterministic external memory compiler:

```text
Vector DB retrieves similar chunks.
ITHZ-MCP compiles deterministic project memory.
```

Markdown files are treated as bootstrap and human-readable documentation. Long-term agent work memory belongs in `.ithz-context/`.

MCP11 adds RC4 readiness work: MCP/Codex config templates, scripted stdio client validation, deterministic gate/risk scoring v2, a native ITHZ dogfood query suite v2 and context pack quality regression. External-client coverage is limited to the scripted stdio client unless an actual host is explicitly tested.

MCP12 adds explicit prompt/response memory capture. The default mode is `summary`: it stores deterministic summaries and hashes, not raw prompt/response text. Full raw local storage requires `full-local-only`, remains redaction-gated and is skipped by team sync.

MCP13 introduces the native-archive memory model. New projects can be initialized around one human bootstrap file, `project.md`, and one native archive, `project.ithz`. ITHZ-MCP uses `ithz-native.exe` to pack, safe-verify, read and update logical files in this archive; search and context-pack compilation read from the archive payload. Prompt-memory writes use native batch memory update instead of full restored-tree staging or two separate archive rewrites. The older `.ithz-context` / `.ithz_mcp` sidecars remain compatibility and debug paths, not the target long-term product shape.

Memory-zone discovery is safe by default: the nearest `project.ithz` wins, nested `project.ithz` files are detected as child zones, and parent archives ignore child-zone contents unless `--include-child-zones` is explicitly used. A nested project can still read or write a parent zone with `--memory-zone parent`, or a sibling/manual zone with `--memory-zone-path <dir-or-project.ithz>`. Archive writes take `project.ithz.lock` and check the archive hash before rewriting.

Cross-zone registry handles monorepo and sibling-project work. The active zone can link referenced zones in `zones/linked_zones.json`, record cross-zone task notes in `zones/cross_zone_events.jsonl`, and build a deterministic cross-zone context pack. This keeps the default focused on the nearest project while still supporting tasks that touch a sibling such as `native_ithz`.

MCP17 adds the archive-memory maintenance model:

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

New memory events are appended to `events/events.jsonl`, searchable current state is derived into `indexes/current_index.json`, and compact read snapshots can be created under `snapshots/`. Historical events are not rewritten; corrections are represented by later events. When explicitly requested with `--include-git`, a memory event can store read-only Git metadata, including the current commit subject/title, without staging, committing, pushing, resetting or checking out code.

For team work, `project.ithz` can be tracked by Git with an ITHZ-aware merge driver. `git-diff-ithz` exposes a stable text summary, while `git-merge-ithz` validates base/ours/theirs archives, unions independent append-only memory events, skips private/local-only prompt memory, blocks secret-like payloads, rebuilds derived indexes and writes a merge report. Git remains the transport; ITHZ-MCP does not replace Git.

MCP configs are memory-first by default: the server `initialize` response and generated config metadata tell compatible hosts to call ITHZ-MCP status/context-pack tools before broad codebase reads. The same metadata now includes best-effort ITHZ-MCP SVG icon branding for hosts that support local MCP icons. Hard enforcement requires host tool permissions that do not expose filesystem/shell access before the memory pack is retrieved.

`project.md` is now the bootstrap file for new agent threads. The intended startup order is: read `project.md`, call ITHZ-MCP status, request an archive context pack for the task, then inspect only the candidate files and evidence gaps returned by the pack. Generated MCP configs declare this with `agent_policy.bootstrap_file=project.md`.

MCP18 adds the missing end-of-task contract. Existing workflow docs or user-provided project rules can be mined into `project.ithz` with `archive-ingest-project-memory`, and completed tasks can be saved with `archive-finalize-task`. The write path is explicit: read-only MCP configs do not expose these tools, while a separate write-enabled profile can append sanitized decisions, gates, risks, next steps, prompt summaries and snapshots into the archive.

MCP19 adds workflow branch profiles. A new or existing project can be adopted with `archive-adopt-project-workflow`: it creates or validates `project.md`, creates `project.ithz` if needed, mines existing Markdown docs and an onboarding prompt, and stores the result under `workflows/profiles/<profile>.json` inside the archive. Different developers can keep separate profiles, and the ITHZ-aware merge driver auto-merges independent profiles while flagging same-profile divergence as `merge_needed`.

MCP20 adds optional agent-history import. During adoption, ITHZ-MCP can discover local Codex/Claude/Cursor/Antigravity-style history records that mention the active project, summarize prompt/response pairs, redact secret-like content and import those summaries into `project.ithz`. If a teammate already committed `project.ithz`, the importer appends your summaries to that same archive with author/time provenance instead of replacing it. Discovery is dry-run by default; writing requires explicit `--apply` or `--import-agent-history` during workflow adoption.

MCP21 adds production-readiness packaging and scenario tests. It validates fresh, adopted and shared project workflows; generates host installer bundles for Codex, Claude Code, Cursor, Antigravity and generic JSON-RPC clients; and creates `dist/ithz_mcp-v0.1-product-candidate`.

MCP22 adds automatic native checkpoints for write-enabled MCP hosts. The read-only profile remains write-free. The separate write-enabled profile exposes `ithz_archive_auto_checkpoint` and instructs compatible hosts to call it at the end of completed tasks, writing sanitized task memory natively into `project.ithz`.

MCP23 adds the one-command project installer, project uninstall flow and compact native archive indexes. `install-project` intentionally treats the current directory as the project root even when the Git root is higher in a monorepo. Native archive builds now default to `compact-v2`, which stores deterministic file summaries and high-signal decision/gate/risk/symbol evidence instead of duplicating every ordinary source line in `index.json` and `context_units.jsonl`. Source file snapshots are not stored by default; `project.ithz` is the memory zone, not a project backup. Installer scratch files are kept under `.ithz-install/tmp/` and removed after successful install unless `--keep-install-artifacts` is explicitly used.

First install also runs project intake. With `--agent-intake auto`, ITHZ-MCP builds a bounded repo dossier first: project scale, directory map, high-signal docs/configs/source files and short redacted excerpts. Codex CLI then runs in read-only mode and is prompted to select the important files or sections from that dossier before writing only durable summaries: workflow, decisions, gates, risks, candidate files, next steps and evidence gaps into `project.ithz`. If Codex CLI is unavailable, the installer records a deterministic fallback and `ithz_mcp.md` tells the host agent to complete intake explicitly in the current thread. Raw secrets remain blocked and source snapshots remain off by default.

`install_ithz.md` is the recommended one-file agent bootstrap installer document. It can be copied into a teammate's project and used as the single instruction file for a local agent: install from a trusted package, initialize the current directory, preserve an existing `project.ithz`, append this user's redacted prompt/workflow memory, configure MCP/Git drivers and report the result. It includes OS-specific defaults so macOS agents do not stop for an A/B/C/D question when native `ithz-native` is missing; they install the supported MCP/Git/Drive subset and report the native-binary gap. The older `ithz_mcp.md` remains included as a fuller reference.

MCP24 adds durable instruction capture. When a user gives a lasting project rule during a task, such as commit/deploy workflow, validation gates, project decisions or must-not-break rules, write-enabled hosts can store it explicitly in `project.ithz` with typed tools instead of leaving it only in the chat. These records live under `instructions/` and are mirrored into append-only events for search and context packs.

Native executable selection is automatic unless overridden: `--native-exe` and `ITHZ_NATIVE_EXE` win first, otherwise ITHZ-MCP checks runtime AVX2 support and chooses the AVX2 binary only when supported, falling back to scalar when bundled.

macOS MCP support is packaged through Python stdio: `ithz_mcp_server.sh`, POSIX host installers and scripted client smoke are included in the product candidate zip. Native `project.ithz` storage on macOS still requires a macOS `ithz-native` binary; otherwise macOS host configs use legacy storage. The safe default is partial install without prompting: host config, `*.ithz` Git diff/merge driver, ITHZ Drive/open-temp fallback if present, and a native-binary gap report.

MCP28 adds a dedicated Ubuntu/Linux package path: `dist/ithz-mcp-ubuntu.tar.gz` for user-local install and `dist/ithz-mcp-ubuntu.deb` for Debian-package install. These packages run the Python stdio MCP server, include Linux host installers, include a Linux `ithz-native` source build kit, and provide extraction-backed fallback commands (`ithz-verify`, `ithz-list`, `ithz-extract-here`, `ithz-open-temp`). They default to legacy storage unless a compatible Linux `ithz-native` binary is supplied or built on the Ubuntu host. Full Linux Drive/FUSE support is not bundled yet.

MCP26 adds deterministic current-memory synthesis and safer archive maintenance. `indexes/memory_synthesis.json` compiles the append-only history into a current working view of decisions, gates, risks, must-not-break rules, forbidden claims, next steps and stale/superseded items. Archive write locks now fail quickly with lock metadata instead of long silent waits, and `archive-finalize-task --snapshot` uses auto snapshot policy: small archives can snapshot immediately, while large archives defer the snapshot and still record the checkpoint. MCP26 Unicode hardening sanitizes invalid lone surrogate characters before JSON-RPC serialization, event hashing and archive JSONL writes. MCP write tool responses are compact for stricter hosts, and large memory zones use automatic queued checkpoint finalization so the host gets a quick standard MCP response while the native `project.ithz` write completes in a background worker.

MCP27 adds `project_ledger_v1`: first-class claim, blocked-claim, replication-pack and reviewer-note projections inside `project.ithz`. The project ledger turns memory into an append-only audit book for AI-assisted work: decisions, gates, risks, scoped claims, blocked claims, checkpoints, replication packs and reviewer guidance are searchable and bounded through MCP. The read-only profile can answer `ithz_can_i_claim`; the write-enabled profile can add claims, block claims, record reviewer notes and create replication-pack records. Windows native archive subprocesses now run with `CREATE_NO_WINDOW`, so MCP writes should not open a visible console window.

## User Documentation

- [Installation Guide](docs/INSTALLATION_GUIDE.md)
- [User Guide](docs/USER_GUIDE.md)
- [Používateľský manuál: ITHZ-MCP](docs/USER_MANUAL_ITHZ_MCP_SK.md)
- [Používateľský manuál: ITHZ Invariant Diff](docs/USER_MANUAL_ITHZ_DIFF_SK.md)
- [Marketing one-pager: ITHZ-MCP](docs/MARKETING_ONE_PAGER_ITHZ_MCP_SK.md)
- [Automatic Native Checkpoints](docs/AUTOMATIC_CHECKPOINTS.md)
- [Durable Instruction Memory](docs/DURABLE_INSTRUCTION_MEMORY.md)
- [Project Ledger](docs/PROJECT_LEDGER.md)
- [ITHZ Invariant Diff](docs/INVARIANT_DIFF.md)
- [Host Installation](docs/HOST_INSTALLATION.md)
- [macOS MCP Setup](docs/MACOS_MCP_SETUP.md)
- [Production Readiness](docs/PRODUCTION_READINESS.md)
- [Safety Model](docs/SAFETY_MODEL.md)
- [Limitations](docs/LIMITATIONS.md)

## Quick Smoke

```powershell
python -m ithz_mcp version
python -m ithz_mcp self-test --verbose
python -m ithz_mcp run-ci-fast
python -m ithz_mcp run-mcp8-hardening
python -m ithz_mcp run-mcp9f-native-ithz
python -m ithz_mcp run-mcp10-markdown-minimal
python -m ithz_mcp run-context-quality-regression
python -m ithz_mcp run-mcp11-external-client
python -m ithz_mcp run-mcp12-prompt-memory
python -m ithz_mcp run-mcp13-host-compat
python -m ithz_mcp run-mcp21-production-readiness
python -m ithz_mcp run-mcp22-auto-checkpoint
python -m ithz_mcp run-mcp23-install-project
python -m ithz_mcp run-mcp24-durable-instructions
python -m ithz_mcp run-mcp25-macos-package
python -m ithz_mcp run-mcp26-memory-synthesis
python -m ithz_mcp run-mcp27-project-ledger
```

