peon-mem 1.0.1 → 1.0.2

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.
 
 
 
@@ -47,15 +52,15 @@ automatically, from a daemon that never leaves your machine.
 
 ## 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 +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
 
@@ -91,12 +96,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 +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)
@@ -177,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)
 
@@ -214,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/)).
 
@@ -225,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
 
@@ -245,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)
 
@@ -275,55 +286,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 +355,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peon-mem",
-  "version": "1.0.1",
+  "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"
+}