pi-brain 0.1.2 → 0.1.5

package/README.md

@@ -1,7 +1,13 @@
+<p align="center">
+  <img src="./banner.png" alt="pi-brain banner" width="720" />
+</p>
+
 # 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.
 
+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
@@ -10,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
 
@@ -43,9 +49,10 @@ LLM providers cache the prefix of each request. If the prefix changes between tu
 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.
+- **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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-brain",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Versioned memory extension for the pi coding agent",
   "keywords": [
     "agent-memory",
@@ -27,7 +27,8 @@
     "skills/",
     "agents/",
     "package.json",
-    "README.md"
+    "README.md",
+    "banner.png"
   ],
   "type": "module",
   "scripts": {

package/skills/brain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use when working on a project with Brain agent memory management. Triggers on memory_commit, memory_branch tool usage, or when the project has a .memory/ directory.
 ---
 
 # Brain — Agent Memory
@@ -19,11 +19,11 @@ Replace `/absolute/path/to/skills/brain` with the skill directory shown in the
 
 ### 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.
+1. **Write `.memory/main.md`** — the project roadmap (see below).
+2. **Make your first commit** when you reach a meaningful milestone.
+
+> **Note:** No `/reload` is needed. The memory tools lazily detect `.memory/`
+> on every call via `tryLoad()`.
 
 ### Writing main.md — Greenfield vs Brownfield
 
@@ -39,6 +39,22 @@ questions as you understand them from conversation with the user.
 Then write the roadmap covering: project purpose, current state, key decisions
 already made, completed milestones, and planned work.
 
+## Context Retrieval
+
+Memory status is **automatically injected** at session start (via the
+`before_agent_start` hook) and appended to every successful `memory_branch` and
+`memory_commit` result. Automatic status is compact and may truncate long
+roadmaps, so keep the newest critical context near the top of `.memory/main.md`.
+You do not need to call a separate tool to see status.
+
+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
+
 ## When to Commit
 
 - You've reached a stable understanding or decision
@@ -60,6 +76,20 @@ already made, completed milestones, and planned work.
 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
@@ -72,28 +102,6 @@ then produces the structured commit entry. You just provide a good `summary` str
 - 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
-
+**Important:** Always review the source branch history BEFORE calling merge.
+Use `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/templates/agents-md.md

@@ -4,13 +4,18 @@ This directory contains your project's agent memory, managed by the Brain extens
 
 ## 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             |
+| Tool            | Purpose                                   |
+| --------------- | ----------------------------------------- |
+| `memory_commit` | Checkpoint a milestone in understanding   |
+| `memory_branch` | Manage branches: create, switch, or merge |
+
+### memory_branch Actions
+
+| Action   | Required Params       | Description                                 |
+| -------- | --------------------- | ------------------------------------------- |
+| `create` | `name`, `purpose`     | Create a new branch and switch to it        |
+| `switch` | `branch`              | Switch active memory branch                 |
+| `merge`  | `branch`, `synthesis` | Synthesize a branch's insights into current |
 
 ## File Structure
 
@@ -35,10 +40,22 @@ 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
 - **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
+- **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/skills/brain/templates/root-agents-section.md

@@ -4,4 +4,4 @@ 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
+Tools: memory_commit, memory_branch (create/switch/merge)

package/src/branches.ts

@@ -1,6 +1,25 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+function sortBranchNames(names: readonly string[]): string[] {
+  const sorted: string[] = [];
+
+  for (const name of names) {
+    const insertIndex = sorted.findIndex(
+      (existing) => existing.localeCompare(name) > 0
+    );
+
+    if (insertIndex === -1) {
+      sorted.push(name);
+      continue;
+    }
+
+    sorted.splice(insertIndex, 0, name);
+  }
+
+  return sorted;
+}
+
 /**
  * Manages `.memory/branches/` directory operations.
  * Each branch has: log.md, commits.md, metadata.yaml.
@@ -64,15 +83,21 @@ export class BranchManager {
     return fs.readFileSync(metaPath, "utf8");
   }
 
+  protected readBranchEntries(): string[] {
+    return fs.readdirSync(this.branchesDir);
+  }
+
   listBranches(): string[] {
     if (!fs.existsSync(this.branchesDir)) {
       return [];
     }
 
-    return fs.readdirSync(this.branchesDir).filter((entry) => {
+    const branchNames = this.readBranchEntries().filter((entry) => {
       const fullPath = path.join(this.branchesDir, entry);
       return fs.statSync(fullPath).isDirectory();
     });
+
+    return sortBranchNames(branchNames);
   }
 
   branchExists(name: string): boolean {

package/src/index.ts

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 
 import type {
   AgentToolResult,
+  BeforeAgentStartEvent,
   ExtensionAPI,
   ExtensionContext,
   SessionBeforeCompactEvent,
@@ -13,9 +14,7 @@ import { BranchManager } from "./branches.js";
 import { LOG_SIZE_WARNING_BYTES } from "./constants.js";
 import { executeMemoryBranch } from "./memory-branch.js";
 import { executeMemoryCommit, finalizeMemoryCommit } from "./memory-commit.js";
-import { executeMemoryStatus } from "./memory-context.js";
-import { executeMemoryMerge } from "./memory-merge.js";
-import { executeMemorySwitch } from "./memory-switch.js";
+import { buildStatusView } from "./memory-context.js";
 import { formatOtaEntry } from "./ota-formatter.js";
 import { extractOtaInput } from "./ota-logger.js";
 import { MemoryState } from "./state.js";
@@ -23,6 +22,8 @@ import { extractCommitBlocks, spawnCommitter } from "./subagent.js";
 
 const MEMORY_NOT_INITIALIZED_MESSAGE =
   "Brain not initialized. Run brain-init.sh first.";
+const BEFORE_AGENT_START_ROADMAP_CHAR_LIMIT = 1200;
+const BEFORE_AGENT_START_BRANCH_LIMIT = 8;
 
 function createTextResult(text: string): AgentToolResult<unknown> {
   return {
@@ -52,6 +53,21 @@ function upsertCurrentSession(state: MemoryState, ctx: ExtensionContext): void {
   state.save();
 }
 
+function setBrainFooterStatus(
+  ctx: ExtensionContext,
+  state: MemoryState | null,
+  branchManager: BranchManager | null
+): void {
+  if (!state || !branchManager || !state.isInitialized) {
+    ctx.ui.setStatus("brain", undefined);
+    return;
+  }
+
+  const turnCount = branchManager.getLogTurnCount(state.activeBranch);
+  const turnLabel = `${turnCount} uncommitted turn${turnCount === 1 ? "" : "s"}`;
+  ctx.ui.setStatus("brain", `Brain: ${state.activeBranch} (${turnLabel})`);
+}
+
 function buildCompactionReminder(
   state: MemoryState,
   branchManager: BranchManager
@@ -85,6 +101,7 @@ function resolveSkillPath(): string {
 export default function activate(pi: ExtensionAPI) {
   let state: MemoryState | null = null;
   let branchManager: BranchManager | null = null;
+  let statusInjected = false;
 
   function tryLoad(ctx: ExtensionContext): boolean {
     if (isMemoryReady(state, branchManager)) {
@@ -104,107 +121,54 @@ export default function activate(pi: ExtensionAPI) {
     return true;
   }
 
-  pi.registerTool({
-    name: "memory_status",
-    label: "Memory Status",
-    description: "Retrieve agent memory status overview.",
-    parameters: Type.Object({
-      level: Type.Optional(Type.String()),
-      branch: Type.Optional(Type.String()),
-      commit: Type.Optional(Type.String()),
-      segment: Type.Optional(Type.String()),
-    }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      if (
-        !tryLoad(ctx) ||
-        !isMemoryReady(state, branchManager) ||
-        !branchManager
-      ) {
-        return createTextResult(MEMORY_NOT_INITIALIZED_MESSAGE);
-      }
-
-      return createTextResult(
-        executeMemoryStatus(params, state, branchManager, ctx.cwd)
-      );
-    },
-  });
-
   pi.registerTool({
     name: "memory_branch",
     label: "Memory Branch",
-    description: "Create a new memory branch.",
-    parameters: Type.Object({
-      name: Type.String({ description: "Branch name" }),
-      purpose: Type.String({ description: "Why this branch exists" }),
-    }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      if (
-        !tryLoad(ctx) ||
-        !isMemoryReady(state, branchManager) ||
-        !branchManager
-      ) {
-        return createTextResult(MEMORY_NOT_INITIALIZED_MESSAGE);
-      }
-
-      const previousBranch = state.activeBranch;
-      const result = executeMemoryBranch(params, state, branchManager);
-
-      if (state.activeBranch !== previousBranch) {
-        upsertCurrentSession(state, ctx);
-      }
-
-      return createTextResult(result);
-    },
-  });
-
-  pi.registerTool({
-    name: "memory_switch",
-    label: "Memory Switch",
-    description: "Switch to another memory branch.",
+    description:
+      "Manage memory branches. Actions: create (new branch), switch (change active branch), merge (synthesize branch into current).",
     parameters: Type.Object({
-      branch: Type.String({ description: "Target branch name" }),
+      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)" })
+      ),
+      purpose: Type.Optional(
+        Type.String({
+          description: "Why this branch exists (required for create)",
+        })
+      ),
+      branch: Type.Optional(
+        Type.String({
+          description: "Target branch (required for switch and merge)",
+        })
+      ),
+      synthesis: Type.Optional(
+        Type.String({ description: "Synthesized insight (required for merge)" })
+      ),
     }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       if (
         !tryLoad(ctx) ||
         !isMemoryReady(state, branchManager) ||
         !branchManager
       ) {
-        return createTextResult(MEMORY_NOT_INITIALIZED_MESSAGE);
+        setBrainFooterStatus(ctx, state, branchManager);
+        return Promise.resolve(
+          createTextResult(MEMORY_NOT_INITIALIZED_MESSAGE)
+        );
       }
 
       const previousBranch = state.activeBranch;
-      const result = executeMemorySwitch(params, state, branchManager);
+      const result = executeMemoryBranch(params, state, branchManager, ctx.cwd);
 
       if (state.activeBranch !== previousBranch) {
         upsertCurrentSession(state, ctx);
       }
 
-      return createTextResult(result);
-    },
-  });
-
-  pi.registerTool({
-    name: "memory_merge",
-    label: "Memory Merge",
-    description:
-      "Merge insights from one memory branch into the active branch.",
-    parameters: Type.Object({
-      branch: Type.String({ description: "Source branch to merge from" }),
-      synthesis: Type.String({
-        description: "Synthesized insight from source branch",
-      }),
-    }),
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      if (
-        !tryLoad(ctx) ||
-        !isMemoryReady(state, branchManager) ||
-        !branchManager
-      ) {
-        return createTextResult(MEMORY_NOT_INITIALIZED_MESSAGE);
-      }
-
-      return createTextResult(executeMemoryMerge(params, state, branchManager));
+      setBrainFooterStatus(ctx, state, branchManager);
+      return Promise.resolve(createTextResult(result));
     },
   });
 
@@ -214,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 (
@@ -222,6 +191,7 @@ export default function activate(pi: ExtensionAPI) {
         !isMemoryReady(state, branchManager) ||
         !branchManager
       ) {
+        setBrainFooterStatus(ctx, state, branchManager);
         return createTextResult(MEMORY_NOT_INITIALIZED_MESSAGE);
       }
 
@@ -246,9 +216,12 @@ export default function activate(pi: ExtensionAPI) {
         params.summary,
         commitContent,
         state,
-        branchManager
+        branchManager,
+        ctx.cwd,
+        params.update_roadmap
       );
 
+      setBrainFooterStatus(ctx, state, branchManager);
       return createTextResult(message);
     },
   });
@@ -257,14 +230,15 @@ export default function activate(pi: ExtensionAPI) {
     state = new MemoryState(ctx.cwd);
     state.load();
     branchManager = new BranchManager(ctx.cwd);
+    statusInjected = false;
 
     if (!state.isInitialized) {
+      setBrainFooterStatus(ctx, state, branchManager);
       return;
     }
 
     upsertCurrentSession(state, ctx);
 
-    const turnCount = branchManager.getLogTurnCount(state.activeBranch);
     const logSizeBytes = branchManager.getLogSizeBytes(state.activeBranch);
 
     if (logSizeBytes >= LOG_SIZE_WARNING_BYTES) {
@@ -273,20 +247,66 @@ export default function activate(pi: ExtensionAPI) {
         `Brain: log.md is large (${sizeKB} KB). You should commit to distill this into structured memory.`,
         "warning"
       );
-    } else {
-      ctx.ui.notify(
-        `Brain active: branch "${state.activeBranch}" (${turnCount} uncommitted turn${turnCount === 1 ? "" : "s"}).`,
-        "info"
-      );
     }
+
+    setBrainFooterStatus(ctx, state, branchManager);
+  });
+
+  pi.on("session_switch", (_event, ctx) => {
+    statusInjected = false;
+
+    state = new MemoryState(ctx.cwd);
+    state.load();
+    branchManager = new BranchManager(ctx.cwd);
+
+    if (state.isInitialized) {
+      upsertCurrentSession(state, ctx);
+    }
+
+    setBrainFooterStatus(ctx, state, branchManager);
+  });
+
+  pi.on("before_agent_start", (_event: BeforeAgentStartEvent, ctx) => {
+    if (statusInjected) {
+      return;
+    }
+
+    if (
+      !tryLoad(ctx) ||
+      !isMemoryReady(state, branchManager) ||
+      !branchManager
+    ) {
+      return;
+    }
+
+    statusInjected = true;
+
+    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: {},
+      },
+    };
+  });
+
+  pi.on("session_compact", () => {
+    statusInjected = false;
   });
 
   pi.on("resources_discover", () => ({
     skillPaths: [resolveSkillPath()],
   }));
 
-  pi.on("turn_end", (event) => {
+  pi.on("turn_end", (event, ctx) => {
     if (!isMemoryReady(state, branchManager) || !branchManager) {
+      setBrainFooterStatus(ctx, state, branchManager);
       return;
     }
 
@@ -297,6 +317,7 @@ export default function activate(pi: ExtensionAPI) {
 
     const entry = formatOtaEntry(input);
     branchManager.appendLog(state.activeBranch, entry);
+    setBrainFooterStatus(ctx, state, branchManager);
   });
 
   pi.on("session_before_compact", (event) => {

package/src/memory-branch.ts

@@ -1,28 +1,173 @@
 import type { BranchManager } from "./branches.js";
+import { generateHash } from "./hash.js";
+import { buildStatusView } from "./memory-context.js";
 import type { MemoryState } from "./state.js";
 
 interface MemoryBranchParams {
-  name: string;
-  purpose: string;
+  action: string;
+  name?: string;
+  purpose?: string;
+  branch?: string;
+  synthesis?: string;
 }
 
-/**
- * Execute the memory_branch tool — create a new memory branch.
- */
-export function executeMemoryBranch(
+interface ActionResult {
+  text: string;
+  ok: boolean;
+}
+
+function executeCreate(
   params: MemoryBranchParams,
   state: MemoryState,
   branches: BranchManager
-): string {
+): ActionResult {
   const { name, purpose } = params;
 
+  if (!name || !purpose) {
+    return {
+      text: '"name" and "purpose" are required for the create action.',
+      ok: false,
+    };
+  }
+
   if (branches.branchExists(name)) {
-    return `Branch "${name}" already exists. Use memory_switch to switch to it.`;
+    return {
+      text: `Branch "${name}" already exists. Use action "switch" to switch to it.`,
+      ok: false,
+    };
   }
 
   branches.createBranch(name, purpose);
   state.setActiveBranch(name);
   state.save();
 
-  return `Created branch "${name}" and switched to it.\nPurpose: ${purpose}`;
+  return {
+    text: `Created branch "${name}" and switched to it.\nPurpose: ${purpose}`,
+    ok: true,
+  };
+}
+
+function executeSwitch(
+  params: MemoryBranchParams,
+  state: MemoryState,
+  branches: BranchManager
+): ActionResult {
+  const { branch } = params;
+
+  if (!branch) {
+    return { text: '"branch" is required for the switch action.', ok: false };
+  }
+
+  if (!branches.branchExists(branch)) {
+    return {
+      text: `Branch "${branch}" not found. Available branches: ${branches.listBranches().join(", ")}`,
+      ok: false,
+    };
+  }
+
+  state.setActiveBranch(branch);
+  state.save();
+
+  const latest = branches.getLatestCommit(branch);
+  const summary = latest ?? "No commits yet.";
+
+  return { text: `Switched to branch "${branch}".\n\n${summary}`, ok: true };
+}
+
+function executeMerge(
+  params: MemoryBranchParams,
+  state: MemoryState,
+  branches: BranchManager
+): ActionResult {
+  const { branch: sourceBranch, synthesis } = params;
+
+  if (!sourceBranch || !synthesis) {
+    return {
+      text: '"branch" and "synthesis" are required for the merge action.',
+      ok: false,
+    };
+  }
+
+  const targetBranch = state.activeBranch;
+
+  if (sourceBranch === targetBranch) {
+    return {
+      text: `Cannot merge branch "${sourceBranch}" into itself.`,
+      ok: false,
+    };
+  }
+
+  if (!branches.branchExists(sourceBranch)) {
+    return {
+      text: `Branch "${sourceBranch}" not found. Available branches: ${branches.listBranches().join(", ")}`,
+      ok: false,
+    };
+  }
+
+  const hash = generateHash();
+  const timestamp = new Date().toISOString();
+  const summary = `Merge from ${sourceBranch}`;
+
+  const entry = [
+    "",
+    "---",
+    "",
+    `## Commit ${hash} | ${timestamp}`,
+    "",
+    `### Merge from ${sourceBranch}`,
+    "",
+    synthesis,
+    "",
+  ].join("\n");
+
+  branches.appendCommit(targetBranch, entry);
+
+  state.setLastCommit(targetBranch, hash, timestamp, summary);
+  state.save();
+
+  return {
+    text: `Merge commit ${hash} written to branch "${targetBranch}" (merged from "${sourceBranch}").`,
+    ok: true,
+  };
+}
+
+/**
+ * Execute the unified memory_branch tool.
+ * Actions: create, switch, merge.
+ * On success, appends the current memory status view.
+ */
+export function executeMemoryBranch(
+  params: MemoryBranchParams,
+  state: MemoryState,
+  branches: BranchManager,
+  projectDir: string
+): string {
+  let result: ActionResult;
+
+  switch (params.action) {
+    case "create": {
+      result = executeCreate(params, state, branches);
+      break;
+    }
+    case "switch": {
+      result = executeSwitch(params, state, branches);
+      break;
+    }
+    case "merge": {
+      result = executeMerge(params, state, branches);
+      break;
+    }
+    default: {
+      return `Unknown action "${params.action}". Valid actions: create, switch, merge.`;
+    }
+  }
+
+  if (!result.ok) {
+    return result.text;
+  }
+
+  const status = buildStatusView(state, branches, projectDir, {
+    compact: true,
+  });
+  return `${result.text}\n\n${status}`;
 }

