@chendpoc/pi-memory 0.1.0

package/src/cli.ts

@@ -0,0 +1,254 @@
+#!/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 { defaultMemoryConfig } from "./config.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: ReturnType<typeof defaultMemoryConfig>): 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 = defaultMemoryConfig();
+  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);
+    }
+    await service.start();
+    const result = await service.query(intent);
+    console.log(JSON.stringify(result, null, 2));
+    await service.stop();
+    return;
+  }
+
+  if (cmd === "status") {
+    await service.start();
+    console.log(JSON.stringify(service.getStatus(), null, 2));
+    await service.stop();
+    return;
+  }
+
+  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 (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 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);
+      }
+    }
+
+    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 }));
+        },
+      );
+      await new Promise(() => {}); // block forever
+    }
+    return;
+  }
+
+  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);
+    }
+    console.log(`Rebuilding FTS5 index at ${dbPath}...`);
+    const { indexed } = await idx.rebuildIndex(sessionsDir);
+    idx.close();
+    console.log(JSON.stringify({ indexed, db_path: dbPath }));
+    return;
+  }
+
+  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;
+    }
+  }
+  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
+`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/config.ts

@@ -0,0 +1,92 @@
+import path from "node:path";
+
+import {
+  defaultBundleRoot,
+  defaultPiHome,
+  defaultSessionsDir,
+  defaultSocketPath,
+  expandPath,
+} from "./paths.js";
+
+export type MemoryProvider = "disabled" | "local" | "cloud";
+
+export type ExtractorType = "regex" | "llm";
+
+export interface TrainerConfig {
+  /** Which extractor to use (default "regex"). */
+  extractor: ExtractorType;
+  /** How many turns per LLM call when extractor is "llm" (default 10). */
+  llm_batch_size: number;
+  /** Auto-train interval: "1h"|"6h"|"12h"|"24h"|null (default null — disabled). */
+  auto_interval: string | null;
+}
+
+export interface MemoryConfig {
+  provider: MemoryProvider;
+  tlmPath: string;
+  socketPath: string;
+  bundleRoot: string;
+  sidecarReadyTimeoutMs: number;
+  queryTimeoutMs: number;
+  clientRequestTimeoutMs: number;
+  sessionsDir: string;
+  memoryMdPaths: string[];
+  trainer: TrainerConfig;
+}
+
+export const defaultTrainerConfig: TrainerConfig = {
+  extractor: "regex",
+  llm_batch_size: 10,
+  auto_interval: null,
+};
+
+export function defaultMemoryConfig(
+  overrides: Partial<MemoryConfig> = {},
+): MemoryConfig {
+  const { trainer: trainerOverrides, ...rest } = overrides;
+  return {
+    provider: "local",
+    tlmPath: "tlm",
+    socketPath: defaultSocketPath(),
+    bundleRoot: defaultBundleRoot(),
+    sidecarReadyTimeoutMs: 15_000,
+    queryTimeoutMs: 2_000,
+    clientRequestTimeoutMs: 5_000,
+    sessionsDir: defaultSessionsDir(),
+    memoryMdPaths: [path.join(defaultPiHome(), "MEMORY.md")],
+    trainer: { ...defaultTrainerConfig, ...trainerOverrides },
+    ...rest,
+  };
+}
+
+/** Normalize user-supplied paths after JSON/env load. */
+export function normalizeMemoryConfig(
+  raw: Partial<MemoryConfig> & Record<string, unknown>,
+): MemoryConfig {
+  const base = defaultMemoryConfig();
+  const rawTrainer = (raw.trainer ?? {}) as Partial<TrainerConfig>;
+  return {
+    provider: (raw.provider as MemoryProvider) ?? base.provider,
+    tlmPath: expandPath(String(raw.tlmPath ?? base.tlmPath)),
+    socketPath: expandPath(String(raw.socketPath ?? base.socketPath)),
+    bundleRoot: expandPath(String(raw.bundleRoot ?? base.bundleRoot)),
+    sidecarReadyTimeoutMs: Number(
+      raw.sidecarReadyTimeoutMs ?? base.sidecarReadyTimeoutMs,
+    ),
+    queryTimeoutMs: Number(raw.queryTimeoutMs ?? base.queryTimeoutMs),
+    clientRequestTimeoutMs: Number(
+      raw.clientRequestTimeoutMs ?? base.clientRequestTimeoutMs,
+    ),
+    sessionsDir: expandPath(String(raw.sessionsDir ?? base.sessionsDir)),
+    memoryMdPaths: Array.isArray(raw.memoryMdPaths)
+      ? raw.memoryMdPaths.map((p) => expandPath(String(p)))
+      : base.memoryMdPaths,
+    trainer: {
+      extractor: (rawTrainer.extractor as ExtractorType) ?? base.trainer.extractor,
+      llm_batch_size: Number(rawTrainer.llm_batch_size ?? base.trainer.llm_batch_size),
+      auto_interval: rawTrainer.auto_interval !== undefined
+        ? rawTrainer.auto_interval
+        : base.trainer.auto_interval,
+    },
+  };
+}

package/src/errclass.ts

@@ -0,0 +1,37 @@
+import { errorSubCode, type ResponseEnvelope } from "./types.js";
+
+export type ErrorClass = "ok" | "retryable" | "permanent" | "unavailable";
+
+export const ErrTransport = new Error("memory: transport failure");
+
+export function classifyTransportError(err: unknown): ErrorClass {
+  return err == null ? "ok" : "unavailable";
+}
+
+/** Maps HTTP status + envelope → error class (Kocoro memory/errclass.go). */
+export function classifyHTTP(
+  status: number,
+  env: ResponseEnvelope | null,
+): ErrorClass {
+  if (status >= 200 && status < 300) return "ok";
+  const sub = env?.error ? errorSubCode(env.error) : "";
+  const code = env?.error?.code ?? "";
+  switch (status) {
+    case 400:
+      return "permanent";
+    case 401:
+    case 403:
+      return "permanent";
+    case 409:
+      return "retryable";
+    case 422:
+      return "permanent";
+    case 503:
+      if (code === "not_ready" || sub === "not_ready") return "unavailable";
+      return "permanent";
+    case 500:
+      return "retryable";
+    default:
+      return "retryable";
+  }
+}

package/src/extension.ts

@@ -0,0 +1,23 @@
+/**
+ * @deprecated Use `@chendpoc/pi-memory/extension` (pi-extension.ts) with real ExtensionAPI.
+ * Re-exports the Pi extension entry for backward compatibility.
+ */
+export { default, default as piMemoryExtension, getSharedMemoryService } from "./pi-extension.js";
+export type { BeforeTurnHook, MemoryHelperLLM } from "./preflight/hook.js";
+export { createBeforeTurnHook } from "./preflight/hook.js";
+
+/** @deprecated Stub types kept for programmatic callers migrating off the old API. */
+export interface PiExtensionAPI {
+  config?: Record<string, unknown>;
+  registerTool(tool: PiAgentTool): void;
+  onBeforeTurn?(hook: import("./preflight/hook.js").BeforeTurnHook): void;
+  onUnload?(fn: () => void | Promise<void>): void;
+}
+
+/** @deprecated */
+export interface PiAgentTool {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  execute(args: Record<string, unknown>, ctx?: { signal?: AbortSignal }): Promise<string>;
+}

package/src/fallback/index.ts

@@ -0,0 +1,24 @@
+import type { FallbackQuery } from "../types.js";
+import { memoryMdSnippet } from "./memoryMd.js";
+import { sessionKeywordSearch } from "./sessionSearch.js";
+
+export type { SessionSearchHit } from "./sessionSearch.js";
+export { sessionKeywordSearch } from "./sessionSearch.js";
+export { memoryMdSnippet } from "./memoryMd.js";
+
+export interface FallbackOptions {
+  sessionsDir: string;
+  memoryMdPaths: string[];
+}
+
+/** Real fallback: session JSON keyword search + MEMORY.md grep. */
+export function createFallbackQuery(opts: FallbackOptions): FallbackQuery {
+  return {
+    async sessionKeyword(query: string, limit: number) {
+      return sessionKeywordSearch(opts.sessionsDir, query, limit);
+    },
+    async memoryFileSnippet(query: string) {
+      return memoryMdSnippet(opts.memoryMdPaths, query);
+    },
+  };
+}

package/src/fallback/llmRerank.ts

@@ -0,0 +1,90 @@
+import type { LLMClient } from "../trainer/llmExtractor.js";
+import type { SessionSearchHit } from "./sessionSearch.js";
+
+export interface RerankOptions {
+  client: LLMClient;
+  maxCandidates?: number;
+  maxTokens?: number;
+}
+
+export interface RankedResult {
+  index: number;
+  score: number;
+  summary: string;
+}
+
+const DEFAULT_MAX_CANDIDATES = 10;
+
+function buildRerankPrompt(query: string, hits: SessionSearchHit[]): string {
+  const numbered = hits
+    .map((h, i) => `#${i}: [${h.session_title || "untitled"}] ${h.snippet}`)
+    .join("\n");
+
+  return `You are a relevance judge. Given a user query and numbered search results from past sessions, rate each result 0-10 for relevance to the query and write a one-sentence summary of the relevant content.
+
+Query: ${query}
+
+Results:
+${numbered}
+
+Respond with ONLY a JSON array (no markdown fences, no explanation):
+[{ "index": 0, "score": 8, "summary": "..." }, ...]`;
+}
+
+interface RawRankedItem {
+  index?: unknown;
+  score?: unknown;
+  summary?: unknown;
+}
+
+function parseRerankResponse(raw: string, hitCount: number): RankedResult[] | null {
+  const cleaned = raw.replace(/^```(?:json)?\s*/m, "").replace(/\s*```\s*$/m, "").trim();
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch {
+    return null;
+  }
+
+  if (!Array.isArray(parsed)) return null;
+
+  const results: RankedResult[] = [];
+  for (const item of parsed as RawRankedItem[]) {
+    const index = typeof item.index === "number" ? item.index : -1;
+    const score = typeof item.score === "number" ? item.score : 0;
+    const summary = typeof item.summary === "string" ? item.summary.trim() : "";
+    if (index < 0 || index >= hitCount || !summary) continue;
+    results.push({ index, score: Math.max(0, Math.min(10, score)), summary });
+  }
+
+  if (results.length === 0) return null;
+
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}
+
+/**
+ * Rerank FTS5 search hits using an LLM. Returns scored + summarized results
+ * sorted by relevance. On any LLM failure, returns null (caller should use
+ * original hits as fallback).
+ */
+export async function rerankWithLLM(
+  query: string,
+  hits: SessionSearchHit[],
+  opts: RerankOptions,
+): Promise<RankedResult[] | null> {
+  if (hits.length === 0) return null;
+
+  const maxCandidates = opts.maxCandidates ?? DEFAULT_MAX_CANDIDATES;
+  const truncated = hits.slice(0, maxCandidates);
+
+  const prompt = buildRerankPrompt(query, truncated);
+
+  try {
+    const response = await opts.client.complete(prompt);
+    return parseRerankResponse(response, truncated.length);
+  } catch {
+    return null;
+  }
+}

package/src/fallback/memoryMd.ts

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+
+const SNIPPET_CAP = 4096;
+
+/**
+ * Best-effort grep of MEMORY.md for query terms (Kocoro memory_fallback.go).
+ * Returns joined matching lines capped at 4KB. Empty string if absent/no match.
+ */
+export async function memoryMdSnippet(
+  paths: string[],
+  query: string,
+): Promise<string> {
+  const q = query.trim().toLowerCase();
+  if (!q) return "";
+
+  for (const p of paths) {
+    let text: string;
+    try {
+      text = await fs.readFile(p, "utf8");
+    } catch {
+      continue;
+    }
+    const matches: string[] = [];
+    let total = 0;
+    for (const line of text.split("\n")) {
+      if (!line.toLowerCase().includes(q)) continue;
+      matches.push(line);
+      total += line.length + 1;
+      if (total > SNIPPET_CAP) break;
+    }
+    if (matches.length > 0) {
+      return matches.join("\n");
+    }
+  }
+  return "";
+}