# ITHZ-MCP User Guide

ITHZ-MCP is deterministic project memory for AI agents.

Core sentence:

```text
Markdown is the bootstrap. ITHZ is the memory zone.
```

Slovak:

```text
Markdown je bootstrap. ITHZ je pamäťová zóna.
```

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

## What ITHZ-MCP Stores

`project.ithz` stores project-relevant agent memory:

- workflow profiles;
- decisions and reasons;
- gates and test results;
- risks and must-not-break rules;
- next steps;
- prompt/response summaries;
- context commits;
- Git metadata when explicitly requested;
- derived search indexes and snapshots.

It does not store secrets by default and does not automatically store raw full chat history.

## The Two-File Model

A normal project should have:

```text
project.md
project.ithz
```

`project.md` is small and human-readable. It tells agents how to start:

1. Read `project.md`.
2. Ask ITHZ-MCP for status.
3. Ask ITHZ-MCP for a context pack.
4. Read only the candidate files and evidence gaps.
5. At the end, write an explicit checkpoint into `project.ithz`.

`project.ithz` is the actual long-term memory zone.

## First Use In A Project

Adopt a project:

```powershell
python -m ithz_mcp archive-adopt-project-workflow `
  --project C:\work\my_project `
  --profile gobi `
  --owner "Gobi" `
  --prompt C:\work\tmp\my_project_onboarding.md
```

Check memory:

```powershell
python -m ithz_mcp archive-memory-status --project C:\work\my_project
```

Ask for a context pack:

```powershell
python -m ithz_mcp archive-get-context-pack `
  --project C:\work\my_project `
  --query "current status gates risks next steps" `
  --max-bytes 12000 `
  --out C:\work\my_project\.ithz-install\tmp\my_project_pack.md
```

Search memory:

```powershell
python -m ithz_mcp archive-search-context `
  --project C:\work\my_project `
  --query "why was auth changed" `
  --limit 10
```

## Daily Agent Workflow

At the beginning of a task:

1. Open the project.
2. Read `project.md`.
3. Use the MCP read-only tools or CLI:

```powershell
python -m ithz_mcp archive-memory-status --project .
New-Item -ItemType Directory -Force -Path .\.ithz-install\tmp | Out-Null
python -m ithz_mcp archive-get-context-pack --project . --query "<task>" --max-bytes 12000 --out .\.ithz-install\tmp\ithz_context_pack.md
```

4. Inspect files named by the pack.
5. Do the work.

At the end of a task:

If the host exposes the write-enabled MCP profile, the preferred path is the automatic native checkpoint tool:

```text
ithz_archive_auto_checkpoint
```

The host should call it before the final answer with a task name, summary, decisions, gates, risks, next steps, changed files and commands when known.

CLI fallback:

```powershell
python -m ithz_mcp archive-finalize-task `
  --project . `
  --task "Short task name" `
  --summary-text "What changed and why." `
  --decision "Decision: ..." `
  --gate "Gate: ..." `
  --risk "Risk: ..." `
  --next "Next: ..." `
  --docs-impact updated `
  --memory-impact handoff-created `
  --include-git
```

Commit with Git when appropriate:

```powershell
git add project.md project.ithz
git commit -m "Update project memory"
```

## MCP Host Usage

Normal host mode is read-only:

```powershell
python -m ithz_mcp mcp-server --project <project> --mode read-only --protocol mcp --storage-profile native-archive
```

Read-only tools include:

- `ithz_context_status`
- `ithz_archive_status`
- `ithz_archive_search_context`
- `ithz_archive_get_context_pack`
- `ithz_workflow_profile_status`
- `ithz_workflow_context_pack`
- `ithz_archive_cross_zone_context_pack`

Write tools are only exposed in an explicit write-enabled profile:

```powershell
python -m ithz_mcp mcp-server --project <project> --mode write-enabled --protocol mcp --storage-profile native-archive
```

Use write-enabled mode only for controlled end-of-task memory writes. Its preferred tool is `ithz_archive_auto_checkpoint`.

## Project Ledger

Project Ledger stores durable project-accounting records inside `project.ithz`:

- allowed or scoped claims;
- blocked claims;
- replication packs;
- reviewer notes.

Ask whether a statement is safe to claim:

```powershell
python -m ithz_mcp ithz-can-i-claim --project . --claim "ITHKOR proves gravity"
```

Add scoped support or blocks only through explicit write-enabled commands:

```powershell
python -m ithz_mcp ithz-add-claim `
  --project . `
  --claim-id claim_d20_special_ithkor_finite_program `
  --text "Special ITHKOR has a scoped finite/QPU diagnostic program." `
  --scope finite/qpu `
  --supporting-gate D20 `
  --status allowed_scoped

python -m ithz_mcp ithz-block-claim `
  --project . `
  --claim-id blocked_gravity_claim `
  --text "ITHKOR proves gravity" `
  --reason "No physical D claim is supported by the current gates." `
  --blocking-gate D20
```

Read-only MCP mode can list and check ledger evidence. Write-enabled MCP mode is required to add or block claims.

## Workflow Profiles

Different developers can keep separate workflow profiles:

```powershell
python -m ithz_mcp archive-adopt-project-workflow --project . --profile gobi --owner "Gobi" --prompt C:\work\tmp\gobi_prompt.md
python -m ithz_mcp archive-adopt-project-workflow --project . --profile colleague --owner "Colleague" --prompt C:\work\tmp\colleague_prompt.md
```

Update a profile later:

