@chendpoc/pi-memory 0.1.12 → 0.2.0

package/src/adapters/llm/factory.ts

@@ -0,0 +1,60 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { readPiMemoryEnv, type PiMemoryEnv } from "../../config/env.js";
+import { isOllamaModelSpec, parseModelSpec } from "./modelSpec.js";
+import { createOllamaLlmClient, ollamaHealthCheck } from "./ollama.js";
+import { createOpenAICompatLlmClient, openaiCompatHealthCheck } from "./openai-compat.js";
+import { tryCreatePiLlmClient } from "./pi-ai.js";
+import { createStandaloneLlmClient } from "./standalone.js";
+import type { LlmClient } from "./types.js";
+
+export type CreateLlmClientOptions = {
+  ctx?: ExtensionContext;
+  modelSpec?: string;
+  env?: PiMemoryEnv;
+};
+
+/** Best-effort LLM client for QueryIntent / consolidate. Returns null when unavailable. */
+export async function createLlmClient(options: CreateLlmClientOptions = {}): Promise<LlmClient | null> {
+  const env = options.env ?? readPiMemoryEnv();
+  const modelSpec = options.modelSpec ?? env.helperModel;
+
+  if (options.ctx) {
+    const fromRegistry = await tryCreatePiLlmClient(options.ctx, modelSpec);
+    if (fromRegistry) return fromRegistry;
+  }
+
+  if (env.openaiCompatBaseUrl && env.openaiCompatModel) {
+    const ok = await openaiCompatHealthCheck(env.openaiCompatBaseUrl);
+    if (ok) {
+      return createOpenAICompatLlmClient({
+        baseUrl: env.openaiCompatBaseUrl,
+        model: env.openaiCompatModel,
+        apiKey: env.openaiCompatApiKey,
+        timeoutMs: env.httpTimeoutMs,
+      });
+    }
+  }
+
+  const ollamaModel = env.ollamaLlmModel ?? (isOllamaModelSpec(modelSpec) ? parseModelSpec(modelSpec).modelId : undefined);
+  if (ollamaModel) {
+    const ok = await ollamaHealthCheck(env.ollamaLlmBaseUrl);
+    if (ok) {
+      return createOllamaLlmClient({
+        baseUrl: env.ollamaLlmBaseUrl,
+        model: ollamaModel,
+        timeoutMs: env.httpTimeoutMs,
+      });
+    }
+  }
+
+  if (env.helperApiKey && modelSpec && !isOllamaModelSpec(modelSpec)) {
+    try {
+      return createStandaloneLlmClient(modelSpec, { apiKey: env.helperApiKey });
+    } catch {
+      // fall through
+    }
+  }
+
+  return null;
+}

package/src/adapters/llm/index.ts

@@ -0,0 +1,7 @@
+export { createLlmClient, type CreateLlmClientOptions } from "./factory.js";
+export { DEFAULT_HELPER_MODEL, DEFAULT_HELPER_PROVIDER, isOllamaModelSpec, parseModelSpec } from "./modelSpec.js";
+export { createOllamaLlmClient, ollamaHealthCheck } from "./ollama.js";
+export { createOpenAICompatLlmClient, openaiCompatHealthCheck } from "./openai-compat.js";
+export { createPiLlmClient } from "./pi-ai.js";
+export { createStandaloneLlmClient } from "./standalone.js";
+export type { LlmClient, OllamaLlmConfig, OpenAICompatLlmConfig } from "./types.js";

package/src/adapters/llm/modelSpec.ts

