peon-mem 1.0.0 → 1.0.2

package/README.md

@@ -1,10 +1,12 @@
 # 🧠 Peon — a memory brain for your AI coding agents
 
+[![npm](https://img.shields.io/npm/v/peon-mem)](https://www.npmjs.com/package/peon-mem) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![tests](https://img.shields.io/badge/tests-passing-brightgreen)](test/)
+
 **Local-first, hierarchical, self-improving memory for Claude Code, Codex, and any MCP client.**
 
-Your AI forgets everything between sessions. Peon doesn't. It records your sessions, consolidates
-them into typed *beliefs* with an LLM, and injects the relevant ones back into every prompt —
-automatically, from a daemon that never leaves your machine.
+Your AI forgets everything between sessions. Peon doesn't. It records your sessions, uses an
+LLM to consolidate them into typed *beliefs*, and injects the relevant ones back into every
+prompt. It runs as a daemon on your machine, and nothing leaves it.
 
 ```
         PEON GLOBAL BRAIN            ← user-level facts & preferences, inherited everywhere
@@ -14,25 +16,30 @@ automatically, from a daemon that never leaves your machine.
 
 ## Why Peon
 
-- **Hierarchical brains** — one global parent brain (who you are, your rules, your tools) plus an
-  isolated child brain per project. Every injection = project memory + inherited global memory.
-- **Two memory layers, honestly measured** — consolidated *beliefs* (decisions, preferences, facts,
-  artifacts…) for gist, plus an *episodic* verbatim layer that recovers exact details lossy
-  summaries drop (measured on LongMemEval: raw-episodic recall 61% vs belief-only 17%).
-- **Auto capture + auto injection** — Claude Code hooks record messages/events and inject a
-  query-ranked memory block (with an `⚠ MOST RELEVANT` headline) into every prompt. Zero effort.
-- **Cost-gated consolidation** — an LLM distills sessions into beliefs only when enough new
-  memory accumulates. Supersede / merge / conflict-detect; nothing is destructively deleted.
-- **Hybrid retrieval** — lexical + semantic RRF fusion, MMR diversity, reinforcement, recency;
-  query-embedding cache (persisted) so repeat prompts cost nothing.
-- **The Neural Universe** — a live monitor at `localhost:3737/monitor` that renders every belief
-  as a star: projects are galaxies, search makes matches flare, autonomous curation pulses.
-- **A daily self-improvement loop (STL)** — Peon audits itself every day: what it recorded,
-  injected, what failed, what consolidation did — and files a report with a verdict.
-- **Eval-gated development** — a committed results ledger (git SHA + qrels + brain fingerprint per
-  row) so retrieval changes are *proven*, not asserted. Negative results stay documented.
-- **Local-first & locked down** — plain JSONL you can read, loopback-only daemon with
-  DNS-rebinding protection, secret redaction at the injection boundary, path-traversal guards.
+- **Hierarchical brains.** One global parent brain holds who you are, your rules, and your
+  tools. Each project gets an isolated child brain. Every injection carries both.
+- **Two memory layers, honestly measured.** Consolidated *beliefs* (decisions, preferences,
+  facts, artifacts) give you the gist. An *episodic* verbatim layer recovers the exact details
+  that lossy summaries drop. On LongMemEval, raw-episodic recall scored 61% where belief-only
+  scored 17%.
+- **Automatic capture and injection.** Claude Code hooks record messages and events, then
+  inject a query-ranked memory block (with an `⚠ MOST RELEVANT` headline) into every prompt.
+  You never have to remember to save anything.
+- **Cost-gated consolidation.** An LLM distills sessions into beliefs only once enough new
+  memory accumulates. It can supersede, merge, and flag conflicts. Nothing is destructively
+  deleted.
+- **Hybrid retrieval.** Lexical and semantic RRF fusion, MMR diversity, reinforcement, and
+  recency. Query embeddings are cached to disk, so repeat prompts cost nothing.
+- **The Neural Universe.** A live monitor at `localhost:3737/monitor` renders every belief as
+  a star. Projects are galaxies, search makes matches flare, and autonomous curation pulses.
+- **A daily self-audit (STL).** Peon checks itself every day: what it recorded, what it
+  injected, what failed, what consolidation did. Then it files a report with a verdict.
+- **Eval-gated development.** A committed results ledger (git SHA, qrels, and brain
+  fingerprint per row) means retrieval changes are proven, not asserted. Negative results stay
+  documented.
+- **Local-first and locked down.** Plain JSONL you can read, a loopback-only daemon with
+  DNS-rebinding protection, secret redaction at the injection boundary, and path-traversal
+  guards.
 
 
 
@@ -40,17 +47,20 @@ automatically, from a daemon that never leaves your machine.
 ![The Neural Universe — every belief is a star, projects are galaxies](docs/assets/neural-universe.png)
 *The live monitor: 18k real beliefs rendered as stars. Type to make matching beliefs flare; click one to inspect it.*
 
+![Search flare — type a query and matching beliefs light up across every galaxy](docs/assets/search-flare.gif)
+*Ask the field: typing "wulver cluster" makes 400+ matching beliefs flare while the rest dim, and the camera flies to them.*
+
 ## Why "Peon"?
 
-The name comes from Indian offices. Every office had a **peon** — the person who walked desk to
+The name comes from Indian offices. Every office had a **peon**, the person who walked desk to
 desk all day: collect a file from this table, note who needs what, carry it to the next table,
-remember where everything is. Not the boss, not the star — but the one person the whole office
-quietly ran on. Nothing moved without him, and he never forgot where anything was.
+remember where everything is. He wasn't the boss or the star, but the whole office quietly ran
+on him. Nothing moved without him, and he never forgot where anything was.
 
-That's exactly this framework, with AI. Peon walks between your sessions and your projects —
-collects what happened at one desk (a session), files it in the right cabinet (a project brain),
-carries the relevant papers to the next desk before you ask (injection), and keeps the master
-ledger upstairs (the global brain). Quiet clerk. Perfect memory. The office runs on him.
+That's this framework, with AI. Peon walks between your sessions and your projects. It collects
+what happened at one desk (a session), files it in the right cabinet (a project brain), carries
+the relevant papers to the next desk before you ask (injection), and keeps the master ledger
+upstairs (the global brain). Quiet clerk. Perfect memory. The office runs on him.
 
 ## How Peon differs from existing memory tools
 
@@ -66,9 +76,9 @@ ledger upstairs (the global brain). Quiet clerk. Perfect memory. The office runs
 | Observability | **live Neural Universe monitor + daily self-audit (STL) + serve telemetry** | dashboard | — | — | — |
 | Verification | **committed eval ledger; negative results kept** | vendor benchmarks | — | vendor benchmarks | — |
 
-Positioning in one line: mem0/Zep are memory **platforms for products you build**; Peon is a
-memory **brain for the coding agents you already use** — plug into Claude Code/Codex in five
-minutes, watch it think, audit every number.
+The short version: mem0 and Zep are memory platforms for products you build. Peon is memory
+for the coding agents you already use. It plugs into Claude Code or Codex in about five
+minutes, and you can watch it think and audit every number it claims.
 
 ## Quickstart
 
@@ -78,20 +88,21 @@ recommended (consolidation + semantic embeddings); without one Peon still works
 One line:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/VineetV2/peon-mem/main/install.sh | bash
+npm install -g peon-mem && peon-mem install
 ```
 
-(or, once you have the CLI: `npm install -g peon-mem && peon-mem install`)
+(no Node? `curl -fsSL https://raw.githubusercontent.com/VineetV2/peon-mem/main/install.sh | bash`)
 
 The guided setup asks four things:
 
 1. **Where your global brain lives** (default: `~/Library/Application Support/Peon`)
-2. **Which LLM** — OpenRouter (one key, any model) · OpenAI · Anthropic · **Ollama (100% local & free)** · or skip
-3. Installs the **daemon** as an auto-start service
-4. **Detects your AI apps** and wires the MCP server (+ hooks for Claude Code) into the ones you
-   pick — auto-configured: Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor, Windsurf,
-   VS Code (Copilot MCP), Zed, LM Studio; detected with in-app instructions: ChatGPT Desktop,
-   Perplexity Desktop. Every touched config gets a `.peon-backup`.
+2. **Which LLM**: OpenRouter (one key, any model) · OpenAI · Anthropic · **Ollama (100% local
+   & free)** · or skip
+3. Installs the **daemon** as an auto-start service (launchd on macOS, systemd user unit on Linux)
+4. **Detects your AI apps** and wires the MCP server (plus hooks for Claude Code) into the
+   ones you pick. Auto-configured: Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor,
+   Windsurf, VS Code (Copilot MCP), Zed, LM Studio. Detected with in-app instructions: ChatGPT
+   Desktop, Perplexity Desktop. Every touched config gets a `.peon-backup`.
 
 That builds the package, starts the daemon as a service, wires your Claude Code hooks + MCP
 server (with a backup of your settings), and writes a config template. Then add your key to
@@ -122,25 +133,28 @@ node dist/daemon-cli.js              # serves 127.0.0.1:3737
 
 Then wire your agent (the installer prints these filled in for your paths):
 
-- **Claude Code** — add the hook to `~/.claude/settings.json` (SessionStart / UserPromptSubmit /
+- **Claude Code**: add the hook to `~/.claude/settings.json` (SessionStart / UserPromptSubmit /
   SessionEnd → `scripts/claude-peon-hook.mjs`) and the MCP server (`dist/index.js`).
-- **Codex / any MCP client** — register `dist/index.js` as a stdio MCP server; 16 tools
+- **Codex / any MCP client**: register `dist/index.js` as a stdio MCP server; 16 tools
   (`start_session`, `get_context`, `search_memory`, `record_message`, `process_memory`, …).
 
 Open `http://127.0.0.1:3737/monitor` and watch your brain grow.
 
 ## How it works
 
-1. **Record** — hooks stream messages/events/tool-calls into `<project>/.peon/raw/` (append-only).
-2. **Consolidate** — past a size gate, an LLM turns the session delta into typed belief records in
-   `.peon/brain/memories.jsonl` (importance/confidence scores, entities, provenance pointers),
-   reconciling against existing beliefs: supersede, merge, conflict-flag. Recoverable, never deleted.
-3. **Retrieve + inject** — on every prompt, beliefs are ranked (RRF lexical+semantic, MMR,
-   reinforcement) and injected alongside episodic verbatim matches and inherited global beliefs.
-4. **Self-curate** — a background brain pass reinforces recalled beliefs, compresses stale
-   clusters, resolves duplicates — every action logged and undoable.
-5. **Self-audit (STL)** — a daily job reports: recorded / injected / went-wrong / consolidation
-   correctness, with serve-latency telemetry and a health verdict.
+1. **Record.** Hooks stream messages, events, and tool calls into `<project>/.peon/raw/`
+   (append-only).
+2. **Consolidate.** Past a size gate, an LLM turns the session delta into typed belief records
+   in `.peon/brain/memories.jsonl` (importance/confidence scores, entities, provenance
+   pointers), reconciling against existing beliefs: supersede, merge, conflict-flag.
+   Recoverable, never deleted.
+3. **Retrieve + inject.** On every prompt, beliefs are ranked (RRF lexical+semantic, MMR,
+   reinforcement) and injected alongside episodic verbatim matches and inherited global
+   beliefs.
+4. **Self-curate.** A background brain pass reinforces recalled beliefs, compresses stale
+   clusters, and resolves duplicates. Every action is logged and undoable.
+5. **Self-audit (STL).** A daily job reports what was recorded, what was injected, what went
+   wrong, and whether consolidation behaved, with serve-latency telemetry and a health verdict.
 
 
 ## Full install (copy-paste)
@@ -172,7 +186,9 @@ launchctl load ~/Library/LaunchAgents/com.peon.daemon.plist
 curl http://127.0.0.1:3737/health        # → {"ok":true}
 ```
 
-Linux: run `node dist/daemon-cli.js` under systemd (`Restart=always`).
+Linux: the installer writes `~/.config/systemd/user/peon-mem.service` and enables it. Manual
+equivalent: `systemctl --user enable --now peon-mem.service`, plus `loginctl enable-linger $USER`
+so it survives logout. (Linux support is young — [issue #1](https://github.com/VineetV2/peon-mem/issues/1) tracks real-machine reports.)
 
 ### 2. Claude Code — hooks (auto capture + injection)
 
@@ -209,7 +225,7 @@ args = ["/ABSOLUTE/PATH/TO/peon/dist/index.js"]
 PEON_DAEMON_URL = "http://127.0.0.1:3737"
 ```
 
-Codex has no hooks — add usage rules to `~/.codex/AGENTS.md` telling it to call
+Codex has no hooks, so add usage rules to `~/.codex/AGENTS.md` telling it to call
 `start_session` + `get_context` at session start and `record_message` for durable facts
 (example block in [docs/](docs/)).
 
@@ -220,8 +236,8 @@ curl "http://127.0.0.1:3737/context?projectPath=$PWD&query=test"   # JSON contex
 open http://127.0.0.1:3737/monitor                                  # the Neural Universe
 ```
 
-Start a Claude Code session in any project, say something decision-shaped, end the session —
-within a minute the monitor shows the belief. Next session injects it.
+Start a Claude Code session in any project, say something decision-shaped, and end the session.
+Within a minute the monitor shows the belief. The next session injects it.
 
 ### MCP tools exposed
 
@@ -240,17 +256,17 @@ launchctl unload ~/Library/LaunchAgents/com.peon.daemon.plist
 
 ## Troubleshooting / FAQ
 
-- **No injection appearing?** `curl http://127.0.0.1:3737/health`; check hook is registered
-  (`claude` → run any prompt → monitor Systems page shows the request).
-- **431 errors on huge prompts?** Handled — the hook caps the retrieval query at 2k chars.
+- **No injection appearing?** `curl http://127.0.0.1:3737/health`; check the hook is registered
+  (run any prompt in `claude`, then look at the monitor's Systems page for the request).
+- **431 errors on huge prompts?** Handled. The hook caps the retrieval query at 2k chars.
 - **No OpenRouter key?** Everything still runs; retrieval is lexical + episodic only
   (semantic ranking and consolidation need a model). `PEON_EMBEDDING_MODE=ollama` works too.
-- **Cost?** Consolidation is gated (default: fires per ~6k new chars, ~cents/day with
-  flash-lite). Query embeddings are cached to disk — repeats are free.
-- **Multiple machines?** Brains are plain files in your repos — commit `.peon/` if you want
-  memory to travel (redact first: raw layer contains session text).
+- **Cost?** Consolidation is gated (default: fires per ~6k new chars, around cents/day with
+  flash-lite). Query embeddings are cached to disk, so repeats are free.
+- **Multiple machines?** Brains are plain files in your repos. Commit `.peon/` if you want
+  memory to travel (redact first: the raw layer contains session text).
 - **Is my data sent anywhere?** Only consolidation/embedding calls to your configured model
-  provider. No telemetry, no cloud store. Daemon rejects non-loopback callers.
+  provider. No telemetry, no cloud store. The daemon rejects non-loopback callers.
 
 ## Configuration (env)
 
@@ -270,32 +286,129 @@ launchctl unload ~/Library/LaunchAgents/com.peon.daemon.plist
 
 ## Project brains
 
-- A brain lives in `<project>/.peon/` — human-readable JSONL + markdown. Commit it or ignore it;
-  your choice (`.gitignore` ships ignoring it).
-- `.peon/root` marks a brain boundary. New brains are born rooted; a parent directory can never
-  swallow a project's memory.
+- A brain lives in `<project>/.peon/` as human-readable JSONL and markdown. Commit it or
+  ignore it; your choice (`.gitignore` ships ignoring it).
+- `.peon/root` marks a brain boundary. New brains are born rooted, so a parent directory can
+  never swallow a project's memory.
 - The global brain lives in `~/Library/Application Support/Peon/global/` (macOS).
 
+## Using Peon with NO AI at all
+
+Some people want a memory system that never calls a model: no API keys, no local LLM, no
+embeddings. Peon supports that. Pick **skip** in the install wizard, or set two env vars in
+`<memory-home>/.env`:
+
+```
+PEON_AI_MODE=off
+PEON_EMBEDDING_MODE=off
+```
+
+The pipeline looks like this without a model. Hooks still capture everything you do into
+`<project>/.peon/raw/` as plain JSONL. As each event arrives, rule-based extraction files it
+into readable brain files: a line that starts with "we decided" or "always use" lands in
+`decisions.md`, preferences land in `preferences.md`, file paths land in `artifacts.md`. No
+model reads it; it's pattern matching, and you can open the files to see exactly what it
+caught. At your next session start, the hook asks the daemon for context, the daemon ranks
+those records by keyword match, recency, and importance, and injects the best ones into your
+prompt. The only step that disappears entirely is consolidation, the nightly LLM pass that
+compresses raw history into deduplicated beliefs. Without it your memory is a well-indexed
+journal instead of a distilled one. Search still finds things; nothing summarizes them.
+
+What still works (all of it deterministic code, no model anywhere):
+
+- **Capture.** Hooks record every prompt, tool call, and session event to plain JSONL in
+  `<project>/.peon/raw/`.
+- **Real-time brain files.** Decisions, preferences, open questions, and artifacts are written
+  live to readable `.md` files by rule-based extraction as events arrive.
+- **Injection.** Session-start context comes from those real-time files, query-focused and
+  budgeted, same as always.
+- **Search.** Lexical retrieval (RRF over keyword rank, recency, importance, and type priors).
+  No embeddings needed. This is the same degrade path the semantic stack falls back to, so it
+  gets exercised constantly.
+- **Episodic recall.** Verbatim what-was-said lookup is lexical by design, so it is unaffected.
+- **Monitor UI, token tracking, cross-project search, backups.** All model-free.
+
+What you give up: consolidation (raw events are never distilled into deduplicated beliefs, so
+memory grows as an append-only journal), semantic search (paraphrased queries need shared
+keywords), automatic entity extraction, and stale-shadow demotion (it compares embeddings).
+
+Two escape hatches if you want curation without external AI:
+
+1. `process_memory` accepts a pre-built `aiResult`. The coding agent you already run (Claude
+   Code, Codex) can do the distillation itself in-session and hand Peon the structured result.
+   Memory stays curated, and Peon itself never spends a token.
+2. Everything is plain JSONL/Markdown on disk. You can edit beliefs by hand or through the
+   monitor's memory endpoints, and Peon backs up before every mutation.
+
+## Measured: does memory actually save tokens?
+
+A/B test with real `claude -p` sessions: one question per session, same repo, same model.
+ON means Peon hooks active (memory injected at session start). OFF means `PEON_DISABLED=1`,
+so the agent falls back to reading files. 20 questions across procedures, past results,
+decisions, and current-state facts; 15 clean ON/OFF pairs survived tooling issues. Token
+counts come from Claude Code's own session transcripts.
+
+| paired, n=15/arm | ON (Peon) | OFF | delta |
+|---|---|---|---|
+| avg tokens (in+out) | **511** | 878 | **−42%** |
+| median tokens | **225** | 1,048 | **−79%** |
+| cache-read tokens | 81.6k | 110.5k | 1.35× less |
+| cheaper arm | **ON wins 12/15** | | |
+
+Answer quality, graded against repo ground truth: 8 ties, 1 clear Peon win, 5 baseline wins,
+1 where both were weak. The Peon win is the interesting one. A rule that was only ever stated
+in a conversation (a professor's citation policy, from an email) got *"no such rule found"*
+from the baseline; Peon recited it exactly. Conversation-borne knowledge has no file to grep.
+
+Honest caveats: the test repo has unusually good docs (a maintained research log), which makes
+the baseline strong, and most repos aren't like that. n=15 is small. Questions were picked to
+have known answers, not sampled from real usage. The test also exposed two real bugs in Peon
+itself: a stale superseded belief outranking the newer truth, and token rows getting lost when
+consolidation outlived the hook timeout. Both are fixed (stale-shadow demotion at retrieval;
+usage logged before consolidation).
+
 ## Honesty section
 
-Peon's development is eval-gated and keeps its negative results: an associative entity graph was
-built, measured (−2.9% Recall@10), and turned OFF by default. Consolidation is lossy by design —
-that's why the episodic layer exists and is regression-tested. The eval harness + committed
-ledger (`npm run eval`) let you verify retrieval changes on your own brain.
+Peon's development is eval-gated and keeps its negative results. An associative entity graph
+was built, measured (−2.9% Recall@10), and turned OFF by default. Consolidation is lossy by
+design; that's why the episodic layer exists and is regression-tested. The eval harness and
+committed ledger (`npm run eval`) let you verify retrieval changes on your own brain.
 
 ## Security
 
-- Daemon binds `127.0.0.1` only and rejects non-loopback `Host`/`Origin` (DNS-rebinding defense).
+- The daemon binds `127.0.0.1` only and rejects non-loopback `Host`/`Origin` headers
+  (DNS-rebinding defense).
 - Secrets (API keys, tokens, JWTs) are redacted at the injection boundary.
-- Path-traversal guarded; per-project write locks; atomic tmp+rename writes; automatic backups
-  before destructive-adjacent operations. Nothing is hard-deleted.
+- Path traversal is guarded. Writes use per-project locks and atomic tmp+rename, with
+  automatic backups before anything destructive-adjacent. Nothing is hard-deleted.
 
 ## License
 
 MIT © Vineet Vora
 
-## Contributing
+## Contributing — I'd love your help
+
+Peon is built and maintained by one person, and I'm open to help making it better. Issues,
+PRs, ideas, criticism of the architecture, or just telling me where it broke on your machine:
+all of it is useful.
+
+Where help would matter most right now:
+
+- **Windows & Linux support.** The daemon install is macOS launchd today. The systemd and Task
+  Scheduler equivalents need real users to test them.
+- **More agent integrations.** The wizard covers 11 apps, but hooks-level capture (like the
+  Claude Code integration) for Codex, Cursor, and others would make memory richer everywhere.
+- **Retrieval quality.** The eval harness (`npm run eval`) makes experiments cheap: better
+  consolidation prompts, smarter staleness handling, local embedding models worth defaulting
+  to.
+- **Benchmarks.** Run the token A/B on your repo and share the numbers, especially where Peon
+  loses. Negative results are first-class here.
+- **Docs and onboarding.** If the README or the wizard confused you, that confusion is a bug
+  report.
+
+Open an issue at [github.com/VineetV2/peon-mem/issues](https://github.com/VineetV2/peon-mem/issues)
+or send a PR directly.
 
-PRs welcome. Rules of the house: every retrieval/quality change ships with a test and an
-eval-ledger run (`npm run eval`); negative results get documented, not deleted; nothing may
-hard-delete user memory. `npm test` must stay green (255 tests).
+Rules of the house: every retrieval/quality change ships with a test and an eval-ledger run
+(`npm run eval`); negative results get documented, not deleted; nothing may hard-delete user
+memory. `npm test` must stay green.

package/bin/peon-mem.mjs

@@ -8,7 +8,7 @@
  *   peon-mem doctor                        health + config check
  */
 import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,7 +16,8 @@ import { createInterface } from "node:readline/promises";
 
 const PKG = dirname(dirname(fileURLToPath(import.meta.url)));
 const HOME = homedir();
-const MAC = platform() === "darwin";
+// PEON_FORCE_PLATFORM lets CI and maintainers exercise the other OS's install path.
+const MAC = (process.env.PEON_FORCE_PLATFORM || platform()) === "darwin";
 const DEFAULT_HOME = MAC ? join(HOME, "Library", "Application Support", "Peon") : join(HOME, ".local", "share", "peon");
 const PLIST = join(HOME, "Library", "LaunchAgents", "com.peon.daemon.plist");
 const HOOK = join(PKG, "scripts", "claude-peon-hook.mjs");
@@ -156,8 +157,34 @@ function installService(memoryHome) {
       execFileSync("launchctl", ["load", PLIST]);
     });
   } else {
-    log("  → Linux: systemd user unit:");
-    log(`      ExecStart=${NODE} ${DAEMON}\n      WorkingDirectory=${memoryHome}\n      Restart=always`);
+    // Linux: write a real systemd user unit instead of printing a recipe.
+    const unitDir = join(HOME, ".config", "systemd", "user");
+    const unitFile = join(unitDir, "peon-mem.service");
+    const unit = `[Unit]
+Description=Peon memory daemon (local-first memory for AI coding agents)
+After=network.target
+
+[Service]
+ExecStart=${NODE} ${DAEMON}
+WorkingDirectory=${memoryHome}
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+    act("daemon service (systemd user unit) → " + unitFile, () => {
+      mkdirSync(unitDir, { recursive: true });
+      writeFileSync(unitFile, unit);
+      // Enable + start when systemd is actually available; on failure fall back to instructions.
+      const r = spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+      if (r.status === 0) {
+        spawnSync("systemctl", ["--user", "enable", "--now", "peon-mem.service"], { stdio: "ignore" });
+      }
+    });
+    log("  → if the daemon isn't running yet:");
+    log("      systemctl --user daemon-reload && systemctl --user enable --now peon-mem.service");
+    log("      loginctl enable-linger $USER   # keeps it running after logout");
   }
 }
 
@@ -205,7 +232,12 @@ if (cmd === "install") {
     if (!up) log("  → Ollama not running. Install: https://ollama.com  then: ollama pull llama3.2 && ollama pull nomic-embed-text");
     else log("  ✔ Ollama detected on :11434 — pull models if missing: ollama pull llama3.2 && ollama pull nomic-embed-text");
   } else {
-    envLines.push("# no provider configured — Peon runs lexical-only. Re-run `peon-mem install` anytime.");
+    envLines.push(
+      "# No-AI mode: no provider, no model calls, no embeddings. Peon runs as a",
+      "# deterministic memory recorder with lexical retrieval. Re-run `peon-mem install` anytime.",
+      "PEON_AI_MODE=off",
+      "PEON_EMBEDDING_MODE=off"
+    );
   }
   if (existsSync(envFile)) log("  ✔ keeping existing " + envFile);
   else act("write " + envFile, () => writeFileSync(envFile, envLines.join("\n") + "\n"));
@@ -244,6 +276,11 @@ if (cmd === "install") {
   rl?.close();
 } else if (cmd === "uninstall") {
   if (MAC && existsSync(PLIST)) act("stop + remove daemon service", () => spawnSync("launchctl", ["unload", PLIST], { stdio: "ignore" }));
+  const UNIT = join(HOME, ".config", "systemd", "user", "peon-mem.service");
+  if (!MAC && existsSync(UNIT)) act("stop + remove daemon service", () => {
+    spawnSync("systemctl", ["--user", "disable", "--now", "peon-mem.service"], { stdio: "ignore" });
+    rmSync(UNIT, { force: true });
+  });
   const settings = join(HOME, ".claude", "settings.json");
   try {
     const s = JSON.parse(readFileSync(settings, "utf8"));

package/dist/memory-store.js

@@ -7,7 +7,7 @@ import { cosineSimilarity, createEmbeddingClient } from "./embeddings.js";
 import { applyDelete, applyMerge, applyPin, applyUpdate } from "./memory-mutations.js";
 import { runSleepCycle } from "./brain.js";
 import { readdir, rm } from "node:fs/promises";
-import { rankMemoryRecords as rankWithRetrieval, computeGraphActivation, diversifyByMMR } from "./retrieval.js";
+import { rankMemoryRecords as rankWithRetrieval, computeGraphActivation, demoteStaleShadows, diversifyByMMR } from "./retrieval.js";
 import { currentAsOf, changesBetween } from "./temporal.js";
 import { inferCanonicalEntities, buildEntityRegistry, canonicalizeEntity } from "./entities.js";
 import { redactSecrets } from "./injection.js";
@@ -464,14 +464,14 @@ export class PeonMemoryStore {
         const limit = options.limit ?? 50;
         const direct = rankWithRetrieval(records, query, { limit, semantic });
         if (!options.expandGraph || direct.length === 0)
-            return direct;
+            return demoteStaleShadows(direct, semantic?.vectorById);
         // FUSED associative recall: spread activation from the direct hits through the entity graph,
         // then RE-RANK with that activation as a (damped) signal — so a strongly-associated belief can
         // enter the top-K and displace a weak direct hit, instead of being appended out of the window.
         const graphActivation = computeGraphActivation(direct, records);
         if (graphActivation.size === 0)
-            return direct;
-        return rankWithRetrieval(records, query, { limit, semantic, graphActivation });
+            return demoteStaleShadows(direct, semantic?.vectorById);
+        return demoteStaleShadows(rankWithRetrieval(records, query, { limit, semantic, graphActivation }), semantic?.vectorById);
     }
     /**
      * Rank records WITHOUT mutating anything — uses only embeddings already on disk
@@ -497,7 +497,7 @@ export class PeonMemoryStore {
                 // lexical-only on any embedding failure
             }
         }
-        return rankWithRetrieval(records, query, { limit: options.limit ?? 50, semantic });
+        return demoteStaleShadows(rankWithRetrieval(records, query, { limit: options.limit ?? 50, semantic }), semantic?.vectorById);
     }
     async buildSemanticInput(query, records) {
         if (!query || !query.trim() || !this.embeddingClient || !this.embeddingStore || records.length === 0) {

package/dist/monitor.js

@@ -92,6 +92,10 @@ const CLIENT_SCRIPT = String.raw `
   function renderRoute(force){
     var r=currentRoute();
     ROUTES.forEach(function(x){ var p=EL("page-"+x); if(p) p.hidden=(x!==r); });
+    // The project dropdown is CONTEXT, not chrome: it only applies inside a project's
+    // Insights/Memory pages. Global pages (Neural Core / Sectors / Systems) hide it —
+    // switching projects there happens by picking a galaxy or a sector card.
+    var sw=EL("switcher"); if(sw) sw.hidden=!(r==="overview"||r==="memory");
     // Nav highlight: overview/memory belong under "projects".
     ["brain","projects","ops"].forEach(function(x){ var t=EL("nav-"+x); if(t) t.classList.toggle("on", x===r || ((r==="overview"||r==="memory")&&x==="projects")); });
     if(r==="brain"){ loadDashboard(force); renderBrainHome(); }
@@ -184,6 +188,20 @@ const CLIENT_SCRIPT = String.raw `
       ' <span class="stl-dot" style="background:'+dotc+'" title="'+esc(stl)+'"></span>';
   }
 
+  var SPRITES={};
+  function nodeSprite(color, glow){
+    var key=color+(glow?"G":"");
+    if(SPRITES[key]) return SPRITES[key];
+    var pad=glow?10:2, R=6, size=(R+pad)*2;
+    var sc=document.createElement("canvas"); sc.width=size; sc.height=size;
+    var g=sc.getContext("2d");
+    if(glow){ g.shadowColor=color; g.shadowBlur=9; }
+    g.fillStyle=color; g.beginPath(); g.arc(size/2,size/2,R,0,6.29); g.fill();
+    if(glow){ g.fill(); }
+    SPRITES[key]={c:sc,R:R,half:size/2};
+    return SPRITES[key];
+  }
+
   function uniProject(n){ /* world position with slow galaxy rotation */
     var t=(Date.now()-UNI.t0);
     var th=n.th + t*n.cl.spin;
@@ -237,18 +255,22 @@ const CLIENT_SCRIPT = String.raw `
     });
     // nodes
     var hits=UNI.hits, dimOthers=!!(hits&&hits.size);
+    // viewport bounds in world coords (with margin) for culling
+    var vw=W/2/UNI.cam.z+30, vh=H/2/UNI.cam.z+30, vcx=UNI.cam.x, vcy=UNI.cam.y;
     UNI.nodes.forEach(function(n){
       uniProject(n);
+      if(n.x<vcx-vw||n.x>vcx+vw||n.y<vcy-vh||n.y>vcy+vh) return; // offscreen — skip draw
       var tw=0.78+0.22*Math.sin(t/900+n.tw);
       var a=n.a*tw, r=n.r;
       if(dimOthers){ if(hits.has(n.id)){ a=1; r=n.r*1.7; } else a*=0.08; }
       if(n.hot) r*=1.15;
-      ctx.beginPath(); ctx.arc(n.x,n.y,r/Math.sqrt(UNI.cam.z),0,6.29);
+      var glow=(dimOthers&&hits.has(n.id))||n===UNI.hover||n===UNI.selected||n.rec.status==="conflicted";
+      var sp=nodeSprite(n.c, glow);
+      var scale=(r/Math.sqrt(UNI.cam.z))/sp.R;
       ctx.globalAlpha=Math.min(1,a);
-      ctx.fillStyle=n.c;
-      if((dimOthers&&hits.has(n.id))||n===UNI.hover||n===UNI.selected||n.rec.status==="conflicted"){ ctx.shadowColor=n.c; ctx.shadowBlur=12; } else ctx.shadowBlur=0;
-      ctx.fill(); ctx.shadowBlur=0; ctx.globalAlpha=1;
+      ctx.drawImage(sp.c, n.x-sp.half*scale, n.y-sp.half*scale, sp.c.width*scale, sp.c.height*scale);
     });
+    ctx.globalAlpha=1;
     // hover crosshair
     if(UNI.hover){ var hN=UNI.hover; var hr=10/UNI.cam.z;
       ctx.strokeStyle="rgba(234,255,255,.85)"; ctx.lineWidth=1/UNI.cam.z;
@@ -257,14 +279,15 @@ const CLIENT_SCRIPT = String.raw `
       ctx.moveTo(hN.x,hN.y-hr*1.8); ctx.lineTo(hN.x,hN.y-hr); ctx.moveTo(hN.x,hN.y+hr); ctx.lineTo(hN.x,hN.y+hr*1.8); ctx.stroke();
     }
     ctx.restore();
-    uniGridBuild();
+    if(!UNI.lastGrid||t-UNI.lastGrid>250){ uniGridBuild(); UNI.lastGrid=t; }
     // tooltip
     var tip=EL("uni-tip");
     if(tip){ if(UNI.hover){ var sp=uniToScreen(UNI.hover,W,H);
         tip.hidden=false; tip.style.left=Math.min(W-330,Math.max(8,sp.x+16))+"px"; tip.style.top=Math.max(8,sp.y-14)+"px";
         tip.innerHTML='<span class="tt-type" style="color:'+UNI.hover.c+'">'+esc(UNI.hover.rec.type)+'</span> '+esc(clip(UNI.hover.rec.content,140));
       } else tip.hidden=true; }
-    UNI.raf=requestAnimationFrame(uniDraw);
+    // ~30fps is indistinguishable here and halves the draw cost on big brains
+    UNI.raf=requestAnimationFrame(function(){ setTimeout(function(){ UNI.raf=0; uniDraw(); }, 15); });
   }
   function uniToScreen(n,W,H){ return { x:(n.x-UNI.cam.x)*UNI.cam.z+W/2, y:(n.y-UNI.cam.y)*UNI.cam.z+H/2 }; }
   function uniToWorld(sx,sy){ var c=uniCanvas(); var W=c.clientWidth,H=c.clientHeight;
@@ -822,7 +845,7 @@ const DOCUMENT = String.raw `<!doctype html>
   .uniwrap::before{content:""; position:absolute; top:0; left:0; width:16px; height:16px; border-top:1.5px solid var(--line2); border-left:1.5px solid var(--line2); z-index:5; pointer-events:none;}
   .uniwrap::after{content:""; position:absolute; bottom:0; right:0; width:16px; height:16px; border-bottom:1.5px solid var(--line2); border-right:1.5px solid var(--line2); z-index:5; pointer-events:none;}
   #uni{position:absolute; inset:0; width:100%; height:100%; cursor:crosshair;}
-  .uni-search{position:absolute; top:14px; left:50%; transform:translateX(-50%); z-index:6; display:flex; gap:8px; align-items:center; width:min(560px,80%);}
+  .uni-search{position:absolute; top:68px; left:50%; transform:translateX(-50%); z-index:6; display:flex; gap:8px; align-items:center; width:min(560px,72%);}
   .uni-search input{flex:1; padding:9px 16px; border:1px solid rgba(89,227,255,.5); clip-path:var(--cham); background:rgba(3,12,22,.88);
     font-family:var(--mono); font-size:12px; color:var(--cyan-ink); backdrop-filter:blur(8px);}
   .uni-search input:focus{border-color:var(--cyan); outline:none; box-shadow:0 0 22px -6px rgba(89,227,255,.9);}
@@ -831,7 +854,7 @@ const DOCUMENT = String.raw `<!doctype html>
   .uni-hud{position:absolute; z-index:6; font-family:var(--mono); font-size:10px; letter-spacing:.12em; color:var(--muted);
     background:rgba(3,12,22,.72); border:1px solid var(--line); padding:7px 12px; clip-path:var(--cham); backdrop-filter:blur(6px);}
   .uni-hud b{color:var(--cyan-ink); font-weight:700;} .uni-hud b.warn{color:var(--amber);}
-  .uni-hud.tl{top:14px; left:14px;} .uni-hud.tr{top:60px; right:14px;}
+  .uni-hud.tl{top:14px; left:14px; max-width:58%;} .uni-hud.tr{top:14px; right:14px;}
   .stl-dot{display:inline-block; width:8px; height:8px; border-radius:50%; margin-left:6px; vertical-align:-1px; box-shadow:0 0 8px currentColor;}
   .uni-legend{position:absolute; left:14px; bottom:76px; z-index:6; display:flex; flex-wrap:wrap; gap:9px; max-width:70%;}
   .ul{display:inline-flex; align-items:center; gap:5px; font-family:var(--mono); font-size:9px; letter-spacing:.1em; text-transform:uppercase; color:var(--muted);}

package/dist/retrieval.d.ts

@@ -104,3 +104,19 @@ export declare function computeGraphActivation(seeds: RankedMemoryRecord[], pool
  * rankMemoryRecords' graphActivation option, which lets associations compete inside the top-K.
  */
 export declare function expandByEntityGraph(seeds: RankedMemoryRecord[], pool: MemoryRecord[], options?: GraphExpandOptions): RankedMemoryRecord[];
+/**
+ * Stale-shadow demotion. Measured failure mode (token A/B, question x1): recall answered with a
+ * SUPERSEDED architecture description because the old belief was still active, semantically strong,
+ * and outranked the newer truth. When two active beliefs in the ranked window describe the same fact
+ * — near-duplicate vectors, or moderately similar with a shared entity and the same type — but were
+ * written in different eras, the older one is treated as a stale shadow of the newer: its score is
+ * scaled down so the newer belief always outranks it. Nothing is deleted or re-statused here; real
+ * supersession stays the consolidator's job. Pinned records are never demoted.
+ */
+export declare function demoteStaleShadows(ranked: RankedMemoryRecord[], vectorById: Map<string, EmbeddingVector> | undefined, options?: {
+    scan?: number;
+    hardSim?: number;
+    softSim?: number;
+    ageGapMs?: number;
+    penalty?: number;
+}): RankedMemoryRecord[];

package/dist/retrieval.js

@@ -390,3 +390,70 @@ function clamp(value) {
 function roundScore(value) {
     return Math.round(value * 1000) / 1000;
 }
+/**
+ * Stale-shadow demotion. Measured failure mode (token A/B, question x1): recall answered with a
+ * SUPERSEDED architecture description because the old belief was still active, semantically strong,
+ * and outranked the newer truth. When two active beliefs in the ranked window describe the same fact
+ * — near-duplicate vectors, or moderately similar with a shared entity and the same type — but were
+ * written in different eras, the older one is treated as a stale shadow of the newer: its score is
+ * scaled down so the newer belief always outranks it. Nothing is deleted or re-statused here; real
+ * supersession stays the consolidator's job. Pinned records are never demoted.
+ */
+export function demoteStaleShadows(ranked, vectorById, options = {}) {
+    if (!vectorById || vectorById.size === 0 || ranked.length < 2)
+        return ranked;
+    const scan = options.scan ?? 30;
+    const hardSim = options.hardSim ?? 0.8;
+    const softSim = options.softSim ?? 0.6;
+    const ageGapMs = options.ageGapMs ?? 3 * 24 * 60 * 60 * 1000;
+    const penalty = options.penalty ?? 0.35;
+    const window = ranked.slice(0, scan);
+    const recordTime = (item) => timestamp(item.record.updatedAt || item.record.createdAt);
+    const shadowOf = new Map(); // demoted id -> newer id it shadows
+    for (let i = 0; i < window.length; i += 1) {
+        for (let j = i + 1; j < window.length; j += 1) {
+            const a = window[i];
+            const b = window[j];
+            if (a.record.type !== b.record.type)
+                continue;
+            if (a.record.status !== "active" || b.record.status !== "active")
+                continue;
+            const va = vectorById.get(a.record.id);
+            const vb = vectorById.get(b.record.id);
+            if (!va || !vb)
+                continue;
+            const sim = cosineSimilarity(va, vb);
+            if (sim < softSim)
+                continue;
+            const sharedEntity = a.record.entities.some((e) => b.record.entities.includes(e));
+            if (sim < hardSim && !sharedEntity)
+                continue;
+            const [older, newer] = recordTime(a) <= recordTime(b) ? [a, b] : [b, a];
+            if (recordTime(newer) - recordTime(older) < ageGapMs)
+                continue;
+            if (older.record.pinned)
+                continue;
+            if (!shadowOf.has(older.record.id))
+                shadowOf.set(older.record.id, newer.record.id);
+        }
+    }
+    if (shadowOf.size === 0)
+        return ranked;
+    return ranked
+        .map((item) => {
+        const newerId = shadowOf.get(item.record.id);
+        if (!newerId)
+            return item;
+        return {
+            ...item,
+            score: roundScore(item.score * penalty),
+            explanation: `${item.explanation}; stale shadow of newer belief ${newerId}`,
+            reasons: [...item.reasons, { kind: "status", label: `stale shadow of ${newerId}`, score: 0 }]
+        };
+    })
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        return timestamp(right.record.updatedAt) - timestamp(left.record.updatedAt);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peon-mem",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -21,7 +21,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.23.0"
   },
-  "description": "Local-first hierarchical memory brain for AI coding agents — auto-capture, LLM consolidation into beliefs, hybrid retrieval, per-prompt injection, a living Neural Universe monitor, and a daily self-improvement loop. Works with Claude Code, Codex, and any MCP client.",
+  "description": "Local-first hierarchical memory brain for AI coding agents \u2014 auto-capture, LLM consolidation into beliefs, hybrid retrieval, per-prompt injection, a living Neural Universe monitor, and a daily self-improvement loop. Works with Claude Code, Codex, and any MCP client.",
   "license": "MIT",
   "keywords": [
     "memory",
@@ -36,7 +36,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/VineetV2/peon-mem"
+    "url": "git+https://github.com/VineetV2/peon-mem.git"
   },
   "engines": {
     "node": ">=20"
@@ -53,5 +53,6 @@
     "docs/assets",
     "README.md",
     "LICENSE"
-  ]
-}
+  ],
+  "mcpName": "io.github.VineetV2/peon-mem"
+}

package/scripts/claude-peon-hook.mjs

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { appendFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createReadStream as fsCreateReadStream, existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { createInterface } from "node:readline";
 
-// Hard off-switch (for A/B testing). When PEON_DISABLED is set, the hook does
-// nothing at all — no recording, no context injection, no daemon calls — so the
-// session runs purely on the cloud model with zero Peon involvement.
-if (/^(1|true|yes|on)$/i.test(process.env.PEON_DISABLED || "")) process.exit(0);
+// Hard off-switch (for A/B testing). When PEON_DISABLED is set, Peon does nothing —
+// no injection, no recording, no daemon calls — EXCEPT counting the session's token
+// usage on Stop/SessionEnd, because the OFF arm's whole purpose is to be the baseline
+// in the token A/B comparison. (Handled inside the main block below.)
+const PEON_OFF = /^(1|true|yes|on)$/i.test(process.env.PEON_DISABLED || "");
 
 const daemonUrl = (process.env.PEON_DAEMON_URL || "http://127.0.0.1:3737").replace(/\/$/, "");
 const stateDir =
@@ -39,6 +40,12 @@ const PEON_FIRST_DIRECTIVE =
 // so it is initialized before the top-level await block calls getProjectContext.
 const MAX_CONTEXT_QUERY_CHARS = 2000;
 
+// Token A/B ledger paths — declared BEFORE the top-level await block (everything the main
+// block touches must be initialized first, or the reference throws a silent TDZ error;
+// that exact bug made token tracking a no-op for weeks).
+const TOKEN_AB_LOG = join(homedir(), "Library", "Application Support", "Peon", "token-ab-log.jsonl");
+const TOKEN_AB_LOGGED_SESSIONS = join(homedir(), "Library", "Application Support", "Peon", "token-ab-sessions.json");
+
 // Resolve any working directory to its ONE project brain, so memory never fragments:
 //   1. collapse git-worktree paths to the repo root (…/.claude/worktrees/x → repo)
 //   2. walk UP to the TOPMOST ancestor that already holds a Peon brain (.peon), bounded by
@@ -88,6 +95,11 @@ try {
     readText(input, ["session_id", "sessionId", "conversation_id", "conversationId", "thread_id", "threadId"]) ||
     externalSessionId;
 
+  if (PEON_OFF) {
+    if (eventName === "Stop" || eventName === "SessionEnd") await trackTokenUsage(input, projectPath, externalSessionId);
+    process.exit(0);
+  }
+
   if (eventName === "SessionStart") {
     await ensurePeonSession({ projectPath, externalSessionId, client: hookClient });
     const context = await getProjectContext(projectPath, "recent project context decisions artifacts current work");
@@ -159,14 +171,17 @@ try {
     // A response TURN finished — capture the summary and let Peon consolidate,
     // but keep the session ALIVE. Stop fires after every turn; the Claude session
     // (and the Peon session) continues across turns and only ends on SessionEnd.
+    // Token tracking runs FIRST: consolidation below can outlive the hook timeout
+    // ("Hook cancelled"), which used to silently drop the token ledger row.
+    await trackTokenUsage(input, projectPath, externalSessionId);
     const finalMessage = extractAssistantSummary(input);
     if (finalMessage.trim()) {
       await recordWithSession({ projectPath, externalSessionId, client: hookClient }, (sessionId) =>
         postJson("/events", { sessionId, type: "assistant_summary", content: finalMessage.slice(0, 2000) }));
     }
     await postJson("/process/auto", { projectPath, trigger: "turn_end" }).catch(() => undefined);
-    await trackTokenUsage(input, projectPath, externalSessionId);
   } else if (eventName === "SessionEnd") {
+    await trackTokenUsage(input, projectPath, externalSessionId);
     const finalMessage = extractAssistantSummary(input);
     if (finalMessage.trim()) {
       await recordWithSession({ projectPath, externalSessionId, client: hookClient }, (sessionId) =>
@@ -180,7 +195,6 @@ try {
       // stale session id gets replayed forever and recording silently dies.
       await removeSession(externalSessionId);
     }
-    await trackTokenUsage(input, projectPath, externalSessionId);
   }
 } catch (error) {
   await appendLocalError({
@@ -400,16 +414,11 @@ function safeName(value) {
   return String(value).replace(/[^a-zA-Z0-9_.-]/g, "_");
 }
 
-const TOKEN_AB_LOG = join(homedir(), "Library", "Application Support", "Peon", "token-ab-log.jsonl");
-
-const TOKEN_AB_LOGGED_SESSIONS = join(homedir(), "Library", "Application Support", "Peon", "token-ab-sessions.json");
-
 async function recordTokenUsage({ projectPath, externalSessionId, transcriptPath }) {
   try {
-    // Only log once per session — Stop fires on every response turn, not just session end.
-    const logged = JSON.parse(await readFile(TOKEN_AB_LOGGED_SESSIONS, "utf8").catch(() => "[]"));
-    if (logged.includes(externalSessionId)) return;
-
+    // Upsert per session: Stop fires after every turn, so each firing re-reads the full
+    // transcript and replaces this session's row — the last Stop leaves the final totals.
+    // (The old once-per-session gate froze turn-1 partials and dropped the rest.)
     const totals = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0, model: "unknown" };
     const rl = createInterface({ input: fsCreateReadStream(transcriptPath), crlfDelay: Infinity });
     for await (const line of rl) {
@@ -425,6 +434,9 @@ async function recordTokenUsage({ projectPath, externalSessionId, transcriptPath
         if (obj?.message?.model) totals.model = obj.message.model;
       } catch { /* skip malformed lines */ }
     }
+    // A Stop can fire before any usage lines hit the transcript — never write an empty row.
+    if (totals.input + totals.output === 0) return;
+
     const peonEnabled = !/^(1|true|yes|on)$/i.test(process.env.PEON_DISABLED || "");
     const record = {
       ts: new Date().toISOString(),
@@ -438,13 +450,20 @@ async function recordTokenUsage({ projectPath, externalSessionId, transcriptPath
       cacheCreateTokens: totals.cacheCreate,
       totalTokens: totals.input + totals.output,
     };
+    if (process.env.PEON_AB_TAG) record.tag = process.env.PEON_AB_TAG;
     const dir = join(homedir(), "Library", "Application Support", "Peon");
     await mkdir(dir, { recursive: true });
-    await appendFile(TOKEN_AB_LOG, JSON.stringify(record) + "\n", "utf8");
-    // Mark session as logged (keep last 500 to avoid unbounded growth)
-    logged.push(externalSessionId);
-    await writeFile(TOKEN_AB_LOGGED_SESSIONS, JSON.stringify(logged.slice(-500)), "utf8");
-  } catch { /* non-fatal */ }
+    // Rewrite the log with this session's previous rows dropped — file stays one row per session.
+    const existing = (await readFile(TOKEN_AB_LOG, "utf8").catch(() => ""))
+      .split("\n").filter(Boolean)
+      .filter((line) => {
+        try { return JSON.parse(line).sessionId !== externalSessionId; } catch { return true; }
+      });
+    existing.push(JSON.stringify(record));
+    const tmp = TOKEN_AB_LOG + ".tmp";
+    await writeFile(tmp, existing.slice(-2000).join("\n") + "\n", "utf8");
+    await rename(tmp, TOKEN_AB_LOG);
+  } catch (e) { if (process.env.PEON_AB_DEBUG) console.error("AB-ERR:", e && e.message); }
 }
 
 async function appendLocalError(error) {