ITHZ-MCP

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

Product vision:

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:

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:

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
• User Guide
• Používateľský manuál: ITHZ-MCP
• Používateľský manuál: ITHZ Invariant Diff
• Marketing one-pager: ITHZ-MCP
• Automatic Native Checkpoints
• Durable Instruction Memory
• Project Ledger
• ITHZ Invariant Diff
• Host Installation
• macOS MCP Setup
• Production Readiness
• Safety Model
• Limitations

Quick Smoke

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