@betterdb/memory 0.1.0

package/src/client/model.ts

@@ -0,0 +1,281 @@
+import { Ollama } from "ollama";
+import { config } from "../config.js";
+import type { SessionSummary } from "../memory/schema.js";
+
+// --- Model Presets ---
+
+export interface ModelPreset {
+  embedModel: string;
+  summarizeModel: string;
+  embedDim: number;
+}
+
+export const PRESET_CLEAN: ModelPreset = {
+  embedModel: "mxbai-embed-large",
+  summarizeModel: "mistral:7b",
+  embedDim: 1024,
+};
+
+export const PRESET_ATTRIBUTION: ModelPreset = {
+  embedModel: "nomic-embed-text",
+  summarizeModel: "qwen2.5:7b",
+  embedDim: 768,
+};
+
+export const PRESET_LIGHTWEIGHT: ModelPreset = {
+  embedModel: "all-minilm",
+  summarizeModel: "qwen2.5:3b",
+  embedDim: 384,
+};
+
+// --- ModelClient Interface ---
+
+export interface ModelClient {
+  embed(text: string): Promise<number[]>;
+  summarize(transcript: string): Promise<SessionSummary>;
+  readonly embedDim: number;
+  readonly preset: ModelPreset;
+}
+
+// --- Composite Model Client ---
+
+export class CompositeModelClient implements ModelClient {
+  constructor(
+    private readonly embedClient: ModelClient,
+    private readonly summarizeClient: ModelClient,
+  ) {}
+
+  embed(text: string): Promise<number[]> {
+    return this.embedClient.embed(text);
+  }
+
+  summarize(transcript: string): Promise<SessionSummary> {
+    return this.summarizeClient.summarize(transcript);
+  }
+
+  get embedDim(): number {
+    return this.embedClient.embedDim;
+  }
+
+  get preset(): ModelPreset {
+    return {
+      embedModel: this.embedClient.preset.embedModel,
+      summarizeModel: this.summarizeClient.preset.summarizeModel,
+      embedDim: this.embedClient.embedDim,
+    };
+  }
+}
+
+// --- Re-exports ---
+
+export { OllamaModelClient } from "./providers/ollama.js";
+export { OpenAIEmbedClient, OpenAISummarizeClient } from "./providers/openai.js";
+export { AnthropicSummarizeClient } from "./providers/anthropic.js";
+export { VoyageEmbedClient } from "./providers/voyage.js";
+export { GroqEmbedClient, GroqSummarizeClient } from "./providers/groq.js";
+export { TogetherEmbedClient, TogetherSummarizeClient } from "./providers/together.js";
+export { buildSummarizePrompt } from "./providers/_prompt.js";
+
+// --- Provider Detection ---
+
+async function detectOllamaModels(): Promise<Set<string>> {
+  try {
+    const ollama = new Ollama({ host: config.ollama.url });
+    const listResponse = await ollama.list();
+    return new Set(listResponse.models.map((m) => m.name.split(":")[0]!));
+  } catch {
+    return new Set();
+  }
+}
+
+// --- Factory ---
+
+export async function createModelClient(): Promise<ModelClient> {
+  const p = config.providers;
+
+  const embedClient = await resolveEmbedProvider(p);
+  const summarizeClient = await resolveSummarizeProvider(p);
+
+  console.error(
+    `[betterdb] embed=${embedClient.preset.embedModel} summarize=${summarizeClient.preset.summarizeModel}`,
+  );
+
+  return new CompositeModelClient(embedClient, summarizeClient);
+}
+
+async function resolveEmbedProvider(
+  p: typeof config.providers,
+): Promise<ModelClient> {
+  // Explicit override
+  if (p.embedProvider) {
+    return createExplicitEmbedProvider(p.embedProvider, p);
+  }
+
+  // Auto-detect: Ollama first
+  const ollamaModels = await detectOllamaModels();
+  const presets = [PRESET_CLEAN, PRESET_ATTRIBUTION, PRESET_LIGHTWEIGHT];
+  for (const preset of presets) {
+    const base = preset.embedModel.split(":")[0]!;
+    if (ollamaModels.has(base)) {
+      const { OllamaModelClient } = await import("./providers/ollama.js");
+      return new OllamaModelClient(preset, config.ollama.url);
+    }
+  }
+
+  // Voyage
+  if (p.voyageKey) {
+    const { VoyageEmbedClient } = await import("./providers/voyage.js");
+    return new VoyageEmbedClient(p.voyageKey);
+  }
+
+  // OpenAI
+  if (p.openaiKey) {
+    const { OpenAIEmbedClient } = await import("./providers/openai.js");
+    return new OpenAIEmbedClient(p.openaiKey);
+  }
+
+  // Groq
+  if (p.groqKey) {
+    const { GroqEmbedClient } = await import("./providers/groq.js");
+    return new GroqEmbedClient(p.groqKey);
+  }
+
+  // Together
+  if (p.togetherKey) {
+    const { TogetherEmbedClient } = await import("./providers/together.js");
+    return new TogetherEmbedClient(p.togetherKey);
+  }
+
+  throw new Error(
+    `No embedding provider available. Options:\n` +
+      `  1. Install Ollama and run: ollama pull mxbai-embed-large\n` +
+      `  2. Set VOYAGE_API_KEY for Voyage AI (voyage-3, dim=1024)\n` +
+      `  3. Set OPENAI_API_KEY for OpenAI (text-embedding-3-small, dim=1536)\n` +
+      `  4. Set GROQ_API_KEY for Groq (nomic-embed-text-v1_5, dim=768)\n` +
+      `  5. Set TOGETHER_API_KEY for Together AI (m2-bert-80M-8k-retrieval, dim=768)\n\n` +
+      `Note: ANTHROPIC_API_KEY does not provide embeddings — pair it with another embed provider.`,
+  );
+}
+
+async function resolveSummarizeProvider(
+  p: typeof config.providers,
+): Promise<ModelClient> {
+  // Explicit override
+  if (p.summarizeProvider) {
+    return createExplicitSummarizeProvider(p.summarizeProvider, p);
+  }
+
+  // Auto-detect: Ollama first
+  const ollamaModels = await detectOllamaModels();
+  const presets = [PRESET_CLEAN, PRESET_ATTRIBUTION, PRESET_LIGHTWEIGHT];
+  for (const preset of presets) {
+    const base = preset.summarizeModel.split(":")[0]!;
+    if (ollamaModels.has(base)) {
+      const { OllamaModelClient } = await import("./providers/ollama.js");
+      return new OllamaModelClient(preset, config.ollama.url);
+    }
+  }
+
+  // Anthropic
+  if (p.anthropicKey) {
+    const { AnthropicSummarizeClient } = await import("./providers/anthropic.js");
+    return new AnthropicSummarizeClient(p.anthropicKey);
+  }
+
+  // OpenAI
+  if (p.openaiKey) {
+    const { OpenAISummarizeClient } = await import("./providers/openai.js");
+    return new OpenAISummarizeClient(p.openaiKey);
+  }
+
+  // Groq
+  if (p.groqKey) {
+    const { GroqSummarizeClient } = await import("./providers/groq.js");
+    return new GroqSummarizeClient(p.groqKey);
+  }
+
+  // Together
+  if (p.togetherKey) {
+    const { TogetherSummarizeClient } = await import("./providers/together.js");
+    return new TogetherSummarizeClient(p.togetherKey);
+  }
+
+  throw new Error(
+    `No summarization provider available. Options:\n` +
+      `  1. Install Ollama and run: ollama pull mistral:7b\n` +
+      `  2. Set ANTHROPIC_API_KEY for Anthropic (claude-haiku-4-5)\n` +
+      `  3. Set OPENAI_API_KEY for OpenAI (gpt-4o-mini)\n` +
+      `  4. Set GROQ_API_KEY for Groq (llama-3.1-8b-instant)\n` +
+      `  5. Set TOGETHER_API_KEY for Together AI (Meta-Llama-3.1-8B-Instruct-Turbo)`,
+  );
+}
+
+// --- Explicit Provider Constructors ---
+
+function createExplicitEmbedProvider(
+  name: string,
+  p: typeof config.providers,
+): ModelClient {
+  switch (name) {
+    case "ollama": {
+      const { OllamaModelClient } = require("./providers/ollama.js");
+      return new OllamaModelClient(PRESET_CLEAN, config.ollama.url);
+    }
+    case "openai": {
+      if (!p.openaiKey) throw new Error("BETTERDB_EMBED_PROVIDER=openai but OPENAI_API_KEY is not set");
+      const { OpenAIEmbedClient } = require("./providers/openai.js");
+      return new OpenAIEmbedClient(p.openaiKey);
+    }
+    case "voyage": {
+      if (!p.voyageKey) throw new Error("BETTERDB_EMBED_PROVIDER=voyage but VOYAGE_API_KEY is not set");
+      const { VoyageEmbedClient } = require("./providers/voyage.js");
+      return new VoyageEmbedClient(p.voyageKey);
+    }
+    case "groq": {
+      if (!p.groqKey) throw new Error("BETTERDB_EMBED_PROVIDER=groq but GROQ_API_KEY is not set");
+      const { GroqEmbedClient } = require("./providers/groq.js");
+      return new GroqEmbedClient(p.groqKey);
+    }
+    case "together": {
+      if (!p.togetherKey) throw new Error("BETTERDB_EMBED_PROVIDER=together but TOGETHER_API_KEY is not set");
+      const { TogetherEmbedClient } = require("./providers/together.js");
+      return new TogetherEmbedClient(p.togetherKey);
+    }
+    default:
+      throw new Error(`Unknown embed provider: ${name}. Valid: ollama, openai, voyage, groq, together`);
+  }
+}
+
+function createExplicitSummarizeProvider(
+  name: string,
+  p: typeof config.providers,
+): ModelClient {
+  switch (name) {
+    case "ollama": {
+      const { OllamaModelClient } = require("./providers/ollama.js");
+      return new OllamaModelClient(PRESET_CLEAN, config.ollama.url);
+    }
+    case "openai": {
+      if (!p.openaiKey) throw new Error("BETTERDB_SUMMARIZE_PROVIDER=openai but OPENAI_API_KEY is not set");
+      const { OpenAISummarizeClient } = require("./providers/openai.js");
+      return new OpenAISummarizeClient(p.openaiKey);
+    }
+    case "anthropic": {
+      if (!p.anthropicKey) throw new Error("BETTERDB_SUMMARIZE_PROVIDER=anthropic but ANTHROPIC_API_KEY is not set");
+      const { AnthropicSummarizeClient } = require("./providers/anthropic.js");
+      return new AnthropicSummarizeClient(p.anthropicKey);
+    }
+    case "groq": {
+      if (!p.groqKey) throw new Error("BETTERDB_SUMMARIZE_PROVIDER=groq but GROQ_API_KEY is not set");
+      const { GroqSummarizeClient } = require("./providers/groq.js");
+      return new GroqSummarizeClient(p.groqKey);
+    }
+    case "together": {
+      if (!p.togetherKey) throw new Error("BETTERDB_SUMMARIZE_PROVIDER=together but TOGETHER_API_KEY is not set");
+      const { TogetherSummarizeClient } = require("./providers/together.js");
+      return new TogetherSummarizeClient(p.togetherKey);
+    }
+    default:
+      throw new Error(`Unknown summarize provider: ${name}. Valid: ollama, openai, anthropic, groq, together`);
+  }
+}

