pi-brain 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Hampson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# pi-brain
+
+Versioned memory for the [pi coding agent](https://github.com/badlogic/pi-mono). Agents commit decisions and reasoning to a `.memory/` directory, preserving context across sessions, compactions, and model switches.
+
+## Getting Started
+
+```bash
+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.
+
+## 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 injection** — No `before_agent_start` hook, no changing content before the conversation. The agent retrieves memory on demand via tool calls, which appear as conversation messages appended at the end (outside the cached prefix).
+- **Fixed tool definitions** — All five tools are registered at startup with static schemas. No tools 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.
+
+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
+
+```bash
+# 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:pi-brain@0.1.0
+
+# Pinned version (git)
+pi install git:github.com/Whamp/pi-brain@v0.1.0
+
+# Project-local (shared via .pi/settings.json)
+pi install -l npm:pi-brain
+
+# Try without installing
+pi -e npm:pi-brain
+```
+
+## Development
+
+```bash
+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

package/agents/memory-committer.md

@@ -0,0 +1,49 @@
+---
+name: memory-committer
+description: Distills OTA logs into structured memory commit entries
+tools: read, grep, find, ls
+model: google-antigravity/gemini-3-flash
+skills: brain
+extensions:
+---
+
+You are a commit distiller for Brain (agent memory).
+
+Before doing anything else, read `.memory/AGENTS.md` for the full protocol reference.
+
+Your job is to read raw OTA logs and previous commits, then produce a structured commit entry.
+
+You will receive a task containing:
+
+- The branch name
+- The commit summary
+- Paths to the OTA log and commits file
+
+Steps:
+
+1. Read `.memory/AGENTS.md`
+2. Read the OTA log for the branch
+3. Read the previous commits (if any) for rolling summary context
+4. Respond with EXACTLY three markdown blocks, nothing else
+
+### Branch Purpose
+
+1-2 sentences restating or refining what this branch is for.
+
+### Previous Progress Summary
+
+A single self-contained rolling summary that synthesizes ALL prior commits into one narrative. A new reader should understand the full branch history from this section alone. If there is no previous commit, write "Initial commit."
+
+### This Commit's Contribution
+
+3-7 concise bullets covering what was just learned, decided, or understood. Focus on:
+
+- Decisions and their rationale
+- What was tried and rejected (negative results matter)
+- Key findings or conclusions
+
+Do NOT include:
+
+- Implementation details (the code captures "what")
+- Filler or padding bullets
+- Anything outside those three blocks

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "pi-brain",
+  "version": "0.1.1",
+  "description": "Versioned memory extension for the pi coding agent",
+  "keywords": [
+    "brain",
+    "context",
+    "memory",
+    "pi",
+    "pi-coding-agent",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/Whamp/pi-brain#readme",
+  "bugs": {
+    "url": "https://github.com/Whamp/pi-brain/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Whamp/pi-brain.git"
+  },
+  "files": [
+    "src/",
+    "!src/**/*.test.ts",
+    "skills/",
+    "agents/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "scripts": {
+    "lint": "oxlint -c .oxlintrc.json",
+    "lint:fix": "oxlint -c .oxlintrc.json --fix",
+    "format": "oxfmt --config .oxfmtrc.jsonc",
+    "format:check": "oxfmt --config .oxfmtrc.jsonc --check",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "deadcode": "knip",
+    "duplicates": "jscpd src/",
+    "secrets": "gitleaks detect --source . --no-git",
+    "check": "bash scripts/check.sh",
+    "fix": "bash scripts/fix.sh",
+    "release": "changelogen --release && git push --follow-tags",
+    "prepare": "node -e \"try{require.resolve('husky')}catch(e){process.exit(0)}\" && husky"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.54.2",
+    "@types/node": "^25.3.0",
+    "changelogen": "^0.6.2",
+    "fast-check": "^4.5.3",
+    "gitleaks": "^1.0.0",
+    "husky": "^9.1.7",
+    "jscpd": "^4.0.8",
+    "knip": "^5.85.0",
+    "lint-staged": "^16.2.7",
+    "oxfmt": "^0.35.0",
+    "oxlint": "^1.50.0",
+    "typescript": "^5.9.3",
+    "ultracite": "^7.2.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  }
+}

package/skills/brain/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: brain
+description: Use when working on a project with Brain agent memory management. Triggers on memory_status, memory_commit, memory_branch, memory_merge, memory_switch tool usage, or when the project has a .memory/ directory.
+---
+
+# Brain — Agent Memory
+
+## Initialization
+
+When the `<skill>` tag loads this file, it includes a `location` attribute with the
+absolute path to this SKILL.md. Use that to derive the init script path:
+
+```bash
+bash "/absolute/path/to/skills/brain/scripts/brain-init.sh"
+```
+
+Replace `/absolute/path/to/skills/brain` with the skill directory shown in the
+`<skill>` tag's `location` attribute (strip the `/SKILL.md` suffix).
+
+### After Init
+
+1. **Tell the user to run `/reload`** — the memory tools won't detect the new `.memory/`
+   directory until the extension reloads.
+2. **Write `.memory/main.md`** — the project roadmap (see below).
+3. **Call `memory_status`** to verify Brain is active.
+4. **Make your first commit** when you reach a meaningful milestone.
+
+### Writing main.md — Greenfield vs Brownfield
+
+**New project (no existing code):** Write goals, intended architecture, and open
+questions as you understand them from conversation with the user.
+
+**Existing project:** Orient yourself first:
+
+- Read `AGENTS.md`, `README.md`, `package.json` (or equivalent)
+- Scan recent git history (`git log --oneline -20`)
+- Read any specs or plans in `docs/`
+
+Then write the roadmap covering: project purpose, current state, key decisions
+already made, completed milestones, and planned work.
+
+## When to Commit
+
+- You've reached a stable understanding or decision
+- You've completed an exploration and have a conclusion
+- You're about to change direction significantly
+- A meaningful amount of work has accumulated (use judgment, not a fixed interval)
+- Before ending a session if significant progress was made
+- **When the extension warns that log.md is large** — even mundane activity is
+  worth distilling. A commit that records "routine maintenance, no significant
+  decisions" tells future agents what was already explored.
+
+## How to Write Good Commits
+
+- Focus on decisions and rationale, not implementation details
+- Capture "why" more than "what" — the code captures "what"
+- Be specific: "Chose PostgreSQL over MongoDB because ACID compliance is required
+  for financial transactions" not "Chose database"
+
+A subagent handles commit distillation — it reads your `log.md` and prior commits,
+then produces the structured commit entry. You just provide a good `summary` string.
+
+## When to Branch
+
+- You want to explore an alternative approach without contaminating current thinking
+- You're prototyping something uncertain
+- You want to compare two design hypotheses
+
+## When to Merge
+
+- A branch has reached a conclusion (positive or negative)
+- The branch's findings should inform the main line of thinking
+- Include what was learned even if the approach was abandoned
+
+**Important:** Always review the source branch history BEFORE calling `memory_merge`.
+Use:
+
+- `memory_status` for high-level status
+- `read .memory/branches/<target>/commits.md` for full branch history
+
+You need the full context to write a good synthesis.
+
+## When to Use Context Retrieval
+
+- Starting a new session on an existing project — call `memory_status` first
+- Before making a decision that might conflict with earlier reasoning
+- When you need to recall the rationale behind a previous decision
+
+## Context Retrieval
+
+Use `memory_status` for high-level status only.
+
+For deep retrieval, use `read` directly:
+
+- `read .memory/branches/<name>/commits.md` — full branch history
+- `read .memory/branches/<name>/log.md` — OTA trace since last commit
+- `read .memory/branches/<name>/metadata.yaml` — structured metadata
+- `read .memory/main.md` — project roadmap
+- `read .memory/AGENTS.md` — full protocol reference

package/skills/brain/scripts/brain-init.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# brain-init.sh — One-time Brain memory initialization
+# Creates .memory/ directory structure and appends Brain section to root AGENTS.md
+# Idempotent: safe to run multiple times without clobbering existing content.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATES_DIR="$SCRIPT_DIR/../templates"
+
+MEMORY_DIR=".memory"
+BRANCHES_DIR="$MEMORY_DIR/branches/main"
+STATE_FILE="$MEMORY_DIR/state.yaml"
+MEMORY_AGENTS_FILE="$MEMORY_DIR/AGENTS.md"
+MAIN_MD_FILE="$MEMORY_DIR/main.md"
+ROOT_AGENTS_FILE="AGENTS.md"
+GITIGNORE_FILE=".gitignore"
+LOG_IGNORE_PATTERN=".memory/branches/*/log.md"
+
+# --- Create .memory directory structure (skip if already exists) ---
+
+if [ ! -d "$BRANCHES_DIR" ]; then
+  mkdir -p "$BRANCHES_DIR"
+fi
+
+if [ ! -f "$BRANCHES_DIR/log.md" ]; then
+  touch "$BRANCHES_DIR/log.md"
+fi
+
+if [ ! -f "$BRANCHES_DIR/commits.md" ]; then
+  cat > "$BRANCHES_DIR/commits.md" <<'EOF'
+# main
+
+**Purpose:** Main project memory branch
+EOF
+fi
+
+if [ ! -f "$BRANCHES_DIR/metadata.yaml" ]; then
+  touch "$BRANCHES_DIR/metadata.yaml"
+fi
+
+if [ ! -f "$MAIN_MD_FILE" ]; then
+  touch "$MAIN_MD_FILE"
+fi
+
+# --- Write state.yaml (skip if already exists) ---
+
+if [ ! -f "$STATE_FILE" ]; then
+  cat > "$STATE_FILE" <<EOF
+active_branch: main
+initialized: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+EOF
+fi
+
+# --- Write .memory/AGENTS.md from template (always overwrite — it's a reference doc) ---
+
+if [ -f "$TEMPLATES_DIR/agents-md.md" ]; then
+  cp "$TEMPLATES_DIR/agents-md.md" "$MEMORY_AGENTS_FILE"
+fi
+
+# --- Append Brain section to root AGENTS.md (idempotent) ---
+
+if [ ! -f "$ROOT_AGENTS_FILE" ]; then
+  touch "$ROOT_AGENTS_FILE"
+fi
+
+if ! grep -q "## Brain" "$ROOT_AGENTS_FILE" 2>/dev/null; then
+  if [ -s "$ROOT_AGENTS_FILE" ]; then
+    echo "" >> "$ROOT_AGENTS_FILE"
+  fi
+  cat "$TEMPLATES_DIR/root-agents-section.md" >> "$ROOT_AGENTS_FILE"
+fi
+
+# --- Ignore transient branch logs in git (idempotent) ---
+
+if [ ! -f "$GITIGNORE_FILE" ]; then
+  touch "$GITIGNORE_FILE"
+fi
+
+if ! grep -Fxq "$LOG_IGNORE_PATTERN" "$GITIGNORE_FILE"; then
+  if [ -s "$GITIGNORE_FILE" ]; then
+    echo "" >> "$GITIGNORE_FILE"
+  fi
+  echo "$LOG_IGNORE_PATTERN" >> "$GITIGNORE_FILE"
+fi
+
+echo "Brain memory initialized successfully."

package/skills/brain/templates/agents-md.md

@@ -0,0 +1,44 @@
+# Brain — Agent Memory
+
+This directory contains your project's agent memory, managed by the Brain extension.
+
+## Tools
+
+| Tool            | Purpose                                 |
+| --------------- | --------------------------------------- |
+| `memory_commit` | Checkpoint a milestone in understanding |
+| `memory_branch` | Create a memory branch for exploration  |
+| `memory_merge`  | Synthesize branch conclusions           |
+| `memory_status` | Multi-resolution retrieval of memory    |
+| `memory_switch` | Switch active memory branch             |
+
+## File Structure
+
+```
+.memory/
+├── AGENTS.md                    # This file — protocol reference
+├── main.md                      # Project roadmap (agent-authored)
+└── branches/
+    └── <branch-name>/
+        ├── commits.md           # Milestone memory snapshots
+        ├── log.md               # OTA trace since last commit (auto)
+        └── metadata.yaml        # Structured context
+```
+
+## Commit Format
+
+Each commit in `commits.md` has three blocks:
+
+- **Branch Purpose** — Why this branch exists
+- **Previous Progress Summary** — Rolling compression of all prior commits
+- **This Commit's Contribution** — What was just learned or decided
+
+The latest commit always contains a self-contained summary of the full branch history.
+
+## Conventions
+
+- **Agent-driven**: You decide when to commit, branch, and merge
+- **Decisions over details**: Capture "why", not "what" — git tracks file changes
+- **Rolling summaries**: Each commit re-synthesizes all prior progress
+- **No direct log.md writes**: The extension maintains log.md automatically
+- **Call `memory_status` first**: Always review context before merging or starting new work

package/skills/brain/templates/root-agents-section.md

@@ -0,0 +1,7 @@
+## Brain — Agent Memory
+
+This project uses Brain for agent memory management.
+
+**Start here when orienting:** Read `.memory/main.md` for the project roadmap, key decisions, and open problems.
+Read `.memory/AGENTS.md` for the full Brain protocol reference.
+Tools: memory_commit, memory_branch, memory_merge, memory_switch, memory_status

package/src/branches.ts

@@ -0,0 +1,125 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Manages `.memory/branches/` directory operations.
+ * Each branch has: log.md, commits.md, metadata.yaml.
+ */
+export class BranchManager {
+  private readonly branchesDir: string;
+
+  constructor(projectDir: string) {
+    this.branchesDir = path.join(projectDir, ".memory", "branches");
+  }
+
+  createBranch(name: string, purpose: string): void {
+    const branchDir = path.join(this.branchesDir, name);
+    fs.mkdirSync(branchDir, { recursive: true });
+    fs.writeFileSync(path.join(branchDir, "log.md"), "");
+    fs.writeFileSync(
+      path.join(branchDir, "commits.md"),
+      `# ${name}\n\n**Purpose:** ${purpose}\n`
+    );
+    fs.writeFileSync(path.join(branchDir, "metadata.yaml"), "");
+  }
+
+  appendLog(branch: string, content: string): void {
+    const logPath = this.logPath(branch);
+    fs.appendFileSync(logPath, content);
+  }
+
+  readLog(branch: string): string {
+    const logPath = this.logPath(branch);
+    if (!fs.existsSync(logPath)) {
+      return "";
+    }
+    return fs.readFileSync(logPath, "utf8");
+  }
+
+  clearLog(branch: string): void {
+    const logPath = this.logPath(branch);
+    if (fs.existsSync(logPath)) {
+      fs.writeFileSync(logPath, "");
+    }
+  }
+
+  appendCommit(branch: string, entry: string): void {
+    const commitsPath = this.commitsPath(branch);
+    fs.appendFileSync(commitsPath, entry);
+  }
+
+  readCommits(branch: string): string {
+    const commitsPath = this.commitsPath(branch);
+    if (!fs.existsSync(commitsPath)) {
+      return "";
+    }
+    return fs.readFileSync(commitsPath, "utf8");
+  }
+
+  readMetadata(branch: string): string {
+    const metaPath = path.join(this.branchesDir, branch, "metadata.yaml");
+    if (!fs.existsSync(metaPath)) {
+      return "";
+    }
+    return fs.readFileSync(metaPath, "utf8");
+  }
+
+  listBranches(): string[] {
+    if (!fs.existsSync(this.branchesDir)) {
+      return [];
+    }
+
+    return fs.readdirSync(this.branchesDir).filter((entry) => {
+      const fullPath = path.join(this.branchesDir, entry);
+      return fs.statSync(fullPath).isDirectory();
+    });
+  }
+
+  branchExists(name: string): boolean {
+    const branchDir = path.join(this.branchesDir, name);
+    return fs.existsSync(branchDir) && fs.statSync(branchDir).isDirectory();
+  }
+
+  getLogSizeBytes(branch: string): number {
+    const lp = this.logPath(branch);
+    if (!fs.existsSync(lp)) {
+      return 0;
+    }
+    return fs.statSync(lp).size;
+  }
+
+  getLogTurnCount(branch: string): number {
+    const log = this.readLog(branch);
+    if (log === "") {
+      return 0;
+    }
+    const matches = log.match(/^## Turn /gm);
+    return matches ? matches.length : 0;
+  }
+
+  getLatestCommit(branch: string): string | null {
+    const commits = this.readCommits(branch);
+    if (commits === "") {
+      return null;
+    }
+
+    // Split on commit separator (--- followed by ## Commit)
+    const parts = commits.split(/\n---\n/);
+    // Find the last part that contains a commit header
+    for (let i = parts.length - 1; i >= 0; i--) {
+      if (parts[i].includes("## Commit ")) {
+        return parts[i].trim();
+      }
+    }
+
+    return null;
+  }
+
+  private logPath(branch: string): string {
+    return path.join(this.branchesDir, branch, "log.md");
+  }
+
+  private commitsPath(branch: string): string {
+    return path.join(this.branchesDir, branch, "commits.md");
+  }
+}

package/src/constants.ts

@@ -0,0 +1,2 @@
+/** 600 KB — approximately 150k-175k tokens of mixed markdown content. */
+export const LOG_SIZE_WARNING_BYTES = 600 * 1024;

package/src/hash.ts

@@ -0,0 +1,8 @@
+import { randomBytes } from "node:crypto";
+
+/**
+ * Generate an 8-character lowercase hex hash for memory commits.
+ */
+export function generateHash(): string {
+  return randomBytes(4).toString("hex");
+}