@chendpoc/pi-memory 0.1.12 → 0.2.0

package/dist/utils/socket.js

@@ -0,0 +1,35 @@
+import { chmodSync, unlinkSync } from "node:fs";
+import { secureFileMode } from "./paths.js";
+import { isUnixLike } from "./platform.js";
+/** Remove stale socket file before bind (Unix domain sockets only). */
+export function removeSocketFile(socketPath) {
+    if (!isUnixLike())
+        return;
+    try {
+        unlinkSync(socketPath);
+    }
+    catch {
+        // ENOENT or in-use; listen() will surface real errors
+    }
+}
+/** Restrict socket permissions after bind (Unix only). */
+export function secureSocketPath(socketPath) {
+    const mode = secureFileMode();
+    if (mode === undefined)
+        return;
+    chmodSync(socketPath, mode);
+}
+/** Remove socket and pid companion files on shutdown. */
+export function cleanupSocketFiles(socketPath, pidPath) {
+    for (const path of [socketPath, pidPath]) {
+        if (!path)
+            continue;
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+//# sourceMappingURL=socket.js.map

package/dist/utils/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../../src/utils/socket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,uEAAuE;AACvE,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,IAAI,CAAC,UAAU,EAAE;QAAE,OAAO;IAC1B,IAAI,CAAC;QACH,UAAU,CAAC,UAAU,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,sDAAsD;IACxD,CAAC;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,SAAS,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,kBAAkB,CAAC,UAAkB,EAAE,OAAgB;IACrE,KAAK,MAAM,IAAI,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,IAAI,CAAC;YACH,UAAU,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/utils/time.d.ts

@@ -0,0 +1,22 @@
+import { type ConfigType, type Dayjs } from "dayjs";
+export type TimeInput = ConfigType;
+/** Current local time. */
+export declare function now(): Dayjs;
+/** Unix epoch ms (deadlines, lock files, external APIs). */
+export declare function nowMs(): number;
+/** Parse stored or external input; invalid values fall back to epoch. */
+export declare function parseTime(input: TimeInput): Dayjs;
+/**
+ * Local timestamp for MEMORY entries, GC markers, shutdown queue.
+ * Format: YYYY-MM-DDTHH:mm:ss.SSS (local wall clock, no Z suffix).
+ */
+export declare function formatTimestamp(input?: TimeInput): string;
+/** Local calendar date (e.g. auto-YYYY-MM-DD-*.md). */
+export declare function formatLocalDate(input?: TimeInput): string;
+/** Fallback timestamp when entry metadata is missing. */
+export declare function epochTimestamp(): string;
+/** Whole calendar days from `from` until `to` (local; default `to` = now). */
+export declare function daysSince(from: TimeInput, to?: TimeInput): number;
+/** Milliseconds left until `deadlineMs` (default clock: now). */
+export declare function remainingMs(deadlineMs: number, atMs?: number): number;
+//# sourceMappingURL=time.d.ts.map

package/dist/utils/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,UAAU,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AAE3D,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC;AAEnC,0BAA0B;AAC1B,wBAAgB,GAAG,IAAI,KAAK,CAE3B;AAED,4DAA4D;AAC5D,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,CAGjD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAGzD;AAED,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAGzD;AAED,yDAAyD;AACzD,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAIjE;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAgB,GAAG,MAAM,CAE9E"}

package/dist/utils/time.js

@@ -0,0 +1,42 @@
+import dayjs from "dayjs";
+/** Current local time. */
+export function now() {
+    return dayjs();
+}
+/** Unix epoch ms (deadlines, lock files, external APIs). */
+export function nowMs() {
+    return dayjs().valueOf();
+}
+/** Parse stored or external input; invalid values fall back to epoch. */
+export function parseTime(input) {
+    const parsed = dayjs(input);
+    return parsed.isValid() ? parsed : dayjs(0);
+}
+/**
+ * Local timestamp for MEMORY entries, GC markers, shutdown queue.
+ * Format: YYYY-MM-DDTHH:mm:ss.SSS (local wall clock, no Z suffix).
+ */
+export function formatTimestamp(input) {
+    const t = input === undefined ? dayjs() : parseTime(input);
+    return t.format("YYYY-MM-DDTHH:mm:ss.SSS");
+}
+/** Local calendar date (e.g. auto-YYYY-MM-DD-*.md). */
+export function formatLocalDate(input) {
+    const t = input === undefined ? dayjs() : parseTime(input);
+    return t.format("YYYY-MM-DD");
+}
+/** Fallback timestamp when entry metadata is missing. */
+export function epochTimestamp() {
+    return formatTimestamp(0);
+}
+/** Whole calendar days from `from` until `to` (local; default `to` = now). */
+export function daysSince(from, to) {
+    const end = to === undefined ? dayjs() : parseTime(to);
+    const start = parseTime(from);
+    return end.startOf("day").diff(start.startOf("day"), "day");
+}
+/** Milliseconds left until `deadlineMs` (default clock: now). */
+export function remainingMs(deadlineMs, atMs = nowMs()) {
+    return Math.max(0, deadlineMs - atMs);
+}
+//# sourceMappingURL=time.js.map

package/dist/utils/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../../src/utils/time.ts"],"names":[],"mappings":"AAAA,OAAO,KAAsC,MAAM,OAAO,CAAC;AAI3D,0BAA0B;AAC1B,MAAM,UAAU,GAAG;IACjB,OAAO,KAAK,EAAE,CAAC;AACjB,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,KAAK;IACnB,OAAO,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC;AAC3B,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,SAAS,CAAC,KAAgB;IACxC,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,MAAM,CAAC,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC3D,OAAO,CAAC,CAAC,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAC7C,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,MAAM,CAAC,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC3D,OAAO,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;AAChC,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,cAAc;IAC5B,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;AAC5B,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,SAAS,CAAC,IAAe,EAAE,EAAc;IACvD,MAAM,GAAG,GAAG,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,OAAe,KAAK,EAAE;IACpE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC,CAAC;AACxC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chendpoc/pi-memory",
-  "version": "0.1.12",
-  "description": "Local episodic memory for Pi coding agent — knowledge graph + memory_recall tool + implicit preflight",
+  "version": "0.2.0",
+  "description": "Cross-session episodic memory for Pi agent — MEMORY.md ground truth, JSONL sidecar retrieval, and Preflight injection",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,22 +16,39 @@
     }
   },
   "bin": {
-    "pi-memory": "./dist/cli.js"
+    "pi-memory": "./dist/cli.js",
+    "pi-memory-sidecar": "./dist/sidecar/server/process.js"
   },
   "scripts": {
-    "build": "tsc",
+    "clean": "rm -rf dist",
+    "build": "rm -rf dist && tsc",
+    "postinstall": "node ./scripts/postinstall.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "rebuild:native": "pnpm rebuild better-sqlite3",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   },
   "files": [
     "dist",
     "src/**/*.ts",
     "!src/**/*.test.ts",
-    "README.md"
+    "templates/MEMORY.md.example",
+    "scripts/path-utils.mjs",
+    "scripts/init-memory-workspace.mjs",
+    "scripts/platform-fs.mjs",
+    "scripts/postinstall.mjs",
+    "README.md",
+    "UBIQUITOUS_LANGUAGE.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=24.0.0 <25"
   },
   "packageManager": "pnpm@10.12.1",
   "keywords": [
@@ -39,7 +56,7 @@
     "pi-extension",
     "pi-agent",
     "episodic-memory",
-    "knowledge-graph",
+    "recent-memory",
     "memory-recall"
   ],
   "license": "MIT",
@@ -58,18 +75,23 @@
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "^1.1.38"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.10.0"
   },
   "devDependencies": {
+    "@changesets/changelog-github": "^0.5.1",
+    "@changesets/cli": "^2.29.5",
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "@types/better-sqlite3": "^7.6.0",
-    "@types/node": "^22.10.0",
-    "typebox": "*",
+    "@types/lodash": "^4.17.24",
+    "@types/node": "^24.0.0",
+    "typebox": "^1.3.3",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0"
   },
@@ -77,6 +99,12 @@
     "better-sqlite3@12.11.1": true
   },
   "dependencies": {
-    "lru-cache": "^11.5.1"
+    "chalk": "^5.6.2",
+    "dayjs": "^1.11.21",
+    "dotenv": "^17.4.2",
+    "execa": "^9.6.1",
+    "lodash": "^4.18.1",
+    "lru-cache": "^11.5.1",
+    "proper-lockfile": "^4.1.2"
   }
 }

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