@@ -0,0 +1,39 @@
+import {
+  DEFAULT_HELPER_MODEL,
+  DEFAULT_HELPER_MODEL_SPEC,
+  DEFAULT_HELPER_PROVIDER,
+} from "../../constants/env.js";
+
+export { DEFAULT_HELPER_MODEL, DEFAULT_HELPER_PROVIDER };
+
+export type ModelSpec = {
+  provider: string;
+  modelId: string;
+};
+
+export function parseModelSpec(
+  spec: string | undefined,
+  defaultProvider = DEFAULT_HELPER_PROVIDER,
+  defaultModelId = DEFAULT_HELPER_MODEL,
+): ModelSpec {
+  if (!spec?.trim()) {
+    return { provider: defaultProvider, modelId: defaultModelId };
+  }
+
+  const trimmed = spec.trim();
+  const slash = trimmed.indexOf("/");
+  if (slash === -1) {
+    return { provider: defaultProvider, modelId: trimmed };
+  }
+
+  return {
+    provider: trimmed.slice(0, slash),
+    modelId: trimmed.slice(slash + 1),
+  };
+}
+
+export function isOllamaModelSpec(spec: string | undefined): boolean {
+  return !!spec?.trim().startsWith("ollama/");
+}
+
+export { DEFAULT_HELPER_MODEL_SPEC };

package/src/adapters/llm/ollama.ts

@@ -0,0 +1,42 @@
+import { postJson } from "../http.js";
+import type { LlmClient, OllamaLlmConfig } from "./types.js";
+
+type OllamaChatResponse = {
+  message?: { content?: string };
+  error?: string;
+};
+
+export async function ollamaHealthCheck(baseUrl: string): Promise<boolean> {
+  try {
+    const url = new URL("/api/tags", baseUrl);
+    const res = await fetch(url, { signal: AbortSignal.timeout(3_000) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export function createOllamaLlmClient(cfg: OllamaLlmConfig): LlmClient {
+  const baseUrl = cfg.baseUrl.replace(/\/$/, "");
+  const timeoutMs = cfg.timeoutMs ?? 60_000;
+
+  return {
+    async complete(prompt, signal) {
+      const resp = await postJson<OllamaChatResponse>(
+        `${baseUrl}/api/chat`,
+        {
+          model: cfg.model,
+          messages: [{ role: "user", content: prompt }],
+          stream: false,
+          options: { num_predict: 1024 },
+        },
+        { timeoutMs, signal },
+      );
+
+      if (resp.error) throw new Error(`Ollama: ${resp.error}`);
+      const text = resp.message?.content?.trim();
+      if (!text) throw new Error("Ollama: empty response");
+      return text;
+    },
+  };
+}

package/src/adapters/llm/openai-compat.ts

@@ -0,0 +1,46 @@
+import { DEFAULT_LLM_COMPAT_TIMEOUT_MS } from "../../constants/timing.js";
+import { postJson } from "../http.js";
+import type { LlmClient, OpenAICompatLlmConfig } from "./types.js";
+
+type ChatCompletionResponse = {
+  choices?: Array<{ message?: { content?: string } }>;
+  error?: { message?: string };
+};
+
+export async function openaiCompatHealthCheck(baseUrl: string): Promise<boolean> {
+  try {
+    const url = new URL("/v1/models", baseUrl);
+    const res = await fetch(url, { signal: AbortSignal.timeout(3_000) });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export function createOpenAICompatLlmClient(cfg: OpenAICompatLlmConfig): LlmClient {
+  const baseUrl = cfg.baseUrl.replace(/\/$/, "");
+  const timeoutMs = cfg.timeoutMs ?? DEFAULT_LLM_COMPAT_TIMEOUT_MS;
+
+  return {
+    async complete(prompt, signal) {
+      const resp = await postJson<ChatCompletionResponse>(
+        `${baseUrl}/v1/chat/completions`,
+        {
+          model: cfg.model,
+          messages: [{ role: "user", content: prompt }],
+          max_tokens: 1024,
+        },
+        {
+          timeoutMs,
+          signal,
+          headers: cfg.apiKey ? { Authorization: `Bearer ${cfg.apiKey}` } : undefined,
+        },
+      );
+
+      if (resp.error?.message) throw new Error(`OpenAI-compat: ${resp.error.message}`);
+      const text = resp.choices?.[0]?.message?.content?.trim();
+      if (!text) throw new Error("OpenAI-compat: empty response");
+      return text;
+    },
+  };
+}

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)}`);
+    },
+  };
+}