{
  "markdown": "# 🧠 Peon — a memory brain for your AI coding agents\n\n[![npm](https://img.shields.io/npm/v/peon-mem)](https://www.npmjs.com/package/peon-mem) [![downloads](https://img.shields.io/npm/dm/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/) [![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-6b4fbb)](https://registry.modelcontextprotocol.io) [![Star on GitHub](https://img.shields.io/github/stars/VineetV2/peon-mem?style=social)](https://github.com/VineetV2/peon-mem)\n\n**Local-first, hierarchical, self-improving memory for Claude Code, Codex, and any MCP client.**\n\nYour AI forgets everything between sessions. Peon doesn't. It records your sessions, uses an\nLLM to consolidate them into typed *beliefs*, and injects the relevant ones back into every\nprompt. It runs as a daemon on your machine, and nothing leaves it.\n\n```\n        PEON GLOBAL BRAIN            ← user-level facts & preferences, inherited everywhere\n       /        |         \\\n  project A  project B  project C    ← rooted child brains (.peon/ in each project)\n```\n\n## Why Peon\n\n- **Hierarchical brains.** One global parent brain holds who you are, your rules, and your\n  tools. Each project gets an isolated child brain. Every injection carries both.\n- **Two memory layers, honestly measured.** Consolidated *beliefs* (decisions, preferences,\n  facts, artifacts) give you the gist. An *episodic* verbatim layer recovers the exact details\n  that lossy summaries drop. In my own LongMemEval run, raw-episodic recall scored 61% where\n  belief-only scored 17% — self-measured, not an independent benchmark; reproduce it with\n  `npm run eval`.\n- **Automatic capture and injection.** Claude Code hooks record messages and events, then\n  inject a query-ranked memory block (with an `⚠ MOST RELEVANT` headline) into every prompt.\n  You never have to remember to save anything.\n- **Cost-gated consolidation.** An LLM distills sessions into beliefs only once enough new\n  memory accumulates. It can supersede, merge, and flag conflicts. Nothing is destructively\n  deleted.\n- **Hybrid retrieval.** Lexical and semantic RRF fusion, MMR diversity, reinforcement, and\n  recency. Query embeddings are cached to disk, so repeat prompts cost nothing.\n- **The Neural Universe.** A live monitor at `localhost:3737/monitor` renders every belief as\n  a star. Projects are galaxies, search makes matches flare, and autonomous curation pulses.\n- **A daily self-audit (STL).** Peon checks itself every day: what it recorded, what it\n  injected, what failed, what consolidation did. Then it files a report with a verdict.\n- **Eval-gated development.** A committed results ledger (git SHA, qrels, and brain\n  fingerprint per row) means retrieval changes are proven, not asserted. Negative results stay\n  documented.\n- **Local-first and locked down.** Plain JSONL you can read, a loopback-only daemon with\n  DNS-rebinding protection, secret redaction at the injection boundary, and path-traversal\n  guards.\n\n\n\n\n![The Neural Universe — every belief is a star, projects are galaxies](docs/assets/neural-universe.png)\n*The live monitor: 18k real beliefs rendered as stars. Type to make matching beliefs flare; click one to inspect it.*\n\n![Search flare — type a query and matching beliefs light up across every galaxy](docs/assets/search-flare.gif)\n\n*Ask the field: typing \"wulver cluster\" makes 400+ matching beliefs flare while the rest dim, and the camera flies to them.*\n\n## Why \"Peon\"?\n\nThe name comes from Indian offices. Every office had a **peon**, the person who walked desk to\ndesk all day: collect a file from this table, note who needs what, carry it to the next table,\nremember where everything is. He wasn't the boss or the star, but the whole office quietly ran\non him. Nothing moved without him, and he never forgot where anything was.\n\nThat's this framework, with AI. Peon walks between your sessions and your projects. It collects\nwhat happened at one desk (a session), files it in the right cabinet (a project brain), carries\nthe relevant papers to the next desk before you ask (injection), and keeps the master ledger\nupstairs (the global brain). Quiet clerk. Perfect memory. The office runs on him.\n\n## How Peon differs from existing memory tools\n\n| | **Peon** | mem0 | Letta/MemGPT | Zep/Graphiti | flat memory files (MEMORY.md) |\n|---|---|---|---|---|---|\n| Runs | **100% local daemon** | cloud or self-host | server | cloud/server | local |\n| Storage | human-readable JSONL you can `cat` | vector DB | DB | graph DB | markdown |\n| Memory model | **beliefs + verbatim episodic layer** | extracted facts | self-edited blocks | temporal knowledge graph | prose |\n| Hierarchy | **global parent brain → per-project child brains, inherited on every prompt** | user/agent/session scopes | per-agent | per-user | per-project file |\n| Capture | **automatic via hooks** (zero effort) | SDK calls you write | agent-managed | SDK calls | agent must remember to write |\n| Conflict handling | supersede/merge, **recoverable — never hard-deletes** | LLM may DELETE | self-edit | invalidation | overwrite |\n| Exact recall | episodic layer regression-tested (61% vs 17% belief-only on LongMemEval, self-measured) | gist only | gist only | graph facts | whatever was written |\n| Observability | **live Neural Universe monitor + daily self-audit (STL) + serve telemetry** | dashboard | — | — | — |\n| Verification | **committed eval ledger; negative results kept** | vendor benchmarks | — | vendor benchmarks | — |\n\nThe short version: mem0 and Zep are memory platforms for products you build. Peon is memory\nfor the coding agents you already use. It plugs into Claude Code or Codex in about five\nminutes, and you can watch it think and audit every number it claims.\n\n## Your agents share one brain\n\nIf you run more than one coding agent — Claude Code and Codex, say — they usually each live in\ntheir own bubble. Whatever you work out with one is gone when you switch to the other.\n\nPoint them at the same project and Peon dissolves that wall. Both agents resolve to the same\n`.peon/` brain (Peon canonicalizes the project path, so the hook, a direct MCP call, and Codex\nall land on one store). So the memory flows between them:\n\n- Codex works out how your build pipeline runs and records it. Next time you open Claude Code\n  in that repo, it's already in the injected context.\n- Claude Code hits a gotcha and files it. Codex sees it the moment it calls `get_context` or\n  `search_memory`.\n- The global brain sits above both, so your preferences and rules follow you into every agent,\n  in every project.\n\nThey aren't chatting in real time. It's a shared notebook both write in and both read from, so\na decision made in one agent shows up in the other without you re-explaining it. One project,\none memory, however many agents.\n\n## Quickstart\n\nRequirements: Node 20+, macOS or Linux. An [OpenRouter](https://openrouter.ai) API key is\nrecommended (consolidation + semantic embeddings); without one Peon still works lexical-only.\n\nOne line:\n\n```bash\nnpm install -g peon-mem && peon-mem install\n```\n\n(no Node? `curl -fsSL https://raw.githubusercontent.com/VineetV2/peon-mem/main/install.sh | bash`)\n\nThe guided setup asks four things:\n\n1. **Where your global brain lives** (default: `~/Library/Application Support/Peon`)\n2. **Which LLM**: OpenRouter (one key, any model) · OpenAI · Anthropic · **Ollama (100% local\n   & free)** · or skip\n3. Installs the **daemon** as an auto-start service (launchd on macOS, systemd user unit on Linux)\n4. **Detects your AI apps** and wires the MCP server (plus hooks for Claude Code) into the\n   ones you pick. Auto-configured: Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor,\n   Windsurf, Cline, VS Code (Copilot MCP), Zed, LM Studio. Detected with in-app instructions: ChatGPT\n   Desktop, Perplexity Desktop. Every touched config gets a `.peon-backup`.\n\nThat builds the package, starts the daemon as a service, wires your Claude Code hooks + MCP\nserver (with a backup of your settings), and writes a config template. Then add your key to\n`~/Library/Application Support/Peon/.env` and open the monitor. `peon-mem install --dry-run`\nshows every action first; `peon-mem uninstall` reverses it (memory data is never touched).\n\nOr manually:\n\n```bash\ngit clone https://github.com/VineetV2/peon-mem && cd peon-mem\nnpm install && npm run build\nnode bin/peon-mem.mjs install --dry-run   # inspect, then run without --dry-run\n```\n\nCreate `.env` in the repo root:\n\n```bash\nOPENROUTER_API_KEY=sk-or-...\nPEON_PROCESSING_MODEL=google/gemini-2.5-flash-lite   # cheap + good enough (measured)\nPEON_EMBEDDING_MODEL=openai/text-embedding-3-small\n```\n\nStart the daemon (the installer prints a launchd/systemd recipe, or just):\n\n```bash\nnode dist/daemon-cli.js              # serves 127.0.0.1:3737\n```\n\nThen wire your agent (the installer prints these filled in for your paths):\n\n- **Claude Code**: add the hook to `~/.claude/settings.json` (SessionStart / UserPromptSubmit /\n  SessionEnd → `scripts/claude-peon-hook.mjs`) and the MCP server (`dist/index.js`).\n- **Codex / any MCP client**: register `dist/index.js` as a stdio MCP server; 16 tools\n  (`start_session`, `get_context`, `search_memory`, `record_message`, `process_memory`, …).\n\nOpen `http://127.0.0.1:3737/monitor` and watch your brain grow.\n\n## How it works\n\n1. **Record.** Hooks stream messages, events, and tool calls into `<project>/.peon/raw/`\n   (append-only).\n2. **Consolidate.** Past a size gate, an LLM turns the session delta into typed belief records\n   in `.peon/brain/memories.jsonl` (importance/confidence scores, entities, provenance\n   pointers), reconciling against existing beliefs: supersede, merge, conflict-flag.\n   Recoverable, never deleted.\n3. **Retrieve + inject.** On every prompt, beliefs are ranked (RRF lexical+semantic, MMR,\n   reinforcement) and injected alongside episodic verbatim matches and inherited global\n   beliefs.\n4. **Self-curate.** A background brain pass reinforces recalled beliefs, compresses stale\n   clusters, and resolves duplicates. Every action is logged and undoable.\n5. **Self-audit (STL).** A daily job reports what was recorded, what was injected, what went\n   wrong, and whether consolidation behaved, with serve-latency telemetry and a health verdict.\n\n\n## Full install (copy-paste)\n\n### 1. Daemon (always-on, macOS launchd)\n\n```bash\nnode scripts/install-peon.mjs           # prints everything below filled in for YOUR paths\n```\n\nOr manually — `~/Library/LaunchAgents/com.peon.daemon.plist`:\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n<plist version=\"1.0\"><dict>\n  <key>Label</key><string>com.peon.daemon</string>\n  <key>ProgramArguments</key><array>\n    <string>/opt/homebrew/bin/node</string>\n    <string>/ABSOLUTE/PATH/TO/peon/dist/daemon-cli.js</string>\n  </array>\n  <key>RunAtLoad</key><true/>\n  <key>KeepAlive</key><true/>\n</dict></plist>\n```\n\n```bash\nlaunchctl load ~/Library/LaunchAgents/com.peon.daemon.plist\ncurl http://127.0.0.1:3737/health        # → {\"ok\":true}\n```\n\nLinux: the installer writes `~/.config/systemd/user/peon-mem.service` and enables it. Manual\nequivalent: `systemctl --user enable --now peon-mem.service`, plus `loginctl enable-linger $USER`\nso it survives logout. (Linux support is young — [issue #1](https://github.com/VineetV2/peon-mem/issues/1) tracks real-machine reports.)\n\n### 2. Claude Code — hooks (auto capture + injection)\n\nMerge into `~/.claude/settings.json` (replace the path):\n\n```json\n{\n  \"hooks\": {\n    \"SessionStart\": [{ \"hooks\": [{ \"type\": \"command\",\n      \"command\": \"node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs\" }] }],\n    \"UserPromptSubmit\": [{ \"hooks\": [{ \"type\": \"command\",\n      \"command\": \"node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs\" }] }],\n    \"SessionEnd\": [{ \"hooks\": [{ \"type\": \"command\",\n      \"command\": \"node /ABSOLUTE/PATH/TO/peon/scripts/claude-peon-hook.mjs\" }] }]\n  }\n}\n```\n\n### 3. Claude Code — MCP server (search/inspect tools)\n\n```bash\nclaude mcp add peon -- node /ABSOLUTE/PATH/TO/peon/dist/index.js\n```\n\n### 4. Codex / any MCP client\n\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.peon]\ncommand = \"node\"\nargs = [\"/ABSOLUTE/PATH/TO/peon/dist/index.js\"]\n[mcp_servers.peon.env]\nPEON_DAEMON_URL = \"http://127.0.0.1:3737\"\n```\n\nCodex has no hooks, so add usage rules to `~/.codex/AGENTS.md` telling it to call\n`start_session` + `get_context` at session start and `record_message` for durable facts\n(example block in [docs/](docs/)).\n\n### 5. Verify\n\n```bash\ncurl \"http://127.0.0.1:3737/context?projectPath=$PWD&query=test\"   # JSON context\nopen http://127.0.0.1:3737/monitor                                  # the Neural Universe\n```\n\nStart a Claude Code session in any project, say something decision-shaped, and end the session.\nWithin a minute the monitor shows the belief. The next session injects it.\n\n### MCP tools exposed\n\n`start_session` · `record_message` · `record_event` · `end_session` · `get_context` ·\n`search_memory` · `inspect_brain` · `build_injection` · `query_projects` (cross-project search) ·\n`quality_report` · `remember_global` · `search_global_memory` · `import_global_memory` ·\n`evaluate_project` · `process_memory` · `maybe_process_memory`\n\n### Uninstall\n\n```bash\nlaunchctl unload ~/Library/LaunchAgents/com.peon.daemon.plist\n# remove the hook entries + MCP server from your agent config\n# your memory stays in <project>/.peon/ and ~/Library/Application\\ Support/Peon/ — plain files, delete when ready\n```\n\n## Troubleshooting / FAQ\n\n- **No injection appearing?** `curl http://127.0.0.1:3737/health`; check the hook is registered\n  (run any prompt in `claude`, then look at the monitor's Systems page for the request).\n- **431 errors on huge prompts?** Handled. The hook caps the retrieval query at 2k chars.\n- **No OpenRouter key?** Everything still runs; retrieval is lexical + episodic only\n  (semantic ranking and consolidation need a model). `PEON_EMBEDDING_MODE=ollama` works too.\n- **Cost?** Consolidation is gated (default: fires per ~6k new chars, around cents/day with\n  flash-lite). Query embeddings are cached to disk, so repeats are free.\n- **Multiple machines?** Brains are plain files in your repos. Commit `.peon/` if you want\n  memory to travel (redact first: the raw layer contains session text).\n- **Is my data sent anywhere?** Only consolidation/embedding calls to your configured model\n  provider. No telemetry, no cloud store. The daemon rejects non-loopback callers.\n\n## Configuration (env)\n\n| Var | Default | Purpose |\n|---|---|---|\n| `OPENROUTER_API_KEY` | — | consolidation + embeddings |\n| `PEON_PROCESSING_MODEL` | `google/gemini-2.5-flash-lite` | consolidation model |\n| `PEON_EMBEDDING_MODE` | auto | `api` / `ollama` / `local` / `off` |\n| `PEON_EMBEDDING_MODEL` | — | e.g. `openai/text-embedding-3-small` or an Ollama model |\n| `PEON_OLLAMA_URL` | `http://127.0.0.1:11434` | local embedding server |\n| `PEON_AI_MODE` | `gated` | `off` disables all LLM calls |\n| `PEON_FLUSH_MIN_CHARS` | `6000` | consolidation cost gate |\n| `PEON_MEMORY_DIR` | `.peon` | per-project brain dir name |\n| `PEON_DAEMON_URL` | `http://127.0.0.1:3737` | daemon address |\n| `PEON_CONSOLIDATION_MAX_DELTA_CHARS` | `60000` | anti truncation-stall chunking |\n| `PEON_DISABLED` | — | hard off-switch for A/B testing |\n\n## Project brains\n\n- A brain lives in `<project>/.peon/` as human-readable JSONL and markdown. Commit it or\n  ignore it; your choice (`.gitignore` ships ignoring it).\n- `.peon/root` marks a brain boundary. New brains are born rooted, so a parent directory can\n  never swallow a project's memory.\n- The global brain lives in `~/Library/Application Support/Peon/global/` (macOS).\n\n## Using Peon with NO AI at all\n\nSome people want a memory system that never calls a model: no API keys, no local LLM, no\nembeddings. Peon supports that. Pick **skip** in the install wizard, or set two env vars in\n`<memory-home>/.env`:\n\n```\nPEON_AI_MODE=off\nPEON_EMBEDDING_MODE=off\n```\n\nThe pipeline looks like this without a model. Hooks still capture everything you do into\n`<project>/.peon/raw/` as plain JSONL. As each event arrives, rule-based extraction files it\ninto readable brain files: a line that starts with \"we decided\" or \"always use\" lands in\n`decisions.md`, preferences land in `preferences.md`, file paths land in `artifacts.md`. No\nmodel reads it; it's pattern matching, and you can open the files to see exactly what it\ncaught. At your next session start, the hook asks the daemon for context, the daemon ranks\nthose records by keyword match, recency, and importance, and injects the best ones into your\nprompt. The only step that disappears entirely is consolidation, the nightly LLM pass that\ncompresses raw history into deduplicated beliefs. Without it your memory is a well-indexed\njournal instead of a distilled one. Search still finds things; nothing summarizes them.\n\nWhat still works (all of it deterministic code, no model anywhere):\n\n- **Capture.** Hooks record every prompt, tool call, and session event to plain JSONL in\n  `<project>/.peon/raw/`.\n- **Real-time brain files.** Decisions, preferences, open questions, and artifacts are written\n  live to readable `.md` files by rule-based extraction as events arrive.\n- **Injection.** Session-start context comes from those real-time files, query-focused and\n  budgeted, same as always.\n- **Search.** Lexical retrieval (RRF over keyword rank, recency, importance, and type priors).\n  No embeddings needed. This is the same degrade path the semantic stack falls back to, so it\n  gets exercised constantly.\n- **Episodic recall.** Verbatim what-was-said lookup is lexical by design, so it is unaffected.\n- **Monitor UI, token tracking, cross-project search, backups.** All model-free.\n\nWhat you give up: consolidation (raw events are never distilled into deduplicated beliefs, so\nmemory grows as an append-only journal), semantic search (paraphrased queries need shared\nkeywords), automatic entity extraction, and stale-shadow demotion (it compares embeddings).\n\nTwo escape hatches if you want curation without external AI:\n\n1. `process_memory` accepts a pre-built `aiResult`. The coding agent you already run (Claude\n   Code, Codex) can do the distillation itself in-session and hand Peon the structured result.\n   Memory stays curated, and Peon itself never spends a token.\n2. Everything is plain JSONL/Markdown on disk. You can edit beliefs by hand or through the\n   monitor's memory endpoints, and Peon backs up before every mutation.\n\n## Measured: does memory actually save tokens?\n\nA/B test with real `claude -p` sessions: one question per session, same repo, same model.\nON means Peon hooks active (memory injected at session start). OFF means `PEON_DISABLED=1`,\nso the agent falls back to reading files. 20 questions across procedures, past results,\ndecisions, and current-state facts; 15 clean ON/OFF pairs survived tooling issues. Token\ncounts come from Claude Code's own session transcripts.\n\n| paired, n=15/arm | ON (Peon) | OFF | delta |\n|---|---|---|---|\n| avg tokens (in+out) | **511** | 878 | **−42%** |\n| median tokens | **225** | 1,048 | **−79%** |\n| cache-read tokens | 81.6k | 110.5k | 1.35× less |\n| cheaper arm | **ON wins 12/15** | | |\n\nAnswer quality, graded against repo ground truth: 8 ties, 1 clear Peon win, 5 baseline wins,\n1 where both were weak. The Peon win is the interesting one. A rule that was only ever stated\nin a conversation (a professor's citation policy, from an email) got *\"no such rule found\"*\nfrom the baseline; Peon recited it exactly. Conversation-borne knowledge has no file to grep.\n\nHonest caveats: the test repo has unusually good docs (a maintained research log), which makes\nthe baseline strong, and most repos aren't like that. n=15 is small. Questions were picked to\nhave known answers, not sampled from real usage. The test also exposed two real bugs in Peon\nitself: a stale superseded belief outranking the newer truth, and token rows getting lost when\nconsolidation outlived the hook timeout. Both are fixed (stale-shadow demotion at retrieval;\nusage logged before consolidation).\n\n## Honesty section\n\nPeon's development is eval-gated and keeps its negative results. An associative entity graph\nwas built, measured (−2.9% Recall@10), and turned OFF by default. Consolidation is lossy by\ndesign; that's why the episodic layer exists and is regression-tested. The eval harness and\ncommitted ledger (`npm run eval`) let you verify retrieval changes on your own brain.\n\n## Security\n\n- The daemon binds `127.0.0.1` only and rejects non-loopback `Host`/`Origin` headers\n  (DNS-rebinding defense).\n- Secrets (API keys, tokens, JWTs) are redacted at the injection boundary.\n- Path traversal is guarded. Writes use per-project locks and atomic tmp+rename, with\n  automatic backups before anything destructive-adjacent. Nothing is hard-deleted.\n\n## License\n\nMIT © Vineet Vora\n\n## Contributing — I'd love your help\n\nPeon is built and maintained by one person, and I'm open to help making it better. Issues,\nPRs, ideas, criticism of the architecture, or just telling me where it broke on your machine:\nall of it is useful.\n\nWhere help would matter most right now:\n\n- **Windows & Linux support.** The daemon install is macOS launchd today. The systemd and Task\n  Scheduler equivalents need real users to test them.\n- **More agent integrations.** The wizard covers 11 apps, but hooks-level capture (like the\n  Claude Code integration) for Codex, Cursor, and others would make memory richer everywhere.\n- **Retrieval quality.** The eval harness (`npm run eval`) makes experiments cheap: better\n  consolidation prompts, smarter staleness handling, local embedding models worth defaulting\n  to.\n- **Benchmarks.** Run the token A/B on your repo and share the numbers, especially where Peon\n  loses. Negative results are first-class here.\n- **Docs and onboarding.** If the README or the wizard confused you, that confusion is a bug\n  report.\n\nOpen an issue at [github.com/VineetV2/peon-mem/issues](https://github.com/VineetV2/peon-mem/issues)\nor send a PR directly.\n\nRules of the house: every retrieval/quality change ships with a test and an eval-ledger run\n(`npm run eval`); negative results get documented, not deleted; nothing may hard-delete user\nmemory. `npm test` must stay green.\n\n---\n\n<div align=\"center\">\n\n**If Peon is useful to you, [★ star it on GitHub](https://github.com/VineetV2/peon-mem)** — it is\nhow other people building with coding agents find it.\n\n</div>\n",
  "bytes": 22655,
  "sha": "1d2e5197792c6995fca5dbb19f7f6dd7a0a13f017e10570112ed207a7b4681a9",
  "repo_slug": "vineetv2/peon-mem",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vineetv2_peon_mem_9e7752a2/readme"
}