pi-brain 0.1.4 → 0.1.6

package/README.md

@@ -6,6 +6,8 @@
 
 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.
 
+Credit: This project is my implementation for Pi of this paper [Git Context Controller: Manage the Context of LLM-based Agents like Git](https://arxiv.org/html/2508.00031v1)
+
 ## Getting Started
 
 ```bash
@@ -14,7 +16,7 @@ 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.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-brain",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Versioned memory extension for the pi coding agent",
   "keywords": [
     "agent-memory",

package/skills/brain/SKILL.md

@@ -76,6 +76,28 @@ For deep retrieval, use `read` directly:
 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.
 
+## After Every Commit
+
+**Re-read `.memory/main.md` and rewrite stale sections.** The roadmap is the first
+thing a new session reads — if it's stale, every future session starts with a wrong
+picture. This means genuine review, not mechanical edits.
+
+After `memory_commit` returns:
+
+1. Read `.memory/main.md` in full.
+2. Rewrite the **Current State** section to describe what is true _right now_ — remove
+   historical context that has migrated to Key Decisions or Milestones.
+3. Add any new entries to **Key Decisions Made**.
+4. Move completed items in **Milestones** and add new planned ones.
+5. Remove or rewrite anything a new reader would find misleading.
+
+The goal is curation, not accumulation. A reader of Current State should understand
+the project as it exists today without wading through history.
+
+For trivial commits that don't change the project's state, decisions, or milestones
+(e.g., minor refactors, typo fixes), you can pass `update_roadmap: false` to skip
+the reminder. Most commits should update the roadmap.
+
 ## When to Branch
 
 - You want to explore an alternative approach without contaminating current thinking

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

@@ -40,6 +40,17 @@ Each commit in `commits.md` has three blocks:
 
 The latest commit always contains a self-contained summary of the full branch history.
 
+## When to Commit
+
+Call `memory_commit` when one of these is true:
+
+- You reached a stable decision or understanding worth preserving.
+- You finished an exploration branch with a clear conclusion.
+- You are about to change direction significantly.
+- You completed meaningful progress and are about to end the session.
+- The extension warns that `log.md` is getting large.
+- You are about to claim the task is complete or hand off to another agent.
+
 ## Conventions
 
 - **Agent-driven**: You decide when to commit, branch, and merge
@@ -47,3 +58,4 @@ The latest commit always contains a self-contained summary of the full branch hi
 - **Rolling summaries**: Each commit re-synthesizes all prior progress
 - **No direct log.md writes**: The extension maintains log.md automatically
 - **Status is automatic**: Memory status is injected at session start and appended to tool results (compact/truncated when large; use `read .memory/main.md` for full roadmap)
+- **Keep main.md current**: After every commit, re-read `.memory/main.md` in full and rewrite stale sections. Current State should describe what is true _right now_ — remove historical context that belongs in Key Decisions or Milestones. The goal is curation, not accumulation. For trivial commits that don't change project state, pass `update_roadmap: false` to skip the reminder.

package/src/index.ts

@@ -101,7 +101,7 @@ function resolveSkillPath(): string {
 export default function activate(pi: ExtensionAPI) {
   let state: MemoryState | null = null;
   let branchManager: BranchManager | null = null;
-  let statusInjected = false;
+  let frozenStatusSnapshot: string | null = null;
 
   function tryLoad(ctx: ExtensionContext): boolean {
     if (isMemoryReady(state, branchManager)) {
@@ -127,12 +127,10 @@ export default function activate(pi: ExtensionAPI) {
     description:
       "Manage memory branches. Actions: create (new branch), switch (change active branch), merge (synthesize branch into current).",
     parameters: Type.Object({
-      action: Type.Union(
-        [Type.Literal("create"), Type.Literal("switch"), Type.Literal("merge")],
-        {
-          description: 'Action to perform: "create", "switch", or "merge"',
-        }
-      ),
+      action: Type.String({
+        enum: ["create", "switch", "merge"],
+        description: 'Action to perform: "create", "switch", or "merge"',
+      }),
       name: Type.Optional(
         Type.String({ description: "Branch name (required for create)" })
       ),
@@ -180,7 +178,12 @@ export default function activate(pi: ExtensionAPI) {
     description: "Checkpoint a milestone in agent memory.",
     parameters: Type.Object({
       summary: Type.String({ description: "Short summary of this checkpoint" }),
-      update_roadmap: Type.Optional(Type.Boolean()),
+      update_roadmap: Type.Optional(
+        Type.Boolean({
+          description:
+            "Update .memory/main.md after commit. Defaults to true — set false to skip for trivial commits.",
+        })
+      ),
     }),
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       if (
@@ -214,7 +217,8 @@ export default function activate(pi: ExtensionAPI) {
         commitContent,
         state,
         branchManager,
-        ctx.cwd
+        ctx.cwd,
+        params.update_roadmap
       );
 
       setBrainFooterStatus(ctx, state, branchManager);
@@ -226,7 +230,7 @@ export default function activate(pi: ExtensionAPI) {
     state = new MemoryState(ctx.cwd);
     state.load();
     branchManager = new BranchManager(ctx.cwd);
-    statusInjected = false;
+    frozenStatusSnapshot = null;
 
     if (!state.isInitialized) {
       setBrainFooterStatus(ctx, state, branchManager);
@@ -249,7 +253,7 @@ export default function activate(pi: ExtensionAPI) {
   });
 
   pi.on("session_switch", (_event, ctx) => {
-    statusInjected = false;
+    frozenStatusSnapshot = null;
 
     state = new MemoryState(ctx.cwd);
     state.load();
@@ -262,11 +266,7 @@ export default function activate(pi: ExtensionAPI) {
     setBrainFooterStatus(ctx, state, branchManager);
   });
 
-  pi.on("before_agent_start", (_event: BeforeAgentStartEvent, ctx) => {
-    if (statusInjected) {
-      return;
-    }
-
+  pi.on("before_agent_start", (event: BeforeAgentStartEvent, ctx) => {
     if (
       !tryLoad(ctx) ||
       !isMemoryReady(state, branchManager) ||
@@ -275,25 +275,21 @@ export default function activate(pi: ExtensionAPI) {
       return;
     }
 
-    statusInjected = true;
+    if (frozenStatusSnapshot === null) {
+      frozenStatusSnapshot = buildStatusView(state, branchManager, ctx.cwd, {
+        compact: true,
+        roadmapCharLimit: BEFORE_AGENT_START_ROADMAP_CHAR_LIMIT,
+        branchLimit: BEFORE_AGENT_START_BRANCH_LIMIT,
+      });
+    }
 
-    const status = buildStatusView(state, branchManager, ctx.cwd, {
-      compact: true,
-      roadmapCharLimit: BEFORE_AGENT_START_ROADMAP_CHAR_LIMIT,
-      branchLimit: BEFORE_AGENT_START_BRANCH_LIMIT,
-    });
     return {
-      message: {
-        customType: "brain-status",
-        content: status,
-        display: true,
-        details: {},
-      },
+      systemPrompt: `${event.systemPrompt}\n\n${frozenStatusSnapshot}`,
     };
   });
 
   pi.on("session_compact", () => {
-    statusInjected = false;
+    frozenStatusSnapshot = null;
   });
 
   pi.on("resources_discover", () => ({

package/src/memory-commit.ts

@@ -34,7 +34,8 @@ export function finalizeMemoryCommit(
   commitContent: string,
   state: MemoryState,
   branches: BranchManager,
-  projectDir: string
+  projectDir: string,
+  updateRoadmap?: boolean
 ): string {
   const branch = state.activeBranch;
   const hash = generateHash();
@@ -60,5 +61,11 @@ export function finalizeMemoryCommit(
   const status = buildStatusView(state, branches, projectDir, {
     compact: true,
   });
-  return `${resultText}\n\n${status}`;
+
+  const roadmapReminder =
+    updateRoadmap === false
+      ? ""
+      : "\n\n**Action required:** Re-read `.memory/main.md` in full and rewrite stale sections. Current State should describe what is true right now — curate, don't just append.";
+
+  return `${resultText}\n\n${status}${roadmapReminder}`;
 }