shariq-pi-extensions 0.1.0

package/extensions/orchestration/types.ts

@@ -0,0 +1,105 @@
+import type { ReasoningEffort } from "../subagents/src/domain.ts";
+
+export const ORCHESTRATION_ROLES = [
+  "orchestrator",
+  "explorer",
+  "frontend",
+  "backend",
+  "general",
+  "reviewer",
+] as const;
+export type OrchestrationRole = (typeof ORCHESTRATION_ROLES)[number];
+
+export interface RoleSettings {
+  model?: string;
+  thinking: ReasoningEffort;
+}
+
+export interface OrchestrationSettings {
+  version: 1;
+  maxWorkersPerProject: 10;
+  roles: Record<OrchestrationRole, RoleSettings>;
+}
+
+export type TaskStatus =
+  | "pending"
+  | "implementing"
+  | "reviewing"
+  | "integrating"
+  | "completed"
+  | "blocked"
+  | "cancelled";
+
+export interface OrchestrationTask {
+  id: string;
+  title: string;
+  description: string;
+  role: Exclude<OrchestrationRole, "orchestrator" | "reviewer">;
+  dependencies: string[];
+  acceptanceCriteria: string[];
+  status: TaskStatus;
+  workerAgentId?: string;
+  reviewerAgentId?: string;
+  fixRounds: number;
+  lastWorkerSettledAt?: number;
+  lastReviewerSettledAt?: number;
+  reviewSummary?: string;
+  filesChanged?: string[];
+  error?: string;
+}
+
+export type RunStatus =
+  | "planning"
+  | "awaiting-approval"
+  | "running"
+  | "paused"
+  | "blocked"
+  | "completed"
+  | "cancelled"
+  | "interrupted";
+
+export interface OrchestrationRun {
+  id: string;
+  objective: string;
+  cwd: string;
+  projectKey: string;
+  gitBacked: boolean;
+  status: RunStatus;
+  summary: string;
+  tasks: OrchestrationTask[];
+  orchestratorAgentId?: string;
+  orchestratorHandledAt?: number;
+  finalReviewerAgentId?: string;
+  finalReviewerHandledAt?: number;
+  finalReviewPassed?: boolean;
+  finalReviewSummary?: string;
+  lastCoordinatedTaskState?: string;
+  createdAt: number;
+  updatedAt: number;
+  completedAt?: number;
+  error?: string;
+}
+
+export interface PlannedTask {
+  id: string;
+  title: string;
+  description: string;
+  role: OrchestrationTask["role"];
+  dependencies?: string[];
+  acceptanceCriteria?: string[];
+}
+
+export interface OrchestratorDecision {
+  decision: "continue" | "complete" | "blocked";
+  summary: string;
+  tasks?: PlannedTask[];
+  blocker?: string;
+}
+
+export interface ReviewDecision {
+  passed: boolean;
+  summary: string;
+  smallFixesApplied?: string[];
+  findings?: string[];
+  validation?: string[];
+}

package/extensions/performance-status/README.md

@@ -0,0 +1,5 @@
+# Performance Status
+
+Adds one compact footer-area status row for the current or latest assistant response.
+
+It reports TPS, time to first token, elapsed response time, response output tokens, and the active tool. Live token counts and TPS are estimates until the provider returns final usage. Final TPS uses conventional decode throughput: provider-reported output tokens divided by first-token-to-message-completion time. TTFT and total elapsed time separately expose provider latency, prefill, and hidden reasoning.

package/extensions/performance-status/index.ts

