@chendpoc/pi-memory 0.2.1 → 0.2.3

package/src/cli/log.ts

@@ -1,46 +0,0 @@
-import { theme } from "./theme.js";
-
-export type CliLogOptions = {
-  verbose?: boolean;
-  debug?: boolean;
-};
-
-export type CliLog = {
-  info(message: string): void;
-  success(message: string): void;
-  warn(message: string): void;
-  error(message: string): void;
-  debug(message: string): void;
-  line(label: string, value: string): void;
-};
-
-function prefix(): string {
-  return `${theme.prefix()} `;
-}
-
-export function createCliLog(opts: CliLogOptions = {}): CliLog {
-  const debugOn = opts.debug ?? process.env.PI_MEMORY_DEBUG === "1";
-
-  return {
-    info(message) {
-      if (!opts.verbose) return;
-      console.error(prefix() + theme.info(message));
-    },
-    success(message) {
-      console.error(prefix() + theme.success(message));
-    },
-    warn(message) {
-      console.error(prefix() + theme.warn(message));
-    },
-    error(message) {
-      console.error(prefix() + theme.error(message));
-    },
-    debug(message) {
-      if (!debugOn && !opts.verbose) return;
-      console.error(prefix() + theme.dim(message));
-    },
-    line(label, value) {
-      console.error(`${prefix()}${theme.label(`${label}`.padEnd(16))} ${theme.value(value)}`);
-    },
-  };
-}

package/src/cli/parseArgs.ts

