@chendpoc/pi-memory 0.1.13 → 0.2.0

package/scripts/init-memory-workspace.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * postinstall: seed MEMORY.md in the memory agent dir when missing or empty.
+ */
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { config } from "dotenv";
+
+import {
+  ensureDir,
+  joinPath,
+  readText,
+  writeText,
+} from "./platform-fs.mjs";
+import { expandHomePath } from "./path-utils.mjs";
+
+const packageRoot = joinPath(dirname(fileURLToPath(import.meta.url)), "..");
+
+function resolveMemoryAgentDir(env) {
+  const fromMemory = env.PI_MEMORY_AGENT_DIR?.trim();
+  if (fromMemory) return expandHomePath(fromMemory);
+  return joinPath(homedir(), CONFIG_DIR_NAME, "pi-memory-data");
+}
+
+async function loadEnvFiles() {
+  const paths = [
+    joinPath(process.cwd(), ".env"),
+    joinPath(process.cwd(), ".env.local"),
+    joinPath(homedir(), CONFIG_DIR_NAME, "agent", "pi-memory.env"),
+  ];
+  if (process.env.PI_MEMORY_ENV_FILE?.trim()) {
+    paths.unshift(process.env.PI_MEMORY_ENV_FILE.trim());
+  }
+  for (const path of paths) {
+    try {
+      await readFile(expandHomePath(path), "utf8");
+      config({ path: expandHomePath(path), override: false, quiet: true });
+    } catch {
+      // missing file
+    }
+  }
+}
+
+async function main() {
+  await loadEnvFiles();
+  const agentDir = resolveMemoryAgentDir(process.env);
+  const memoryFile = joinPath(agentDir, "MEMORY.md");
+
+  const existing = await readText(memoryFile);
+  if (existing.trim()) return;
+
+  const template = await readText(joinPath(packageRoot, "templates", "MEMORY.md.example"));
+  await ensureDir(agentDir);
+  await writeText(memoryFile, template);
+}
+
+main().catch(() => {
+  process.exitCode = 0;
+});

package/scripts/path-utils.mjs

@@ -0,0 +1,12 @@
+/** Postinstall mirror of src/utils/paths.ts expandHomePath — keep in sync. */
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function expandHomePath(input) {
+  const trimmed = input.trim();
+  if (trimmed === "~") return homedir();
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+    return join(homedir(), trimmed.slice(2));
+  }
+  return trimmed;
+}

package/scripts/platform-fs.mjs

