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.

Kimetsu carries useful lessons between sessions and retrieves relevant project knowledge before a task. Storage and retrieval run locally without LLM API calls. Automatic lesson extraction can use a configured model; its cost and connectivity depend on that configuration.

Learn more at kimetsu.dev.

What it is

This package connects Kimetsu through Pi's native extension and skill interfaces:

• Extension (extensions/kimetsu.ts) — a TypeScript Pi extension that hooks Pi lifecycle events and invokes the kimetsu binary to warm, load, and persist brain context around each session. Interactive hooks have a 10-second timeout; session saving has a separate five-minute limit for model-based distillation. 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 to reuse injected context, correct outdated memories, and cite memories that actually helped during a task.

What's new in 0.1.5

• Pi 1.2.0 compatibility: custom-triggered turns expire old memory without treating background notifications as user prompts.
• Integration tests exercise Pi's real loader, event runner, model-message conversion, and session saving with the Kimetsu 2.8.0 CLI in isolated fixtures.
• Refreshed development dependencies and removed the source-map-js advisory.

Previously in 0.1.4

• Fresh memory per task: older raw injections are excluded from model requests and new summaries, including after corrections, queued user messages, and branch changes.
• Session saving gets up to five minutes, while interactive hooks retain their 10-second limits.
• Updated guidance for memory reuse, corrections, and usefulness feedback.
• Verified with Pi 0.85.1 and Kimetsu 2.8.0 on Linux, macOS, and Windows; updated dependencies, isolated integration tests, and protected CI and release gates.

Why Kimetsu

• Remembers project knowledge — conventions, failure patterns, and useful commands stay available across sessions.
• 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 — citations provide usefulness feedback; maintenance identifies memories that may need pruning.
• Local retrieval — lexical search in the default lean build, with optional local embeddings and reranking. No LLM API calls for retrieval.
• Stays yours — a local SQLite brain per project, with optional user-wide memory. No hosted vector database is required.

For Kimetsu's benchmark results, datasets, and evaluation limits, see the core project's benchmark notes. Those evaluate the memory system; this package's CI verifies its Pi integration.

Prerequisites

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

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

The kimetsu binary must be on PATH. Kimetsu 2.8.0 is the tested release for this package; the CLI integration requires at least 2.7.0. 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

From the Git project whose memory you want to use, initialize Kimetsu if that project does not already have a brain:

cd /path/to/your/project
kimetsu init
kimetsu brain status

Start Pi in that project, or run /reload in an existing Pi session to load the extension and skill. Confirm installation with pi list.

Upgrade

For an installation that follows the latest npm version:

pi update npm:kimetsu-pi

For a pinned installation, select this version explicitly:

pi install npm:[email protected]

Then restart Pi or run /reload. Pi package updates and Kimetsu CLI updates are separate; use npm install -g kimetsu-ai@latest if the CLI also needs updating.

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 | | context | Filters earlier Kimetsu injections out of each model request | | session_before_compact, session_before_tree | Excludes Kimetsu injections from new summaries | | session_tree | Expires the previous branch's active injection | | 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.

Only the current task's Kimetsu injection is sent to the model. Older injections remain in the saved transcript but are filtered from subsequent model requests, including when retrieval returns no context. Ordinary conversation and other extensions' messages are preserved. Queued user messages expire the previous injection; tool continuations keep it. New compaction and branch summaries omit raw Kimetsu injections. This does not rewrite earlier assistant answers or existing summaries.

Session saving can make two model calls, so it may take longer than retrieval. Pi awaits it when closing or switching a session, for up to five minutes; it normally finishes sooner. The longer deadline applies only to session-end-hook. Prompt retrieval, warm-up, and stop-hook retain their 10-second limits. Saving remains best-effort and needs a clean shutdown.

The bundled skill teaches the agent to reuse relevant injected context, fetch missing evidence, correct existing memories, and cite only memories that actually helped. Run kimetsu brain status from the project directory to inspect the brain. Automatic model-based distillation requires configuration.

Development

npm ci
npm test
npm run typecheck

To run the optional CLI integration test, set KIMETSU_TEST_BINARY to the absolute path of a Kimetsu 2.8.0+ executable named kimetsu (kimetsu.exe on Windows), then run npm run test:integration. This command fails if the binary is missing. It creates an isolated temporary brain, uses lexical retrieval without model calls, and verifies correction, context filtering, citation, and session persistence.

The fixture anchors a new Git repository and gives subprocesses temporary homes, caches, and user-brain paths. It removes inherited Git/Kimetsu overrides and credentials before initialization. Never run integration commands against your normal project or home brain.

CI requires the real CLI test on Linux, macOS, and Windows using checksum-pinned Kimetsu 2.8.0 binaries and the minimum supported Node version. The required checks gate also requires typechecking, tests, the dependency audit, and package dry-run. Release tags must match the package version and point to a commit on main with successful CI. Wait for that commit's CI before tagging; a release started too early must be rerun after CI passes.

Links

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

License

MIT OR Apache-2.0