@@ -1,175 +0,0 @@
-export type CliCommand =
-  | "consolidate"
-  | "maintenance"
-  | "drain-shutdown-queue"
-  | "init"
-  | "status"
-  | "help";
-
-export type CommonCliOptions = {
-  agentDir?: string;
-  verbose: boolean;
-};
-
-export type ConsolidateCliOptions = CommonCliOptions & {
-  cron: boolean;
-  force: boolean;
-};
-
-export type MaintenanceCliOptions = ConsolidateCliOptions;
-
-export type DrainShutdownQueueCliOptions = CommonCliOptions;
-
-export type StatusCliOptions = CommonCliOptions;
-
-export type InitCliOptions = CommonCliOptions;
-
-export type ParsedCli =
-  | { command: "help"; error?: string }
-  | { command: "consolidate"; options: ConsolidateCliOptions }
-  | { command: "maintenance"; options: MaintenanceCliOptions }
-  | { command: "drain-shutdown-queue"; options: DrainShutdownQueueCliOptions }
-  | { command: "init"; options: InitCliOptions }
-  | { command: "status"; options: StatusCliOptions };
-
-function parseCommonFlags(
-  rest: string[],
-  base: CommonCliOptions,
-): ParsedCli | CommonCliOptions {
-  const options = { ...base };
-
-  for (let i = 0; i < rest.length; i++) {
-    const arg = rest[i]!;
-    switch (arg) {
-      case "--verbose":
-      case "-v":
-        options.verbose = true;
-        break;
-      case "--agent-dir": {
-        const value = rest[++i];
-        if (!value) return { command: "help", error: "--agent-dir requires a path" };
-        options.agentDir = value;
-        break;
-      }
-      default:
-        return { command: "help", error: `Unknown flag: ${arg}` };
-    }
-  }
-
-  return options;
-}
-
-function parseConsolidateLikeFlags(
-  rest: string[],
-  command: Extract<CliCommand, "consolidate" | "maintenance">,
-): ParsedCli {
-  const options: ConsolidateCliOptions = {
-    cron: false,
-    force: false,
-    verbose: false,
-  };
-
-  for (let i = 0; i < rest.length; i++) {
-    const arg = rest[i]!;
-    switch (arg) {
-      case "--cron":
-        options.cron = true;
-        break;
-      case "--force":
-        options.force = true;
-        break;
-      case "--verbose":
-      case "-v":
-        options.verbose = true;
-        break;
-      case "--agent-dir": {
-        const value = rest[++i];
-        if (!value) return { command: "help", error: "--agent-dir requires a path" };
-        options.agentDir = value;
-        break;
-      }
-      default:
-        return { command: "help", error: `Unknown flag: ${arg}` };
-    }
-  }
-
-  return { command, options };
-}
-
-export function parseCliArgs(argv: string[]): ParsedCli {
-  const args = argv.filter((arg) => arg !== "--");
-  if (args.length === 0) {
-    return { command: "help" };
-  }
-
-  const [command, ...rest] = args;
-  if (command === "help" || command === "--help" || command === "-h") {
-    return { command: "help" };
-  }
-
-  if (command === "status") {
-    const parsed = parseCommonFlags(rest, { verbose: false });
-    if ("command" in parsed) return parsed;
-    return { command: "status", options: parsed };
-  }
-
-  if (command === "init") {
-    const parsed = parseCommonFlags(rest, { verbose: false });
-    if ("command" in parsed) return parsed;
-    return { command: "init", options: parsed };
-  }
-
-  if (command === "consolidate") {
-    return parseConsolidateLikeFlags(rest, "consolidate");
-  }
-
-  if (command === "maintenance") {
-    return parseConsolidateLikeFlags(rest, "maintenance");
-  }
-
-  if (command === "drain-shutdown-queue") {
-    const parsed = parseCommonFlags(rest, { verbose: false });
-    if ("command" in parsed) return parsed;
-    return { command: "drain-shutdown-queue", options: parsed };
-  }
-
-  return { command: "help", error: `Unknown command: ${command}` };
-}
-
-export const CLI_HELP = `pi-memory — standalone tools for Pi local memory
-
-Usage:
-  pi-memory init [options]
-  pi-memory status [options]
-  pi-memory maintenance [options]
-  pi-memory consolidate [options]
-  pi-memory drain-shutdown-queue [options]
-
-Commands:
-  init                    Create MEMORY.md from template when missing or empty
-  status                  Print MEMORY.md, sidecar, and vector index diagnostics
-  maintenance             Daily job: consolidate, then drain shutdown queue
-  consolidate             Run consolidate job (dedupe + optional reindex)
-  drain-shutdown-queue    Ingest durable facts from queued session shutdown metadata
-
-Options:
-  --agent-dir PATH        Memory data directory (overrides PI_MEMORY_AGENT_DIR)
-  --verbose, -v           Extra stderr output (TTY colors when supported)
-
-Consolidate / maintenance:
-  --cron                  Daily OS cron slot (passes cronFired to shouldConsolidate)
-  --force                 Run consolidate even when shouldConsolidate is false
-
-Environment:
-  PI_MEMORY_ENV_FILE        Explicit .env path
-  PI_MEMORY_AGENT_DIR       Memory data root; default ~/.pi/pi-memory-data
-  PI_MEMORY_DEBUG=1         Debug stderr logs (extension preflight + CLI)
-  NO_COLOR                  Disable chalk colors
-
-Examples:
-  pi-memory init
-  pi-memory status
-  pi-memory maintenance --cron --verbose
-  pi-memory consolidate --force --verbose
-  pi-memory drain-shutdown-queue --verbose
-`;

package/src/cli/status.ts