package/src/client/providers/_prompt.ts

@@ -0,0 +1,35 @@
+/**
+ * Strip markdown code fences that LLMs sometimes wrap around JSON output.
+ */
+export function stripCodeFences(text: string): string {
+  return text.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "").trim();
+}
+
+/**
+ * Shared summarization prompt used by all providers.
+ * Ensures consistent structured data extraction regardless of which model runs it.
+ */
+export const buildSummarizePrompt = (transcript: string): string =>
+  `
+You are extracting structured data from a Claude Code session transcript.
+Return ONLY valid JSON matching this exact structure, with no explanation:
+{
+  "decisions": [],
+  "patterns": [],
+  "problemsSolved": [],
+  "openThreads": [],
+  "filesChanged": [],
+  "oneLineSummary": ""
+}
+
+Fields:
+- decisions: max 10 specific technical decisions made
+- patterns: max 5 reusable approaches or code patterns used
+- problemsSolved: max 5 objects with "problem" and "resolution" keys
+- openThreads: max 5 unresolved questions or TODOs discovered
+- filesChanged: all file paths modified or created
+- oneLineSummary: single sentence — what did this session accomplish?
+
+Transcript:
+${transcript}
+`.trim();

package/src/client/providers/anthropic.ts

@@ -0,0 +1,70 @@
+import { SessionSummarySchema, type SessionSummary } from "../../memory/schema.js";
+import type { ModelClient, ModelPreset } from "../model.js";
+import { buildSummarizePrompt, stripCodeFences } from "./_prompt.js";
+
+interface AnthropicClient {
+  messages: {
+    create(params: {
+      model: string;
+      max_tokens: number;
+      messages: Array<{ role: string; content: string }>;
+    }): Promise<{
+      content: Array<{ type: string; text?: string }>;
+    }>;
+  };
+}
+
+export class AnthropicSummarizeClient implements ModelClient {
+  private client: AnthropicClient | null = null;
+  private apiKey: string;
+  readonly embedDim = 0;
+  readonly preset: ModelPreset = {
+    embedModel: "n/a",
+    summarizeModel: "claude-haiku-4-5",
+    embedDim: 0,
+  };
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  private async getClient(): Promise<AnthropicClient> {
+    if (!this.client) {
+      const { default: Anthropic } = await import("@anthropic-ai/sdk");
+      this.client = new Anthropic({ apiKey: this.apiKey }) as unknown as AnthropicClient;
+    }
+    return this.client;
+  }
+
+  async embed(_text: string): Promise<number[]> {
+    throw new Error(
+      "Anthropic does not provide embeddings — configure a separate embed provider",
+    );
+  }
+
+  async summarize(transcript: string): Promise<SessionSummary> {
+    const client = await this.getClient();
+    const response = await client.messages.create({
+      model: "claude-haiku-4-5",
+      max_tokens: 2048,
+      messages: [
+        { role: "user", content: buildSummarizePrompt(transcript) },
+      ],
+    });
+
+    const textBlock = response.content.find((b) => b.type === "text");
+    const content = textBlock?.text;
+    if (!content) {
+      console.error("[betterdb] Anthropic summarization returned empty response");
+      return SessionSummarySchema.parse({});
+    }
+
+    const parsed = SessionSummarySchema.safeParse(JSON.parse(stripCodeFences(content)));
+    if (!parsed.success) {
+      console.error("[betterdb] Failed to parse Anthropic summarization:", parsed.error.message);
+      return SessionSummarySchema.parse({});
+    }
+
+    return parsed.data;
+  }
+}

