peon-mem 1.0.1 → 1.0.3

package/README.md

@@ -1,12 +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-255%20passing-brightgreen)](test/)
+[![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
@@ -16,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.
 
 
 
@@ -43,19 +48,20 @@ automatically, from a daemon that never leaves your machine.
 *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
 
@@ -71,9 +77,29 @@ 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.
+
+## Your agents share one brain
+
+If you run more than one coding agent — Claude Code and Codex, say — they usually each live in
+their own bubble. Whatever you work out with one is gone when you switch to the other.
+
+Point them at the same project and Peon dissolves that wall. Both agents resolve to the same
+`.peon/` brain (Peon canonicalizes the project path, so the hook, a direct MCP call, and Codex
+all land on one store). So the memory flows between them:
+
+- Codex works out how your build pipeline runs and records it. Next time you open Claude Code
+  in that repo, it's already in the injected context.
+- Claude Code hits a gotcha and files it. Codex sees it the moment it calls `get_context` or
+  `search_memory`.
+- The global brain sits above both, so your preferences and rules follow you into every agent,
+  in every project.
+
+They aren't chatting in real time. It's a shared notebook both write in and both read from, so
+a decision made in one agent shows up in the other without you re-explaining it. One project,
+one memory, however many agents.
 
 ## Quickstart
 
@@ -91,12 +117,13 @@ npm install -g peon-mem && peon-mem install
 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
@@ -127,25 +154,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)
@@ -177,7 +207,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)
 
@@ -214,7 +246,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/)).
 
@@ -225,8 +257,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
 
@@ -245,17 +277,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)
 
@@ -275,55 +307,67 @@ 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, fully deterministic. Peon supports that as a first-class mode: pick **skip** in the
-install wizard, or set two env vars in `<memory-home>/.env`:
+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
 ```
 
-**What still works (all of it deterministic code, no model anywhere):**
+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.
 
-- **Capture** — hooks record every prompt, tool call, and session event to plain JSONL in
+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
+- **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
+- **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 + type priors).
-  No embeddings needed; this is the same degrade path the semantic stack falls back to.
-- **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.
+- **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 —
+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:**
+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
+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. Peon backs up before every mutation.
+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, real `claude -p` sessions, one question per session, same repo, same model. ON = Peon
-hooks active (memory injected at session start), OFF = `PEON_DISABLED=1` (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 read from Claude Code's own
-session transcripts.
+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 |
 |---|---|---|---|
@@ -332,38 +376,60 @@ session transcripts.
 | 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 both-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) — the baseline answered *"no such
-rule found"*, Peon recited it exactly. Conversation-borne knowledge has no file to grep.
+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 — most repos aren't like that; n=15 is small; questions were picked to have
-known answers, not sampled from real usage. Two weaknesses this test exposed — a stale
-superseded belief outranking the newer truth, and token rows lost when consolidation outlived
-the hook timeout — are both fixed (stale-shadow demotion at retrieval; usage logged before
-consolidation).
+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");
   }
 }
 
@@ -249,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/brain.js

@@ -53,12 +53,25 @@ export function resolveConflicts(records, now, protectGlobalScope = true) {
     // to active, loser archived (recoverable).
     const candidates = records.filter((r) => r.status === "active" || r.status === "conflicted");
     const conflicts = detectMemoryConflicts(candidates);
-    if (conflicts.length === 0)
-        return { records: [...records], actions: [] };
     const byId = new Map(records.map((r) => [r.id, r]));
     const archived = new Set();
     const reactivated = new Set();
     const actions = [];
+    // Every belief that is part of a CURRENTLY-detected conflict. Anything still flagged
+    // "conflicted" but not in this set is an orphan — the consolidator (or an older, looser
+    // detector) benched it, but it no longer collides with anything. Left alone it stays out of
+    // recall forever; the July→August backlog was 100+ such orphans. Reactivate them below.
+    const inLiveConflict = new Set();
+    for (const c of conflicts) {
+        inLiveConflict.add(c.leftId);
+        inLiveConflict.add(c.rightId);
+    }
+    for (const r of records) {
+        if (r.status === "conflicted" && !inLiveConflict.has(r.id)) {
+            reactivated.add(r.id);
+            actions.push({ type: "resolve_conflict", detail: `reactivated stale conflict flag on "${r.content.slice(0, 40)}"`, affectedIds: [r.id] });
+        }
+    }
     for (const conflict of conflicts) {
         const left = byId.get(conflict.leftId);
         const right = byId.get(conflict.rightId);

package/dist/entities.js

@@ -18,6 +18,25 @@
 const SRC_ROOTS = new Set(["src", "lib", "scripts", "test", "tests", "app", "apps", "packages", "dist", "bin"]);
 const FILE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs|json|md|mdx|html|css|scss|py|ipynb|pdf|txt|yml|yaml|toml|sh|sql|rs|go|java|rb|c|cpp|h)$/i;
 const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*(?:[.#][A-Za-z_$][\w$]*)*$/;
+// Bare common words that are never useful DOMAIN entities. Without this gate a lowercase token
+// like "not" / "use" / "no" falls through the identifier branch and becomes a domain concept —
+// then two unrelated beliefs that merely both contain that word "share an entity" and get
+// false-flagged as conflicting. Only applies to plain lowercase words: file paths, product
+// acronyms (BIRD, DTS-SQL), and code symbols carry caps/digits/separators and never land here.
+const ENTITY_STOPWORDS = new Set([
+    "the", "this", "that", "these", "those", "a", "an", "it", "its", "we", "i", "you", "he", "she",
+    "they", "them", "our", "your", "their", "his", "her",
+    "if", "when", "then", "than", "for", "and", "but", "or", "nor", "so", "to", "in", "on", "of",
+    "at", "by", "as", "is", "are", "was", "were", "be", "been", "being", "do", "does", "did", "done",
+    "not", "no", "yes", "none", "null", "na", "nan", "true", "false",
+    "use", "used", "using", "avoid", "add", "added", "fix", "fixed", "make", "made", "set", "run",
+    "ran", "get", "got", "put", "new", "old", "now", "also", "with", "without", "from", "into",
+    "enable", "enabled", "disable", "disabled", "allow", "allowed", "deny", "forbidden",
+    "required", "optional", "about", "what", "which", "how", "why", "who", "where"
+]);
+function isEntityStopword(key) {
+    return ENTITY_STOPWORDS.has(key.toLowerCase());
+}
 /** Canonicalize one raw entity string. Returns null for junk (empty, too long, pure noise). */
 export function canonicalizeEntity(raw) {
     const s = (raw ?? "").trim().replace(/^[`'"]+|[`'"]+$/g, "").trim();