@@ -1,323 +0,0 @@
-import { readPiMemoryEnv, resolveEmbedDim } from "../config/env.js";
-import { DEFAULT_HASH_EMBED_DIM } from "../constants/env.js";
-import { createEmbedder } from "../adapters/embed/factory.js";
-import { fetchIndexStats, ping } from "../sidecar/client.js";
-import type { IndexStats } from "../sidecar/protocol.js";
-import { resolveSidecarPaths } from "../sidecar/paths.js";
-import { getVecStore } from "../sidecar/server/vec/store.js";
-import { createMemoryStore } from "../store/index.js";
-import type { MemoryStats } from "../store/types.js";
-import { pathExists } from "../utils/fs.js";
-
-import type { Theme } from "@earendil-works/pi-coding-agent";
-
-import type { CliLog } from "./log.js";
-import { theme } from "./theme.js";
-
-export type StatusPalette = {
-  dim: (text: string) => string;
-  ok: (text: string) => string;
-  bad: (text: string) => string;
-  warn: (text: string) => string;
-};
-
-const plainPalette: StatusPalette = {
-  dim: (text) => text,
-  ok: (text) => text,
-  bad: (text) => text,
-  warn: (text) => text,
-};
-
-export function cliStatusPalette(): StatusPalette {
-  return {
-    dim: theme.dim,
-    ok: theme.ok,
-    bad: theme.bad,
-    warn: theme.warn,
-  };
-}
-
-export function piStatusPalette(theme: Theme): StatusPalette {
-  return {
-    dim: (text) => theme.fg("dim", text),
-    ok: (text) => theme.fg("success", text),
-    bad: (text) => theme.fg("error", text),
-    warn: (text) => theme.fg("warning", text),
-  };
-}
-
-export type MemoryStatusReport = {
-  agentDir: string;
-  memory: MemoryStats;
-  sidecar: {
-    socketPath: string;
-    running: boolean;
-  };
-  vectorIndex: {
-    dbPath: string;
-    exists: boolean;
-    generation?: number;
-    chunkCount?: number;
-    embeddingProvider?: string;
-    embeddingModel?: string;
-    embeddingDim?: number;
-    /** Set when the index file exists but could not be read locally. */
-    readError?: string;
-    /** Stats came from sidecar RPC rather than opening sqlite in-process. */
-    fromSidecar?: boolean;
-  };
-  embedder: {
-    provider: string;
-    model: string;
-    dim: number;
-  };
-};
-
-function applyLocalVecStats(
-  report: MemoryStatusReport,
-  dbPath: string,
-): void {
-  const vec = getVecStore(dbPath);
-  report.vectorIndex.generation = vec.getIndexGeneration();
-  report.vectorIndex.chunkCount = vec.getChunkCount();
-  const meta = vec.getStoredEmbeddingMeta();
-  if (meta) {
-    report.vectorIndex.embeddingProvider = meta.provider;
-    report.vectorIndex.embeddingModel = meta.model;
-    report.vectorIndex.embeddingDim = meta.dim;
-  }
-}
-
-function applySidecarVecStats(report: MemoryStatusReport, stats: IndexStats): void {
-  report.vectorIndex.fromSidecar = true;
-  report.vectorIndex.generation = stats.index_generation;
-  report.vectorIndex.chunkCount = stats.chunk_count;
-  if (stats.embedding_provider && stats.embedding_model && stats.embedding_dim !== undefined) {
-    report.vectorIndex.embeddingProvider = stats.embedding_provider;
-    report.vectorIndex.embeddingModel = stats.embedding_model;
-    report.vectorIndex.embeddingDim = stats.embedding_dim;
-  }
-}
-
-function embedderMatchesIndex(report: MemoryStatusReport): boolean {
-  const { embeddingProvider, embeddingModel, embeddingDim } = report.vectorIndex;
-  if (!embeddingProvider || !embeddingModel || embeddingDim === undefined) return true;
-  return (
-    embeddingProvider === report.embedder.provider &&
-    embeddingModel === report.embedder.model &&
-    embeddingDim === report.embedder.dim
-  );
-}
-
-function resolveConfiguredEmbedder(env: ReturnType<typeof readPiMemoryEnv>): MemoryStatusReport["embedder"] {
-  try {
-    const embedder = createEmbedder(env);
-    return { provider: embedder.provider, model: embedder.model, dim: embedder.dim };
-  } catch {
-    const embedModel =
-      env.embedder === "openai"
-        ? env.openaiEmbedModel
-        : env.embedder === "ollama"
-          ? env.ollamaEmbedModel
-          : "hash/dev";
-    const dim =
-      env.embedder === "hash"
-        ? (env.embedDimOverride ?? DEFAULT_HASH_EMBED_DIM)
-        : resolveEmbedDim(embedModel, env.embedDimOverride);
-    return { provider: env.embedder, model: embedModel, dim };
-  }
-}
-
-export async function gatherMemoryStatus(agentDir: string): Promise<MemoryStatusReport> {
-  const store = createMemoryStore({ agentDir });
-  await store.ensureInitialized();
-
-  const sidecar = resolveSidecarPaths(agentDir);
-  const env = readPiMemoryEnv();
-
-  const sidecarRunning = await ping(sidecar.socketPath);
-
-  const report: MemoryStatusReport = {
-    agentDir,
-    memory: await store.getStats(),
-    sidecar: {
-      socketPath: sidecar.socketPath,
-      running: sidecarRunning,
-    },
-    vectorIndex: {
-      dbPath: sidecar.dbPath,
-      exists: pathExists(sidecar.dbPath),
-    },
-    embedder: resolveConfiguredEmbedder(env),
-  };
-
-  if (!report.vectorIndex.exists) return report;
-
-  if (sidecarRunning) {
-    const result = await fetchIndexStats(sidecar.socketPath);
-    if ("stats" in result) {
-      applySidecarVecStats(report, result.stats);
-      return report;
-    }
-    const hint = result.error.includes("unknown frame type")
-      ? "restart sidecar (reload Pi session or pi-memory)"
-      : result.error;
-    report.vectorIndex.readError = hint;
-    return report;
-  }
-
-  try {
-    applyLocalVecStats(report, sidecar.dbPath);
-  } catch (error) {
-    report.vectorIndex.readError =
-      error instanceof Error ? error.message : "unable to open vector index (start sidecar)";
-  }
-
-  return report;
-}
-
-type MemoryStatusRow = {
-  label: string;
-  value: () => string;
-};
-
-function formatVectorIndexLine(report: MemoryStatusReport): string {
-  const { generation, chunkCount, readError } = report.vectorIndex;
-  if (readError) {
-    return `(unreadable: ${readError})`;
-  }
-  if (generation === undefined || chunkCount === undefined) {
-    return "(unknown — start sidecar or run pi-memory status again)";
-  }
-  return `gen=${generation} chunks=${chunkCount}`;
-}
-
-function formatIndexEmbedderLine(report: MemoryStatusReport, palette: StatusPalette): string {
-  const { embeddingProvider, embeddingModel, embeddingDim, chunkCount, readError } = report.vectorIndex;
-  if (readError) {
-    return palette.dim("(unavailable)");
-  }
-  if (!embeddingProvider || !embeddingModel || embeddingDim === undefined) {
-    if (chunkCount === 0) {
-      return palette.dim("(empty — reindex pending)");
-    }
-    return palette.dim("(no embedding meta — run reindex)");
-  }
-
-  const label = `${embeddingProvider}/${embeddingModel} (${embeddingDim}d)`;
-  if (embedderMatchesIndex(report)) {
-    return label;
-  }
-  return palette.warn(`${label} ≠ configured`);
-}
-
-function memoryStatusRows(report: MemoryStatusReport, palette: StatusPalette = plainPalette): MemoryStatusRow[] {
-  const lastConsolidated = report.memory.lastConsolidatedAt ?? "(never)";
-  const sidecarState = report.sidecar.running ? "running" : "not reachable";
-  const sidecarDetail = `${sidecarState} (${report.sidecar.socketPath})`;
-
-  const rows: MemoryStatusRow[] = [
-    { label: "agent dir", value: () => report.agentDir },
-    { label: "MEMORY lines", value: () => String(report.memory.lineCount) },
-    { label: "entries", value: () => String(report.memory.entryCount) },
-    { label: "overflow files", value: () => String(report.memory.overflowFileCount) },
-    {
-      label: "last consolidate",
-      value: () =>
-        !report.memory.lastConsolidatedAt ? palette.dim(lastConsolidated) : lastConsolidated,
-    },
-    {
-      label: "sidecar",
-      value: () => {
-        const state = report.sidecar.running ? palette.ok(sidecarState) : palette.bad(sidecarState);
-        return `${state} ${palette.dim(`(${report.sidecar.socketPath})`)}`;
-      },
-    },
-  ];
-
-  if (!report.vectorIndex.exists) {
-    rows.push({
-      label: "vector index",
-      value: () => palette.dim("(missing — write MEMORY or start session)"),
-    });
-  } else {
-    rows.push({
-      label: "vector index",
-      value: () => {
-        const line = formatVectorIndexLine(report);
-        if (report.vectorIndex.readError) return palette.bad(line);
-        if (report.vectorIndex.generation === undefined || report.vectorIndex.chunkCount === undefined) {
-          return palette.dim(line);
-        }
-        return line;
-      },
-    });
-    rows.push({
-      label: "index embedder",
-      value: () => formatIndexEmbedderLine(report, palette),
-    });
-  }
-
-  rows.push({
-    label: "configured embedder",
-    value: () => `${report.embedder.provider}/${report.embedder.model} (${report.embedder.dim}d)`,
-  });
-
-  return rows;
-}
-
-export function formatMemoryStatusSummary(
-  report: MemoryStatusReport,
-  palette: StatusPalette,
-  accent: (text: string) => string,
-): string {
-  const parts = [
-    accent("pi-memory"),
-    palette.dim(`entries=${report.memory.entryCount}`),
-    report.sidecar.running ? palette.ok("sidecar up") : palette.bad("sidecar down"),
-  ];
-
-  if (!report.vectorIndex.exists) {
-    parts.push(palette.dim("no index"));
-  } else {
-    const vec = formatVectorIndexLine(report);
-    if (report.vectorIndex.readError) {
-      parts.push(palette.bad(vec));
-    } else if (report.vectorIndex.generation === undefined || report.vectorIndex.chunkCount === undefined) {
-      parts.push(palette.dim(vec));
-    } else {
-      parts.push(vec);
-    }
-  }
-
-  return parts.join(palette.dim(" · "));
-}
-
-export function formatMemoryStatusLines(report: MemoryStatusReport): string[] {
-  return memoryStatusRows(report).map(
-    ({ label, value }) => `${label.padEnd(16)} ${value()}`,
-  );
-}
-
-export function formatMemoryStatusTuiLines(
-  report: MemoryStatusReport,
-  palette: StatusPalette,
-  theme: Theme,
-): string[] {
-  return memoryStatusRows(report, palette).map(
-    ({ label, value }) => `${theme.fg("muted", label.padEnd(16))} ${value()}`,
-  );
-}
-
-export function printMemoryStatus(report: MemoryStatusReport, log: CliLog): void {
-  const palette = cliStatusPalette();
-  for (const { label, value } of memoryStatusRows(report, palette)) {
-    log.line(label, value());
-  }
-}
-
-export async function runStatusCommand(agentDir: string, log: CliLog): Promise<number> {
-  const report = await gatherMemoryStatus(agentDir);
-  printMemoryStatus(report, log);
-  return 0;
-}

