pi-icm-hook

A Pi extension wrapping ICM — persistent, semantic, cross-session memory via the same SQLite database your editors already use.

Why

Pi forgets between sessions. You wire up AGENTS.md with CLI instructions, but it's fragile — the model has to remember to call icm recall and icm store at the right times. Miss one, and context is lost.

This extension makes ICM native to Pi:

• 8 tools — icm_recall, icm_store, icm_update, icm_forget, icm_consolidate, icm_health, icm_topics, icm_stats
• Auto-recall — memories injected into the system prompt at the start of every agent cycle
• Auto-save — regex-based trigger detection saves decisions, fixes, preferences, learnings, and gotchas automatically
• Footer indicator — 📚 N · 💾 topic on every response, showing recall count and what was saved

One SQLite file. Shared with Hermes, Claude Code, Cursor, OpenCode, Codex CLI — all your editors.

Quickstart

Three steps, under two minutes if icm is already on your $PATH.

1. Verify ICM is installed.

icm --version    # expected: e.g. "icm 0.10.43"

If not found: https://github.com/rtk-ai/icm

2. Install the extension.

pi install npm:pi-icm-hook

From local:

pi install ./icm.ts

3. Restart Pi. The footer 📚 N · 💾 — at the end of responses confirms it's active.

That's it. No config file, no daemon, no prompts to copy-paste.

Tools

| Tool | Description | |---|---| | icm_recall | Search memories by query, topic, or both. Returns ranked results. | | icm_store | Save a memory with topic, content, importance, and keywords. | | icm_update | Edit an existing memory by ID. | | icm_forget | Delete a memory by ID or clear an entire topic. | | icm_consolidate | Merge all memories in a topic into a single summary. | | icm_health | Audit memory health — staleness, consolidation needs. | | icm_topics | List all memory topics. | | icm_stats | Global memory statistics (count, average weight, date range). |

Lifecycle Hooks

| Event | Action | |---|---| | session_start | Checks ICM availability. Gracesful degrade if missing. | | before_agent_start | Recalls memories matching the user's prompt. Injects them + a save directive into the system prompt. | | message_end | Runs trigger detection on the assistant's response. Auto-saves decisions, fixes, preferences, learnings, and gotchas. Injects the 📚 N · 💾 topic footer. | | session_before_compact | Saves a context marker before compaction truncates the session. | | session_shutdown | Cleanup. |

Auto-Save Triggers

The extension detects these categories and saves to the corresponding ICM topic:

| Trigger | Topic Template | Example | |---|---|---| | Error resolved | errors-resolved-{project} | errors-resolved-pi-icm-hook | | Decision made | decisions-{project} | decisions-chatterbox | | Preference discovered | preferences | preferences (global) | | Learning / insight | learnings-{project} | learnings-moon-backend | | Gotcha / pitfall | gotchas-{project} | gotchas-cloudflare-wrangler |

{project} is derived automatically from basename(cwd).

Configuration

Edit constants at the top of icm.ts:

const DEFAULT_CONFIG = {
  recallLimit: 5,           // top-K memories to recall (default: 5)
  prefetchEnabled: true,    // auto-inject on every agent cycle
  defaultImportance: "high", // default for auto-saves
  readTimeoutMs: 3000,      // timeout for recall/health/topics/stats
  writeTimeoutMs: 5000,     // timeout for store/update/forget/consolidate
  indicatorEnabled: true,   // show 📚 · 💾 footer on responses
};

How It Works

User prompt
  │
  ├── before_agent_start
  │   ├── icm recall <prompt> --format json --limit 5
  │   ├── Format recalled memories
  │   └── Inject into system prompt + save directive
  │
  ├── LLM generates response
  │   ├── Can call icm_recall / icm_store / etc. as tools
  │   └── ...
  │
  └── message_end
      ├── Detect triggers in assistant text (regex, no LLM cost)
      ├── Fire-and-forget icm store for each match
      └── Inject 📚 N · 💾 topic footer

No LLM calls wasted on memory management. Triggers are pure regex, recall is a single subprocess call at the start of each prompt cycle.

Related Projects

• hermes-icm-memory — Same patterns, for the Hermes agent (Python)
• ICM — The memory engine (Rust)
• Pi — The coding agent runtime

License

BSD 3-Clause — see LICENSE.