Peon Mem

🧠 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, 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

/ | \ project A project B project C ← rooted child brains (.peon/ in each project)

Why Peon

• 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. In my own LongMemEval run, raw-episodic recall scored 61% where belief-only scored 17% — self-measured, not an independent benchmark; reproduce it with npm run eval.
• 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.

*The live monitor: 18k real beliefs rendered as stars. Type to make matching beliefs flare; click one to inspect it.*

*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 desk all day: collect a file from this table, note who needs what, carry it to the next table, 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 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

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

Requirements: Node 20+, macOS or Linux. An OpenRouter API key is recommended (consolidation + semantic embeddings); without one Peon still works lexical-only.

One line:

npm install -g peon-mem && peon-mem install

(no Node? curl -fsSL https://raw.githubusercontent.com/VineetV2/peon-mem/main/install.sh | bash)

The guided setup asks four things:

1. Where your global brain lives (default: ~/Library/Application Support/Peon)
2. Which LLM: OpenRouter (one key, any model) · OpenAI · Anthropic · Ollama (100% local & free) · or skip
3. Installs the daemon as an auto-start service (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, Cline, 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:

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:

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):

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, and tool calls into /.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)

1. Daemon (always-on, macOS launchd)

node scripts/install-peon.mjs           # prints everything below filled in for YOUR paths

Or manually — ~/Library/LaunchAgents/com.peon.daemon.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">

Label com.peon.daemon ProgramArguments /opt/homebrew/bin/node /ABSOLUTE/PATH/TO/peon/dist/daemon-cli.js

RunAtLoad KeepAlive

launchctl load ~/Library/LaunchAgents/com.peon.daemon.plist

curl http://127.0.0.1:3737/health # → {"ok":true}

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 tracks real-machine reports.)

2. Claude Code — hooks (auto capture + injection)

Merge into ~/.claude/settings.json (replace the path):

{

"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": [