ICM (Infinite Context Memory)

ICM uses three layers of automatic memory extraction. All three layers are implemented with zero LLM cost and are installed automatically via icm init --mode hook.

Workflow Summary:

1. PostToolUse (Layer 0) captures raw events.
2. PreCompact (Layer 1) captures context before it's compressed.
3. UserPromptSubmit (Layer 2) performs the recall and injection loop.

ICM extracts memories automatically using a three-layer architecture designed to minimize LLM costs and latency. These layers capture different stages of the interaction lifecycle:

1. Layer 0: Pattern hooks (icm hook post) - Rule-based extraction (zero LLM cost) from tool outputs, such as Bash errors, git commits, config changes, decisions, preferences, learnings, and constraints.
2. Layer 1: PreCompact (icm hook compact) - Extracts context from transcripts just before they are compressed, ensuring information isn't lost during context window management. It uses the same patterns as Layer 0 with a --store-raw fallback.
3. Layer 2: UserPromptSubmit (icm hook prompt) - Injects relevant memories into the context immediately when a user sends a prompt, so the agent starts with the necessary background information.

To automatically install and configure all three layers, use the following command:

icm init --mode hook

ICM achieves project isolation through a specific topic naming convention rather than a separate database column. This ensures that memories from Project A do not leak into Project B.

Naming Convention

Use the format {kind}-{project} for project-specific memories. Certain topics are global and will always be included across all projects:

• {kind}-{project}: e.g., decisions-icm, errors-resolved-icm, contexte-rtk-cloud
• preferences: Global user preferences
• identity: Global user identity

Automatic Project Detection

When using the icm_wake_up command, ICM performs segment-aware matching. For example, providing { project: "icm" } will match decisions-icm or errors-icm-core, but will not match icmp-notes.

To automate isolation, run each project from its own directory. The UserPromptSubmit hook (icm hook prompt) and the SessionStart hook (icm hook start) automatically derive the project name from the cwd (current working directory) field in the hook JSON using the basename of the directory.

// Example icm_wake_up call
{
  "project": "icm"
}

ICM uses two primary data models to manage information: Memory for raw data points and Memoir for structured knowledge graphs.

Memory

Represents an individual piece of information. Key fields include:

• id: A ULID.
• importance: An enum (Critical, High, Medium, Low) that controls how the memory decays over time.
• source: Where the memory came from (ClaudeCode, Conversation, or Manual).
• embedding: An optional vector (384, 768, or 1024 dimensions) for semantic search.

Memoir (Knowledge Graph)

Organizes information into structured concepts using a graph model:

• Memoir: A named container for a specific knowledge domain.
• Concept: A node in the graph representing a defined idea. Concepts are unique within a memoir.
• ConceptLink: A typed edge connecting two concepts. Relations include PartOf, DependsOn, RelatedTo, Contradicts, Refines, AlternativeTo, CausedBy, InstanceOf, and SupersededBy.

ICM uses two distinct memory models to manage information:

Episodic Memory (Topics)

Captures decisions, errors, and preferences. Memories have a weight that decays over time based on their importance level:

Decay is access-aware: Frequently recalled memories decay slower (formula: decay / (1 + access_count * 0.1)). Decay is applied automatically if more than 24 hours have passed since the last decay event.

Memory Health Features:

• Auto-deduplication: Updates existing memories if new content has >85% similarity to an existing topic.
• Consolidation Prompts: icm_memory_store prompts the caller to consolidate when a topic exceeds 7 records.
• Health Audits: icm_memory_health reports entry counts, average weights, stale entries, and consolidation needs.
• No Silent Data Loss: critical and high importance memories are never automatically pruned.

Semantic Memory (Memoirs)