System Architecture Specification¶
Applies to: icx v1.2.0 candidate
References: ref-docs/research-report.md §§1–7, ref-docs/initial-concept.md, docs/adr/0005-v1-1-0-workspace-trust-store-and-daemon.md
1. Architectural Overview & Core Principles¶
Infinity-Context (icx) is structured around five invariants:
- Central-State Ownership (Module 50): Each project has one workspace, a private
directory outside the repository holding a single SQLite store (
icx.sqlite3). Every writer (hook, daemon, MCP server, proxy) takes the workspace lock before saving, and every save is one transaction. Whenicx daemonis running it keeps the MMU resident and serializes its requests with other writers through the same lock;icx hookforwards to it over a private Unix socket and falls back to in-process handling on any daemon error. - One-Directional Crate Dependency DAG: No circular dependencies exist across the 8 workspace crates (§2).
- Lossless Provenance After Redaction (Module 20): Every compressed packet (
AHTL) in the active window carries a#icx:<hash>handle into a BLAKE3-verified content-addressed store. The store holds the tool output after secret redaction, byte for byte; dereferencing returns exactly those bytes. - Bounded Context and Retained-Prefix Stability: Sealed cache epochs are not rewritten in cold history. Prompt assembly selects whole recent frames within a persisted model budget; older frames can be omitted from the prompt while remaining recoverable. Per-turn recall and cross-agent events go into the Ephemeral Tail Slot. Paging or changing model policy can change the selected prefix and invalidate provider caches; no unlimited stable prefix or provider cache-hit rate is guaranteed. See ADR 0006.
- No Network or Model Calls in Synchronous Hooks:
PreToolUse,PostToolUse,PreInvocationandUserPromptSubmithandling is local, deterministic Rust.
2. Workspace Crate Topology & Dependency Graph¶
flowchart TD
CLI["crates/icx-cli (binary: icx; includes the daemon)"]
PROXY["crates/icx-proxy (HTTP/1.1 & SSE reverse proxy)"]
ADAPT["crates/icx-adapters (MMU, SQLite store, workspace trust, Claude/Codex/agy/Hermes/Muse, MCP)"]
BUS["crates/icx-bus (telepathy ring: in-process seqlock or file-backed)"]
STORE["crates/icx-store (bi-temporal graph & PPR)"]
CODEC["crates/icx-codec (AHTL codec, skeletonizer & redactor)"]
HDC["crates/icx-hdc (10,240-bit HDC, fractal IFS & Titans-inspired surprise gate)"]
CORE["crates/icx-core (BLAKE3 CAS, FastCDC, Merkle-DAG & cache-epoch controller)"]
CLI --> PROXY & ADAPT & BUS & STORE & CODEC & HDC & CORE
PROXY --> ADAPT & CORE
ADAPT --> BUS & STORE & CODEC & HDC & CORE
BUS --> CORE
STORE --> CORE
CODEC --> CORE
HDC --> CORE
Crate Responsibilities¶
| Crate | Layer | Responsibility |
|---|---|---|
icx-core |
L0 Foundation | Core identifiers (ArtifactId, Blake3Digest, AgentKind) and IcxError, FastCDC content-defined chunking (spread masks), BLAKE3 CAS with collision detection (IcxError::HashCollision), MerkleContextDag, and CacheEpochController. Chunks are stored uncompressed. |
icx-hdc |
L1 Math/Index | 10,240-bit Hypervector ([u64; 160]), XOR binding, permutation, Delta-rule bundling, Hamming distance via u64::count_ones, hybrid exact-token/HDC candidate retrieval with lexical precedence, ICXHDC05 snapshots, FractalTrajectoryArchive (FCGA), and the Titans-inspired TitansSurpriseGate. Legacy 03/04 snapshots remain readable and the MMU rebuilds their postings from CAS events. |
icx-codec |
L1 Codec | Secret redaction (SecretRedactor::redact for storage, sanitize for model-facing text), structural skeletonizer (StructuralSkeletonizer), and the AHTL encoder/decoder. |
icx-store |
L2 Graph | In-memory bi-temporal knowledge graph compiled to CSR, and HippoRAG-style Personalized PageRank (PPR). Persistence is handled by icx-adapters. |
icx-bus |
L2 IPC | SeqlockTelemetryBus: a 256-slot ring with an in-process atomic seqlock backend and a file-backed backend (positional I/O, writer mutex plus file lock, optimistic readers). See docs/wire-protocol-and-shm-bus.md. |
icx-adapters |
L3 Harnesses | InfinityContextMmu; the SQLite workspace store (store.rs) and workspace location/trust policy (workspace.rs); hook wire translators for Claude Code, OpenAI Codex, Antigravity CLI (agy), Meta Muse Code (capture and context, v1.3.0) and Hermes Agent (logic only; Hermes needs a Python ContextEngine shim that calls icx hook --agent hermes); and the single-tool MCP pager. |
icx-proxy |
L3 Wire Plane | Local HTTP/1.1 reverse proxy with SSE for Anthropic, OpenAI and Gemini request formats: token authentication, cache-breakpoint placement, forged-marker escaping and streaming deref expansion. Upstream requests are sent with curl. |
icx-cli |
L4 Entrypoint | The icx binary: init, trust, context-budget, daemon, hook, mcp-serve, proxy, proxy-transform, encode-ahtl, decode-ahtl, deref, status, doctor, benchmark. |
3. End-to-End Execution Flows¶
3.1 Flow A: Bulky Tool Output Virtualization (PostToolUse)¶
sequenceDiagram
participant Agent as Agent CLI (Claude / Codex / agy)
participant Hook as icx hook (or icx daemon)
participant Bus as Telepathy ring (file-backed)
participant Store as CAS, Merkle-DAG & HDC index (icx.sqlite3)
Agent->>Hook: stdin JSON (tool_name, tool_input, tool_response), bounded to 64 MiB
Hook->>Hook: 1. SecretRedactor::redact(tool_response)
Hook->>Store: 2. FastCDC + BLAKE3 CAS insert -> #icx:7f3a91c0d2e4b6a8
Hook->>Hook: 3. TitansSurpriseGate score + StructuralSkeletonizer
Hook->>Hook: 4. AHTL stub packet (escaped for model-facing output)
Hook->>Bus: 5. publish(agent, #icx:7f3a91c0d2e4b6a8, hdc_sketch, fractal_q15, packet)
Hook->>Store: 6. commit one SQLite WAL transaction (synchronous FULL)
Hook-->>Agent: stdout JSON (agent-specific replacement or capture-only response)
The response shape is agent-specific; for example Claude Code requires updatedToolOutput in
the tool's own output shape. Codex captures output for later recall but sends no unsupported
replacement field; the original native output remains visible. See
docs/agent-adapters-and-interception.md.
3.2 Flow B: Pre-Model Associative Recall & Cross-Agent Events (SessionStart / UserPromptSubmit / PreInvocation / select_context)¶
- The user submits a prompt or the agent prepares its next model call.
icxcomputes a query hypervector from the prompt text and the current trajectory coordinate, and extracts query tokens.- It then:
- polls the telepathy ring for events from other agents in the same workspace
(
poll_workspace_since); - unions exact token postings with approximate candidates (Stage 1: 1,024-bit hypervector prefix, Bloom and summary features; Stage 2: full 10,240-bit Hamming distance and verified fractal suffix depth); exact query-token coverage has precedence in final ranking;
- runs Personalized PageRank (\(\alpha = 0.15\), 6 iterations in the MMU) over edges currently valid in the bi-temporal graph.
- The selected packets and cross-agent frames are packed whole into the Ephemeral Tail Slot (default 1,024 conservative accounting units; the Anthropic/OpenAI presets use 2,048). Header and best recall are prioritized; oversized subjects can use compact recoverable handles. Unsent sibling events do not advance the read cursor. The slot is returned via:
- Claude Code and Codex:
hookSpecificOutput.additionalContext; - Antigravity CLI:
injectSteps[].systemMessagewithmetadata.user_markdown: ""; - Hermes: the
ContextEngine.select_context()tail message.
3.3 Flow C: Workspace Resolution and the Resident Daemon¶
- Resolve the workspace:
--dir>ICX_DIR> the per-project default<state_dir>/workspaces/<first 16 hex of blake3(canonical project root)>, where the project root is the nearest ancestor containing.gitandstate_dirisICX_STATE_HOME, else$XDG_STATE_HOME/icx, else~/.local/state/icx. - Verify trust: the directory must be owned by the effective uid, have no group/other
permission bits, and carry a valid
OWNERseal; a sealed store must carry a valid MAC. A repository-local.icx/is never used implicitly (icx trust --dir <path>adopts one). See docs/security-and-threat-model.md §4.1. - Dispatch:
icx hookconnects tows-<hash>.sockin$XDG_RUNTIME_DIR/icxif a daemon is running (disable withICX_NO_DAEMON=1;ICX_DAEMON_AUTOSTART=1starts one in the background on first use). The daemon checks the peer uid withSO_PEERCRED, handles the request against its resident MMU, and commits to SQLite under the workspace lock before sending success. WAL usessynchronous=FULL. Save failure produces a failed response and discards the unsaved state (the daemon exits after 5 consecutive failures, v1.2.2); a failed dispatch is never saved; there is no acknowledged write-behind queue. Each request revalidates the storegeneration, so writes by the MCP server or proxy are picked up. Filesystem and hardware synchronization behavior still bounds durability guarantees. - Fallback: with no daemon, or on any daemon error, the hook loads the store, handles the event and saves in one transaction.
4. Rejected Architectural Alternatives¶
See docs/adr/ for the Nygard-format ADRs:
- Rejected: LLM-on-the-Critical-Path Summarization: calling a secondary model during
PostToolUseorPreInvocationadds network latency and can produce summaries that drop or invent identifiers.icxuses deterministic structural extraction, surprise gating and AHTL encoding on the hot path. - Rejected: Mutating Mid-History Messages Every Turn: rewriting message \(i < N - k\)
invalidates the provider's prefix cache for every later token.
icxseals history into stable epochs. Bounded window selection can nevertheless remove older frames from the selected provider prefix; the tradeoff is documented in ADR 0006. - Rejected (v1.1.0): Repository-local workspace by default: a
.icx/inside the repository can be shipped by a cloned repository and would be trusted. See ADR-0005. - Rejected (v1.1.0): Multiple JSON state files: they could not be saved atomically together and forced a full reload per hook. Replaced by one SQLite store. See ADR-0005.