@chendpoc/pi-memory 0.1.13 → 0.2.0

package/src/adapters/llm/pi-ai.ts

@@ -0,0 +1,75 @@
+import { complete } from "@earendil-works/pi-ai/compat";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { nowMs } from "../../utils/time.js";
+import type { LlmClient } from "./types.js";
+import { extractTextFromResponse } from "./extractText.js";
+import { parseModelSpec } from "./modelSpec.js";
+
+async function resolveModelAuth(ctx: ExtensionContext, provider: string, modelId: string) {
+  const model = ctx.modelRegistry.find(provider, modelId);
+  if (!model) return null;
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok || !auth.apiKey) return null;
+
+  return {
+    model,
+    apiKey: auth.apiKey,
+    headers: auth.headers,
+    env: auth.env,
+  };
+}
+
+export async function tryCreatePiLlmClient(
+  ctx: ExtensionContext,
+  modelSpec?: string,
+): Promise<LlmClient | null> {
+  const { provider, modelId } = parseModelSpec(modelSpec);
+  const model = ctx.modelRegistry.find(provider, modelId);
+  if (!model) return null;
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok || !auth.apiKey) return null;
+
+  return createPiLlmClient(ctx, modelSpec);
+}
+
+export function createPiLlmClient(ctx: ExtensionContext, modelSpec?: string): LlmClient {
+  const { provider, modelId } = parseModelSpec(modelSpec);
+
+  return {
+    async complete(prompt, signal) {
+      const resolved = await resolveModelAuth(ctx, provider, modelId);
+      if (!resolved) {
+        throw new Error(`LLM model not available: ${provider}/${modelId}`);
+      }
+
+      const response = await complete(
+        resolved.model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: prompt }],
+              timestamp: nowMs(),
+            },
+          ],
+        },
+        {
+          apiKey: resolved.apiKey,
+          headers: resolved.headers,
+          env: resolved.env,
+          maxTokens: 1024,
+          signal,
+        },
+      );
+
+      const text = extractTextFromResponse(response.content);
+      if (!text.trim()) {
+        throw new Error("LLM response was empty");
+      }
+      return text;
+    },
+  };
+}

package/src/adapters/llm/standalone.ts

@@ -0,0 +1,60 @@
+import pickBy from "lodash/pickBy.js";
+
+import { complete, getEnvApiKey, getModels } from "@earendil-works/pi-ai/compat";
+
+import { nowMs } from "../../utils/time.js";
+
+import type { LlmClient } from "./types.js";
+import { extractTextFromResponse } from "./extractText.js";
+import { parseModelSpec } from "./modelSpec.js";
+
+function toProviderEnv(env: NodeJS.ProcessEnv): Record<string, string> {
+  return pickBy(env, (value): value is string => value !== undefined);
+}
+
+export function createStandaloneLlmClient(
+  modelSpec: string,
+  options: { apiKey?: string; env?: NodeJS.ProcessEnv } = {},
+): LlmClient {
+  const { provider, modelId } = parseModelSpec(modelSpec);
+  const providerEnv = toProviderEnv(options.env ?? process.env);
+  type ProviderArg = Parameters<typeof getModels>[0];
+  const model = getModels(provider as ProviderArg).find((item) => item.id === modelId);
+  if (!model) {
+    throw new Error(`Model not found: ${provider}/${modelId}`);
+  }
+
+  const apiKey = options.apiKey ?? getEnvApiKey(provider, providerEnv);
+  if (!apiKey) {
+    throw new Error(`No API key for ${provider}`);
+  }
+
+  return {
+    async complete(prompt, signal) {
+      const response = await complete(
+        model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: prompt }],
+              timestamp: nowMs(),
+            },
+          ],
+        },
+        {
+          apiKey,
+          maxTokens: 1024,
+          env: providerEnv,
+          signal,
+        },
+      );
+
+      const text = extractTextFromResponse(response.content);
+      if (!text.trim()) {
+        throw new Error("LLM response was empty");
+      }
+      return text;
+    },
+  };
+}

package/src/adapters/llm/types.ts

@@ -0,0 +1,16 @@
+export type LlmClient = {
+  complete(prompt: string, signal?: AbortSignal): Promise<string>;
+};
+
+export type OllamaLlmConfig = {
+  baseUrl: string;
+  model: string;
+  timeoutMs?: number;
+};
+
+export type OpenAICompatLlmConfig = {
+  baseUrl: string;
+  model: string;
+  apiKey?: string;
+  timeoutMs?: number;
+};

package/src/cli/init.ts

@@ -0,0 +1,18 @@
+import { initializeMemoryWorkspace } from "../init/workspace.js";
+
+import type { CliLog } from "./log.js";
+
+export async function runInitCommand(agentDir: string, log: CliLog): Promise<number> {
+  const result = await initializeMemoryWorkspace(agentDir);
+
+  log.line("agent dir", result.agentDir);
+  log.line("memory file", result.memoryFile);
+
+  if (result.skipped) {
+    log.warn("MEMORY.md already exists (left unchanged)");
+    return 0;
+  }
+
+  log.success("Created MEMORY.md from pi-memory template");
+  return 0;
+}

