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.