peon-mem

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




![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.*

![Search flare — type a query and matching beliefs light up across every galaxy](docs/assets/search-flare.gif)

*Ask the field: typing "wulver cluster" makes 400+ matching beliefs flare while the rest dim, and the camera flies to them.*

## Why "Peon"?

The name comes from Indian offices. Every office had a **peon**, the person who walked desk to
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

| | **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 | — |

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

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

### 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: 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/issu