@@ -0,0 +1,171 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+interface GenerationMetrics {
+  requestStartedAt?: number;
+  firstTokenAt?: number;
+  completedAt?: number;
+  streamedChars: number;
+  exactOutputTokens?: number;
+  activeTool?: string;
+  phase: "idle" | "waiting" | "generating" | "tool" | "done";
+}
+
+const STATUS_ID = "generation-performance";
+const RENDER_INTERVAL_MS = 100;
+
+function duration(seconds: number) {
+  if (!Number.isFinite(seconds) || seconds < 0) return "—";
+  return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+
+function tokenCount(tokens: number, estimated = false) {
+  const value = tokens < 1_000
+    ? `${Math.max(0, Math.round(tokens))}`
+    : `${(tokens / 1_000).toFixed(1)}k`;
+  return `${estimated ? "~" : ""}${value}`;
+}
+
+function values(metrics: GenerationMetrics, now = Date.now()) {
+  const elapsed = metrics.requestStartedAt
+    ? Math.max(0, (Math.min(metrics.completedAt ?? now, now) - metrics.requestStartedAt) / 1_000)
+    : undefined;
+  const ttft = metrics.requestStartedAt && metrics.firstTokenAt
+    ? Math.max(0, (metrics.firstTokenAt - metrics.requestStartedAt) / 1_000)
+    : undefined;
+  const estimatedTokens = metrics.streamedChars / 4;
+  const outputTokens = metrics.exactOutputTokens ?? estimatedTokens;
+  // Conventional TPS measures decode throughput from first streamed token to
+  // completion. TTFT and elapsed time separately expose provider latency,
+  // prefill, and hidden reasoning before visible streaming begins.
+  const generationSeconds = metrics.firstTokenAt
+    ? Math.max(0, ((metrics.completedAt ?? now) - metrics.firstTokenAt) / 1_000)
+    : undefined;
+  const tps = generationSeconds && generationSeconds > 0.05
+    ? outputTokens / generationSeconds
+    : undefined;
+  return {
+    elapsed,
+    ttft,
+    outputTokens,
+    estimated: metrics.exactOutputTokens === undefined,
+    tps,
+  };
+}
+
+export function formatPerformanceStatus(
+  metrics: GenerationMetrics,
+  ctx: ExtensionContext,
+  now = Date.now(),
+) {
+  const theme = ctx.ui.theme;
+  const measured = values(metrics, now);
+  const label = metrics.phase === "waiting"
+    ? "waiting"
+    : metrics.phase === "generating"
+      ? "generating"
+      : metrics.phase === "tool"
+        ? `tool ${metrics.activeTool ?? "running"}`
+        : "last response";
+  const parts = [
+    `${theme.fg("accent", "◆")} ${theme.fg(metrics.phase === "done" ? "muted" : "accent", label)}`,
+    measured.tps === undefined
+      ? undefined
+      : theme.fg("text", `TPS ${measured.estimated ? "~" : ""}${Math.round(measured.tps)} tok/s`),
+    measured.ttft === undefined ? undefined : theme.fg("muted", `TTFT ${duration(measured.ttft)}`),
+    measured.elapsed === undefined ? undefined : theme.fg("muted", duration(measured.elapsed)),
+    measured.outputTokens > 0
+      ? theme.fg("muted", `${tokenCount(measured.outputTokens, measured.estimated)} out`)
+      : undefined,
+  ].filter((part): part is string => Boolean(part));
+  return parts.join(theme.fg("dim", " · "));
+}
+
+export default function performanceStatus(pi: ExtensionAPI) {
+  const metrics: GenerationMetrics = { streamedChars: 0, phase: "idle" };
+  let renderTimer: ReturnType<typeof setTimeout> | undefined;
+  let lastRenderAt = 0;
+
+  const render = (ctx: ExtensionContext, immediate = false) => {
+    if (!ctx.hasUI || metrics.phase === "idle") return;
+    const now = Date.now();
+    const remaining = RENDER_INTERVAL_MS - (now - lastRenderAt);
+    if (!immediate && remaining > 0) {
+      if (!renderTimer) {
+        renderTimer = setTimeout(() => {
+          renderTimer = undefined;
+          lastRenderAt = Date.now();
+          ctx.ui.setStatus(STATUS_ID, formatPerformanceStatus(metrics, ctx));
+        }, remaining);
+        renderTimer.unref?.();
+      }
+      return;
+    }
+    if (renderTimer) clearTimeout(renderTimer);
+    renderTimer = undefined;
+    lastRenderAt = now;
+    ctx.ui.setStatus(STATUS_ID, formatPerformanceStatus(metrics, ctx, now));
+  };
+
+  pi.on("turn_start", (_event, ctx) => {
+    metrics.requestStartedAt = Date.now();
+    metrics.firstTokenAt = undefined;
+    metrics.completedAt = undefined;
+    metrics.streamedChars = 0;
+    metrics.exactOutputTokens = undefined;
+    metrics.activeTool = undefined;
+    metrics.phase = "waiting";
+    render(ctx, true);
+  });
+
+  pi.on("message_update", (event, ctx) => {
+    if (event.message.role !== "assistant") return;
+    const update = event.assistantMessageEvent;
+    if (update.type === "text_delta" || update.type === "thinking_delta" || update.type === "toolcall_delta") {
+      metrics.firstTokenAt ??= Date.now();
+      metrics.streamedChars += update.delta.length;
+      metrics.phase = "generating";
+      render(ctx);
+      return;
+    }
+    if (update.type === "done") {
+      metrics.firstTokenAt ??= metrics.requestStartedAt ?? Date.now();
+      metrics.completedAt = Date.now();
+      metrics.exactOutputTokens = update.message.usage.output;
+      metrics.phase = "done";
+      render(ctx, true);
+    }
+  });
+
+  pi.on("message_end", (event, ctx) => {
+    if (event.message.role !== "assistant") return;
+    metrics.completedAt ??= Date.now();
+    metrics.exactOutputTokens = event.message.usage.output;
+    metrics.phase = "done";
+    render(ctx, true);
+  });
+
+  pi.on("tool_execution_start", (event, ctx) => {
+    metrics.activeTool = event.toolName;
+    metrics.phase = "tool";
+    render(ctx, true);
+  });
+
+  pi.on("tool_execution_end", (_event, ctx) => {
+    metrics.activeTool = undefined;
+    metrics.phase = metrics.completedAt ? "done" : "generating";
+    render(ctx, true);
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setStatus(STATUS_ID, undefined);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (renderTimer) clearTimeout(renderTimer);
+    renderTimer = undefined;
+    if (ctx.hasUI) ctx.ui.setStatus(STATUS_ID, undefined);
+  });
+}

package/extensions/pi-memory/README.md

@@ -0,0 +1,53 @@
+# pi-memory
+
+Pi-native durable memory built only from work performed inside Pi.
+
+## Boundaries
+
+- Captures Pi session messages, project identity, compaction summaries, explicit memory edits, and only an allowlist of Pi-native coding/terminal/subagent tool events.
+- Does not ingest web/browser/search, screenshot/OCR, screen, audio, camera, application-observation, Chronicle, Skysight, or passive computer-recording tool events.
+- Uses SQLite as the source of truth. The two generated `MEMORY.md` surfaces are read-only projections for people:
+  - `<agent-dir>/pi-memory/global/MEMORY.md`
+  - `<agent-dir>/pi-memory/projects/<project-slug>-<project-hash-prefix>/MEMORY.md`
+- Runs only in TUI/RPC sessions, so headless children and print/JSON jobs do not create memory.
+- Persists its extraction provider, model, and reasoning in `<agent-dir>/pi-memory/config.json`; `/memory-model` changes all three. The initial default is `openai-codex/gpt-5.6-luna` at `max` reasoning.
+
+## Architecture
+
+- `src/database.ts` — schema, FTS5 search, ranking, leases, retries, provenance, and lifecycle.
+- `src/session.ts` — branch-aware Pi session capture with bounded tool output.
+- `src/extraction.ts` — no-tool structured extraction through Pi's model registry.
+- `src/retrieval.ts` — scoped retrieval and character-bounded estimated context injection.
+- `src/projection.ts` — generated global/project Markdown views.
+- `src/service.ts` — lifecycle and queue ownership.
+
+The completed bootstrap import is detached from its former sources. Imported knowledge is owned by Pi Memory as `bootstrap-import` provenance with Pi-local opaque identifiers. Runtime code never scans or reads another agent's memory directories.
+
+## Commands
+
+- `/memory-status`
+- `/memory-model` (interactive provider → model → reasoning selector)
+- `/memory-model <provider>/<model> <reasoning>`
+- `/memory-search <query>`
+- `/memory-review [query]`
+- `/memory-save [global|project] <text>`
+- `/memory-correct <id> <replacement text>`
+- `/memory-forget <id>`
+- `/memory-rebuild`
+- `/memory-process`
+
+## Tools
+
+- `pi_memory_search`
+- `pi_memory_read`
+- `pi_memory_save`
+- `pi_memory_correct`
+- `pi_memory_forget`
+- `pi_memory_status`
+
+## Validation
+
+```bash
+npm run check
+npm test
+```

package/extensions/pi-memory/index.ts

@@ -0,0 +1,326 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import {
+  defaultConfig,
+  MEMORY_REASONING_LEVELS,
+  saveMemoryModelConfig,
+  type MemoryModelConfig,
+  type MemoryReasoningLevel,
+} from "./src/config.ts";
+import { formatMemoryContext, selectForInjection } from "./src/retrieval.ts";
+import { MemoryService } from "./src/service.ts";
+import { MEMORY_KINDS, type MemoryKind, type MemoryRecord, type MemoryScope } from "./src/types.ts";
+
+function toolText(text: string, details: Record<string, unknown> = {}) {
+  return { content: [{ type: "text" as const, text }], details };
+}
+
+function formatSearchResults(results: MemoryRecord[]): string {
+  if (results.length === 0) return "No matching memories.";
+  return results.map((memory) =>
+    `${memory.memoryId}  ${memory.scope}/${memory.kind}  ${memory.title}\n${memory.content}`,
+  ).join("\n\n");
+}
+
+const MEMORY_TOOL_NAMES = new Set([
+  "pi_memory_search",
+  "pi_memory_read",
+  "pi_memory_save",
+  "pi_memory_correct",
+  "pi_memory_forget",
+  "pi_memory_status",
+]);
+
+export default function piMemory(pi: ExtensionAPI) {
+  const config = defaultConfig();
+  const service = new MemoryService(config);
+
+  const active = (ctx: ExtensionContext): boolean => config.enabledModes.has(ctx.mode);
+  const projectFor = (ctx: Pick<ExtensionContext, "cwd">) => service.project(ctx.cwd);
+
+  pi.registerTool({
+    name: "pi_memory_search",
+    label: "Search Pi Memory",
+    description: "Search durable global and current-project memories. Returns at most the requested number of concise records.",
+    promptSnippet: "Search durable Pi memories for deeper historical context",
+    promptGuidelines: ["Use pi_memory_search when auto-injected memory is insufficient and past Pi work could materially help."],
+    parameters: Type.Object({
+      query: Type.String({ minLength: 1, description: "What to find" }),
+      limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 30 })),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const project = projectFor(ctx);
+      const results = service.search(params.query, project.id, params.limit ?? 10);
+      service.database.recordAccess(results.map((memory) => memory.memoryId));
+      return toolText(formatSearchResults(results), { count: results.length, memoryIds: results.map((memory) => memory.memoryId) });
+    },
+  });
+
+  pi.registerTool({
+    name: "pi_memory_read",
+    label: "Read Pi Memory",
+    description: "Read one durable memory by exact ID, including scope, provenance, confidence, and timestamps.",
+    parameters: Type.Object({ memoryId: Type.String({ minLength: 1 }) }),
+    async execute(_id, params, signal) {
+      signal?.throwIfAborted();
+      const memory = service.database.getMemory(params.memoryId);
+      if (!memory || memory.status !== "active") throw new Error(`Active memory not found: ${params.memoryId}`);
+      service.database.recordAccess([memory.memoryId]);
+      const sources = service.database.listSources(memory.memoryId);
+      return toolText(JSON.stringify({ ...memory, sources }, null, 2), { memoryId: memory.memoryId, sourceCount: sources.length });
+    },
+  });
+
+  pi.registerTool({
+    name: "pi_memory_save",
+    label: "Save Pi Memory",
+    description: "Save one explicit durable memory. Use global only for stable cross-project preferences; otherwise use project.",
+    parameters: Type.Object({
+      scope: StringEnum(["global", "project"] as const),
+      kind: StringEnum(MEMORY_KINDS),
+      title: Type.String({ minLength: 1, maxLength: 160 }),
+      content: Type.String({ minLength: 1, maxLength: 4000 }),
+      tags: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 80 }), { maxItems: 16 })),
+      importance: Type.Optional(Type.Integer({ minimum: 1, maximum: 5 })),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const memory = service.save({
+        scope: params.scope,
+        project: projectFor(ctx),
+        kind: params.kind,
+        title: params.title,
+        content: params.content,
+        ...(params.tags ? { tags: params.tags } : {}),
+        ...(params.importance ? { importance: params.importance } : {}),
+      });
+      return toolText(`Saved ${memory.scope} memory ${memory.memoryId}: ${memory.title}`, { memoryId: memory.memoryId });
+    },
+  });
+
+  pi.registerTool({
+    name: "pi_memory_correct",
+    label: "Correct Pi Memory",
+    description: "Correct an existing durable memory by exact memory ID. Use only when the user corrects stored information.",
+    parameters: Type.Object({
+      memoryId: Type.String({ minLength: 1 }),
+      title: Type.Optional(Type.String({ minLength: 1, maxLength: 160 })),
+      content: Type.Optional(Type.String({ minLength: 1, maxLength: 4000 })),
+      tags: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 80 }), { maxItems: 16 })),
+      importance: Type.Optional(Type.Integer({ minimum: 1, maximum: 5 })),
+    }),
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      signal?.throwIfAborted();
+      const memory = service.correct(params.memoryId, {
+        project: projectFor(ctx),
+        ...(params.title ? { title: params.title } : {}),
+        ...(params.content ? { content: params.content } : {}),
+        ...(params.tags ? { tags: params.tags } : {}),
+        ...(params.importance ? { importance: params.importance } : {}),
+      });
+      if (!memory) throw new Error(`Active memory not found: ${params.memoryId}`);
+      return toolText(`Corrected memory ${memory.memoryId}: ${memory.title}`, { memoryId: memory.memoryId });
+    },
+  });
+
+  pi.registerTool({
+    name: "pi_memory_forget",
+    label: "Forget Pi Memory",
+    description: "Soft-delete one durable memory by exact ID. Use only on an explicit user request to forget it.",
+    parameters: Type.Object({ memoryId: Type.String({ minLength: 1 }) }),
+    async execute(_id, params, signal) {
+      signal?.throwIfAborted();
+      if (!service.forget(params.memoryId)) throw new Error(`Active memory not found: ${params.memoryId}`);
+      return toolText(`Forgot memory ${params.memoryId}.`, { memoryId: params.memoryId });
+    },
+  });
+
+  pi.registerTool({
+    name: "pi_memory_status",
+    label: "Pi Memory Status",
+    description: "Show Pi Memory counts, queue state, and storage paths.",
+    parameters: Type.Object({}),
+    async execute() {
+      const status = service.status();
+      return toolText(JSON.stringify(status, null, 2), status);
+    },
+  });
+
+  pi.registerCommand("memory-status", {
+    description: "Show Pi Memory status",
+    handler: async (_args, ctx) => ctx.ui.notify(JSON.stringify(service.status()), "info"),
+  });
+
+  pi.registerCommand("memory-model", {
+    description: "Select the provider, model, and reasoning level used only for Pi Memory extraction",
+    handler: async (args, ctx) => {
+      const available = ctx.modelRegistry.getAvailable();
+      let selected: MemoryModelConfig | undefined;
+      const direct = args.trim().match(/^(\S+)\/(\S+)\s+(off|minimal|low|medium|high|xhigh|max)$/);
+
+      if (direct) {
+        const [, provider, model, reasoning] = direct;
+        const match = available.find((candidate) => candidate.provider === provider && candidate.id === model);
+        if (!match) {
+          ctx.ui.notify(`Unavailable memory model: ${provider}/${model}`, "error");
+          return;
+        }
+        if (!match.reasoning && reasoning !== "off") {
+          ctx.ui.notify(`${provider}/${model} does not support reasoning; select off.`, "error");
+          return;
+        }
+        selected = { provider: provider!, model: model!, reasoning: reasoning as MemoryReasoningLevel };
+      } else if (args.trim()) {
+        ctx.ui.notify("Usage: /memory-model [provider/model reasoning]", "warning");
+        return;
+      } else {
+        if (!ctx.hasUI) {
+          ctx.ui.notify("Usage: /memory-model <provider/model> <reasoning>", "warning");
+          return;
+        }
+        const current = config.extractionModel;
+        const providers = [...new Set(available.map((model) => model.provider))].sort();
+        providers.sort((a, b) => Number(b === current.provider) - Number(a === current.provider));
+        const provider = await ctx.ui.select("Pi Memory extraction provider", providers);
+        if (!provider) return;
+
+        const providerModels = available.filter((model) => model.provider === provider);
+        providerModels.sort((a, b) => Number(b.id === current.model && provider === current.provider) - Number(a.id === current.model && provider === current.provider) || a.id.localeCompare(b.id));
+        const modelId = await ctx.ui.select("Pi Memory extraction model", providerModels.map((model) => model.id));
+        if (!modelId) return;
+        const model = providerModels.find((candidate) => candidate.id === modelId)!;
+
+        const levels = model.reasoning ? [...MEMORY_REASONING_LEVELS] : ["off" as const];
+        levels.sort((a, b) => Number(b === current.reasoning) - Number(a === current.reasoning));
+        const reasoning = await ctx.ui.select("Pi Memory extraction reasoning", levels);
+        if (!reasoning) return;
+        selected = { provider, model: modelId, reasoning: reasoning as MemoryReasoningLevel };
+      }
+
+      config.extractionModel = selected;
+      saveMemoryModelConfig(config.root, selected);
+      ctx.ui.notify(`Pi Memory extraction: ${selected.provider}/${selected.model} (${selected.reasoning})`, "info");
+    },
+  });
+
+  pi.registerCommand("memory-search", {
+    description: "Search Pi Memory: /memory-search <query>",
+    handler: async (args, ctx) => {
+      const query = args.trim();
+      if (!query) { ctx.ui.notify("Usage: /memory-search <query>", "warning"); return; }
+      const results = service.search(query, projectFor(ctx).id, 10);
+      service.database.recordAccess(results.map((memory) => memory.memoryId));
+      ctx.ui.notify(formatSearchResults(results).slice(0, 8_000), "info");
+    },
+  });
+
+  pi.registerCommand("memory-review", {
+    description: "Review high-priority global and current-project memories",
+    handler: async (args, ctx) => {
+      const project = projectFor(ctx);
+      const query = args.trim();
+      const memories = query ? service.search(query, project.id, 30) : service.review(project.id, 30);
+      ctx.ui.notify(formatSearchResults(memories).slice(0, 12_000), "info");
+    },
+  });
+
+  pi.registerCommand("memory-save", {
+    description: "Save a memory: /memory-save [global|project] <text>",
+    handler: async (args, ctx) => {
+      const match = args.trim().match(/^(?:(global|project)\s+)?([\s\S]+)$/);
+      if (!match) { ctx.ui.notify("Usage: /memory-save [global|project] <text>", "warning"); return; }
+      const scope = (match[1] ?? "project") as MemoryScope;
+      const content = match[2]!.trim();
+      const memory = service.save({
+        scope,
+        project: projectFor(ctx),
+        kind: "reference",
+        title: content.split(/[.!?\n]/, 1)[0]!.slice(0, 140),
+        content,
+      });
+      ctx.ui.notify(`Saved ${scope} memory ${memory.memoryId}`, "info");
+    },
+  });
+
+  pi.registerCommand("memory-correct", {
+    description: "Correct memory content: /memory-correct <id> <replacement text>",
+    handler: async (args, ctx) => {
+      const match = args.trim().match(/^(\S+)\s+([\s\S]+)$/);
+      if (!match) { ctx.ui.notify("Usage: /memory-correct <id> <replacement text>", "warning"); return; }
+      const memory = service.correct(match[1]!, { project: projectFor(ctx), content: match[2]!.trim() });
+      ctx.ui.notify(memory ? `Corrected ${memory.memoryId}` : `Active memory not found: ${match[1]}`, memory ? "info" : "warning");
+    },
+  });
+
+  pi.registerCommand("memory-forget", {
+    description: "Forget a memory by exact ID: /memory-forget <id>",
+    handler: async (args, ctx) => {
+      const memoryId = args.trim();
+      if (!memoryId) { ctx.ui.notify("Usage: /memory-forget <id>", "warning"); return; }
+      const forgotten = service.forget(memoryId);
+      ctx.ui.notify(forgotten ? `Forgot ${memoryId}` : `Active memory not found: ${memoryId}`, forgotten ? "info" : "warning");
+    },
+  });
+
+  pi.registerCommand("memory-rebuild", {
+    description: "Rebuild the Pi Memory search index and Markdown projections",
+    handler: async (_args, ctx) => {
+      service.rebuild();
+      ctx.ui.notify("Pi Memory search index and projections rebuilt.", "info");
+    },
+  });
+
+  pi.registerCommand("memory-process", {
+    description: "Capture this session and process pending memory jobs",
+    handler: async (_args, ctx) => {
+      if (!active(ctx)) { ctx.ui.notify("Memory capture is disabled in this Pi mode.", "warning"); return; }
+      service.enqueueCurrentSession(ctx, projectFor(ctx));
+      await service.processPending(ctx, 10);
+      ctx.ui.notify(`Memory processing finished. ${service.status().memories} active memories.`, "info");
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (!active(ctx)) {
+      pi.setActiveTools(pi.getActiveTools().filter((name) => !MEMORY_TOOL_NAMES.has(name)));
+      return;
+    }
+    service.initialize(ctx.cwd);
+    ctx.ui.setStatus("pi-memory", `memory ${service.status().memories}`);
+    void service.processPending(ctx, 1);
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!active(ctx)) return;
+    const project = projectFor(ctx);
+    const memories = selectForInjection(service.database, event.prompt, project.id, {
+      maxResults: config.maxInjectedMemories,
+      maxCharacters: config.maxInjectedCharacters,
+    });
+    if (memories.length === 0) return;
+    service.database.recordAccess(memories.map((memory) => memory.memoryId));
+    return { systemPrompt: `${event.systemPrompt}\n\n${formatMemoryContext(memories)}` };
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (!active(ctx)) return;
+    service.enqueueCurrentSession(ctx, projectFor(ctx));
+    void service.processPending(ctx, 1).then(() => {
+      if (ctx.hasUI) ctx.ui.setStatus("pi-memory", `memory ${service.status().memories}`);
+    });
+  });
+
+  pi.on("session_before_compact", async (_event, ctx) => {
+    if (!active(ctx)) return;
+    service.enqueueCurrentSession(ctx, projectFor(ctx));
+    void service.processPending(ctx, 1);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (active(ctx)) service.enqueueCurrentSession(ctx, projectFor(ctx));
+    if (ctx.hasUI) ctx.ui.setStatus("pi-memory", undefined);
+    await service.shutdown();
+  });
+}