@chendpoc/pi-memory 0.1.12 → 0.2.0

package/src/cli.ts

@@ -1,255 +1,105 @@
 #!/usr/bin/env node
-import fs from "node:fs";
-import path from "node:path";
 
-import { createStandaloneLLMClient } from "./adapters/piComplete.js";
-import { installBundle } from "./bundle/install.js";
-import type { MemoryConfig } from "./config.js";
-import { loadMemoryConfig } from "./settings.js";
-import { openSessionIndex } from "./fallback/sessionIndex.js";
-import { SidecarClient } from "./sidecar/client.js";
-import { MemoryService } from "./service.js";
-import { trainBundle } from "./trainer/index.js";
-import { createLLMFactExtractor } from "./trainer/llmExtractor.js";
-import { createTrainScheduler } from "./trainer/scheduler.js";
-import type { QueryIntent } from "./types.js";
-
-async function tryReloadSidecar(cfg: MemoryConfig): Promise<void> {
-  try {
-    fs.accessSync(cfg.socketPath, fs.constants.F_OK);
-  } catch {
-    return;
-  }
-  const client = new SidecarClient(cfg.socketPath, cfg.clientRequestTimeoutMs);
-  try {
-    await client.reload();
-  } catch {
-    /* sidecar not running — install still succeeded */
-  }
-}
-
-async function main(): Promise<void> {
-  const [cmd, ...rest] = process.argv.slice(2);
-  if (!cmd || cmd === "help" || cmd === "--help") {
-    printHelp();
-    process.exit(0);
-  }
-
-  const cfg = loadMemoryConfig();
-  const service = new MemoryService(cfg);
-
-  if (cmd === "health") {
-    await service.start();
-    const h = await service.health();
-    console.log(JSON.stringify({ status: service.getStatus(), health: h }, null, 2));
-    await service.stop();
-    return;
-  }
-
-  if (cmd === "query") {
-    const json = rest.join(" ").trim();
-    if (!json) {
-      console.error('Usage: pi-memory query \'{"anchor_mentions":["Alice"],"mode":"direct_relation"}\'');
-      process.exit(1);
-    }
-    let intent: QueryIntent;
-    try {
-      intent = JSON.parse(json) as QueryIntent;
-    } catch (e) {
-      console.error("Invalid JSON intent:", e);
-      process.exit(1);
+import { createLlmClient } from "./adapters/llm/index.js";
+import { resolveAgentDirFromEnv } from "./config/agentDir.js";
+import { loadEnv } from "./config/loadEnv.js";
+import {
+  runConsolidateCommand,
+  runDrainShutdownQueueCommand,
+  runMaintenanceCommand,
+} from "./cli/jobs.js";
+import { createCliLog } from "./cli/log.js";
+import { CLI_HELP, parseCliArgs } from "./cli/parseArgs.js";
+import { runInitCommand } from "./cli/init.js";
+import { runStatusCommand } from "./cli/status.js";
+import { theme } from "./cli/theme.js";
+import { createMemoryStore } from "./store/index.js";
+
+async function main(): Promise<number> {
+  loadEnv();
+
+  const parsed = parseCliArgs(process.argv.slice(2));
+  if (parsed.command === "help") {
+    if (parsed.error) {
+      console.error(theme.error(parsed.error));
     }
-    await service.start();
-    const result = await service.query(intent);
-    console.log(JSON.stringify(result, null, 2));
-    await service.stop();
-    return;
+    console.log(CLI_HELP);
+    return parsed.error ? 1 : 0;
   }
 
-  if (cmd === "status") {
-    await service.start();
-    console.log(JSON.stringify(service.getStatus(), null, 2));
-    await service.stop();
-    return;
+  const agentDir = resolveAgentDirFromEnv(
+    "options" in parsed ? parsed.options.agentDir : undefined,
+  );
+
+  if (parsed.command === "init") {
+    const log = createCliLog({ verbose: true, debug: parsed.options.verbose });
+    return runInitCommand(agentDir, log);
   }
 
-  if (cmd === "install-bundle") {
-    const bundlePath = rest[0];
-    if (!bundlePath) {
-      console.error("Usage: pi-memory install-bundle <path-to-bundle-dir>");
-      process.exit(1);
-    }
-    const result = await installBundle({
-      bundleRoot: cfg.bundleRoot,
-      sourceDir: bundlePath,
-    });
-    await tryReloadSidecar(cfg);
-    console.log(JSON.stringify(result, null, 2));
-    return;
+  if (parsed.command === "status") {
+    const log = createCliLog({ verbose: true, debug: parsed.options.verbose });
+    return runStatusCommand(agentDir, log);
   }
 
-  if (cmd === "train") {
-    const flags = parseTrainFlags(rest);
-    let extractOpts;
-    if (flags.extractor === "llm") {
-      try {
-        const client = createStandaloneLLMClient(flags.model);
-        extractOpts = {
-          llmExtractor: createLLMFactExtractor({
-            client,
-            batchSize: cfg.trainer.llm_batch_size,
-          }),
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        console.error(`LLM extractor unavailable (${message}) — falling back to regex.`);
-        extractOpts = undefined;
-      }
-    }
+  const store = createMemoryStore({ agentDir });
+  await store.ensureInitialized();
 
-    const result = await trainBundle({
-      sessionsDir: flags.sessionsDir ?? cfg.sessionsDir,
-      bundleRoot: cfg.bundleRoot,
-      full: flags.full,
-      dryRun: flags.dryRun,
-      noMerge: flags.noMerge,
-      extractOpts,
-    });
-    if (result.sessionsProcessed === 0) {
-      console.log("No new sessions to process.");
-    } else {
-      const output: Record<string, unknown> = {
-        sessions_processed: result.sessionsProcessed,
-        entities: result.entityCount,
-        relations: result.relationCount,
-        events: result.eventCount,
-        dry_run: result.dryRun,
-        bundle_dir: result.bundleResult?.bundleDir ?? null,
-        installed: result.installResult?.installed_dir ?? null,
-      };
-      if (result.delta) {
-        output.delta = {
-          added: result.delta.added,
-          updated: result.delta.updated,
-          deleted: result.delta.deleted,
-          skipped: result.delta.skipped,
-        };
-      }
-      console.log(JSON.stringify(output, null, 2));
-      if (!result.dryRun) {
-        await tryReloadSidecar(cfg);
-      }
-    }
+  const llm = await createLlmClient();
 
-    if (flags.watch) {
-      const interval = cfg.trainer.auto_interval ?? "1h";
-      console.log(`Watching for new sessions (interval: ${interval})...`);
-      createTrainScheduler(
-        { interval, trainConfig: { sessionsDir: flags.sessionsDir ?? cfg.sessionsDir, bundleRoot: cfg.bundleRoot } },
-        (log) => {
-          console.log(JSON.stringify({ type: "scheduled_run", ...log }));
-        },
+  if (parsed.command === "maintenance") {
+    const log = createCliLog({ verbose: parsed.options.verbose });
+    if (parsed.options.verbose && !llm) {
+      log.warn(
+        "no helper LLM configured; consolidate uses rule-based dedupe; shutdown drain skips LLM extract",
       );
-      await new Promise(() => {}); // block forever
     }
-    return;
+    return runMaintenanceCommand({
+      store,
+      agentDir,
+      llm,
+      options: parsed.options,
+      log,
+    });
   }
 
-  if (cmd === "index") {
-    const sessionsDir = rest.find((a, i) => rest[i - 1] === "--sessions-dir") ?? cfg.sessionsDir;
-    const dbPath = path.join(cfg.bundleRoot, "sessions.db");
-    const idx = openSessionIndex(dbPath);
-    if (!idx) {
-      console.error("Failed to open SQLite — is better-sqlite3 installed?");
-      process.exit(1);
+  if (parsed.command === "drain-shutdown-queue") {
+    const log = createCliLog({ verbose: parsed.options.verbose });
+    if (parsed.options.verbose && !llm) {
+      log.warn("no helper LLM configured; shutdown drain skips sessions without compaction export");
     }
-    console.log(`Rebuilding FTS5 index at ${dbPath}...`);
-    const { indexed } = await idx.rebuildIndex(sessionsDir);
-    idx.close();
-    console.log(JSON.stringify({ indexed, db_path: dbPath }));
-    return;
+    return runDrainShutdownQueueCommand({
+      store,
+      agentDir,
+      llm,
+      verbose: parsed.options.verbose,
+      log,
+    });
   }
 
-  console.error(`Unknown command: ${cmd}`);
-  printHelp();
-  process.exit(1);
-}
-
-function parseTrainFlags(args: string[]): {
-  sessionsDir?: string;
-  full: boolean;
-  dryRun: boolean;
-  noMerge: boolean;
-  extractor: "regex" | "llm";
-  watch: boolean;
-  model?: string;
-} {
-  let sessionsDir: string | undefined;
-  let full = false;
-  let dryRun = false;
-  let noMerge = false;
-  let extractor: "regex" | "llm" = "regex";
-  let watch = false;
-  let model: string | undefined;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]!;
-    if (arg === "--full") { full = true; continue; }
-    if (arg === "--dry-run") { dryRun = true; continue; }
-    if (arg === "--no-merge") { noMerge = true; continue; }
-    if (arg === "--watch") { watch = true; continue; }
-    if (arg === "--model" && i + 1 < args.length) {
-      model = args[++i];
-      continue;
-    }
-    if (arg === "--sessions-dir" && i + 1 < args.length) {
-      sessionsDir = args[++i];
-      continue;
-    }
-    if (arg === "--extractor" && i + 1 < args.length) {
-      const val = args[++i]!;
-      if (val === "llm" || val === "regex") extractor = val;
-      continue;
+  if (parsed.command === "consolidate") {
+    const log = createCliLog({ verbose: parsed.options.verbose });
+    if (parsed.options.verbose && !llm) {
+      log.warn("no helper LLM configured; using rule-based dedupe only");
     }
+    return runConsolidateCommand({
+      store,
+      agentDir,
+      llm,
+      cron: parsed.options.cron,
+      force: parsed.options.force,
+      verbose: parsed.options.verbose,
+      log,
+    });
   }
-  return { sessionsDir, full, dryRun, noMerge, extractor, watch, model };
-}
-
-function printHelp(): void {
-  console.log(`pi-memory — local TLM episodic memory (mode B)
-
-Commands:
-  health              Start sidecar (if bundle present) and print /health
-  status              Print MemoryService status snapshot
-  query               POST /query with JSON QueryIntent
-  install-bundle      Copy a local bundle dir into ~/.pi/memory/current
-  train               Build a bundle from session history (delta merge by default)
-    --sessions-dir    Override sessions directory (default from config)
-    --full            Ignore marker, rebuild from all sessions
-    --dry-run         Show extraction stats without writing bundle
-    --no-merge        Skip delta merge, full rebuild (ignore existing bundle)
-    --extractor       Extractor type: "regex" (default) or "llm"
-    --model           LLM model for --extractor llm (default: deepseek/deepseek-v4-flash)
-    --watch           Run once then schedule periodic re-training
-  index               Rebuild SQLite FTS5 session search index
-    --sessions-dir    Override sessions directory (default from config)
-
-Environment:
-  Place bundle at ~/.pi/memory/current/ (symlink to bundles/<ts>/)
-  Session fallback searches ~/.pi/sessions/*.json
-  Install tlm on PATH or set memory.tlmPath in Pi extension config
-  LLM extractor uses provider env vars (e.g. DEEPSEEK_API_KEY for deepseek/deepseek-v4-flash)
 
-Example:
-  pi-memory query '{"mode":"direct_relation","anchor_mentions":["Alice"]}'
-  pi-memory install-bundle ./my-bundle-2026-06-01T00-00-00Z
-  pi-memory train --full
-  pi-memory train --extractor llm
-  pi-memory train --watch
-  pi-memory index
-`);
+  return 1;
 }
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    const log = createCliLog({ verbose: true });
+    log.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  },
+);

package/src/commands/index.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { createRememberCommand } from "./remember.js";
+import { createMemoryStatusCommand } from "./status.js";
+import type { CommandDeps } from "./types.js";
+
+export type { CommandDeps, MemoryStatusCommandDeps, RememberCommandDeps } from "./types.js";
+export { parseRememberArgs } from "./parseRememberArgs.js";
+
+export function registerCommands(pi: ExtensionAPI, deps: CommandDeps): void {
+  pi.registerCommand("remember", {
+    description: "Append a user-authored note to MEMORY.md",
+    handler: createRememberCommand(deps),
+  });
+
+  pi.registerCommand("memory-status", {
+    description: "Show MEMORY.md, sidecar, and vector index diagnostics (toggle expand/collapse; hide to dismiss)",
+    handler: createMemoryStatusCommand(deps),
+  });
+}

package/src/commands/parseMemoryStatusArgs.ts

@@ -0,0 +1,11 @@
+export type MemoryStatusAction = "toggle" | "refresh" | "hide" | "expand" | "collapse";
+
+export function parseMemoryStatusArgs(args: string | string[]): MemoryStatusAction {
+  const text = (Array.isArray(args) ? args.join(" ") : args).trim().toLowerCase();
+  if (!text) return "toggle";
+  if (text === "hide" || text === "close" || text === "off" || text === "dismiss") return "hide";
+  if (text === "refresh" || text === "reload") return "refresh";
+  if (text === "expand" || text === "open" || text === "show") return "expand";
+  if (text === "collapse" || text === "fold" || text === "min") return "collapse";
+  return "toggle";
+}

package/src/commands/parseRememberArgs.ts

@@ -0,0 +1,55 @@
+import { MEMORY_SECTIONS, type MemorySection } from "../store/types.js";
+
+const SECTION_ALIASES: Record<string, MemorySection> = {
+  preferences: "Preferences",
+  preference: "Preferences",
+  prefs: "Preferences",
+  pref: "Preferences",
+  conventions: "Conventions",
+  convention: "Conventions",
+  conv: "Conventions",
+  findings: "Findings",
+  finding: "Findings",
+  todos: "Todos",
+  todo: "Todos",
+};
+
+export type ParsedRememberArgs =
+  | { section: MemorySection; content: string }
+  | { error: string };
+
+function normalizeArgs(raw: string | string[]): string {
+  return (Array.isArray(raw) ? raw.join(" ") : raw).trim();
+}
+
+function matchSection(token: string): MemorySection | undefined {
+  const key = token.toLowerCase();
+  if (SECTION_ALIASES[key]) return SECTION_ALIASES[key];
+  return MEMORY_SECTIONS.find((section) => section.toLowerCase() === key);
+}
+
+/** Parse `/remember [section]? content`. Default section: Findings. */
+export function parseRememberArgs(raw: string | string[]): ParsedRememberArgs {
+  const text = normalizeArgs(raw);
+  if (!text) {
+    return {
+      error: "Usage: /remember [Preferences|Conventions|Findings|Todos] <content>",
+    };
+  }
+
+  const space = text.indexOf(" ");
+  const firstToken = space === -1 ? text : text.slice(0, space);
+  const section = matchSection(firstToken);
+
+  if (section) {
+    const content = space === -1 ? "" : text.slice(space + 1).trim();
+    if (!content) {
+      return {
+        error: `Usage: /remember ${section} <content>`,
+      };
+    }
+    return { section, content };
+  }
+
+  return { section: "Findings", content: text };
+}

package/src/commands/remember.ts

@@ -0,0 +1,43 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import type { MemoryStore } from "../store/memoryStore.js";
+import { parseRememberArgs } from "./parseRememberArgs.js";
+
+export type RememberCommandDeps = {
+  getMemoryStore(): MemoryStore | null;
+  onRemembered?(): Promise<void>;
+};
+
+export function createRememberCommand(deps: RememberCommandDeps) {
+  return async (args: string | string[], ctx: ExtensionCommandContext): Promise<void> => {
+    const memoryStore = deps.getMemoryStore();
+    if (!memoryStore) {
+      ctx.ui.notify("pi-memory: not started", "warning");
+      return;
+    }
+
+    const parsed = parseRememberArgs(args);
+    if ("error" in parsed) {
+      ctx.ui.notify(parsed.error, "warning");
+      return;
+    }
+
+    try {
+      await memoryStore.ensureInitialized();
+      await memoryStore.appendUser({
+        id: "",
+        section: parsed.section,
+        content: parsed.content,
+        timestamp: "",
+      });
+      await deps.onRemembered?.();
+
+      ctx.ui.notify(`Saved to MEMORY.md (${parsed.section})`, "info");
+    } catch (error) {
+      ctx.ui.notify(
+        `Remember failed: ${error instanceof Error ? error.message : String(error)}`,
+        "warning",
+      );
+    }
+  };
+}

package/src/commands/status.ts

@@ -0,0 +1,112 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import {
+  formatMemoryStatusLines,
+  gatherMemoryStatus,
+} from "../cli/status.js";
+import { resolveMemoryAgentDir } from "../config/agentDir.js";
+import { createMemoryStatusWidget, type MemoryStatusWidgetState } from "../ui/memoryStatusWidget.js";
+
+import { parseMemoryStatusArgs } from "./parseMemoryStatusArgs.js";
+
+export type MemoryStatusCommandDeps = {
+  getAgentDir(): string | null;
+};
+
+let memoryStatusWidgetState: MemoryStatusWidgetState | null = null;
+
+export function resetMemoryStatusWidgetState(): void {
+  memoryStatusWidgetState = null;
+}
+
+function renderMemoryStatusWidget(
+  ctx: ExtensionCommandContext,
+  state: MemoryStatusWidgetState,
+): void {
+  ctx.ui.setWidget("pi-memory-status", (tui, theme) => createMemoryStatusWidget(tui, theme, state), {
+    placement: "aboveEditor",
+  });
+}
+
+function applyMemoryStatusAction(
+  action: ReturnType<typeof parseMemoryStatusArgs>,
+  refreshed: boolean,
+): void {
+  if (!memoryStatusWidgetState) return;
+
+  if (action === "expand") {
+    memoryStatusWidgetState.expanded = true;
+    return;
+  }
+  if (action === "collapse") {
+    memoryStatusWidgetState.expanded = false;
+    return;
+  }
+  if (action === "toggle" && !refreshed) {
+    memoryStatusWidgetState.expanded = !memoryStatusWidgetState.expanded;
+    return;
+  }
+  if (action === "toggle" && refreshed) {
+    memoryStatusWidgetState.expanded = false;
+  }
+}
+
+export function createMemoryStatusCommand(deps: MemoryStatusCommandDeps) {
+  return async (args: string | string[], ctx: ExtensionCommandContext): Promise<void> => {
+    const action = parseMemoryStatusArgs(args);
+
+    if (action === "hide") {
+      memoryStatusWidgetState = null;
+      if (ctx.hasUI) {
+        ctx.ui.setWidget("pi-memory-status", undefined);
+      }
+      return;
+    }
+
+    const agentDir = deps.getAgentDir() ?? resolveMemoryAgentDir();
+
+    const needsFetch = action === "refresh" || !memoryStatusWidgetState;
+
+    if (needsFetch) {
+      if (ctx.hasUI) {
+        ctx.ui.setWorkingMessage("Checking memory…");
+      }
+
+      try {
+        const report = await gatherMemoryStatus(agentDir);
+        memoryStatusWidgetState = {
+          report,
+          expanded: memoryStatusWidgetState?.expanded ?? false,
+        };
+      } catch (error) {
+        ctx.ui.notify(
+          `Memory status failed: ${error instanceof Error ? error.message : String(error)}`,
+          "warning",
+        );
+        return;
+      } finally {
+        if (ctx.hasUI) {
+          ctx.ui.setWorkingMessage();
+        }
+      }
+    }
+
+    applyMemoryStatusAction(action, needsFetch);
+
+    if (ctx.hasUI) {
+      renderMemoryStatusWidget(ctx, memoryStatusWidgetState!);
+      return;
+    }
+
+    const lines = ["pi-memory status", ...formatMemoryStatusLines(memoryStatusWidgetState!.report)];
+    ctx.ui.notify(lines.join("\n"), "info");
+  };
+}
+
+export function getMemoryStatusWidgetStateForTest(): MemoryStatusWidgetState | null {
+  return memoryStatusWidgetState;
+}
+
+export function setMemoryStatusWidgetStateForTest(state: MemoryStatusWidgetState | null): void {
+  memoryStatusWidgetState = state;
+}

package/src/commands/types.ts

@@ -0,0 +1,12 @@
+import type { MemoryStore } from "../store/memoryStore.js";
+
+export type RememberCommandDeps = {
+  getMemoryStore(): MemoryStore | null;
+  onRemembered?(): Promise<void>;
+};
+
+export type MemoryStatusCommandDeps = {
+  getAgentDir(): string | null;
+};
+
+export type CommandDeps = RememberCommandDeps & MemoryStatusCommandDeps;

package/src/compact/index.ts

@@ -0,0 +1,4 @@
+export { parseMemoryExport, hasMemoryExportSection } from "./parseMemoryExport.js";
+export { buildCompactionSummaryPrompt, DUAL_PURPOSE_SUMMARY_TEMPLATE } from "./summaryPrompt.js";
+export { runDualPurposeCompactionSummary } from "./runSummary.js";
+export { registerCompactHandlers, type CompactHandlerDeps } from "./register.js";

package/src/compact/parseMemoryExport.ts

@@ -0,0 +1,71 @@
+import { parseMemoryMarkdown } from "../store/markdown/parse.js";
+import { MEMORY_SECTIONS, type MemorySection, type StoreMemoryEntry } from "../store/types.js";
+
+const MEMORY_EXPORT_HEADER_RE = /^##\s+Memory Export\s*$/im;
+
+function extractMemoryExportBlock(summary: string): string {
+  const match = MEMORY_EXPORT_HEADER_RE.exec(summary);
+  if (!match) return "";
+
+  let body = summary.slice(match.index + match[0].length);
+  const nextTopLevel = body.search(/^##\s+(?!#)/m);
+  if (nextTopLevel >= 0) {
+    body = body.slice(0, nextTopLevel);
+  }
+
+  return body.trim();
+}
+
+/** Normalize ### Section headers to ## for shared markdown parser. */
+function normalizeExportMarkdown(exportBody: string): string {
+  const lines = exportBody.split("\n");
+  const normalized: string[] = [];
+
+  for (const line of lines) {
+    const subsection = line.match(/^###\s+(Preferences|Conventions|Findings|Todos)\s*$/);
+    if (subsection) {
+      normalized.push(`## ${subsection[1]}`);
+      continue;
+    }
+    normalized.push(line);
+  }
+
+  return normalized.join("\n");
+}
+
+function parseExportBullets(exportBody: string): StoreMemoryEntry[] {
+  const normalized = normalizeExportMarkdown(exportBody);
+  if (!normalized.trim()) return [];
+
+  const parsed = parseMemoryMarkdown(normalized, "memory-export");
+  return parsed.map((entry) => ({
+    id: "",
+    section: entry.section,
+    content: entry.content,
+    timestamp: "",
+  }));
+}
+
+/** Parse durable facts from the ## Memory Export section of a dual-purpose summary. */
+export function parseMemoryExport(summary: string): StoreMemoryEntry[] {
+  const exportBody = extractMemoryExportBlock(summary);
+  if (!exportBody) return [];
+
+  const entries = parseExportBullets(exportBody);
+  const seen = new Set<string>();
+
+  return entries.filter((entry) => {
+    const key = `${entry.section}\0${entry.content.trim()}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return entry.content.trim().length > 0;
+  });
+}
+
+export function hasMemoryExportSection(summary: string): boolean {
+  return MEMORY_EXPORT_HEADER_RE.test(summary);
+}
+
+export function isKnownExportSection(name: string): name is MemorySection {
+  return (MEMORY_SECTIONS as readonly string[]).includes(name);
+}