package/src/client/providers/groq.ts

@@ -0,0 +1,102 @@
+import { SessionSummarySchema, type SessionSummary } from "../../memory/schema.js";
+import type { ModelClient, ModelPreset } from "../model.js";
+import { buildSummarizePrompt, stripCodeFences } from "./_prompt.js";
+import { createOpenAI, type OpenAIClient } from "./openai.js";
+
+export class GroqEmbedClient implements ModelClient {
+  private client: OpenAIClient | null = null;
+  private apiKey: string;
+  readonly embedDim = 768;
+  readonly preset: ModelPreset = {
+    embedModel: "nomic-embed-text-v1_5",
+    summarizeModel: "n/a",
+    embedDim: 768,
+  };
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  private async getClient(): Promise<OpenAIClient> {
+    if (!this.client) {
+      this.client = await createOpenAI(this.apiKey, "https://api.groq.com/openai/v1");
+    }
+    return this.client;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const client = await this.getClient();
+    try {
+      const response = await client.embeddings.create({
+        model: "nomic-embed-text-v1_5",
+        input: text,
+      });
+      const first = response.data[0];
+      if (!first) {
+        throw new Error("Groq embed returned no embeddings");
+      }
+      return first.embedding;
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (message.includes("404") || message.includes("not found")) {
+        throw new Error("Groq embedding API unavailable — try a different embed provider");
+      }
+      throw err;
+    }
+  }
+
+  async summarize(_transcript: string): Promise<SessionSummary> {
+    throw new Error("GroqEmbedClient does not support summarization — use GroqSummarizeClient");
+  }
+}
+
+export class GroqSummarizeClient implements ModelClient {
+  private client: OpenAIClient | null = null;
+  private apiKey: string;
+  readonly embedDim = 0;
+  readonly preset: ModelPreset = {
+    embedModel: "n/a",
+    summarizeModel: "llama-3.1-8b-instant",
+    embedDim: 0,
+  };
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  private async getClient(): Promise<OpenAIClient> {
+    if (!this.client) {
+      this.client = await createOpenAI(this.apiKey, "https://api.groq.com/openai/v1");
+    }
+    return this.client;
+  }
+
+  async embed(_text: string): Promise<number[]> {
+    throw new Error("GroqSummarizeClient does not support embedding — use GroqEmbedClient");
+  }
+
+  async summarize(transcript: string): Promise<SessionSummary> {
+    const client = await this.getClient();
+    const response = await client.chat.completions.create({
+      model: "llama-3.1-8b-instant",
+      messages: [
+        { role: "user", content: buildSummarizePrompt(transcript) },
+      ],
+      response_format: { type: "json_object" },
+    });
+
+    const content = response.choices[0]?.message.content;
+    if (!content) {
+      console.error("[betterdb] Groq summarization returned empty response");
+      return SessionSummarySchema.parse({});
+    }
+
+    const parsed = SessionSummarySchema.safeParse(JSON.parse(stripCodeFences(content)));
+    if (!parsed.success) {
+      console.error("[betterdb] Failed to parse Groq summarization:", parsed.error.message);
+      return SessionSummarySchema.parse({});
+    }
+
+    return parsed.data;
+  }
+}

