# ICM Technical Architecture ## Overview ICM is a Rust workspace of 4 crates that compile into a single binary. No runtime dependencies, no external services. ``` icm (binary) ├── icm-core Types, traits, embedder ├── icm-store SQLite + FTS5 + sqlite-vec ├── icm-mcp MCP server (JSON-RPC 2.0 over stdio) └── icm-cli CLI, config, extraction, benchmarks ``` ## Crate Dependency Graph ``` icm-cli ──────► icm-core │ ▲ ├──► icm-store ─┘ │ ▲ └──► icm-mcp ──► icm-store │ └──► icm-core ``` ## Architecture at a glance Who talks to what. Every entry point ends in the same store, so a memory written through one is visible through the others. ```mermaid flowchart LR subgraph agents["AI coding agents"] A1["Claude Code, Codex,
Gemini CLI, Copilot CLI"] A2["Cursor, Zed, VS Code,
other MCP clients"] A3["Scripts, cron, you"] end subgraph entry["icm-cli: one binary, four entry points"] H["Hooks
icm hook start / prompt / post / compact / end"] C["CLI
icm store, recall, memoir, ..."] M["MCP server (icm-mcp)
icm serve"] W["HTTP API
icm serve --http"] end subgraph engine["icm-store"] R["Recall engine v2
recall.rs"] S["Store backend
SQLite by default,
Postgres or OpenSearch"] end subgraph core["icm-core: types and pure logic"] F["Rank fusion, token budget,
date windows, auto-link, wake-up"] E["Embedder (fastembed + ONNX Runtime)
optional"] end DB[("memories.db
memories, FTS5 index, vector index,
memoirs, feedback, transcripts")] L["Your LLM command-line tool
or an API-key provider
(extraction and summaries only)"] A1 --> H A1 --> C A2 --> M A3 --> C A3 --> W entry -- "recall" --> R entry -- "store, update, forget" --> S entry -- "embed the text
(not the hooks)" --> E R --> S R --> F S --> DB H -. "queued text" .-> L C -. "consolidate, briefing" .-> L ``` Storing and recalling never reach the LLM box. Only the extraction worker, `icm consolidate` and `icm briefing` do, and only when a summarizer provider is configured. ## Function flows The three paths a memory takes, with the function that does each step. Names are the ones in the source. ### Storing a memory `icm store`, the MCP `icm_memory_store` tool and HTTP `/store` follow the same steps; the CLI functions are shown. ```mermaid flowchart TD A["icm store -t topic -c text
cmd_store"] --> B{"Embedding model
loaded?"} B -- yes --> C["embed_text"] B -- no --> D C --> D{"find_similar_memory
same topic, cosine above 0.95?"} D -- yes --> E["merge_summaries, union_keywords,
max_importance"] E --> F["store.update"] D -- no --> G["store.store"] G --> H["store_in_transaction
row in memories, FTS5 index by trigger,
vector in vec_memories"] H --> I{"Vector does not fit
the index dimension?"} I -- yes --> J["stored again without the vector"] I -- no --> K J --> K["auto_link_memory, add_backrefs
related_ids to the nearest memories"] F --> K K --> L["maybe_auto_consolidate
off by default"] ``` ### Recalling One engine behind four callers. The prompt hook is the read-only, keyword-only caller. ```mermaid flowchart TD subgraph callers["Callers"] C1["icm recall
cmd_recall, cmd_recall_v2"] C2["MCP icm_memory_recall
tool_recall, tool_recall_v2"] C3["HTTP /recall
handle_recall"] C4["Prompt hook
cmd_hook_prompt, recall_context"] end C1 --> R C2 --> R C3 --> R C4 --> R R["RecallEngine::resolve
v2 unless --engine legacy
or ICM_RECALL_ENGINE=legacy"] --> V["recall_v2"] V --> T["parse_query_window
does the query name a period?"] T --> Q["search_ranked
project, topic and keyword filters
applied inside each arm"] Q --> L1["Lexical arm
FTS5 BM25"] Q --> L2["Vector arm
sqlite-vec KNN
only with an embedder"] Q --> L3["Temporal arm
created in the named window"] L1 --> U["rrf_fuse
reciprocal rank fusion, k = 60"] L2 --> U L3 --> U U --> N{"No arm matched?"} N -- yes --> S2["substring search
on the query words"] N -- no --> X S2 --> X{"max_tokens given?"} X -- yes --> B1["select_within_budget
as many best hits as fit"] X -- no --> B2["cut at limit"] B1 --> Z["related_ids neighbors appended
in the room left"] B2 --> Z Z --> W2["batch_update_access
skipped by the read-only hook"] W2 --> O["rendered result"] ``` ### A session, through the hooks What `icm init` wires into an agent, and what each hook calls. ```mermaid sequenceDiagram participant A as Agent (Claude Code, ...) participant I as icm hook participant D as memories.db participant X as LLM CLI (optional) A->>I: SessionStart I->>D: cmd_hook_start, build_hook_start_pack
critical and high memories of this project I-->>A: wake-up pack loop each prompt A->>I: UserPromptSubmit I->>D: cmd_hook_prompt, recall_context
recall_v2, keyword-only, read-only I-->>A: memories relevant to the prompt I->>D: [extraction.conversation] in_session:
enqueue_conversation, full excerpts only end loop each tool call A->>I: PreToolUse I-->>A: cmd_hook_pre: allow icm commands A->>I: PostToolUse I->>D: cmd_hook_post: increment_hook_counter
every N calls: enqueue_pending_extraction,
or extract by rules when the provider is "none" end A->>I: PreCompact I->>D: cmd_hook_compact: [extraction.conversation] enabled:
enqueue_conversation, otherwise extract by rules I-)X: detached worker: extract-pending A->>I: SessionEnd I->>D: cmd_hook_end: [extraction.conversation] enabled:
enqueue_conversation; extract by rules when the provider is "none" I-)X: detached workers: extract-pending,
consolidate-pending, briefing X-)D: facts written as memories ``` The workers run only when the extraction summarizer is not `none`; they are what turns the queued tool output and conversation excerpts into memories. Conversation excerpts are queued only with `[extraction.conversation] enabled = true` (compaction and session end) or `in_session = true` (each prompt), both off by default, and their sizes come from the same section. `enqueue_conversation` reads the transcript from the byte offset it reached last time for that session (`icm_metadata`), renders what the user and the agent wrote with each tool result cut to 1,500 characters, and queues it in excerpts of up to 60,000 characters, the 12 most recent per fire; each excerpt is one provider call. With `in_session`, UserPromptSubmit also queues full excerpts, as soon as the conversation has one, and leaves the rest for later; PreCompact and SessionEnd queue everything up to the end of the transcript. An excerpt the provider fails on stays queued for the next run. Each distilled fact is dated at the capture of the queue rows it came from (the latest one in its group), not at the drain, and its source is `extracted` with the project and the tools captured (`Bash`, `conversation`, …), so distilled facts are told apart from written ones. With an agent that has no SessionEnd hook, run `icm extract-pending` yourself. ## icm-core Foundation crate. No I/O, no database — only types and traits. ### Data Types #### Memory ```rust pub struct Memory { pub id: String, // ULID pub created_at: DateTime, pub updated_at: DateTime, pub last_accessed: DateTime, pub access_count: u32, pub weight: f32, // 1.0 at creation, decays over time pub topic: String, pub summary: String, pub raw_excerpt: Option, pub keywords: Vec, pub importance: Importance, // Critical | High | Medium | Low pub source: MemorySource, // ClaudeCode | Conversation | Manual pub related_ids: Vec, pub embedding: Option>, // 384/768/1024d depending on model } ``` #### Importance ```rust pub enum Importance { Critical, // decay: 0.0 (never), prune: never High, // decay: 0.5x rate, prune: never Medium, // decay: 1.0x rate, prune: when weight < threshold Low, // decay: 2.0x rate, prune: when weight < threshold } ``` #### Memoir (Knowledge Graph) ```rust pub struct Memoir { pub id: String, pub name: String, // unique pub description: String, pub created_at: DateTime, pub updated_at: DateTime, pub consolidation_threshold: u32, // default: 50 } pub struct Concept { pub id: String, pub memoir_id: String, pub name: String, // unique within memoir pub definition: String, pub labels: Vec