package/src/memory-commit.ts

@@ -1,5 +1,6 @@
 import type { BranchManager } from "./branches.js";
 import { generateHash } from "./hash.js";
+import { buildStatusView } from "./memory-context.js";
 import type { MemoryState } from "./state.js";
 import { buildCommitterTask } from "./subagent.js";
 
@@ -26,13 +27,15 @@ export function executeMemoryCommit(
 
 /**
  * Step 2: Write the agent's commit content to commits.md,
- * clear log.md, and update state.
+ * clear log.md, update state, and return result with status.
  */
 export function finalizeMemoryCommit(
   summary: string,
   commitContent: string,
   state: MemoryState,
-  branches: BranchManager
+  branches: BranchManager,
+  projectDir: string,
+  updateRoadmap?: boolean
 ): string {
   const branch = state.activeBranch;
   const hash = generateHash();
@@ -54,5 +57,15 @@ export function finalizeMemoryCommit(
   state.setLastCommit(branch, hash, timestamp, summary);
   state.save();
 
-  return `Commit ${hash} written to branch "${branch}".`;
+  const resultText = `Commit ${hash} written to branch "${branch}".`;
+  const status = buildStatusView(state, branches, projectDir, {
+    compact: true,
+  });
+
+  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}`;
 }

package/src/memory-context.ts

@@ -4,7 +4,15 @@ import * as path from "node:path";
 import type { BranchManager } from "./branches.js";
 import { LOG_SIZE_WARNING_BYTES } from "./constants.js";
 import type { MemoryState } from "./state.js";
-import type { MemoryStatusParams } from "./types.js";
+
+interface StatusViewOptions {
+  compact?: boolean;
+  roadmapCharLimit?: number;
+  branchLimit?: number;
+}
+
+const DEFAULT_COMPACT_ROADMAP_CHAR_LIMIT = 1200;
+const DEFAULT_COMPACT_BRANCH_LIMIT = 8;
 
 function extractCommitSummaryLine(commitEntry: string): string {
   const marker = "### This Commit's Contribution";
@@ -30,31 +38,91 @@ function extractCommitSummaryLine(commitEntry: string): string {
   return "(unknown)";
 }
 
-function buildStatusView(
-  state: MemoryState,
-  branches: BranchManager,
-  projectDir: string
-): string {
-  const lines = ["# Memory Status", ""];
-
+function buildRoadmapSection(
+  lines: string[],
+  projectDir: string,
+  compact: boolean,
+  roadmapCharLimit: number
+): void {
   const mainMdPath = path.join(projectDir, ".memory", "main.md");
-  if (fs.existsSync(mainMdPath)) {
-    const roadmap = fs.readFileSync(mainMdPath, "utf8").trim();
-    if (roadmap) {
-      lines.push(roadmap, "");
-    } else {
-      lines.push(
-        "Roadmap is empty. Update `.memory/main.md` with project goals and current state.",
-        ""
-      );
-    }
-  } else {
+  if (!fs.existsSync(mainMdPath)) {
     lines.push(
       "No roadmap found. Create `.memory/main.md` to set project goals.",
       ""
     );
+    return;
+  }
+
+  const roadmap = fs.readFileSync(mainMdPath, "utf8").trim();
+  if (!roadmap) {
+    lines.push(
+      "Roadmap is empty. Update `.memory/main.md` with project goals and current state.",
+      ""
+    );
+    return;
+  }
+
+  if (!compact || roadmap.length <= roadmapCharLimit) {
+    lines.push(roadmap, "");
+    return;
+  }
+
+  const excerpt = roadmap.slice(0, roadmapCharLimit).trimEnd();
+  lines.push(excerpt, "");
+  lines.push(
+    `_Roadmap truncated for automatic status output. Use \`read .memory/main.md\` for full roadmap._`,
+    ""
+  );
+}
+
+function buildBranchesSection(
+  lines: string[],
+  state: MemoryState,
+  branches: BranchManager,
+  compact: boolean,
+  branchLimit: number
+): void {
+  const branchList = branches.listBranches();
+  if (branchList.length === 0) {
+    return;
   }
 
+  lines.push("## Branches", "");
+
+  const visibleBranches = compact
+    ? branchList.slice(0, branchLimit)
+    : branchList;
+  for (const name of visibleBranches) {
+    const latest = branches.getLatestCommit(name);
+    const summary = latest ? extractCommitSummaryLine(latest) : "(no commits)";
+    const marker = name === state.activeBranch ? " (active)" : "";
+    lines.push(`- **${name}**${marker}: ${summary}`);
+  }
+
+  if (compact && branchList.length > visibleBranches.length) {
+    const remaining = branchList.length - visibleBranches.length;
+    const branchLabel = remaining === 1 ? "branch" : "branches";
+    lines.push(`- ... ${remaining} more ${branchLabel} not shown.`);
+  }
+
+  lines.push("");
+}
+
+export function buildStatusView(
+  state: MemoryState,
+  branches: BranchManager,
+  projectDir: string,
+  options: StatusViewOptions = {}
+): string {
+  const compact = options.compact ?? false;
+  const roadmapCharLimit =
+    options.roadmapCharLimit ?? DEFAULT_COMPACT_ROADMAP_CHAR_LIMIT;
+  const branchLimit = options.branchLimit ?? DEFAULT_COMPACT_BRANCH_LIMIT;
+
+  const lines = ["# Memory Status", ""];
+
+  buildRoadmapSection(lines, projectDir, compact, roadmapCharLimit);
+
   lines.push(`Active branch: ${state.activeBranch}`, "");
 
   const logSizeBytes = branches.getLogSizeBytes(state.activeBranch);
@@ -67,21 +135,7 @@ function buildStatusView(
     );
   }
 
