Pi Mem

pi-mem

Harness-verified memory recall for coding agents. Re-checks a memory note against ground truth on read, and stamps it ✅ verified · ⚠️ stale · ◻️ unverifiable — so the agent stops trusting its own context (KV cache) and asks the harness to double-check instead.

An agent's "memory" is usually just text sitting in its context window. It rots: the file it cites moves, the flag it remembers gets removed, the command it recalls stops working — but the text still reads confidently. The usual mitigation is a passive tag ("this note is 30 days old, verify it yourself") that the agent is told to honor and rarely does.

pi-mem makes that verification active. A memory note may declare a verify: block of deterministic, ground-truth checks. On recall, pi-mem runs them and returns a verdict the agent can't ignore — stale notes are named and quarantined; authored preferences with no ground truth are labeled honestly rather than dressed up as facts.

> Built on the pi-gate trust pattern: the runner and > canonical store live outside the agent's writable tree. The agent can propose memory, but > it cannot stamp its own memory verified — only this runner can. That is the whole point.

Install

git clone https://github.com/renezander030/pi-mem && cd pi-mem
sudo ln -sf "$PWD/pi-mem" /usr/local/bin/pi-mem

Node 18+, zero runtime dependencies (foundation.js is vendored).

Use

pi-mem recall "deploy flow"     # relevant notes, each stamped, JSON (add -H for a table)
pi-mem verify          # run one note's checks now; per-check report
pi-mem check           # show the verify manifest WITHOUT running it (dry plan)
pi-mem survey                   # catalog notes + check counts
pi-mem trust                    # register the store as trusted (enables exec-kind checks)

Point it at your store with PI_MEM_STORE=/path/to/memory (a dir of markdown notes).

The three states

| State | Glyph | Meaning | |---|---|---| | verified | ✅ | a ground-truth check ran and all runnable checks passed — re-confirmed this session | | stale | ⚠️ | a check ran and failed — the remembered fact no longer holds; do not act on it | | unverifiable | ◻️ | no runnable ground-truth check exists (pure authored claim) — labeled, never a false green |

Design rule: bias to false-negatives, never false-positives. A wrong "stale" makes the agent discard true knowledge, so auto-extraction is deliberately conservative (only high-confidence absolute filesystem paths; web routes and URLs are left ◻️ unverifiable). For reliable checks, declare them.

Declaring checks

---
name: reference_deploy
verify:
  - kind: file  path: /srv/app/deploy.sh                    # exists? (add line: N to assert a line)
  - kind: grep  path: /srv/app/deploy.sh   needle: "wrangler pages deploy"
  - kind: git   repo: /srv/app             path: deploy.sh  # still tracked?
  - kind: cmd   run: "app --version"                        # liveness (trust-gated)
  - kind: codegraph  repo: /srv/app  symbol: main           # re-derive (trust-gated)
---
The deploy script lives at `/srv/app/deploy.sh`; run it after every push.

file, grep, git are read-only and always run. cmd, codegraph execute code and run only on a trusted store (pi-mem trust) — otherwise they're reported as unrunnable, not passed.

Wire it into your harness

Register the SessionStart hook so every session opens with a live memory verdict instead of stale text. For Claude Code (~/.claude/settings.json):

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "node /path/to/pi-mem/hooks/sessionstart.mjs" } ] }
    ]
  }
}

The hook re-derives every verifiable note and injects a report that puts ⚠️ stale notes up front.

Two kinds of agent memory

pi-mem is the read-time verifier. It complements:

• pi-okf — authored knowledge bundles (OKF format)
• pi-codegraph — derived code knowledge (codebase graph)

All three share the pi-gate trust boundary: harness owns the canonical state; the agent proposes, the harness verifies.

Tests

npm test   # bash test/run.sh — deterministic, runs against test/fixtures

License

MIT © 2026 Rene Zander

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: renezander030
• Source: renezander030/pi-mem
• License: MIT

Install and usage instructions live in the source repository linked above.