package/src/cli/jobs.ts

@@ -0,0 +1,144 @@
+import type { CliLog } from "./log.js";
+import { runConsolidateJob } from "../consolidate/runJob.js";
+import { runDrainShutdownQueueJob } from "../shutdown/runDrainJob.js";
+import type { LlmClient } from "../adapters/llm/types.js";
+import type { MemoryStore } from "../store/memoryStore.js";
+
+export type MaintenanceCliOptions = {
+  cron: boolean;
+  force: boolean;
+  verbose: boolean;
+};
+
+export async function runMaintenanceCommand(opts: {
+  store: MemoryStore;
+  agentDir: string;
+  llm: LlmClient | null;
+  options: MaintenanceCliOptions;
+  log: CliLog;
+}): Promise<number> {
+  const { store, agentDir, llm, options, log } = opts;
+
+  log.debug(`maintenance agentDir=${agentDir} cron=${options.cron} force=${options.force}`);
+
+  log.line("step", "consolidate");
+  const consolidateResult = await runConsolidateJob({
+    store,
+    agentDir,
+    llm,
+    cronFired: options.cron,
+    force: options.force,
+  });
+
+  switch (consolidateResult.status) {
+    case "skipped":
+      log.warn("consolidate skipped (conditions not met)");
+      break;
+    case "consolidated":
+      log.success("consolidate complete");
+      if (options.verbose) {
+        log.line("entries", `${consolidateResult.stats.entriesBefore} → ${consolidateResult.stats.entriesAfter}`);
+        log.line(
+          "overflow files",
+          `${consolidateResult.stats.overflowBefore} → ${consolidateResult.stats.overflowAfter}`,
+        );
+      }
+      break;
+    case "failed":
+      log.error(`consolidate failed: ${consolidateResult.error.message}`);
+      return 1;
+  }
+
+  log.line("step", "drain-shutdown-queue");
+  const drainResult = await runDrainShutdownQueueJob({ store, agentDir, llm });
+
+  switch (drainResult.status) {
+    case "empty":
+      log.warn("shutdown queue empty");
+      return 0;
+    case "drained":
+      log.success("shutdown queue drained");
+      if (options.verbose) {
+        log.line("queued sessions", String(drainResult.stats.queued));
+        log.line("ingested sessions", String(drainResult.stats.ingested));
+        log.line("skipped sessions", String(drainResult.stats.skipped));
+        log.line("appended entries", String(drainResult.stats.appended));
+        if (drainResult.stats.indexGeneration !== undefined) {
+          log.line("index generation", String(drainResult.stats.indexGeneration));
+        }
+      }
+      return 0;
+    case "failed":
+      log.error(`shutdown queue drain failed: ${drainResult.error.message}`);
+      return 1;
+  }
+}
+
+export async function runDrainShutdownQueueCommand(opts: {
+  store: MemoryStore;
+  agentDir: string;
+  llm: LlmClient | null;
+  verbose: boolean;
+  log: CliLog;
+}): Promise<number> {
+  const result = await runDrainShutdownQueueJob({
+    store: opts.store,
+    agentDir: opts.agentDir,
+    llm: opts.llm,
+  });
+
+  switch (result.status) {
+    case "empty":
+      opts.log.warn("shutdown queue empty");
+      return 0;
+    case "drained":
+      opts.log.success("shutdown queue drained");
+      if (opts.verbose) {
+        opts.log.line("queued sessions", String(result.stats.queued));
+        opts.log.line("ingested sessions", String(result.stats.ingested));
+        opts.log.line("skipped sessions", String(result.stats.skipped));
+        opts.log.line("appended entries", String(result.stats.appended));
+      }
+      return 0;
+    case "failed":
+      opts.log.error(`shutdown queue drain failed: ${result.error.message}`);
+      return 1;
+  }
+}
+
+export async function runConsolidateCommand(opts: {
+  store: MemoryStore;
+  agentDir: string;
+  llm: LlmClient | null;
+  cron: boolean;
+  force: boolean;
+  verbose: boolean;
+  log: CliLog;
+}): Promise<number> {
+  const result = await runConsolidateJob({
+    store: opts.store,
+    agentDir: opts.agentDir,
+    llm: opts.llm,
+    cronFired: opts.cron,
+    force: opts.force,
+  });
+
+  switch (result.status) {
+    case "skipped":
+      opts.log.warn("consolidate skipped (conditions not met)");
+      return 0;
+    case "consolidated":
+      opts.log.success("consolidate complete");
+      if (opts.verbose) {
+        opts.log.line("entries", `${result.stats.entriesBefore} → ${result.stats.entriesAfter}`);
+        opts.log.line(
+          "overflow files",
+          `${result.stats.overflowBefore} → ${result.stats.overflowAfter}`,
+        );
+      }
+      return 0;
+    case "failed":
+      opts.log.error(`consolidate failed: ${result.error.message}`);
+      return 1;
+  }
+}

package/src/cli/log.ts

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

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