package/src/client/providers/ollama.ts

@@ -0,0 +1,53 @@
+import { Ollama } from "ollama";
+import { config } from "../../config.js";
+import { SessionSummarySchema, type SessionSummary } from "../../memory/schema.js";
+import type { ModelClient, ModelPreset } from "../model.js";
+import { buildSummarizePrompt, stripCodeFences } from "./_prompt.js";
+
+export class OllamaModelClient implements ModelClient {
+  private ollama: Ollama;
+  readonly preset: ModelPreset;
+  readonly embedDim: number;
+
+  constructor(preset: ModelPreset, ollamaUrl?: string) {
+    this.ollama = new Ollama({ host: ollamaUrl ?? config.ollama.url });
+    this.preset = preset;
+    this.embedDim = preset.embedDim;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const response = await this.ollama.embed({
+      model: this.preset.embedModel,
+      input: text,
+    });
+    const first = response.embeddings[0];
+    if (!first) {
+      throw new Error("Ollama embed returned no embeddings");
+    }
+    return first;
+  }
+
+  async summarize(transcript: string): Promise<SessionSummary> {
+    const response = await this.ollama.chat({
+      model: this.preset.summarizeModel,
+      messages: [
+        { role: "user", content: buildSummarizePrompt(transcript) },
+      ],
+      format: "json",
+    });
+
+    const parsed = SessionSummarySchema.safeParse(
+      JSON.parse(stripCodeFences(response.message.content)),
+    );
+
+    if (!parsed.success) {
+      console.error(
+        "[betterdb] Failed to parse Ollama summarization response:",
+        parsed.error.message,
+      );
+      return SessionSummarySchema.parse({});
+    }
+
+    return parsed.data;
+  }
+}

