pi-memory

Persistent, file-based memory for the pi coding agent. The agent accumulates durable learnings (corrections, build commands, decisions, preferences) across sessions in plain markdown you can read, edit, and diff.

Design rationale and research: docs/design.md, docs/research/.

How it works

Two scopes, mirroring pi's own global/project convention:

~/.pi/agent/memory/      # global: this user, all projects (machine-local)
<repo>/.pi/memory/       # project: committed to the repo, shared with the team
├── MEMORY.md            # concise index — injected into every session (capped)
├── <topic>.md           # detail files — the agent reads them on demand
└── archive/             # stale content is moved here, never injected

On every prompt, the extension appends a memory block to the system prompt: a short usage preamble plus each scope's MEMORY.md, capped at 200 lines / 8 KiB per scope. The agent saves and updates memories by editing these files with pi's built-in edit/write tools — every change is visible in the tool log and (for project scope) in version control.

Project memory is only read in trusted projects, and the extension never creates directories on its own — files appear the first time the agent saves something.

Install

pi install npm:@josephakern/pi-memory                 # global, from npm
pi install git:github.com/josephkern/pi-memory        # global, from git
pi install -l npm:@josephakern/pi-memory              # project-local (.pi/settings.json)

Or for development:

pi -e ./src/index.ts

Usage

There is nothing to set up. Tell pi things like "remember that we use pnpm here" — or just work; the agent saves what seems durable.

• /memory — show both scopes: files, sizes, what's injected vs. capped, trust state.
• /memory pages — preview ClawVM-style typed pages derived from MEMORY.md and page-table sidecar status.
• /memory verify — rebuild page-table.jsonl sidecars from current MEMORY.md files.
• /memory remember global|project <text> — stage an append-only memory write in writeback-journal.jsonl.
• /memory flush — validate/commit pending writeback operations and rebuild page tables.
• /memory faults / /memory traces / /memory trace <id> — inspect memory faults and residency/writeback traces.
• /memory off / /memory on — toggle injection for the current session.
• pi --no-memory — start with injection disabled.

Memory files are plain markdown: edit or delete them in your editor any time.

Configuration

Optional config.json in either memory directory (project overrides global, like pi settings):

{
  "enabled": true,
  "maxInjectLines": 200,
  "maxInjectBytes": 8192,
  "pageTableInjection": true,
  "maxMemoryTokens": 4096,
  "traceEnabled": true,
  "strictWriteback": true
}

Development

npm install
npm run typecheck
npm test

Provider-backed memory smoke tests are opt-in because they call real pi agents:

npm run test:provider