kimetsu-pi 0.1.0 → 0.1.2

package/README.md

@@ -1,17 +1,59 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/RodCor/kimetsu/main/docs/assets/kimetsu-logo.png" alt="Kimetsu logo" width="180" />
+
 # kimetsu-pi
 
-Kimetsu brain as a Pi.dev package: persistent, cross-session memory for the Pi coding agent.
+### Memory for your Pi agent that gets sharper every run.
 
-## What it is
+</div>
+
+**kimetsu-pi** brings [Kimetsu](https://kimetsu.dev) — a local-first memory brain
+for coding agents — to the [Pi](https://pi.dev) 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](https://kimetsu.dev)**.
 
-Pi (the Pi.dev coding agent) has no MCP support, so this package brings Kimetsu's
-persistent memory to Pi through Pi's own extension points instead:
+## What it is
 
-- **Extension** (`extensions/kimetsu.ts`) — a TypeScript Pi extension that hooks into
-  Pi lifecycle events (`session_start`, `agent_end`, `session_shutdown`) and shells out
-  to the `kimetsu` binary to warm, load, and persist brain context around each session.
-- **Skill** (`skills/kimetsu-brain/SKILL.md`) — a Pi skill that teaches the agent when
-  and how to consult and record memories during a task.
+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`, `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 |
 
 ## Prerequisite
 
@@ -21,11 +63,9 @@ The `kimetsu` binary must be on `PATH`. Install it with:
 npm install -g kimetsu-ai
 ```
 
-or via cargo, or one of the prebuilt archives — see
-[github.com/RodCor/kimetsu](https://github.com/RodCor/kimetsu) for all install options.
-
-If the binary is not found, the extension silently no-ops on every lifecycle hook —
-Pi's startup and session behavior are completely unaffected.
+or via cargo or a prebuilt archive — see the
+**[install guide](https://kimetsu.dev/docs/)** for all options. If the binary is
+absent, the extension silently no-ops and Pi is unaffected.
 
 ## Install
 
@@ -49,10 +89,11 @@ npm test
 npm run typecheck
 ```
 
-## License
+## Links
 
-MIT OR Apache-2.0
+- **Website & docs:** [kimetsu.dev](https://kimetsu.dev)
+- **Main project:** [github.com/RodCor/kimetsu](https://github.com/RodCor/kimetsu)
 
-## See also
+## License
 
-Main project: [github.com/RodCor/kimetsu](https://github.com/RodCor/kimetsu)
+MIT OR Apache-2.0

package/extensions/kimetsu.ts

@@ -8,16 +8,32 @@ import { spawn } from "node:child_process";
 
 function kimetsuExec(args: string[]): Promise<void> {
   return new Promise((resolve) => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      resolve();
+    };
     try {
       const child = spawn("kimetsu", args, {
         stdio: "ignore",
         shell: false,
         windowsHide: true,
       });
-      child.on("error", () => resolve()); // binary not on PATH — silent no-op
-      child.on("close", () => resolve());
+      // A hung binary must never stall the lifecycle hook: cap the wait and
+      // kill the child if it overruns. unref() so the timer alone can't keep
+      // the host process alive.
+      timer = setTimeout(() => {
+        child.kill();
+        done();
+      }, 10000);
+      if (typeof timer.unref === "function") timer.unref();
+      child.on("error", done); // binary not on PATH — silent no-op
+      child.on("close", done); // finished, or killed by the timeout above
     } catch {
-      resolve(); // any unexpected error — silent no-op
+      done(); // any unexpected error — silent no-op
     }
   });
 }

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "kimetsu-pi",
-  "version": "0.1.0",
-  "description": "Kimetsu brain as a Pi.dev package — persistent cross-session memory for the Pi coding agent.",
-  "keywords": ["pi-package", "pi", "kimetsu", "memory", "extension", "skill"],
-  "homepage": "https://github.com/RodCor/kimetsu-pi#readme",
+  "version": "0.1.2",
+  "description": "Kimetsu brain as a Pi.dev package — local-first, cross-session memory for the Pi coding agent that gets sharper every run.",
+  "keywords": ["pi-package", "pi", "kimetsu", "memory", "brain", "rag", "mcp", "extension", "skill"],
+  "homepage": "https://kimetsu.dev",
   "repository": { "type": "git", "url": "git+https://github.com/RodCor/kimetsu-pi.git" },
   "license": "MIT OR Apache-2.0",
   "type": "module",
   "pi": {
     "extensions": ["./extensions"],
-    "skills": ["./skills"]
+    "skills": ["./skills"],
+    "image": "https://raw.githubusercontent.com/RodCor/kimetsu/main/docs/assets/kimetsu-logo.png"
   },
   "files": ["extensions/", "skills/", "README.md", "LICENSE"],
   "engines": { "node": ">=16" },