package/src/cli/theme.ts

@@ -1,26 +0,0 @@
-import chalk from "chalk";
-
-function colorEnabled(stream: NodeJS.WriteStream = process.stderr): boolean {
-  return Boolean(stream.isTTY) && !process.env.NO_COLOR && process.env.FORCE_COLOR !== "0";
-}
-
-export function paint(
-  fn: (text: string) => string,
-  text: string,
-  stream: NodeJS.WriteStream = process.stderr,
-): string {
-  return colorEnabled(stream) ? fn(text) : text;
-}
-
-export const theme = {
-  prefix: (stream?: NodeJS.WriteStream) => paint(chalk.cyan.bold, "pi-memory", stream),
-  info: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.blue, text, stream),
-  success: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.green, text, stream),
-  warn: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.yellow, text, stream),
-  error: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.red, text, stream),
-  dim: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.dim, text, stream),
-  label: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.gray, text, stream),
-  value: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.white, text, stream),
-  ok: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.green, text, stream),
-  bad: (text: string, stream?: NodeJS.WriteStream) => paint(chalk.red, text, stream),
-};

package/src/cli.ts

@@ -1,105 +0,0 @@
-#!/usr/bin/env node
-
-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));
-    }
-    console.log(CLI_HELP);
-    return parsed.error ? 1 : 0;
-  }
-
-  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 (parsed.command === "status") {
-    const log = createCliLog({ verbose: true, debug: parsed.options.verbose });
-    return runStatusCommand(agentDir, log);
-  }
-
-  const store = createMemoryStore({ agentDir });
-  await store.ensureInitialized();
-
-  const llm = await createLlmClient();
-
-  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",
-      );
-    }
-    return runMaintenanceCommand({
-      store,
-      agentDir,
-      llm,
-      options: parsed.options,
-      log,
-    });
-  }
-
-  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");
-    }
-    return runDrainShutdownQueueCommand({
-      store,
-      agentDir,
-      llm,
-      verbose: parsed.options.verbose,
-      log,
-    });
-  }
-
-  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 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

@@ -1,20 +0,0 @@
-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),
-  });
-}