-  const branchList = branches.listBranches();
-  if (branchList.length > 0) {
-    lines.push("## Branches", "");
-
-    for (const name of branchList) {
-      const latest = branches.getLatestCommit(name);
-      const summary = latest
-        ? extractCommitSummaryLine(latest)
-        : "(no commits)";
-      const marker = name === state.activeBranch ? " (active)" : "";
-      lines.push(`- **${name}**${marker}: ${summary}`);
-    }
-
-    lines.push("");
-  }
+  buildBranchesSection(lines, state, branches, compact, branchLimit);
 
   lines.push("## Deep Retrieval", "");
   lines.push("Use `read .memory/branches/<name>/commits.md` for full history.");
@@ -92,16 +146,3 @@ function buildStatusView(
 
   return lines.join("\n");
 }
-
-/**
- * Execute the memory_status tool — status overview.
- * Additional parameters are accepted for backward compatibility but ignored.
- */
-export function executeMemoryStatus(
-  _params: MemoryStatusParams,
-  state: MemoryState,
-  branches: BranchManager,
-  projectDir: string
-): string {
-  return buildStatusView(state, branches, projectDir);
-}

package/src/types.ts

@@ -8,13 +8,6 @@ export interface OtaEntryInput {
   observations: string[];
 }
 
-export interface MemoryStatusParams {
-  level?: string;
-  branch?: string;
-  commit?: string;
-  segment?: string;
-}
-
 export interface SubagentResult {
   text: string;
   exitCode: number;

package/src/memory-merge.ts

@@ -1,52 +0,0 @@
-import type { BranchManager } from "./branches.js";
-import { generateHash } from "./hash.js";
-import type { MemoryState } from "./state.js";
-
-interface MemoryMergeParams {
-  branch: string;
-  synthesis: string;
-}
-
-/**
- * Execute the memory_merge tool — synthesize a branch back into the current branch.
- * The agent should call memory_status BEFORE calling this.
- */
-export function executeMemoryMerge(
-  params: MemoryMergeParams,
-  state: MemoryState,
-  branches: BranchManager
-): string {
-  const { branch: sourceBranch, synthesis } = params;
-  const targetBranch = state.activeBranch;
-
-  if (sourceBranch === targetBranch) {
-    return `Cannot merge branch "${sourceBranch}" into itself.`;
-  }
-
-  if (!branches.branchExists(sourceBranch)) {
-    return `Branch "${sourceBranch}" not found. Available branches: ${branches.listBranches().join(", ")}`;
-  }
-
-  const hash = generateHash();
-  const timestamp = new Date().toISOString();
-  const summary = `Merge from ${sourceBranch}`;
-
-  const entry = [
-    "",
-    "---",
-    "",
-    `## Commit ${hash} | ${timestamp}`,
-    "",
-    `### Merge from ${sourceBranch}`,
-    "",
-    synthesis,
-    "",
-  ].join("\n");
-
-  branches.appendCommit(targetBranch, entry);
-
-  state.setLastCommit(targetBranch, hash, timestamp, summary);
-  state.save();
-
-  return `Merge commit ${hash} written to branch "${targetBranch}" (merged from "${sourceBranch}").`;
-}

package/src/memory-switch.ts

@@ -1,29 +0,0 @@
-import type { BranchManager } from "./branches.js";
-import type { MemoryState } from "./state.js";
-
-interface MemorySwitchParams {
-  branch: string;
-}
-
-/**
- * Execute the memory_switch tool — switch the active memory branch.
- */
-export function executeMemorySwitch(
-  params: MemorySwitchParams,
-  state: MemoryState,
-  branches: BranchManager
-): string {
-  const { branch } = params;
-
-  if (!branches.branchExists(branch)) {
-    return `Branch "${branch}" not found. Available branches: ${branches.listBranches().join(", ")}`;
-  }
-
-  state.setActiveBranch(branch);
-  state.save();
-
-  const latest = branches.getLatestCommit(branch);
-  const summary = latest ?? "No commits yet.";
-
-  return `Switched to branch "${branch}".\n\n${summary}`;
-}