kimetsu-pi

Memory for your Pi agent that gets sharper every run.

kimetsu-pi brings Kimetsu — a local-first memory brain for coding agents — to the Pi coding agent.

Coding agents are brilliant and forgetful: every session starts from zero. Kimetsu is a sidecar brain that captures the lessons your agent earns, learns which ones actually help, and hands them back before the next task. The memory pipeline makes no LLM calls — storage and retrieval are 100% local, free, and offline-capable.

Learn more at kimetsu.dev.

What it is

Pi has no MCP layer, so this package brings Kimetsu to Pi through Pi's own extension points:

• Extension (extensions/kimetsu.ts) — a TypeScript Pi extension that hooks Pi lifecycle events (session_start, before_agent_start, agent_end, session_shutdown) and shells out to the kimetsu binary to warm, load, and persist brain context around each session. Each call is capped by a timeout, so a slow or hung binary never stalls Pi. If the binary is not on PATH, every hook silently no-ops and Pi is completely unaffected.
• Skill (skills/kimetsu-brain/SKILL.md) — a Pi skill that teaches the agent when and how to consult and record memories during a task.

Why Kimetsu

• Remembers what matters — conventions, failure patterns, the exact command that regenerates your schema. Captured once, retrieved by meaning.
• Speaks first — proactive session-start digests, episodic resumes, and pre-task context, so the agent's first turn already knows your repo.
• Learns what helps — cited memories get promoted; stale advice decays and is pruned.
• Model-free retrieval — FTS5 + local embeddings + local reranking. Zero API cost, works offline.
• Stays yours — one SQLite file per project. No cloud, no vector DB, no telemetry. Back it up with cp.

Benchmarks

| | | |---:|---| | 89.4% | LoCoMo, the long-conversation memory benchmark | | 83.0% | LongMemEval, the public long-term-memory benchmark | | 73.3% | BEAM 100K memory benchmark | | 13× | cheaper per solved task ($0.19 vs $2.47 on a Terminal-Bench slice) | | ~1M | memories in ~3 GB RAM with sub-2s retrieval, one SQLite file |

Prerequisites

Install current Pi (Node.js 22.19 or newer):

npm install -g @earendil-works/pi-coding-agent

The kimetsu v2.7.0 or newer binary must be on PATH. Install it with:

npm install -g kimetsu-ai

or via cargo or a prebuilt archive — see the install guide for all options. If the binary is absent, the extension silently no-ops and Pi is unaffected.

Install

pi install npm:kimetsu-pi

What it does on each event

| Pi lifecycle event | Kimetsu command run | | --- | --- | | session_start | kimetsu brain warm | | before_agent_start | kimetsu brain context-hook --warm-on-first-prompt | | agent_end | kimetsu brain stop-hook | | session_shutdown | kimetsu brain session-end-hook |

The extension uses Pi's SessionManager identity, so /new, /resume, and /fork keep separate Kimetsu warm-start and deduplication state. It also passes Pi's persisted JSONL transcript to the stop and session-end hooks, enabling Kimetsu's configured distiller and automatic work-episode capture.

Development

npm install
npm test
npm run typecheck

Links

• Website & docs: kimetsu.dev
• Main project: github.com/RodCor/kimetsu

License

MIT OR Apache-2.0