@@ -0,0 +1,65 @@
+/**
+ * Postinstall-safe fs helpers when dist/ is not built yet.
+ * Path expansion: scripts/path-utils.mjs expandHomePath (mirrors src/utils/paths.ts).
+ * After build, scripts/postinstall.mjs prefers `pi-memory init` (compiled src/utils/fs.ts).
+ */
+import { expandHomePath } from "./path-utils.mjs";
+import { mkdirSync } from "node:fs";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+export { expandHomePath };
+
+export function joinPath(...segments) {
+  return join(...segments);
+}
+
+export function pathDirname(filePath) {
+  return dirname(filePath);
+}
+
+export function isWindows() {
+  return process.platform === "win32";
+}
+
+export function mkdirOptions() {
+  if (isWindows()) return { recursive: true };
+  return { recursive: true, mode: 0o700 };
+}
+
+export function isENOENT(error) {
+  return error?.code === "ENOENT";
+}
+
+export async function ensureDir(dirPath) {
+  await mkdir(expandHomePath(dirPath), mkdirOptions());
+}
+
+export function ensureDirSync(dirPath) {
+  mkdirSync(expandHomePath(dirPath), mkdirOptions());
+}
+
+export async function readText(filePath) {
+  try {
+    return await readFile(expandHomePath(filePath), "utf8");
+  } catch (error) {
+    if (isENOENT(error)) return "";
+    throw error;
+  }
+}
+
+export async function writeText(filePath, content) {
+  const resolved = expandHomePath(filePath);
+  await ensureDir(dirname(resolved));
+  await writeFile(resolved, content, "utf8");
+}
+
+export async function appendText(filePath, content) {
+  const resolved = expandHomePath(filePath);
+  await ensureDir(dirname(resolved));
+  await appendFile(resolved, content, "utf8");
+}
+
+export function pathBasename(filePath) {
+  return basename(filePath);
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Prefer compiled `pi-memory init` when dist exists; otherwise pre-build JS fallback.
+ */
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const cli = join(packageRoot, "dist", "cli.js");
+
+if (existsSync(cli)) {
+  spawnSync(process.execPath, [cli, "init"], { cwd: packageRoot, stdio: "ignore" });
+} else {
+  await import("./init-memory-workspace.mjs");
+}

package/src/adapters/embed/factory.ts

@@ -0,0 +1,50 @@
+import { DEFAULT_HASH_EMBED_DIM } from "../../constants/env.js";
+import { readPiMemoryEnv, resolveEmbedDim } from "../../config/env.js";
+import { createHashEmbedder } from "./hash.js";
+import { createOllamaEmbedder } from "./ollama.js";
+import { createOpenAiEmbedder } from "./openai.js";
+import type { Embedder } from "./types.js";
+
+let cachedEmbedder: Embedder | undefined;
+
+export function createEmbedder(env = readPiMemoryEnv()): Embedder {
+  switch (env.embedder) {
+    case "openai": {
+      if (!env.openaiApiKey) {
+        throw new Error("PI_MEMORY_EMBEDDER=openai requires PI_MEMORY_OPENAI_API_KEY or OPENAI_API_KEY");
+      }
+      const dim = resolveEmbedDim(env.openaiEmbedModel, env.embedDimOverride);
+      return createOpenAiEmbedder({
+        apiKey: env.openaiApiKey,
+        model: env.openaiEmbedModel,
+        dim,
+        timeoutMs: env.httpTimeoutMs,
+      });
+    }
+    case "ollama": {
+      const dim = resolveEmbedDim(env.ollamaEmbedModel, env.embedDimOverride);
+      return createOllamaEmbedder({
+        baseUrl: env.ollamaBaseUrl,
+        model: env.ollamaEmbedModel,
+        dim,
+        timeoutMs: env.httpTimeoutMs,
+      });
+    }
+    default: {
+      const dim = env.embedDimOverride ?? DEFAULT_HASH_EMBED_DIM;
+      return createHashEmbedder(dim);
+    }
+  }
+}
+
+export function getEmbedder(): Embedder {
+  cachedEmbedder ??= createEmbedder();
+  return cachedEmbedder;
+}
+
+/** @internal test hook */
+export function resetEmbedderForTests(): void {
+  cachedEmbedder = undefined;
+}
+
+export type { Embedder } from "./types.js";

package/src/adapters/embed/hash.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+
+import type { Embedder } from "./types.js";
+import { normalizeEmbedding } from "./normalize.js";
+
+export function createHashEmbedder(dim: number): Embedder {
+  const embedSync = (text: string): Float32Array => {
+    const vec = new Float32Array(dim);
+    const digest = createHash("sha256").update(text).digest();
+    for (let i = 0; i < dim; i++) {
+      const byte = digest[i % digest.length]!;
+      const sign = digest[(i + 7) % digest.length]! & 1 ? 1 : -1;
+      vec[i] = sign * (byte / 255);
+    }
+    return normalizeEmbedding(vec);
+  };
+
+  return {
+    provider: "hash",
+    model: "hash/dev",
+    dim,
+    async embed(text) {
+      return embedSync(text);
+    },
+    async embedBatch(texts) {
+      return texts.map(embedSync);
+    },
+  };
+}

package/src/adapters/embed/normalize.ts

@@ -0,0 +1,13 @@
+export function normalizeEmbedding(vec: Float32Array): Float32Array {
+  let norm = 0;
+  for (let i = 0; i < vec.length; i++) norm += vec[i]! * vec[i]!;
+  norm = Math.sqrt(norm) || 1;
+  for (let i = 0; i < vec.length; i++) vec[i]! /= norm;
+  return vec;
+}
+
+export function assertEmbeddingDim(embedding: Float32Array, expectedDim: number, label: string): void {
+  if (embedding.length !== expectedDim) {
+    throw new Error(`${label} dimension mismatch: expected ${expectedDim}, got ${embedding.length}`);
+  }
+}

package/src/adapters/embed/ollama.ts

@@ -0,0 +1,49 @@
+import { postJson } from "../http.js";
+import { assertEmbeddingDim, normalizeEmbedding } from "./normalize.js";
+import type { Embedder } from "./types.js";
+
+type OllamaEmbedResponse = {
+  model: string;
+  embeddings: number[][];
+};
+
+function joinUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}${path}`;
+}
+
+export function createOllamaEmbedder(opts: {
+  baseUrl: string;
+  model: string;
+  dim: number;
+  timeoutMs: number;
+}): Embedder {
+  const url = joinUrl(opts.baseUrl, "/api/embed");
+
+  const embedRemote = async (texts: string[]): Promise<Float32Array[]> => {
+    const json = await postJson<OllamaEmbedResponse>(
+      url,
+      { model: opts.model, input: texts.length === 1 ? texts[0] : texts },
+      { timeoutMs: opts.timeoutMs },
+    );
+
+    return json.embeddings.map((row, index) => {
+      const embedding = normalizeEmbedding(new Float32Array(row));
+      assertEmbeddingDim(embedding, opts.dim, `Ollama ${opts.model} row ${index}`);
+      return embedding;
+    });
+  };
+
+  return {
+    provider: "ollama",
+    model: opts.model,
+    dim: opts.dim,
+    async embed(text) {
+      const [embedding] = await embedRemote([text]);
+      return embedding!;
+    },
+    async embedBatch(texts) {
+      if (texts.length === 0) return [];
+      return embedRemote(texts);
+    },
+  };
+}

package/src/adapters/embed/openai.ts

@@ -0,0 +1,46 @@
+import { postJson } from "../http.js";
+import { assertEmbeddingDim, normalizeEmbedding } from "./normalize.js";
+import type { Embedder } from "./types.js";
+
+type OpenAiEmbedResponse = {
+  data: Array<{ embedding: number[]; index: number }>;
+};
+
+export function createOpenAiEmbedder(opts: {
+  apiKey: string;
+  model: string;
+  dim: number;
+  timeoutMs: number;
+}): Embedder {
+  const embedRemote = async (texts: string[]): Promise<Float32Array[]> => {
+    const json = await postJson<OpenAiEmbedResponse>(
+      "https://api.openai.com/v1/embeddings",
+      { model: opts.model, input: texts },
+      {
+        headers: { Authorization: `Bearer ${opts.apiKey}` },
+        timeoutMs: opts.timeoutMs,
+      },
+    );
+
+    return json.data
+      .sort((a, b) => a.index - b.index)
+      .map((row) => {
+        const embedding = normalizeEmbedding(new Float32Array(row.embedding));
+        assertEmbeddingDim(embedding, opts.dim, `OpenAI ${opts.model}`);
+        return embedding;
+      });
+  };
+
+  return {
+    provider: "openai",
+    model: opts.model,
+    dim: opts.dim,
+    async embed(text) {
+      const [embedding] = await embedRemote([text]);
+      return embedding!;
+    },
+    async embedBatch(texts) {
+      return embedRemote(texts);
+    },
+  };
+}

package/src/adapters/embed/types.ts

@@ -0,0 +1,9 @@
+import type { EmbedderProvider } from "../../config/env.js";
+
+export type Embedder = {
+  provider: EmbedderProvider;
+  model: string;
+  dim: number;
+  embed(text: string): Promise<Float32Array>;
+  embedBatch(texts: string[]): Promise<Float32Array[]>;
+};

package/src/adapters/http.ts

@@ -0,0 +1,42 @@
+export type PostJsonOptions = {
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+};
+
+export class HttpRequestError extends Error {
+  constructor(
+    readonly url: string,
+    readonly status: number,
+    readonly body: string,
+  ) {
+    super(`${url} failed (${status}): ${body}`);
+    this.name = "HttpRequestError";
+  }
+}
+
+export async function postJson<T>(
+  url: string,
+  body: unknown,
+  opts: PostJsonOptions = {},
+): Promise<T> {
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  const signal = opts.signal ?? AbortSignal.timeout(timeoutMs);
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...opts.headers,
+    },
+    body: JSON.stringify(body),
+    signal,
+  });
+
+  const text = await res.text();
+  if (!res.ok) {
+    throw new HttpRequestError(url, res.status, text);
+  }
+
+  return JSON.parse(text) as T;
+}

package/src/adapters/index.ts

@@ -0,0 +1,16 @@
+export { HttpRequestError, postJson, type PostJsonOptions } from "./http.js";
+export {
+  createEmbedder,
+  getEmbedder,
+  resetEmbedderForTests,
+  type Embedder,
+} from "./embed/factory.js";
+export {
+  createLlmClient,
+  createOllamaLlmClient,
+  createOpenAICompatLlmClient,
+  createPiLlmClient,
+  createStandaloneLlmClient,
+  parseModelSpec,
+  type LlmClient,
+} from "./llm/index.js";

package/src/adapters/llm/extractText.ts

@@ -0,0 +1,6 @@
+export function extractTextFromResponse(content: Array<{ type: string; text?: string }>): string {
+  return content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text ?? "")
+    .join("\n");
+}

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