peon-mem 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vineet Vora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# 🧠 Peon — a memory brain for your AI coding agents
+
+**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.
+
+```
+        PEON GLOBAL BRAIN            ← user-level facts & preferences, inherited everywhere
+       /        |         \
+  project A  project B  project C    ← rooted child brains (.peon/ in each project)
+```
+
+## 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.
+
+
+
+
+![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.*
+
+## Why "Peon"?
+
+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.
+
+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.
+
+## How Peon differs from existing memory tools
+
+| | **Peon** | mem0 | Letta/MemGPT | Zep/Graphiti | flat memory files (MEMORY.md) |
+|---|---|---|---|---|---|
+| Runs | **100% local daemon** | cloud or self-host | server | cloud/server | local |
+| Storage | human-readable JSONL you can `cat` | vector DB | DB | graph DB | markdown |
+| Memory model | **beliefs + verbatim episodic layer** | extracted facts | self-edited blocks | temporal knowledge graph | prose |
+| Hierarchy | **global parent brain → per-project child brains, inherited on every prompt** | user/agent/session scopes | per-agent | per-user | per-project file |
+| Capture | **automatic via hooks** (zero effort) | SDK calls you write | agent-managed | SDK calls | agent must remember to write |
+| Conflict handling | supersede/merge, **recoverable — never hard-deletes** | LLM may DELETE | self-edit | invalidation | overwrite |
+| Exact recall | episodic layer regression-tested (61% vs 17% belief-only, LongMemEval) | gist only | gist only | graph facts | whatever was written |
+| 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.
+
+## Quickstart
+
+Requirements: Node 20+, macOS or Linux. An [OpenRouter](https://openrouter.ai) API key is
+recommended (consolidation + semantic embeddings); without one Peon still works lexical-only.
+
+One line:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/VineetV2/peon-mem/main/install.sh | bash
+```
+
+(or, once you have the CLI: `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`.
+
+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
+`~/Library/Application Support/Peon/.env` and open the monitor. `peon-mem install --dry-run`
+shows every action first; `peon-mem uninstall` reverses it (memory data is never touched).
+
+Or manually:
+
+```bash
+git clone https://github.com/VineetV2/peon-mem && cd peon-mem
+npm install && npm run build
+node bin/peon-mem.mjs install --dry-run   # inspect, then run without --dry-run
+```
+
+Create `.env` in the repo root:
+
+```bash
+OPENROUTER_API_KEY=sk-or-...
+PEON_PROCESSING_MODEL=google/gemini-2.5-flash-lite   # cheap + good enough (measured)
+PEON_EMBEDDING_MODEL=openai/text-embedding-3-small
+```
+
+Start the daemon (the installer prints a launchd/systemd recipe, or just):
+
+```bash
+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 /
+  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
+  (`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.
+
+
+## Full install (copy-paste)
+
+### 1. Daemon (always-on, macOS launchd)
+
+```bash
+node scripts/install-peon.mjs           # prints everything below filled in for YOUR paths
+```
+
+Or manually — `~/Library/LaunchAgents/com.peon.daemon.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.peon.daemon</string>
+  <key>ProgramArguments</key><array>
+    <string>/opt/homebrew/bin/node</string>
+    <string>/ABSOLUTE/PATH/TO/peon/dist/daemon-cli.js</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+</dict></plist>
+```
+
+```bash
+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`).
+
+### 2. Claude Code — hooks (auto capture + injection)
+
+Merge into `~/.claude/settings.json` (replace the path):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{ "hooks": [{ "type": "command",
+      "command": "node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs" }] }],
+    "UserPromptSubmit": [{ "hooks": [{ "type": "command",
+      "command": "node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs" }] }],
+    "SessionEnd": [{ "hooks": [{ "type": "command",
+      "command": "node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs" }] }]
+  }
+}
+```
+
+### 3. Claude Code — MCP server (search/inspect tools)
+
+```bash
+claude mcp add peon -- node /ABSOLUTE/PATH/TO/peon/dist/index.js
+```
+
+### 4. Codex / any MCP client
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.peon]
+command = "node"
+args = ["/ABSOLUTE/PATH/TO/peon/dist/index.js"]
+[mcp_servers.peon.env]
+PEON_DAEMON_URL = "http://127.0.0.1:3737"
+```
+
+Codex has no hooks — 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/)).
+
+### 5. Verify
+
+```bash
+curl "http://127.0.0.1:3737/context?projectPath=$PWD&query=test"   # JSON context
+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.
+
+### MCP tools exposed
+
+`start_session` · `record_message` · `record_event` · `end_session` · `get_context` ·
+`search_memory` · `inspect_brain` · `build_injection` · `query_projects` (cross-project search) ·
+`quality_report` · `remember_global` · `search_global_memory` · `import_global_memory` ·
+`evaluate_project` · `process_memory` · `maybe_process_memory`
+
+### Uninstall
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.peon.daemon.plist
+# remove the hook entries + MCP server from your agent config
+# your memory stays in <project>/.peon/ and ~/Library/Application\ Support/Peon/ — plain files, delete when ready
+```
+
+## 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 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).
+- **Is my data sent anywhere?** Only consolidation/embedding calls to your configured model
+  provider. No telemetry, no cloud store. Daemon rejects non-loopback callers.
+
+## Configuration (env)
+
+| Var | Default | Purpose |
+|---|---|---|
+| `OPENROUTER_API_KEY` | — | consolidation + embeddings |
+| `PEON_PROCESSING_MODEL` | `google/gemini-2.5-flash-lite` | consolidation model |
+| `PEON_EMBEDDING_MODE` | auto | `api` / `ollama` / `local` / `off` |
+| `PEON_EMBEDDING_MODEL` | — | e.g. `openai/text-embedding-3-small` or an Ollama model |
+| `PEON_OLLAMA_URL` | `http://127.0.0.1:11434` | local embedding server |
+| `PEON_AI_MODE` | `gated` | `off` disables all LLM calls |
+| `PEON_FLUSH_MIN_CHARS` | `6000` | consolidation cost gate |
+| `PEON_MEMORY_DIR` | `.peon` | per-project brain dir name |
+| `PEON_DAEMON_URL` | `http://127.0.0.1:3737` | daemon address |
+| `PEON_CONSOLIDATION_MAX_DELTA_CHARS` | `60000` | anti truncation-stall chunking |
+| `PEON_DISABLED` | — | hard off-switch for A/B testing |
+
+## 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.
+- The global brain lives in `~/Library/Application Support/Peon/global/` (macOS).
+
+## 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.
+
+## Security
+
+- Daemon binds `127.0.0.1` only and rejects non-loopback `Host`/`Origin` (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.
+
+## License
+
+MIT © Vineet Vora
+
+## Contributing
+
+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).

package/bin/peon-mem.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * peon-mem — guided installer/manager for the Peon memory brain.
+ *
+ *   peon-mem install [--yes] [--dry-run]   guided setup: memory home → LLM → daemon → MCP apps
+ *   peon-mem uninstall                     remove service + hooks (memory data is never touched)
+ *   peon-mem daemon                        run the daemon in the foreground
+ *   peon-mem doctor                        health + config check
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+
+const PKG = dirname(dirname(fileURLToPath(import.meta.url)));
+const HOME = homedir();
+const MAC = 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");
+const DAEMON = join(PKG, "dist", "daemon-cli.js");
+const MCP = join(PKG, "dist", "index.js");
+const NODE = process.execPath;
+
+const cmd = process.argv[2] || "help";
+const DRY = process.argv.includes("--dry-run");
+const YES = process.argv.includes("--yes") || !process.stdout.isTTY;
+const log = (s) => console.log(s);
+const act = (desc, fn) => { log((DRY ? "  [dry-run] " : "  ✔ ") + desc); if (!DRY) fn(); };
+const rl = YES ? null : createInterface({ input: process.stdin, output: process.stdout });
+async function ask(q, def) {
+  if (!rl) return def;
+  const a = (await rl.question(`${q}${def ? ` [${def}]` : ""}: `)).trim();
+  return a || def;
+}
+
+function which(bin) { return spawnSync("which", [bin], { stdio: "pipe" }).status === 0; }
+function backupWrite(file, content) {
+  if (existsSync(file)) copyFileSync(file, file + ".peon-backup");
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, content);
+}
+
+// ---------- app detection ----------
+// wire kinds: hooks+CLI (claude code) · toml (codex) · mcpServers JSON (most apps) ·
+// vscode "servers" JSON · zed context_servers · manual (UI-configured apps get instructions)
+const APP_SUPPORT = MAC ? join(HOME, "Library", "Application Support") : join(HOME, ".config");
+function detectApps() {
+  return [
+    { id: "claude",   name: "Claude Code",    kind: "claude-code",
+      found: which("claude") || existsSync(join(HOME, ".claude")) },
+    { id: "claude-desktop", name: "Claude Desktop", kind: "json",
+      file: join(APP_SUPPORT, "Claude", "claude_desktop_config.json"),
+      found: existsSync(join(APP_SUPPORT, "Claude")) || existsSync("/Applications/Claude.app") },
+    { id: "codex",    name: "Codex",          kind: "toml",
+      found: existsSync(join(HOME, ".codex")) },
+    { id: "gemini",   name: "Gemini CLI",     kind: "json",
+      file: join(HOME, ".gemini", "settings.json"),
+      found: which("gemini") || existsSync(join(HOME, ".gemini")) },
+    { id: "cursor",   name: "Cursor",         kind: "json",
+      file: join(HOME, ".cursor", "mcp.json"),
+      found: existsSync(join(HOME, ".cursor")) || existsSync("/Applications/Cursor.app") },
+    { id: "windsurf", name: "Windsurf",       kind: "json",
+      file: join(HOME, ".codeium", "windsurf", "mcp_config.json"),
+      found: existsSync(join(HOME, ".codeium", "windsurf")) || existsSync("/Applications/Windsurf.app") },
+    { id: "vscode",   name: "VS Code (Copilot MCP)", kind: "vscode",
+      file: MAC ? join(APP_SUPPORT, "Code", "User", "mcp.json") : join(HOME, ".config", "Code", "User", "mcp.json"),
+      found: which("code") || existsSync(MAC ? join(APP_SUPPORT, "Code") : join(HOME, ".config", "Code")) },
+    { id: "zed",      name: "Zed",            kind: "zed",
+      file: join(HOME, ".config", "zed", "settings.json"),
+      found: existsSync(join(HOME, ".config", "zed")) || existsSync("/Applications/Zed.app") },
+    { id: "lmstudio", name: "LM Studio",      kind: "json",
+      file: join(HOME, ".lmstudio", "mcp.json"),
+      found: existsSync(join(HOME, ".lmstudio")) || existsSync("/Applications/LM Studio.app") },
+    { id: "chatgpt",  name: "ChatGPT Desktop", kind: "manual",
+      found: existsSync("/Applications/ChatGPT.app"),
+      how: "ChatGPT → Settings → Connectors → Advanced → enable Developer Mode → add MCP server: command=" },
+    { id: "perplexity", name: "Perplexity Desktop", kind: "manual",
+      found: existsSync("/Applications/Perplexity.app") || existsSync("/Applications/Perplexity- Ask Anything.app"),
+      how: "Perplexity → Settings → Connectors → Add Connector → Advanced: command=" }
+  ];
+}
+
+// ---------- per-app wiring ----------
+function wireClaude() {
+  const settings = join(HOME, ".claude", "settings.json");
+  let s = {}; try { s = JSON.parse(readFileSync(settings, "utf8")); } catch {}
+  s.hooks = s.hooks || {};
+  let changed = false;
+  for (const ev of ["SessionStart", "UserPromptSubmit", "SessionEnd"]) {
+    const arr = (s.hooks[ev] = s.hooks[ev] || []);
+    if (!JSON.stringify(arr).includes("claude-peon-hook.mjs")) {
+      arr.push({ hooks: [{ type: "command", command: `"${NODE}" "${HOOK}"` }] }); changed = true;
+    }
+  }
+  if (changed) act("Claude Code: hooks → " + settings + " (backup kept)", () => backupWrite(settings, JSON.stringify(s, null, 2) + "\n"));
+  else log("  ✔ Claude Code: hooks already present");
+  if (!DRY) {
+    const r = spawnSync("claude", ["mcp", "add", "peon", "--", NODE, MCP], { stdio: "ignore" });
+    log(r.status === 0 ? "  ✔ Claude Code: MCP server registered" : `  → run manually: claude mcp add peon -- "${NODE}" "${MCP}"`);
+  } else log("  [dry-run] Claude Code: claude mcp add peon");
+}
+function wireCodex() {
+  const f = join(HOME, ".codex", "config.toml");
+  let s = ""; try { s = readFileSync(f, "utf8"); } catch {}
+  if (s.includes("[mcp_servers.peon]")) return log("  ✔ Codex: MCP already configured");
+  const block = `\n[mcp_servers.peon]\ncommand = "${NODE}"\nargs = ["${MCP}"]\n\n[mcp_servers.peon.env]\nPEON_DAEMON_URL = "http://127.0.0.1:3737"\n`;
+  act("Codex: [mcp_servers.peon] → " + f + " (backup kept)", () => backupWrite(f, s + block));
+}
+function wireJsonMcp(name, file) {
+  let s = {}; try { s = JSON.parse(readFileSync(file, "utf8")); } catch {}
+  s.mcpServers = s.mcpServers || {};
+  if (s.mcpServers.peon) return log(`  ✔ ${name}: MCP already configured`);
+  s.mcpServers.peon = { command: NODE, args: [MCP], env: { PEON_DAEMON_URL: "http://127.0.0.1:3737" } };
+  act(`${name}: mcpServers.peon → ${file} (backup kept)`, () => backupWrite(file, JSON.stringify(s, null, 2) + "\n"));
+}
+
+function wireVsCode(file) {
+  let s = {}; try { s = JSON.parse(readFileSync(file, "utf8")); } catch {}
+  s.servers = s.servers || {};
+  if (s.servers.peon) return log("  ✔ VS Code: MCP already configured");
+  s.servers.peon = { type: "stdio", command: NODE, args: [MCP], env: { PEON_DAEMON_URL: "http://127.0.0.1:3737" } };
+  act("VS Code: servers.peon → " + file + " (backup kept)", () => backupWrite(file, JSON.stringify(s, null, 2) + "\n"));
+}
+function wireZed(file) {
+  let s = {}; try { s = JSON.parse(readFileSync(file, "utf8")); } catch {}
+  s.context_servers = s.context_servers || {};
+  if (s.context_servers.peon) return log("  ✔ Zed: MCP already configured");
+  s.context_servers.peon = { command: { path: NODE, args: [MCP] }, settings: {} };
+  act("Zed: context_servers.peon → " + file + " (backup kept)", () => backupWrite(file, JSON.stringify(s, null, 2) + "\n"));
+}
+
+// ---------- service ----------
+function installService(memoryHome) {
+  if (MAC) {
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.peon.daemon</string>
+  <key>ProgramArguments</key><array>
+    <string>${NODE}</string>
+    <string>${DAEMON}</string>
+  </array>
+  <key>WorkingDirectory</key><string>${memoryHome}</string>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${memoryHome}/daemon.out.log</string>
+  <key>StandardErrorPath</key><string>${memoryHome}/daemon.err.log</string>
+</dict></plist>\n`;
+    act("daemon service (launchd, auto-start) → " + PLIST, () => {
+      mkdirSync(dirname(PLIST), { recursive: true });
+      writeFileSync(PLIST, plist);
+      spawnSync("launchctl", ["unload", PLIST], { stdio: "ignore" });
+      execFileSync("launchctl", ["load", PLIST]);
+    });
+  } else {
+    log("  → Linux: systemd user unit:");
+    log(`      ExecStart=${NODE} ${DAEMON}\n      WorkingDirectory=${memoryHome}\n      Restart=always`);
+  }
+}
+
+async function health() {
+  try { const r = await fetch("http://127.0.0.1:3737/health"); return (await r.json()).ok === true; } catch { return false; }
+}
+
+// ================= commands =================
+if (cmd === "install") {
+  log("\n🧠 Peon setup — a memory brain for your AI agents\n");
+
+  // Step 1 — memory home
+  log("Step 1/4 · Where should Peon's GLOBAL brain live?");
+  log("  (press Enter to accept the default)");
+  const memoryHome = await ask("  memory home", DEFAULT_HOME);
+  act("create " + memoryHome, () => mkdirSync(memoryHome, { recursive: true }));
+
+  // Step 2 — LLM provider
+  log("\nStep 2/4 · LLM for consolidation + semantic retrieval");
+  log("  1) OpenRouter  — one key, any model (default: gemini-2.5-flash-lite, ~cents/day)");
+  log("  2) OpenAI      — gpt-4o-mini + text-embedding-3-small");
+  log("  3) Anthropic   — Claude Haiku (embeddings fall back local — pair with Ollama for semantic)");
+  log("  4) Ollama      — 100% local + free (llama3.2 + nomic-embed-text on your machine)");
+  log("  5) skip        — lexical-only memory, add a provider later");
+  const choice = await ask("  choose 1-5", "1");
+  const envFile = join(memoryHome, ".env");
+  let envLines = [`# Peon config — generated by peon-mem install`];
+  if (choice === "1") {
+    const key = await ask("  OpenRouter API key (sk-or-…)", "");
+    envLines.push("PEON_PROVIDER=openrouter", `OPENROUTER_API_KEY=${key}`,
+      "PEON_PROCESSING_MODEL=google/gemini-2.5-flash-lite", "PEON_EMBEDDING_MODEL=openai/text-embedding-3-small");
+  } else if (choice === "2") {
+    const key = await ask("  OpenAI API key (sk-…)", "");
+    envLines.push("PEON_PROVIDER=openai", `OPENAI_API_KEY=${key}`,
+      "PEON_PROCESSING_MODEL=gpt-4o-mini", "PEON_EMBEDDING_MODEL=text-embedding-3-small");
+  } else if (choice === "3") {
+    const key = await ask("  Anthropic API key (sk-ant-…)", "");
+    envLines.push("PEON_PROVIDER=anthropic", `ANTHROPIC_API_KEY=${key}`,
+      "PEON_PROCESSING_MODEL=claude-haiku-4-5-20251001",
+      "# Anthropic has no embeddings API — install Ollama + set PEON_EMBEDDING_MODE=ollama for semantic retrieval");
+  } else if (choice === "4") {
+    envLines.push("PEON_PROVIDER=ollama", "PEON_EMBEDDING_MODE=ollama",
+      "PEON_PROCESSING_MODEL=llama3.2", "PEON_EMBEDDING_MODEL=nomic-embed-text");
+    const up = await fetch("http://127.0.0.1:11434/api/tags").then((r) => r.ok).catch(() => false);
+    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.");
+  }
+  if (existsSync(envFile)) log("  ✔ keeping existing " + envFile);
+  else act("write " + envFile, () => writeFileSync(envFile, envLines.join("\n") + "\n"));
+
+  // Step 3 — daemon
+  log("\nStep 3/4 · Daemon (always-on, 127.0.0.1:3737)");
+  installService(memoryHome);
+
+  // Step 4 — apps
+  log("\nStep 4/4 · Wire your AI apps (detected on this machine)");
+  const apps = detectApps();
+  apps.forEach((a, i) => log(`  ${i + 1}) ${a.found ? "🟢" : "⚪"} ${a.name}${a.found ? "" : " (not detected)"}`));
+  const detected = apps.filter((a) => a.found).map((a) => a.id);
+  const pick = await ask(`  install MCP into (comma ids or 'all') — detected: ${detected.join(",") || "none"}`, detected.join(",") || "none");
+  const chosen = pick === "all" ? apps.map((a) => a.id) : pick.split(",").map((x) => x.trim()).filter(Boolean);
+  for (const id of chosen) {
+    const app = apps.find((a) => a.id === id);
+    if (!app) { log("  ⚠ unknown app id: " + id); continue; }
+    if (app.kind === "claude-code") wireClaude();
+    else if (app.kind === "toml") wireCodex();
+    else if (app.kind === "json") wireJsonMcp(app.name, app.file);
+    else if (app.kind === "vscode") wireVsCode(app.file);
+    else if (app.kind === "zed") wireZed(app.file);
+    else if (app.kind === "manual") {
+      log(`  → ${app.name} is configured in-app (no config file). In the app:`);
+      log(`     ${app.how}"${NODE}" args=["${MCP}"]`);
+    }
+  }
+
+  if (!DRY) {
+    await new Promise((r) => setTimeout(r, 1500));
+    log("\n" + ((await health()) ? "✔ daemon healthy — http://127.0.0.1:3737" : "⚠ daemon not answering — check " + memoryHome + "/daemon.err.log"));
+  }
+  log("🌌 Monitor (the Neural Universe): http://127.0.0.1:3737/monitor");
+  log("Memory lives in <project>/.peon/ (child brains) + " + memoryHome + " (global brain)\n");
+  rl?.close();
+} else if (cmd === "uninstall") {
+  if (MAC && existsSync(PLIST)) act("stop + remove daemon service", () => spawnSync("launchctl", ["unload", PLIST], { stdio: "ignore" }));
+  const settings = join(HOME, ".claude", "settings.json");
+  try {
+    const s = JSON.parse(readFileSync(settings, "utf8"));
+    for (const ev of Object.keys(s.hooks || {}))
+      s.hooks[ev] = s.hooks[ev].filter((h) => !JSON.stringify(h).includes("claude-peon-hook.mjs"));
+    act("remove Peon hooks from " + settings, () => backupWrite(settings, JSON.stringify(s, null, 2) + "\n"));
+  } catch {}
+  log("Remove [mcp_servers.peon] / mcpServers.peon from Codex/Gemini/Cursor configs if you added them.");
+  log("Memory data untouched: <project>/.peon/ and " + DEFAULT_HOME);
+  rl?.close();
+} else if (cmd === "daemon") {
+  await import(DAEMON);
+} else if (cmd === "doctor") {
+  log("package : " + PKG);
+  log("daemon  : " + ((await health()) ? "healthy (127.0.0.1:3737)" : "DOWN"));
+  const settings = join(HOME, ".claude", "settings.json");
+  log("hooks   : " + (existsSync(settings) && readFileSync(settings, "utf8").includes("claude-peon-hook.mjs") ? "installed" : "not installed"));
+  log("config  : " + join(DEFAULT_HOME, ".env") + (existsSync(join(DEFAULT_HOME, ".env")) ? "" : " (missing — run peon-mem install)"));
+  rl?.close();
+} else {
+  log("peon-mem — memory brain for AI coding agents");
+  log("  peon-mem install [--yes] [--dry-run]   guided setup (memory home → LLM → daemon → apps)");
+  log("  peon-mem uninstall                     remove service + hooks (data stays)");
+  log("  peon-mem daemon                        run daemon in foreground");
+  log("  peon-mem doctor                        health check");
+  rl?.close();
+}