Peon Mem

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