# Limitations

- ITHZ-MCP does not replace Git.
- ITHZ-MCP is not a production database.
- ITHZ-MCP is not a secret manager.
- ITHZ-MCP is not a full semantic vector database in this stage.
- Current search is deterministic keyword scoring.
- It does not guarantee lower token use for every task.
- The MCP shim is local stdin/stdout style and hardened by smoke tests; it is not yet certified against every external MCP client.
- MCP server icon support is best effort. ITHZ-MCP publishes SVG icon metadata in `initialize` and generated configs, but the visible icon in Codex, Claude Code, Cursor, Antigravity or another host depends on that host's local MCP UI support.
- Team sync is a local/shared-dir MVP, not cloud sync.
- Ubuntu/Linux MCP packaging provides the Python stdio MCP runtime, host installers, a Linux `ithz-native` source build kit, and extraction-backed fallback commands. Native `project.ithz` storage on Ubuntu requires a compatible Linux `ithz-native` binary supplied separately or built on the Ubuntu host. Full Linux Drive/FUSE support is not bundled yet.
- Benchmarks are fixture-based unless explicitly stated.
- Token reduction claims are limited to measured fixture suites.
- Native ITHZ ingestion is a read-only dogfood index over docs and result metadata, not a native archive engine adapter.
- Markdown-minimal migration is currently audit and dry-run planning only.
- The context compiler benchmark is deterministic and fixture-based; it does not prove that embeddings or vector databases are generally worse.
- External MCP/Codex client coverage is limited to the scripted local stdio client unless an actual host is explicitly tested.
- Scoring v2 improves measured fixture gate/risk recall only within the deterministic regression suite.
- ITHZ-MCP does not dismiss vector databases or embeddings; it offers a deterministic support-pack workflow for project memory.
- Prompt memory is not a full chat-history replacement unless explicitly enabled.
- Raw prompt/response storage may contain sensitive data and is redaction-gated.
- Team sync does not push local-only prompt memory.
- Default prompt memory behavior is conservative and summary-first.
- Prompt safety is contextual; users must choose capture mode deliberately and keep redaction gates enabled.
- Native archive memory depends on a compatible `ithz-native.exe` being available locally.
- Native executable auto-selection is local-only: explicit `--native-exe` or `ITHZ_NATIVE_EXE` override the resolver; otherwise ITHZ-MCP selects AVX2 only when runtime CPU detection reports support and falls back to scalar when available.
- macOS packages can install MCP host config and Git/Drive fallback without native storage. Native `project.ithz` creation or rewrite on macOS still requires a compatible macOS `ithz-native` binary; installers should report that as a native-binary gap instead of stopping for a generic user-choice prompt.
- Native archive search loads deterministic index data from `project.ithz` through `ithz-native --extract-file ... --output -`, avoiding full restored-tree disk extraction.
- Native prompt-memory writes use `ithz-native --update-files ... --input -`, so `prompts/prompt_log.jsonl` and `manifest.json` are updated in one memory-backed archive rewrite and avoid full restored-tree staging on disk. The current writer still decodes existing archive files to memory and rewrites the archive file; it is not a true in-place or zero-copy database engine.
- Native archive `compact-v2` indexes intentionally drop duplicate ordinary line units from `index.json` and `context_units.jsonl`. Search keeps deterministic file summaries, high-signal headings, decisions, gates, risks and symbols; exact arbitrary text search inside every source line remains a job for direct file inspection after the context pack points to candidate files.
- Nested project memory zones are explicit. The nearest `project.ithz` is the default active zone; parent and sibling archives require explicit selection. Cross-zone writes are local file rewrites protected by a lock and archive hash precondition, not multi-writer distributed transactions.
- Nested-zone discovery is intentionally bounded on large repositories. Increase `ITHZ_MCP_CHILD_ZONE_SCAN_MAX_DIRS` when a project deliberately contains more nested ITHZ zones than the default status scan should inspect.
- Cross-zone registry is local and explicit. It records linked-zone metadata and events, and can compile context across linked zones, but it is not a distributed transaction layer across multiple archives.
- Append-only memory keeps audit history stable, but it still requires derived indexes and snapshots for useful working memory. Current snapshots are local compact summaries, not garbage collection or irreversible compaction.
- Current-memory synthesis is deterministic and rule-based. It improves the working view of decisions, gates, risks, forbidden claims and next steps, but it is not an LLM judgment engine and can still require direct evidence checks.
- Project Ledger claim checks are deterministic ledger lookups, not legal, scientific or product-truth certification. `ithz-can-i-claim` can answer from stored allowed/blocked claims, gates and replication-pack evidence; if the ledger does not contain enough evidence, the safe answer is `not_found_needs_evidence`.
- Concurrent archive writes are local-file serialized with `project.ithz.lock`. Lock contention now fails quickly with metadata instead of waiting for a long timeout; callers should retry or finalize later rather than assume the write was saved.
- `archive-finalize-task --snapshot --snapshot-mode auto` defers snapshots on large archives to avoid end-of-task timeout pressure. The checkpoint append still completes, and snapshots can be created later with an explicit full snapshot command if needed.
- The ITHZ-aware Git merge driver is semantic for project memory layers, not a general binary merge system. If history is rewritten, payloads look secret-like, or a conflict is unclear, it returns `merge_needed` and requires human/agent review.
- MCP13 host compatibility is verified by scripted stdio MCP calls unless a real external host is explicitly smoke-tested.
- Memory-first behavior is enforceable only when the host supports staged tool permissions or honors MCP/server config instructions. If a host exposes shell/filesystem tools immediately, ITHZ-MCP can guide the agent but cannot block direct codebase reads by itself.
- End-of-task checkpoint writes require an explicit write-enabled MCP profile or CLI command; read-only MCP mode intentionally does not save task results. Compatible hosts are instructed to call `ithz_archive_auto_checkpoint` automatically at task completion, but the write is still an explicit MCP tool call and depends on host behavior.
- MCP write responses are sanitized for invalid Unicode and use compact text plus compact `structuredContent`; external hosts may still require a process restart after installing a new package because MCP server code is loaded when the host session starts.
- Large native memory zones may queue `ithz_archive_auto_checkpoint` finalization in a local background worker to avoid MCP host timeouts. The MCP call returns `queued=true` with a job log path, and the worker performs the native `project.ithz` write outside the host request timeout.
- Workflow intake stores durable extracted facts, not a guaranteed complete raw copy of every user prompt or project document.
- LLM-assisted first intake is bounded by a deterministic repo dossier and short redacted excerpts. It improves first-install project understanding when Codex CLI is available, but it is still an intake summary, not a complete semantic audit of every file.
- Workflow branch profiles separate different people or team workflows, but same-profile divergent edits still require human/agent resolution through `merge_needed`.
- Agent-history import is best-effort and local-format dependent. Codex, Claude, Cursor and Antigravity can store history differently across versions, so explicit `--root` may be needed. Import stores summaries with author/time provenance, not a guaranteed complete raw chat archive.
- Host installer scripts generate and optionally write local MCP config files, but external host applications can change their config format. The scripted stdio client is automated; real host UI smoke remains a per-host manual or host-specific validation step unless the host exposes a noninteractive MCP test command.
- macOS MCP server support is Python stdio based. The package includes POSIX launchers and host installer scripts, but native `project.ithz` storage on macOS requires a separate macOS `ithz-native` binary. Without it, macOS configs should use the legacy storage profile.
- ITHZ Drive / Explorer file association and virtual-drive shell integration are Windows-only in the current package; they are not provided by the macOS MCP package.