@@ -55,10 +74,15 @@ export function canonicalizeEntity(raw) {
             return { key: s.toLowerCase(), name: s, kind: "concept", namespace: "domain" };
         if (/[A-Z_]/.test(s.slice(1)))
             return { key: s, name: s, kind: "symbol", namespace: "code" };
-        // lowercase single token (e.g. "vllm", "ollama") — treat as a domain concept
+        // lowercase single token (e.g. "vllm", "ollama") — treat as a domain concept, unless it's a
+        // bare common word ("not", "use", "no") that would only create noise and false conflicts.
+        if (isEntityStopword(s))
+            return null;
         return { key: s.toLowerCase(), name: s, kind: "concept", namespace: "domain" };
     }
     // Multi-word phrase / proper noun → domain concept.
+    if (isEntityStopword(s))
+        return null;
     return { key: s.toLowerCase(), name: s, kind: "concept", namespace: "domain" };
 }
 // Common capitalized words that START sentences / clauses — not domain entities.

package/dist/global-memory.js

@@ -9,7 +9,12 @@ export class PeonGlobalMemoryStore {
         this.globalDir = globalDir;
     }
     static defaultDirectory() {
-        return PeonGlobalMemoryStore.defaultGlobalDir;
+        // PEON_GLOBAL_DIR relocates the global brain. Tests set it to a temp dir so they never read
+        // or write the real global store at ~/Library/Application Support/Peon/global — without this
+        // a tool created without an explicit globalMemoryDir falls back to the real store, which made
+        // cross-project isolation tests flaky and let test runs pollute the user's actual global brain.
+        const override = process.env.PEON_GLOBAL_DIR;
+        return override && override.trim() ? override.trim() : PeonGlobalMemoryStore.defaultGlobalDir;
     }
     static async open(options = {}) {
         const store = new PeonGlobalMemoryStore(options.globalDir ?? PeonGlobalMemoryStore.defaultDirectory());

package/dist/quality.js

@@ -37,6 +37,13 @@ export function detectMemoryConflicts(records) {
             const reason = opposingLanguageReason(left.content, right.content);
             if (!reason)
                 continue;
+            // Same-topic gate. A shared entity + one opposing word-pair somewhere in two long beliefs
+            // is a weak signal: on a research brain, dozens of beliefs all mention "BIRD" and one says
+            // "use X" while an unrelated one says "avoid Y". They don't contradict — they're just both
+            // about BIRD. Require the two beliefs to actually be discussing the same thing before
+            // calling it a conflict: several shared entities, or real content overlap beyond the token.
+            if (!sameTopic(left, right))
+                continue;
             conflicts.push({
                 entity,
                 leftId: left.id,
@@ -228,6 +235,47 @@ function sharedEntity(left, right) {
     }
     return undefined;
 }
+const TOPIC_STOP = new Set([
+    "the", "a", "an", "and", "or", "but", "to", "of", "in", "on", "for", "with", "is", "are", "was",
+    "were", "be", "as", "at", "by", "it", "this", "that", "we", "our", "use", "used", "using", "from",
+    "not", "no", "yes", "do", "does", "did", "so", "if", "then", "than", "when", "which", "what"
+]);
+/** Content tokens (lowercased, ≥3 chars, minus stopwords) — the topical fingerprint of a belief. */
+function contentTokens(text) {
+    const out = new Set();
+    for (const raw of (text ?? "").toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length >= 3 && !TOPIC_STOP.has(raw))
+            out.add(raw);
+    }
+    return out;
+}
+/**
+ * True when two beliefs are actually discussing the same thing — the precondition for their
+ * opposing language to be a real contradiction rather than a coincidence. Satisfied by either
+ * multiple shared entities (a strong same-subject signal) or meaningful content overlap
+ * (Jaccard of content tokens above a floor). Prevents "both mention BIRD, one says use / one
+ * says avoid, about unrelated things" from being flagged.
+ */
+function sameTopic(left, right) {
+    const le = new Set(left.entities.map(normalizeEntity));
+    const re = new Set(right.entities.map(normalizeEntity));
+    let sharedEntities = 0;
+    for (const e of le)
+        if (re.has(e))
+            sharedEntities += 1;
+    if (sharedEntities >= 2)
+        return true;
+    const lt = contentTokens(left.content);
+    const rt = contentTokens(right.content);
+    if (lt.size === 0 || rt.size === 0)
+        return false;
+    let inter = 0;
+    for (const t of lt)
+        if (rt.has(t))
+            inter += 1;
+    const jaccard = inter / (lt.size + rt.size - inter);
+    return jaccard >= 0.25;
+}
 function opposingLanguageReason(left, right) {
     const leftText = normalizeMemory(left);
     const rightText = normalizeMemory(right);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peon-mem",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -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"
 }