{"id":43659253,"url":"https://github.com/rtk-ai/icm","last_synced_at":"2026-05-23T10:09:25.772Z","repository":{"id":336125165,"uuid":"1148370786","full_name":"rtk-ai/icm","owner":"rtk-ai","description":"Permanent memory for AI agents. Single binary, zero dependencies, MCP native.","archived":false,"fork":false,"pushed_at":"2026-04-11T10:25:09.000Z","size":880,"stargazers_count":174,"open_issues_count":1,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-11T10:29:05.695Z","etag":null,"topics":["ai-agents","claude-code","experimental","mcp","memory","rust"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rtk-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T22:15:56.000Z","updated_at":"2026-04-11T10:25:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rtk-ai/icm","commit_stats":null,"previous_names":["rtk-ai/icm"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/rtk-ai/icm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtk-ai%2Ficm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtk-ai%2Ficm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtk-ai%2Ficm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtk-ai%2Ficm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rtk-ai","download_url":"https://codeload.github.com/rtk-ai/icm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rtk-ai%2Ficm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31882886,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T09:23:21.276Z","status":"ssl_error","status_checked_at":"2026-04-16T09:23:15.028Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","experimental","mcp","memory","rust"],"created_at":"2026-02-04T21:29:14.439Z","updated_at":"2026-05-23T10:09:25.759Z","avatar_url":"https://github.com/rtk-ai.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"[English](README.md) | [Français](README_fr.md) | [Español](README_es.md) | [Deutsch](README_de.md) | [Italiano](README_it.md) | [Português](README_pt.md) | [Nederlands](README_nl.md) | [Polski](README_pl.md) | [Русский](README_ru.md) | [日本語](README_ja.md) | [中文](README_zh.md) | [العربية](README_ar.md) | [한국어](README_ko.md)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"ICM — Infinite Context Memory\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eICM\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Permanent memory for AI agents. Single binary, zero dependencies, MCP native.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/rtk-ai/icm/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/rtk-ai/icm/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/rtk-ai/icm/releases/latest\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/rtk-ai/icm?color=purple\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache--2.0-blue.svg\" alt=\"Apache-2.0\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e ⚠️ **Project status: experimental**\n\u003e\n\u003e ICM is pre-1.0 and under active development. Breaking changes can land\n\u003e in any minor release, and hooks/MCP configuration formats may shift.\n\u003e\n\u003e That said, I (the maintainer) use ICM every day as my primary AI\n\u003e coding memory layer — it's experimental in API stability, not in\n\u003e day-to-day usefulness.\n\u003e\n\u003e My focus is currently on [rtk](https://github.com/rtk-ai/rtk); ICM\n\u003e updates are merged on a best-effort cadence. Issues and pull requests\n\u003e are welcome but may take longer to review than usual.\n\u003e\n\u003e ICM is Apache-2.0 licensed and ships **as-is, without warranty of any\n\u003e kind** (see [LICENSE](LICENSE)). Before any destructive operation, run\n\u003e the read-only equivalent first (`icm uninstall --dry-run`,\n\u003e `icm uninstall --check`).\n\n---\n\nICM gives your AI agent a real memory — not a note-taking tool, not a context manager, a **memory**.\n\n```\n                       ICM (Infinite Context Memory)\n            ┌──────────────────────┬─────────────────────────┐\n            │   MEMORIES (Topics)  │   MEMOIRS (Knowledge)   │\n            │                      │                         │\n            │  Episodic, temporal  │  Permanent, structured  │\n            │                      │                         │\n            │  ┌───┐ ┌───┐ ┌───┐  │    ┌───┐               │\n            │  │ m │ │ m │ │ m │  │    │ C │──depends_on──┐ │\n            │  └─┬─┘ └─┬─┘ └─┬─┘  │    └───┘              │ │\n            │    │decay │     │    │      │ refines      ┌─▼─┐│\n            │    ▼      ▼     ▼    │    ┌─▼─┐            │ C ││\n            │  weight decreases    │    │ C │──part_of──\u003e└───┘│\n            │  over time unless    │    └───┘                 │\n            │  accessed/critical   │  Concepts + Relations    │\n            ├──────────────────────┴─────────────────────────┤\n            │             SQLite + FTS5 + sqlite-vec          │\n            │        Hybrid search: BM25 (30%) + cosine (70%) │\n            └─────────────────────────────────────────────────┘\n```\n\n**Two memory models:**\n\n- **Memories** — store/recall with temporal decay by importance. Critical memories never fade, low-importance ones decay naturally. Filter by topic or keyword.\n- **Memoirs** — permanent knowledge graphs. Concepts linked by typed relations (`depends_on`, `contradicts`, `superseded_by`, ...). Filter by label.\n- **Feedback** — record corrections when AI predictions are wrong. Search past mistakes before making new predictions. Closed-loop learning.\n\n## One memory, every AI tool — no re-explaining\n\nThe point of ICM: **you stop re-explaining context every time you switch\nAI tools**. Tell Claude Code about your project's auth strategy on\nMonday — Tuesday's Gemini session already knows it. Hit a Postgres\nindexing gotcha in a Codex run — next week's Cursor session finds the\nfix in `errors-resolved`.\n\nThis works because every AI tool you configure with `icm init` reads\nand writes the **same SQLite database** at the OS-standard data\nlocation (e.g. `~/.local/share/icm/memories.db` on Linux,\n`~/Library/Application Support/icm/memories.db` on macOS,\n`%APPDATA%\\icm\\icm\\data\\memories.db` on Windows):\n\n- A `icm store -t decisions-myapp -c \"...\"` from Claude Code is\n  immediately visible to Codex, Gemini, Cursor, Roo, Amp, Aider, ...\n- `icm recall \"query\"` from any tool searches the same corpus.\n- Topics (`decisions-myapp`, `preferences`, `errors-resolved`, ...)\n  are global — there is no per-tool partition.\n\nThe [multi-agent benchmark](#multi-agent-unified-memory) below confirms\nit end-to-end: facts seeded through ICM are recalled with 100% accuracy\nby Claude Code, Gemini CLI, Copilot CLI, Cursor Agent, and Aider —\n**98% cross-agent efficiency** on the standard test.\n\nIf you want isolation (per-project, per-tool, etc.) pass `--db \u003cpath\u003e`\nor set `ICM_DB_PATH`; each path is an independent corpus.\n\n## Install\n\n```bash\n# Homebrew (macOS / Linux)\nbrew tap rtk-ai/tap \u0026\u0026 brew install icm\n\n# Quick install (macOS / Linux) — verifies SHA256 against the release checksums\ncurl -fsSL https://raw.githubusercontent.com/rtk-ai/icm/main/install.sh | sh\n\n# Quick install (Windows PowerShell)\nirm https://raw.githubusercontent.com/rtk-ai/icm/main/install.ps1 | iex\n\n# From source\ncargo install --path crates/icm-cli\n```\n\nRe-run the install command to upgrade to the latest release. To pin a version, pass `--version icm-vX.Y.Z` (sh: `sh -s -- --version …`).\n\n## Setup\n\n```bash\n# Auto-detect and configure all supported tools\nicm init\n```\n\nConfigures **17 tools** in one command ([full integration guide](docs/integrations.md)):\n\n| Tool | MCP | Hooks | CLI | Skills |\n|------|:---:|:-----:|:---:|:------:|\n| Claude Code | `~/.claude.json` | 5 hooks | `CLAUDE.md` | `/recall` `/remember` |\n| Claude Desktop | JSON | — | — | — |\n| Gemini CLI | `~/.gemini/settings.json` | 5 hooks | `GEMINI.md` | — |\n| Codex CLI | `~/.codex/config.toml` | 4 hooks | `AGENTS.md` | — |\n| Copilot CLI | `~/.copilot/mcp-config.json` | 4 hooks | `.github/copilot-instructions.md` | — |\n| Cursor | `~/.cursor/mcp.json` | — | — | `.mdc` rule |\n| Windsurf | JSON | — | `.windsurfrules` | — |\n| VS Code | `~/Library/.../Code/User/mcp.json` | — | — | — |\n| Amp | JSON | — | — | `/icm-recall` `/icm-remember` |\n| Amazon Q | JSON | — | — | — |\n| Cline | VS Code globalStorage | — | — | — |\n| Roo Code | VS Code globalStorage | — | — | `.md` rule |\n| Kilo Code | VS Code globalStorage | — | — | — |\n| Zed | `~/.zed/settings.json` | — | — | — |\n| OpenCode | JSON | TS plugin | — | — |\n| Continue.dev | `~/.continue/config.yaml` | — | — | — |\n| Aider | — | — | `.aider.conventions.md` | — |\n\nOr manually:\n\n```bash\n# Claude Code\nclaude mcp add icm -- icm serve\n\n# Compact mode (shorter responses, saves tokens)\nclaude mcp add icm -- icm serve --compact\n\n# Any MCP client: command = \"icm\", args = [\"serve\"]\n```\n\n### Skills / rules\n\n```bash\nicm init --mode skill\n```\n\nInstalls slash commands and rules for Claude Code (`/recall`, `/remember`), Cursor (`.mdc` rule), Roo Code (`.md` rule), and Amp (`/icm-recall`, `/icm-remember`).\n\n### CLI instructions\n\n```bash\nicm init --mode cli\n```\n\nInjects ICM instructions into each tool's instruction file:\n\n| Tool | File |\n|------|------|\n| Claude Code | `CLAUDE.md` |\n| GitHub Copilot | `.github/copilot-instructions.md` |\n| Windsurf | `.windsurfrules` |\n| OpenAI Codex | `AGENTS.md` |\n| Gemini | `~/.gemini/GEMINI.md` |\n\n### Hooks (5 tools)\n\n```bash\nicm init --mode hook\n```\n\nInstalls auto-extraction and auto-recall hooks for all supported tools:\n\n| Tool | SessionStart | PreTool | PostTool | Compact | PromptRecall | Config |\n|------|:-----------:|:-------:|:--------:|:-------:|:------------:|--------|\n| Claude Code | `icm hook start` | `icm hook pre` | `icm hook post` | `icm hook compact` | `icm hook prompt` | `~/.claude/settings.json` |\n| Gemini CLI | `icm hook start` | `icm hook pre` | `icm hook post` | `icm hook compact` | `icm hook prompt` | `~/.gemini/settings.json` |\n| Codex CLI | `icm hook start` | `icm hook pre` | `icm hook post` | — | `icm hook prompt` | `~/.codex/hooks.json` |\n| Copilot CLI | `icm hook start` | `icm hook pre` | `icm hook post` | — | `icm hook prompt` | `.github/hooks/icm.json` |\n| OpenCode | session start | — | tool extract | compaction | — | `~/.config/opencode/plugins/icm.ts` |\n\n**What each hook does:**\n\n| Hook | What it does |\n|------|-------------|\n| `icm hook start` | Inject a wake-up pack of critical/high memories at session start (~500 tokens) |\n| `icm hook pre` | Auto-allow `icm` CLI commands (no permission prompt) |\n| `icm hook post` | Extract facts from tool output every N calls (auto-extraction) |\n| `icm hook compact` | Extract memories from transcript before context compression |\n| `icm hook prompt` | Inject recalled context at the start of each user prompt |\n\n## CLI vs MCP\n\nICM can be used via CLI (`icm` commands) or MCP server (`icm serve`). Both access the same database.\n\n| | CLI | MCP |\n|---|-----|-----|\n| **Latency** | ~30ms (direct binary) | ~50ms (JSON-RPC stdio) |\n| **Token cost** | 0 (hook-based, invisible) | ~20-50 tokens/call (tool schema) |\n| **Setup** | `icm init --mode hook` | `icm init --mode mcp` |\n| **Works with** | Claude Code, Gemini, Codex, Copilot, OpenCode (via hooks) | All 17 MCP-compatible tools |\n| **Auto-extraction** | Yes (hooks trigger `icm extract`) | Yes (MCP tools call store) |\n| **Best for** | Power users, token savings | Universal compatibility |\n\n## Dashboard\n\n```bash\nicm dashboard    # or: icm tui\n```\n\nInteractive TUI with 5 tabs: Overview, Topics, Memories, Health, Memoirs. Keyboard navigation (vim-style: j/k, g/G, Tab, 1-5), live search (/), auto-refresh.\n\nRequires the `tui` feature (enabled by default). Build without: `cargo install --path crates/icm-cli --no-default-features --features embeddings`.\n\n## CLI\n\n### Memories (episodic, with decay)\n\n```bash\n# Store\nicm store -t \"my-project\" -c \"Use PostgreSQL for the main DB\" -i high -k \"db,postgres\"\n\n# Recall\nicm recall \"database choice\"\nicm recall \"auth setup\" --topic \"my-project\" --limit 10\nicm recall \"architecture\" --keyword \"postgres\"\n\n# Manage\nicm forget \u003cmemory-id\u003e\nicm consolidate --topic \"my-project\"\nicm topics\nicm stats\n\n# Extract facts from text (rule-based, zero LLM cost)\necho \"The parser uses Pratt algorithm\" | icm extract -p my-project\n```\n\n### Memoirs (permanent knowledge graphs)\n\n```bash\n# Create a memoir\nicm memoir create -n \"system-architecture\" -d \"System design decisions\"\n\n# Add concepts with labels\nicm memoir add-concept -m \"system-architecture\" -n \"auth-service\" \\\n  -d \"Handles JWT tokens and OAuth2 flows\" -l \"domain:auth,type:service\"\n\n# Link concepts\nicm memoir link -m \"system-architecture\" --from \"api-gateway\" --to \"auth-service\" -r depends-on\n\n# Search with label filter\nicm memoir search -m \"system-architecture\" \"authentication\"\nicm memoir search -m \"system-architecture\" \"service\" --label \"domain:auth\"\n\n# Inspect neighborhood\nicm memoir inspect -m \"system-architecture\" \"auth-service\" -D 2\n\n# Export graph (formats: json, dot, ascii, ai)\nicm memoir export -m \"system-architecture\" -f ascii   # Box-drawing with confidence bars\nicm memoir export -m \"system-architecture\" -f dot      # Graphviz DOT (color = confidence level)\nicm memoir export -m \"system-architecture\" -f ai       # Markdown optimized for LLM context\nicm memoir export -m \"system-architecture\" -f json     # Structured JSON with all metadata\n\n# Generate SVG visualization\nicm memoir export -m \"system-architecture\" -f dot | dot -Tsvg \u003e graph.svg\n```\n\n### Transcripts (verbatim session replay)\n\nStore every message exchanged with an agent as-is — no summarization, no extraction.\nSearch later with FTS5 (BM25 + boolean + phrase + prefix). Useful for session replay,\npost-mortem review, compliance audit, training data. Complementary to curated memories.\n\n```bash\n# 1. Start a session\nSID=$(icm transcript start-session --agent claude-code --project myapp)\n\n# 2. Record every turn verbatim\nicm transcript record -s \"$SID\" -r user      -c \"Pourquoi on avait choisi Postgres ?\"\nicm transcript record -s \"$SID\" -r assistant -c \"JSONB natif, BRIN pour les logs, auto-vacuum tuné.\"\nicm transcript record -s \"$SID\" -r tool      -c '{\"cmd\":\"psql -c ...\"}' -t Bash --tokens 42\n\n# 3. Replay, search, inspect\nicm transcript list-sessions --project myapp\nicm transcript show \"$SID\" --limit 200\nicm transcript search \"postgres JSONB\"                    # BM25 ranked\nicm transcript search '\"auto-vacuum\"'                     # phrase match\nicm transcript search \"postgres OR mysql\" --session \"$SID\" # boolean, scoped\nicm transcript stats\n\n# 4. Delete a session (cascade deletes its messages)\nicm transcript forget \"$SID\"\n```\n\nRust + SQLite + FTS5 — 0 Python, 0 ChromaDB, 0 external service. Writes are ~10× faster than\nChromaDB-based verbatim stores; the whole transcript lives in the same SQLite file as your\nmemories and memoirs.\n\n## MCP Tools (31)\n\n### Memory tools\n\n| Tool | Description |\n|------|-------------|\n| `icm_memory_store` | Store with auto-dedup (\u003e85% similarity → update instead of duplicate) |\n| `icm_memory_recall` | Search by query, filter by topic / keyword / project |\n| `icm_memory_update` | Edit a memory in-place (content, importance, keywords) |\n| `icm_memory_forget` | Delete a memory by ID |\n| `icm_memory_forget_topic` | Delete all memories in a given topic |\n| `icm_memory_consolidate` | Merge all memories of a topic into one summary |\n| `icm_memory_extract_patterns` | Detect recurring patterns within a topic and surface them as concepts |\n| `icm_memory_list_topics` | List all topics with counts |\n| `icm_memory_stats` | Global memory statistics |\n| `icm_memory_health` | Per-topic hygiene audit (staleness, consolidation needs) |\n| `icm_memory_embed_all` | Backfill embeddings for vector search |\n\n### Session tools\n\n| Tool | Description |\n|------|-------------|\n| `icm_wake_up` | Build a project-scoped wake-up pack (critical/high memories + preferences) for SessionStart-style context injection |\n| `icm_learn` | Scan a project directory and seed a Memoir knowledge graph from its code/docs |\n\n### Memoir tools (knowledge graphs)\n\n| Tool | Description |\n|------|-------------|\n| `icm_memoir_create` | Create a new memoir (knowledge container) |\n| `icm_memoir_list` | List all memoirs |\n| `icm_memoir_show` | Show memoir details and all concepts |\n| `icm_memoir_add_concept` | Add a concept with labels |\n| `icm_memoir_refine` | Update a concept's definition |\n| `icm_memoir_search` | Full-text search, optionally filtered by label |\n| `icm_memoir_search_all` | Search across all memoirs |\n| `icm_memoir_link` | Create typed relation between concepts |\n| `icm_memoir_inspect` | Inspect concept and graph neighborhood (BFS) |\n| `icm_memoir_export` | Export graph (json, dot, ascii, ai) with confidence levels |\n\n### Feedback tools (learning from mistakes)\n\n| Tool | Description |\n|------|-------------|\n| `icm_feedback_record` | Record a correction when an AI prediction was wrong |\n| `icm_feedback_search` | Search past corrections to inform future predictions |\n| `icm_feedback_stats` | Feedback statistics: total count, breakdown by topic, most applied |\n\n### Transcript tools (verbatim session replay)\n\n| Tool | Description |\n|------|-------------|\n| `icm_transcript_start_session` | Create a session for verbatim message capture; returns `session_id` |\n| `icm_transcript_record` | Append a raw message (role, content, optional tool + tokens + metadata) |\n| `icm_transcript_search` | FTS5 search across messages (BM25, boolean, phrase, prefix) |\n| `icm_transcript_show` | Replay full message thread of a session, chronologically |\n| `icm_transcript_stats` | Sessions, messages, bytes, breakdown by role/agent/top-sessions |\n\n### Relation types\n\n`part_of` · `depends_on` · `related_to` · `contradicts` · `refines` · `alternative_to` · `caused_by` · `instance_of` · `superseded_by`\n\n## How it works\n\n### Dual memory model\n\n**Episodic memory (Topics)** captures decisions, errors, preferences. Each memory has a weight that decays over time based on importance:\n\n| Importance | Decay | Prune | Behavior |\n|-----------|-------|-------|----------|\n| `critical` | none | never | Never forgotten, never pruned |\n| `high` | slow (0.5x rate) | never | Fades slowly, never auto-deleted |\n| `medium` | normal | yes | Standard decay, pruned when weight \u003c threshold |\n| `low` | fast (2x rate) | yes | Quickly forgotten |\n\nDecay is **access-aware**: frequently recalled memories decay slower (`decay / (1 + access_count × 0.1)`). Applied automatically on recall (if \u003e24h since last decay).\n\n**Memory hygiene** is built-in:\n- **Auto-dedup**: storing content \u003e85% similar to an existing memory in the same topic updates it instead of creating a duplicate\n- **Consolidation hints**: when a topic exceeds 7 entries, `icm_memory_store` warns the caller to consolidate\n- **Health audit**: `icm_memory_health` reports per-topic entry count, average weight, stale entries, and consolidation needs\n- **No silent data loss**: critical and high-importance memories are never auto-pruned\n\n**Semantic memory (Memoirs)** captures structured knowledge as a graph. Concepts are permanent — they get refined, never decayed. Use `superseded_by` to mark obsolete facts instead of deleting them.\n\n### Hybrid search\n\nWith embeddings enabled, ICM uses hybrid search:\n- **FTS5 BM25** (30%) — full-text keyword matching\n- **Cosine similarity** (70%) — semantic vector search via sqlite-vec\n\nDefault model: `intfloat/multilingual-e5-base` (768d, 100+ languages). Configurable in your [config file](#configuration):\n\n```toml\n[embeddings]\n# enabled = false                          # Disable entirely (no model download)\nmodel = \"intfloat/multilingual-e5-base\"    # 768d, multilingual (default)\n# model = \"intfloat/multilingual-e5-small\" # 384d, multilingual (lighter)\n# model = \"intfloat/multilingual-e5-large\" # 1024d, multilingual (best accuracy)\n# model = \"Xenova/bge-small-en-v1.5\"      # 384d, English-only (fastest)\n# model = \"jinaai/jina-embeddings-v2-base-code\"  # 768d, code-optimized\n```\n\nTo skip the embedding model download entirely, use any of these:\n```bash\nicm --no-embeddings serve          # CLI flag\nICM_NO_EMBEDDINGS=1 icm serve     # Environment variable\n```\nOr set `enabled = false` in your config file. ICM will fall back to FTS5 keyword search (still works, just no semantic matching).\n\nChanging the model automatically re-creates the vector index (existing embeddings are cleared and can be regenerated with `icm_memory_embed_all`).\n\n### Storage\n\nSingle SQLite file. No external services, no network dependency.\n\n```\n~/Library/Application Support/dev.icm.icm/memories.db                    # macOS\n~/.local/share/dev.icm.icm/memories.db                                   # Linux\nC:\\Users\\\u003cuser\u003e\\AppData\\Local\\icm\\icm\\data\\memories.db                   # Windows\n```\n\n### Configuration\n\n```bash\nicm config                    # Show active config\n```\n\nConfig file location (platform-specific, or `$ICM_CONFIG`):\n\n```\n~/Library/Application Support/dev.icm.icm/config.toml                    # macOS\n~/.config/icm/config.toml                                                # Linux\nC:\\Users\\\u003cuser\u003e\\AppData\\Roaming\\icm\\icm\\config\\config.toml              # Windows\n```\n\nSee [config/default.toml](config/default.toml) for all options.\n\n## Auto-extraction\n\nICM extracts memories automatically via three layers:\n\n```\n  Layer 0: Pattern hooks              Layer 1: PreCompact           Layer 2: UserPromptSubmit\n  (zero LLM cost)                     (zero LLM cost)               (zero LLM cost)\n  ┌──────────────────┐                ┌──────────────────┐          ┌──────────────────┐\n  │ PostToolUse hook  │                │ PreCompact hook   │          │ UserPromptSubmit  │\n  │                   │                │                   │          │                   │\n  │ • Bash errors     │                │ Context about to  │          │ User sends prompt │\n  │ • git commits     │                │ be compressed →   │          │ → icm recall      │\n  │ • config changes  │                │ extract memories  │          │ → inject context  │\n  │ • decisions       │                │ from transcript   │          │                   │\n  │ • preferences     │                │ before they're    │          │ Agent starts with  │\n  │ • learnings       │                │ lost forever      │          │ relevant memories  │\n  │ • constraints     │                │                   │          │ already loaded     │\n  │                   │                │ Same patterns +   │          │                   │\n  │ Rule-based, no LLM│                │ --store-raw fallbk│          │                   │\n  └──────────────────┘                └──────────────────┘          └──────────────────┘\n```\n\n| Layer | Status | LLM cost | Hook command | Description |\n|-------|--------|----------|-------------|-------------|\n| Layer 0 | Implemented | 0 | `icm hook post` | Rule-based keyword extraction from tool output |\n| Layer 1 | Implemented | 0 | `icm hook compact` | Extract from transcript before context compression |\n| Layer 2 | Implemented | 0 | `icm hook prompt` | Inject recalled memories on each user prompt |\n\nAll 3 layers are installed automatically by `icm init --mode hook`.\n\n## Benchmarks\n\n### Storage performance\n\n```\nICM Benchmark (1000 memories, 384d embeddings)\n──────────────────────────────────────────────────────────\nStore (no embeddings)      1000 ops      34.2 ms      34.2 µs/op\nStore (with embeddings)    1000 ops      51.6 ms      51.6 µs/op\nFTS5 search                 100 ops       4.7 ms      46.6 µs/op\nVector search (KNN)         100 ops      59.0 ms     590.0 µs/op\nHybrid search               100 ops      95.1 ms     951.1 µs/op\nDecay (batch)                 1 ops       5.8 ms       5.8 ms/op\n──────────────────────────────────────────────────────────\n```\n\nApple M1 Pro, in-memory SQLite, single-threaded. `icm bench --count 1000`\n\n### Agent efficiency\n\nMulti-session workflow with a real Rust project (12 files, ~550 lines). Sessions 2+ show the biggest gains as ICM recalls instead of re-reading files.\n\n```\nICM Agent Benchmark (10 sessions, model: haiku, 3 runs averaged)\n══════════════════════════════════════════════════════════════════\n                            Without ICM         With ICM      Delta\nSession 2 (recall)\n  Turns                             5.7              4.0       -29%\n  Context (input)                 99.9k            67.5k       -32%\n  Cost                          $0.0298          $0.0249       -17%\n\nSession 3 (recall)\n  Turns                             3.3              2.0       -40%\n  Context (input)                 74.7k            41.6k       -44%\n  Cost                          $0.0249          $0.0194       -22%\n══════════════════════════════════════════════════════════════════\n```\n\n`icm bench-agent --sessions 10 --model haiku`\n\n### Knowledge retention\n\nAgent recalls specific facts from a dense technical document across sessions. Session 1 reads and memorizes; sessions 2+ answer 10 factual questions **without** the source text.\n\n```\nICM Recall Benchmark (10 questions, model: haiku, 5 runs averaged)\n══════════════════════════════════════════════════════════════════════\n                                               No ICM     With ICM\n──────────────────────────────────────────────────────────────────────\nAverage score                                      5%          68%\nQuestions passed                                 0/10         5/10\n══════════════════════════════════════════════════════════════════════\n```\n\n`icm bench-recall --model haiku`\n\n### Local LLMs (ollama)\n\nSame test with local models — pure context injection, no tool use needed.\n\n```\nModel               Params   No ICM   With ICM     Delta\n─────────────────────────────────────────────────────────\nqwen2.5:14b           14B       4%       97%       +93%\nmistral:7b             7B       4%       93%       +89%\nllama3.1:8b            8B       4%       93%       +89%\nqwen2.5:7b             7B       4%       90%       +86%\nphi4:14b              14B       6%       79%       +73%\nllama3.2:3b            3B       0%       76%       +76%\ngemma2:9b              9B       4%       76%       +72%\nqwen2.5:3b             3B       2%       58%       +56%\n─────────────────────────────────────────────────────────\n```\n\n`scripts/bench-ollama.sh qwen2.5:14b`\n\n### LongMemEval (ICLR 2025)\n\nStandard academic benchmark — 500 questions across 6 memory abilities, from the [LongMemEval paper](https://arxiv.org/abs/2410.10813) (ICLR 2025).\n\n```\nLongMemEval Results — ICM (oracle variant, 500 questions)\n════════════════════════════════════════════════════════════════\nCategory                        Retrieval     Answer (Sonnet)\n────────────────────────────────────────────────────────────────\nsingle-session-user                100.0%           91.4%\ntemporal-reasoning                 100.0%           85.0%\nsingle-session-assistant           100.0%           83.9%\nmulti-session                      100.0%           81.2%\nknowledge-update                   100.0%           80.8%\nsingle-session-preference          100.0%           50.0%\n────────────────────────────────────────────────────────────────\nOVERALL                            100.0%           82.0%\n════════════════════════════════════════════════════════════════\n```\n\n- **Retrieval** = does ICM find the right information? **100% across all categories.**\n- **Answer** = can the LLM produce the correct answer from retrieved context? Depends on the LLM, not ICM.\n- The retrieval score is the ICM benchmark. The answer score reflects the downstream LLM capability.\n\n`scripts/bench-longmemeval.py --judge claude --workers 8`\n\n### Test protocol\n\nAll benchmarks use **real API calls** — no mocks, no simulated responses, no cached answers.\n\n- **Agent benchmark**: Creates a real Rust project in a tempdir. Runs N sessions with `claude -p --output-format json`. Without ICM: empty MCP config. With ICM: real MCP server + auto-extraction + context injection.\n- **Knowledge retention**: Uses a fictional technical document (the \"Meridian Protocol\"). Scores answers by keyword matching against expected facts. 120s timeout per invocation.\n- **Isolation**: Each run uses its own tempdir and fresh SQLite DB. No session persistence.\n\n### Multi-agent unified memory\n\nAll 17 tools share the same SQLite database. A memory stored by Claude is instantly available to Gemini, Codex, Copilot, Cursor, and every other tool.\n\n```\nICM Multi-Agent Efficiency Benchmark (10 seeded facts, 5 CLI agents)\n╔══════════════╦═══════╦══════════╦════════╦═══════════╦═══════╗\n║ Agent        ║ Facts ║ Accuracy ║ Detail ║ Latency   ║ Score ║\n╠══════════════╬═══════╬══════════╬════════╬═══════════╬═══════╣\n║ Claude Code  ║ 10/10 ║   100%   ║  5/5   ║    ~15s   ║   99  ║\n║ Gemini CLI   ║ 10/10 ║   100%   ║  5/5   ║    ~33s   ║   94  ║\n║ Copilot CLI  ║ 10/10 ║   100%   ║  5/5   ║    ~10s   ║  100  ║\n║ Cursor Agent ║ 10/10 ║   100%   ║  5/5   ║    ~16s   ║   99  ║\n║ Aider        ║ 10/10 ║   100%   ║  5/5   ║     ~5s   ║  100  ║\n╠══════════════╬═══════╬══════════╬════════╬═══════════╬═══════╣\n║ AVERAGE      ║       ║          ║        ║           ║   98  ║\n╚══════════════╩═══════╩══════════╩════════╩═══════════╩═══════╝\n```\n\nScore = 60% recall accuracy + 30% fact detail + 10% speed. **98% multi-agent efficiency.**\n\n## Why ICM\n\n| Capability | ICM | Mem0 | Engram | AgentMemory |\n|-----------|:---:|:----:|:------:|:-----------:|\n| Tool support | **17** | SDK only | ~6-8 | ~10 |\n| One-command setup | `icm init` | manual SDK | manual | manual |\n| Hooks (auto-recall at startup) | 5 tools | none | via MCP | 1 tool |\n| Hybrid search (FTS5 + vector) | 30/70 weighted | vector only | FTS5 only | FTS5+vector |\n| Multilingual embeddings | 100+ langs (768d) | depends | none | English 384d |\n| Knowledge graph | Memoir system | none | none | none |\n| Temporal decay + consolidation | access-aware | none | basic | basic |\n| TUI dashboard | `icm dashboard` | none | yes | web viewer |\n| Auto-extraction from tool output | 3 layers, zero LLM | none | none | none |\n| Feedback/correction loop | `icm_feedback_*` | none | none | none |\n| Runtime | Rust single binary | Python | Go | Node.js |\n| Local-first, zero dependencies | SQLite file | cloud-first | SQLite | SQLite |\n| Multi-agent recall accuracy | **98%** | N/A | N/A | 95.2% |\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Integration Guide](docs/integrations.md) | Setup for all 17 tools: Claude Code, Copilot, Cursor, Windsurf, Zed, Amp, etc. |\n| [Technical Architecture](docs/architecture.md) | Crate structure, search pipeline, decay model, sqlite-vec integration, testing |\n| [User Guide](docs/guide.md) | Installation, topic organization, consolidation, extraction, troubleshooting |\n| [Product Overview](docs/product.md) | Use cases, benchmarks, comparison with alternatives |\n\n## License\n\n[Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtk-ai%2Ficm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frtk-ai%2Ficm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frtk-ai%2Ficm/lists"}