pi-brain 0.1.1

package/src/index.ts

@@ -0,0 +1,310 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+  SessionBeforeCompactEvent,
+} from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+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 { formatOtaEntry } from "./ota-formatter.js";
+import { extractOtaInput } from "./ota-logger.js";
+import { MemoryState } from "./state.js";
+import { extractCommitBlocks, spawnCommitter } from "./subagent.js";
+
+const MEMORY_NOT_INITIALIZED_MESSAGE =
+  "Brain not initialized. Run brain-init.sh first.";
+
+function createTextResult(text: string): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text }],
+    details: {},
+  };
+}
+
+function isMemoryReady(
+  state: MemoryState | null,
+  branchManager: BranchManager | null
+): state is MemoryState {
+  return state !== null && branchManager !== null && state.isInitialized;
+}
+
+function upsertCurrentSession(state: MemoryState, ctx: ExtensionContext): void {
+  const sessionFile = ctx.sessionManager.getSessionFile();
+  if (!sessionFile) {
+    return;
+  }
+
+  state.upsertSession(
+    sessionFile,
+    state.activeBranch,
+    new Date().toISOString()
+  );
+  state.save();
+}
+
+function buildCompactionReminder(
+  state: MemoryState,
+  branchManager: BranchManager
+): string {
+  const branch = state.activeBranch;
+  const turns = branchManager.getLogTurnCount(branch);
+  const summary = state.lastCommit?.summary ?? "No commits yet";
+
+  return [
+    `Brain memory active on branch "${branch}".`,
+    `${turns} uncommitted turn${turns === 1 ? "" : "s"} in .memory/branches/${branch}/log.md.`,
+    `Latest commit summary: ${summary}.`,
+  ].join(" ");
+}
+
+function appendCompactionReminder(
+  event: SessionBeforeCompactEvent,
+  reminder: string
+): void {
+  event.customInstructions = event.customInstructions
+    ? `${event.customInstructions}\n\n${reminder}`
+    : reminder;
+}
+
+function resolveSkillPath(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  const currentDir = path.dirname(currentFile);
+  return path.resolve(currentDir, "../skills/brain");
+}
+
+export default function activate(pi: ExtensionAPI) {
+  let state: MemoryState | null = null;
+  let branchManager: BranchManager | null = null;
+
+  function tryLoad(ctx: ExtensionContext): boolean {
+    if (isMemoryReady(state, branchManager)) {
+      return true;
+    }
+
+    const candidate = new MemoryState(ctx.cwd);
+    candidate.load();
+
+    if (!candidate.isInitialized) {
+      return false;
+    }
+
+    state = candidate;
+    branchManager = new BranchManager(ctx.cwd);
+    upsertCurrentSession(state, ctx);
+    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.",
+    parameters: Type.Object({
+      branch: Type.String({ description: "Target branch name" }),
+    }),
+    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 = executeMemorySwitch(params, state, branchManager);
+
+      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));
+    },
+  });
+
+  pi.registerTool({
+    name: "memory_commit",
+    label: "Memory Commit",
+    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()),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (
+        !tryLoad(ctx) ||
+        !isMemoryReady(state, branchManager) ||
+        !branchManager
+      ) {
+        return createTextResult(MEMORY_NOT_INITIALIZED_MESSAGE);
+      }
+
+      const { task } = executeMemoryCommit(params, state, branchManager);
+
+      const result = await spawnCommitter(ctx.cwd, task, signal);
+
+      if (result.exitCode !== 0 || result.error) {
+        return createTextResult(
+          `Commit failed: ${result.error ?? "subagent exited with non-zero code"}`
+        );
+      }
+
+      const commitContent = extractCommitBlocks(result.text);
+      if (!commitContent) {
+        return createTextResult(
+          "Commit failed: could not extract commit blocks from subagent response."
+        );
+      }
+
+      const message = finalizeMemoryCommit(
+        params.summary,
+        commitContent,
+        state,
+        branchManager
+      );
+
+      return createTextResult(message);
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    state = new MemoryState(ctx.cwd);
+    state.load();
+    branchManager = new BranchManager(ctx.cwd);
+
+    if (!state.isInitialized) {
+      return;
+    }
+
+    upsertCurrentSession(state, ctx);
+
+    const turnCount = branchManager.getLogTurnCount(state.activeBranch);
+    const logSizeBytes = branchManager.getLogSizeBytes(state.activeBranch);
+
+    if (logSizeBytes >= LOG_SIZE_WARNING_BYTES) {
+      const sizeKB = Math.round(logSizeBytes / 1024);
+      ctx.ui.notify(
+        `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"
+      );
+    }
+  });
+
+  pi.on("resources_discover", () => ({
+    skillPaths: [resolveSkillPath()],
+  }));
+
+  pi.on("turn_end", (event) => {
+    if (!isMemoryReady(state, branchManager) || !branchManager) {
+      return;
+    }
+
+    const input = extractOtaInput(event);
+    if (!input) {
+      return;
+    }
+
+    const entry = formatOtaEntry(input);
+    branchManager.appendLog(state.activeBranch, entry);
+  });
+
+  pi.on("session_before_compact", (event) => {
+    if (!isMemoryReady(state, branchManager) || !branchManager) {
+      return;
+    }
+
+    const reminder = buildCompactionReminder(state, branchManager);
+    appendCompactionReminder(event, reminder);
+  });
+}

package/src/memory-branch.ts

@@ -0,0 +1,28 @@
+import type { BranchManager } from "./branches.js";
+import type { MemoryState } from "./state.js";
+
+interface MemoryBranchParams {
+  name: string;
+  purpose: string;
+}
+
+/**
+ * Execute the memory_branch tool — create a new memory branch.
+ */
+export function executeMemoryBranch(
+  params: MemoryBranchParams,
+  state: MemoryState,
+  branches: BranchManager
+): string {
+  const { name, purpose } = params;
+
+  if (branches.branchExists(name)) {
+    return `Branch "${name}" already exists. Use memory_switch to switch to it.`;
+  }
+
+  branches.createBranch(name, purpose);
+  state.setActiveBranch(name);
+  state.save();
+
+  return `Created branch "${name}" and switched to it.\nPurpose: ${purpose}`;
+}

package/src/memory-commit.ts

@@ -0,0 +1,58 @@
+import type { BranchManager } from "./branches.js";
+import { generateHash } from "./hash.js";
+import type { MemoryState } from "./state.js";
+import { buildCommitterTask } from "./subagent.js";
+
+interface MemoryCommitParams {
+  summary: string;
+  update_roadmap?: boolean;
+}
+
+/**
+ * Build the subagent task string for commit distillation.
+ * The subagent reads log.md and commits.md itself.
+ */
+export function executeMemoryCommit(
+  params: MemoryCommitParams,
+  state: MemoryState,
+  _branches: BranchManager
+): { task: string } {
+  const branch = state.activeBranch;
+
+  return {
+    task: buildCommitterTask(branch, params.summary),
+  };
+}
+
+/**
+ * Step 2: Write the agent's commit content to commits.md,
+ * clear log.md, and update state.
+ */
+export function finalizeMemoryCommit(
+  summary: string,
+  commitContent: string,
+  state: MemoryState,
+  branches: BranchManager
+): string {
+  const branch = state.activeBranch;
+  const hash = generateHash();
+  const timestamp = new Date().toISOString();
+
+  const entry = [
+    "",
+    "---",
+    "",
+    `## Commit ${hash} | ${timestamp}`,
+    "",
+    commitContent,
+    "",
+  ].join("\n");
+
+  branches.appendCommit(branch, entry);
+  branches.clearLog(branch);
+
+  state.setLastCommit(branch, hash, timestamp, summary);
+  state.save();
+
+  return `Commit ${hash} written to branch "${branch}".`;
+}

package/src/memory-context.ts

@@ -0,0 +1,107 @@
+import * as fs from "node:fs";
+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";
+
+function extractCommitSummaryLine(commitEntry: string): string {
+  const marker = "### This Commit's Contribution";
+  const markerIndex = commitEntry.indexOf(marker);
+
+  if (markerIndex !== -1) {
+    const afterMarker = commitEntry.slice(markerIndex + marker.length);
+    const firstContentLine = afterMarker
+      .split("\n")
+      .map((line) => line.trim())
+      .find((line) => line.length > 0);
+
+    if (firstContentLine) {
+      return firstContentLine.slice(0, 100);
+    }
+  }
+
+  const headerMatch = /## Commit ([a-f0-9]+)/.exec(commitEntry);
+  if (headerMatch) {
+    return `commit ${headerMatch[1]}`;
+  }
+
+  return "(unknown)";
+}
+
+function buildStatusView(
+  state: MemoryState,
+  branches: BranchManager,
+  projectDir: string
+): string {
+  const lines = ["# Memory Status", ""];
+
+  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 {
+    lines.push(
+      "No roadmap found. Create `.memory/main.md` to set project goals.",
+      ""
+    );
+  }
+
+  lines.push(`Active branch: ${state.activeBranch}`, "");
+
+  const logSizeBytes = branches.getLogSizeBytes(state.activeBranch);
+  if (logSizeBytes >= LOG_SIZE_WARNING_BYTES) {
+    const sizeKB = Math.round(logSizeBytes / 1024);
+    lines.push(
+      `**Warning:** log.md is large (${sizeKB} KB). ` +
+        "You should commit to distill this into structured memory.",
+      ""
+    );
+  }
+
+  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("");
+  }
+
+  lines.push("## Deep Retrieval", "");
+  lines.push("Use `read .memory/branches/<name>/commits.md` for full history.");
+  lines.push("Use `read .memory/branches/<name>/log.md` for OTA trace.");
+  lines.push("Use `read .memory/branches/<name>/metadata.yaml` for metadata.");
+  lines.push("Use `read .memory/main.md` for roadmap.");
+  lines.push("Use `read .memory/AGENTS.md` for protocol details.");
+
+  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/memory-merge.ts

@@ -0,0 +1,52 @@
+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

@@ -0,0 +1,29 @@
+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}`;
+}

package/src/ota-formatter.ts

@@ -0,0 +1,31 @@
+/**
+ * Formats OTA (Observation-Thought-Action) log entries for log.md.
+ * Follows the Brain spec format with full fidelity.
+ */
+
+import type { OtaEntryInput } from "./types.js";
+
+export type { OtaEntryInput } from "./types.js";
+
+export function formatOtaEntry(input: OtaEntryInput): string {
+  const lines = [
+    `## Turn ${input.turnNumber} | ${input.timestamp} | ${input.model}`,
+    "",
+    `**Thought**: ${input.thought}`,
+  ];
+
+  if (input.thinking) {
+    lines.push(`**Thinking**: ${input.thinking}`);
+  }
+
+  if (input.actions.length > 0) {
+    lines.push(`**Action**: ${input.actions.join(", ")}`);
+  }
+
+  if (input.observations.length > 0) {
+    lines.push(`**Observation**: ${input.observations.join("; ")}`);
+  }
+
+  lines.push("");
+  return `${lines.join("\n")}\n`;
+}