pi-brain 0.1.4 → 0.1.5

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.5",
   "description": "Versioned memory extension for the pi coding agent",
   "keywords": [
     "agent-memory",

package/skills/brain/SKILL.md

@@ -76,6 +76,20 @@ 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
+
+**Update `.memory/main.md` to reflect the current state.** The roadmap is the first
+thing a new session reads — if it's stale, every future session starts with a wrong
+picture. After `memory_commit` returns, review and update:
+
+- **Current State** section — reflect what's actually true now
+- **Key Decisions Made** — add any new decisions from this commit
+- **Milestones** — move completed items, add new planned ones
+
+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, update `.memory/main.md` to reflect the new state — current state, decisions, and milestones. The roadmap is the first thing new sessions read; stale roadmaps cause wrong orientation. For trivial commits that don't change project state (e.g., minor refactors), pass `update_roadmap: false` to skip the reminder.

package/src/index.ts

@@ -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);

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:** Update `.memory/main.md` to reflect this commit — current state, decisions, and milestones. The roadmap is the first thing new sessions read.";
+
+  return `${resultText}\n\n${status}${roadmapReminder}`;
 }