# Pi Mem

> Harness-verified memory recall for coding agents — re-checks a memory note against ground truth on read (verified/stale/unverifiable). Built on the pi-gate trust boundary.

- **Type:** MCP server
- **Install:** `agentstack add mcp-renezander030-pi-mem`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [renezander030](https://agentstack.voostack.com/s/renezander030)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [renezander030](https://github.com/renezander030)
- **Source:** https://github.com/renezander030/pi-mem

## Install

```sh
agentstack add mcp-renezander030-pi-mem
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/renezander030/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

```bash
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

```bash
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

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

```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](https://github.com/renezander030/pi-okf)** — authored knowledge bundles (OKF format)
- **[pi-codegraph](https://github.com/renezander030/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

```bash
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](https://github.com/renezander030)
- **Source:** [renezander030/pi-mem](https://github.com/renezander030/pi-mem)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-renezander030-pi-mem
- Seller: https://agentstack.voostack.com/s/renezander030
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.