# 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