```powershell
python -m ithz_mcp workflow-ingest-prompt `
  --project . `
  --profile gobi `
  --owner "Gobi" `
  --prompt C:\work\tmp\updated_workflow.md `
  --set-default
```

Ask for profile-scoped context:

```powershell
python -m ithz_mcp workflow-context-pack `
  --project . `
  --profile gobi `
  --query "deployment workflow and gates" `
  --max-bytes 12000 `
  --out C:\work\tmp\workflow_pack.md
```

## Prompt Memory

Default prompt memory is conservative. Summary mode stores deterministic summaries and hashes, not raw full prompt text.

Record a prompt/response pair:

```powershell
python -m ithz_mcp archive-record-prompt-response `
  --project . `
  --prompt C:\work\tmp\prompt.md `
  --response C:\work\tmp\response.md `
  --task "Investigated issue X" `
  --mode summary
```

Search prompt memory:

```powershell
python -m ithz_mcp archive-search-context --project . --query "Investigated issue X" --limit 10
```

`full-redacted` removes secret-like values. `full-local-only` is explicit local storage and is skipped by team sync/merge output.

## Historical Prompt Import

Dry-run discovery:

```powershell
python -m ithz_mcp agent-history-discover --project . --source codex --source antigravity --max-records 50
```

Apply import:

```powershell
python -m ithz_mcp archive-import-agent-history --project . --source codex --source antigravity --author "Gobi" --apply
```

Imported records include author/time provenance when available or provided.

## Nested And Sibling Projects

Root discovery uses the nearest `project.ithz`.

If you are in a nested project:

- the child `project.ithz` is active by default;
- parent memory is ignored unless requested;
- sibling memory is ignored unless explicitly linked or addressed.

Read parent memory:

```powershell
python -m ithz_mcp archive-get-context-pack --project . --memory-zone parent --query "parent deployment rules" --max-bytes 12000
```

Read a sibling/manual zone:

```powershell
python -m ithz_mcp archive-get-context-pack --project . --memory-zone-path C:\work\ITHKOR\native_ithz --query "native archive safety gates" --max-bytes 12000
```

Link a sibling zone:

```powershell
python -m ithz_mcp archive-link-zone --project . --zone native_ithz --path C:\work\ITHKOR\native_ithz --relationship sibling
python -m ithz_mcp archive-cross-zone-context-pack --project . --query "changes touching ithz_mcp and native_ithz" --max-bytes 16000
```

## Team Workflow With Git

Recommended team workflow:

```powershell
git pull
# work
python -m ithz_mcp archive-finalize-task --project . --task "..." --summary-text "..."
git add project.md project.ithz
git commit -m "Update code and project memory"
git push
```

For parallel work, install the ITHZ-aware Git driver:

```powershell
python -m ithz_mcp install-git-drivers --repo . --dry-run
python -m ithz_mcp install-git-drivers --repo .
```

The merge driver can auto-merge independent append-only memory events. It returns `merge_needed` for ambiguous conflicts, rewritten history, divergent same refs, invalid archives or secret-like payloads.

## What To Commit

Usually commit:

```text
project.md
project.ithz
.gitattributes
```

If `.gitattributes` already existed before ITHZ-MCP, installation only appends the ITHZ line and preserves existing rules.

Usually do not commit:

```text
.ithz-install/
temporary context packs
host smoke transcripts
private local prompt logs
```

Host config files may be committed only if your team wants project-local MCP config and has reviewed paths.

## Safety Rules

ITHZ-MCP ignores or redacts:

- `.env`
- `*.key`
- `*.pem`
- secret-like names;
- credential-like content;
- private key blocks;
- token-like strings;
- build/cache/vendor directories.

It does not automatically push raw prompt memory.

## Troubleshooting

Check native executable selection:

```powershell
python -m ithz_mcp archive-memory-status --project .
```

If native executable is missing, set:

```powershell
$env:ITHZ_NATIVE_EXE = "C:\path\to\ithz-native.exe"
```

Validate MCP config:

```powershell
python -m ithz_mcp write-host-installers --project . --out .\.ithz-install\host_installers
python -m ithz_mcp mcp-config-validate --config .\.ithz-install\host_installers\codex_mcp_config.sample.json
```

Run scripted MCP smoke:

```powershell
python -m ithz_mcp mcp-client-smoke --config .\.ithz-install\host_installers\codex_mcp_config.sample.json --out .\.ithz-install\host_installers\smoke_transcript.jsonl
```

If the host UI cannot see tools, verify:

- config path is where that host expects it;
- `command` points to Python or `ithz_mcp_server.cmd`;
- `args` include `mcp-server`;
- `mode` is `read-only`;
- `storage_profile` is `native-archive`;
- the project path exists.

Remove ITHZ-MCP from the project with a dry-run first:

```powershell
python -m ithz_mcp uninstall-project
python -m ithz_mcp uninstall-project --apply
```

Use `--keep-project-md` if you want to keep the human bootstrap file. Use `--keep-host-configs` if you want to preserve project-local MCP host configs such as `.mcp.json`, `.antigravity/mcp.json`, `.cursor/mcp.json` or `.claude/mcp.json`; otherwise ITHZ-marked host configs are removed by default.

## Product Boundaries

ITHZ-MCP shares agent work memory. Git shares code history.

ITHZ-MCP does not replace Git.

ITHZ-MCP does not replace a production database.

ITHZ-MCP is not cloud sync.

ITHZ-MCP does not guarantee lower token use for every task.

ITHZ-MCP does not dismiss vector databases or embeddings.