package/src/client/providers/openai.ts

@@ -0,0 +1,125 @@
+import { SessionSummarySchema, type SessionSummary } from "../../memory/schema.js";
+import type { ModelClient, ModelPreset } from "../model.js";
+import { buildSummarizePrompt, stripCodeFences } from "./_prompt.js";
+
+interface OpenAIClient {
+  embeddings: {
+    create(params: {
+      model: string;
+      input: string;
+    }): Promise<{ data: Array<{ embedding: number[] }> }>;
+  };
+  chat: {
+    completions: {
+      create(params: {
+        model: string;
+        messages: Array<{ role: string; content: string }>;
+        response_format: { type: string };
+      }): Promise<{
+        choices: Array<{ message: { content: string | null } }>;
+      }>;
+    };
+  };
+}
+
+async function createOpenAI(apiKey: string, baseURL?: string): Promise<OpenAIClient> {
+  // @ts-expect-error — openai is an optional dependency, lazy-loaded
+  const { default: OpenAI } = await import("openai");
+  return new (OpenAI as new (opts: { apiKey: string; baseURL?: string }) => OpenAIClient)({
+    apiKey,
+    ...(baseURL ? { baseURL } : {}),
+  });
+}
+
+export class OpenAIEmbedClient implements ModelClient {
+  private client: OpenAIClient | null = null;
+  private apiKey: string;
+  readonly embedDim = 1536;
+  readonly preset: ModelPreset = {
+    embedModel: "text-embedding-3-small",
+    summarizeModel: "n/a",
+    embedDim: 1536,
+  };
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  private async getClient(): Promise<OpenAIClient> {
+    if (!this.client) {
+      this.client = await createOpenAI(this.apiKey);
+    }
+    return this.client;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const client = await this.getClient();
+    const response = await client.embeddings.create({
+      model: "text-embedding-3-small",
+      input: text,
+    });
+    const first = response.data[0];
+    if (!first) {
+      throw new Error("OpenAI embed returned no embeddings");
+    }
+    return first.embedding;
+  }
+
+  async summarize(_transcript: string): Promise<SessionSummary> {
+    throw new Error("OpenAIEmbedClient does not support summarization — use OpenAISummarizeClient");
+  }
+}
+
+export class OpenAISummarizeClient implements ModelClient {
+  private client: OpenAIClient | null = null;
+  private apiKey: string;
+  readonly embedDim = 0;
+  readonly preset: ModelPreset = {
+    embedModel: "n/a",
+    summarizeModel: "gpt-4o-mini",
+    embedDim: 0,
+  };
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  private async getClient(): Promise<OpenAIClient> {
+    if (!this.client) {
+      this.client = await createOpenAI(this.apiKey);
+    }
+    return this.client;
+  }
+
+  async embed(_text: string): Promise<number[]> {
+    throw new Error("OpenAISummarizeClient does not support embedding — use OpenAIEmbedClient");
+  }
+
+  async summarize(transcript: string): Promise<SessionSummary> {
+    const client = await this.getClient();
+    const response = await client.chat.completions.create({
+      model: "gpt-4o-mini",
+      messages: [
+        { role: "user", content: buildSummarizePrompt(transcript) },
+      ],
+      response_format: { type: "json_object" },
+    });
+
+    const content = response.choices[0]?.message.content;
+    if (!content) {
+      console.error("[betterdb] OpenAI summarization returned empty response");
+      return SessionSummarySchema.parse({});
+    }
+
+    const parsed = SessionSummarySchema.safeParse(JSON.parse(stripCodeFences(content)));
+    if (!parsed.success) {
+      console.error("[betterdb] Failed to parse OpenAI summarization:", parsed.error.message);
+      return SessionSummarySchema.parse({});
+    }
+
+    return parsed.data;
+  }
+}
+
+// Re-export the helper for Groq and Together providers
+export { createOpenAI, type OpenAIClient };