pi-brain

Versioned memory for the pi coding agent. Agents commit decisions and reasoning to a .memory/ directory, preserving context across sessions, compactions, and model switches.

Credit: This project is my implementation for Pi of this paper Git Context Controller: Manage the Context of LLM-based Agents like Git

Getting Started

pi install npm:pi-brain

Open pi in any project and say "initialize Brain" (or run /skill:brain). The agent creates .memory/ and starts remembering.

That's it. The agent decides when to commit, branch, and merge — you don't need to manage anything. However, you can always prompt the agent to remember something specific if you'd like.

How It Works

Brain adds five tools and a few lifecycle hooks to pi. The design is simple: the agent works normally, and Brain records what happens in the background.

Every turn, Brain appends a structured log entry to .memory/branches/<branch>/log.md. This happens automatically via the turn_end hook — the agent doesn't call anything.

When the agent reaches a milestone, it calls memory_commit with a short summary. Brain spawns a subagent in a fresh context window that reads the raw log, distills it into a structured commit (decisions, rationale, what was tried and rejected), and appends it to commits.md. The log is then cleared.

Each commit is self-contained. It includes a rolling summary of all prior commits, so the latest commit always tells the full branch story. A new session can read one commit and know everything.

Branching and merging work like you'd expect. The agent branches to explore alternatives without contaminating the main line, then merges conclusions back with a synthesis.

The Five Tools

| Tool | What it does | | --------------- | ---------------------------------------------------------------- | | memory_status | Quick status overview — active branch, latest commit, turn count | | memory_commit | Checkpoint a milestone (subagent distills the log) | | memory_branch | Create a branch for exploration | | memory_switch | Switch between branches | | memory_merge | Merge insights from one branch into another |

For deep retrieval, the agent uses pi's built-in read tool on .memory/ files directly. No special API needed.

Prompt Cache Safety

LLM providers cache the prefix of each request. If the prefix changes between turns, the cache misses and you pay full latency and cost. Many memory systems break this by injecting dynamic state into the system prompt.

Brain avoids this entirely:

• Static AGENTS.md — Written once at init, never updated. No branch names, no commit counts, no dynamic state. The system prompt prefix stays identical across every turn and session.
• No per-turn prompt mutation — Brain does not rewrite systemPrompt between turns. Status context is appended as message content, keeping the cached prefix stable.
• Fixed tool definitions — Tool schemas are static at startup. No tools are added or removed mid-conversation.
• Subagent isolation — Commit distillation runs in a separate API call with its own cache. The main agent's cache is never touched.
• Regression-tested safety — Prompt-cache safety invariants are covered in src/cache-safety.test.ts (property tests for append-only prompt behavior, lifecycle-gated status injection, and deterministic status rendering).

The result: Brain adds zero overhead to your prompt cache hit rate.

What Gets Created

.memory/
├── AGENTS.md                      # Protocol reference
├── main.md                        # Project roadmap (agent-authored)
├── state.yaml                     # Active branch, session tracking
└── branches/
    └── main/
        ├── commits.md             # Distilled milestone snapshots
        ├── log.md                 # Raw turn log (gitignored)
        └── metadata.yaml          # Structured context

Everything in .memory/ is tracked in git except log.md (transient working state). This means memory is shared across machines and team members.

Install Options

# From npm (recommended)
pi install npm:pi-brain

# From git (latest)
pi install git:github.com/Whamp/pi-brain

# Pinned version (npm)
pi install npm:[email protected]

# Pinned version (git)
pi install git:github.com/Whamp/[email protected]

# Project-local (shared via .pi/settings.json)
pi install -l npm:pi-brain

# Try without installing
pi -e npm:pi-brain

Development

git clone https://github.com/Whamp/pi-brain.git
cd pi-brain
pnpm install --prod=false
pnpm run check               # lint + typecheck + format + tests + deadcode + secrets

pi -e ./src/index.ts          # run pi with extension loaded from source

| Command | Purpose | | ------------------ | --------------- | | pnpm run check | Full validation | | pnpm run test | Tests only | | pnpm run release | Bump, tag, push |

License

MIT