@betterdb/memory 0.1.0

package/src/client/providers/together.ts

@@ -0,0 +1,94 @@
+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 TogetherEmbedClient implements ModelClient {
+  private client: OpenAIClient | null = null;
+  private apiKey: string;
+  readonly embedDim = 768;
+  readonly preset: ModelPreset = {
+    embedModel: "togethercomputer/m2-bert-80M-8k-retrieval",
+    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.together.xyz/v1");
+    }
+    return this.client;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const client = await this.getClient();
+    const response = await client.embeddings.create({
+      model: "togethercomputer/m2-bert-80M-8k-retrieval",
+      input: text,
+    });
+    const first = response.data[0];
+    if (!first) {
+      throw new Error("Together AI embed returned no embeddings");
+    }
+    return first.embedding;
+  }
+
+  async summarize(_transcript: string): Promise<SessionSummary> {
+    throw new Error("TogetherEmbedClient does not support summarization — use TogetherSummarizeClient");
+  }
+}
+
+export class TogetherSummarizeClient implements ModelClient {
+  private client: OpenAIClient | null = null;
+  private apiKey: string;
+  readonly embedDim = 0;
+  readonly preset: ModelPreset = {
+    embedModel: "n/a",
+    summarizeModel: "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
+    embedDim: 0,
+  };
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  private async getClient(): Promise<OpenAIClient> {
+    if (!this.client) {
+      this.client = await createOpenAI(this.apiKey, "https://api.together.xyz/v1");
+    }
+    return this.client;
+  }
+
+  async embed(_text: string): Promise<number[]> {
+    throw new Error("TogetherSummarizeClient does not support embedding — use TogetherEmbedClient");
+  }
+
+  async summarize(transcript: string): Promise<SessionSummary> {
+    const client = await this.getClient();
+    const response = await client.chat.completions.create({
+      model: "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
+      messages: [
+        { role: "user", content: buildSummarizePrompt(transcript) },
+      ],
+      response_format: { type: "json_object" },
+    });
+
+    const content = response.choices[0]?.message.content;
+    if (!content) {
+      console.error("[betterdb] Together AI summarization returned empty response");
+      return SessionSummarySchema.parse({});
+    }
+
+    const parsed = SessionSummarySchema.safeParse(JSON.parse(stripCodeFences(content)));
+    if (!parsed.success) {
+      console.error("[betterdb] Failed to parse Together AI summarization:", parsed.error.message);
+      return SessionSummarySchema.parse({});
+    }
+
+    return parsed.data;
+  }
+}

package/src/client/providers/voyage.ts

@@ -0,0 +1,46 @@
+import type { SessionSummary } from "../../memory/schema.js";
+import type { ModelClient, ModelPreset } from "../model.js";
+
+interface VoyageEmbedResponse {
+  data: Array<{ embedding: number[] }>;
+}
+
+export class VoyageEmbedClient implements ModelClient {
+  private apiKey: string;
+  readonly embedDim = 1024;
+  readonly preset: ModelPreset = {
+    embedModel: "voyage-3",
+    summarizeModel: "n/a",
+    embedDim: 1024,
+  };
+
+  constructor(apiKey: string) {
+    this.apiKey = apiKey;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const response = await fetch("https://api.voyageai.com/v1/embeddings", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ model: "voyage-3", input: [text] }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Voyage API error: ${response.status} ${response.statusText}`);
+    }
+
+    const data = (await response.json()) as VoyageEmbedResponse;
+    const first = data.data[0];
+    if (!first) {
+      throw new Error("Voyage embed returned no embeddings");
+    }
+    return first.embedding;
+  }
+
+  async summarize(_transcript: string): Promise<SessionSummary> {
+    throw new Error("Voyage AI does not provide summarization — configure a separate summarize provider");
+  }
+}

package/src/client/valkey.ts

@@ -0,0 +1,448 @@
+import Redis from "iovalkey";
+import { config } from "../config.js";
+import {
+  EpisodicMemorySchema,
+  KnowledgeEntrySchema,
+  type EpisodicMemory,
+  type KnowledgeEntry,
+} from "../memory/schema.js";
+
+// --- Embedding Serialization ---
+
+export function embeddingToBuffer(embedding: number[]): Buffer {
+  const buf = Buffer.allocUnsafe(embedding.length * 4);
+  embedding.forEach((v, i) => buf.writeFloatLE(v, i * 4));
+  return buf;
+}
+
+export function bufferToEmbedding(buf: Buffer): number[] {
+  return Array.from(
+    { length: buf.length / 4 },
+    (_, i) => buf.readFloatLE(i * 4),
+  );
+}
+
+// --- Valkey Client ---
+
+export class ValkeyClient {
+  private client: Redis;
+
+  constructor(client: Redis) {
+    this.client = client;
+  }
+
+  // --- Index Management ---
+
+  async assertEmbedDim(expectedDim: number, providerLabel?: string): Promise<void> {
+    const stored = await this.client.get("betterdb:meta:embedDim");
+    const storedProvider = await this.client.get("betterdb:meta:embedProvider");
+    if (stored === null) {
+      await this.client.set("betterdb:meta:embedDim", String(expectedDim));
+      if (providerLabel) {
+        await this.client.set("betterdb:meta:embedProvider", providerLabel);
+      }
+      return;
+    }
+    if (Number(stored) !== expectedDim) {
+      const storedLabel = storedProvider ? ` (${storedProvider})` : "";
+      const currentLabel = providerLabel ? ` (${providerLabel})` : "";
+      throw new Error(
+        `Embedding dimension mismatch: index was built with dim=${stored}${storedLabel}, ` +
+          `but current provider produces dim=${expectedDim}${currentLabel}. ` +
+          `Run 'bun run migrate-embeddings' to re-embed all memories.`,
+      );
+    }
+    // Update provider label if it changed but dim is the same
+    if (providerLabel && providerLabel !== storedProvider) {
+      await this.client.set("betterdb:meta:embedProvider", providerLabel);
+    }
+  }
+
+  async ensureIndex(embedDim: number, providerLabel?: string): Promise<void> {
+    await this.assertEmbedDim(embedDim, providerLabel);
+
+    try {
+      await this.client.call(
+        "FT.CREATE",
+        config.valkey.indexName,
+        "ON",
+        "HASH",
+        "PREFIX",
+        "1",
+        "betterdb:memory:",
+        "SCHEMA",
+        "embedding",
+        "VECTOR",
+        "HNSW",
+        "6",
+        "TYPE",
+        "FLOAT32",
+        "DIM",
+        String(embedDim),
+        "DISTANCE_METRIC",
+        "COSINE",
+        "project",
+        "TAG",
+        "branch",
+        "TAG",
+        "oneLineSummary",
+        "TAG",
+        "importanceScore",
+        "NUMERIC",
+        "timestamp",
+        "NUMERIC",
+        "accessCount",
+        "NUMERIC",
+      );
+    } catch (err: unknown) {
+      const message = err instanceof Error
+        ? err.message
+        : String(err);
+      if (message.includes("already exists")) {
+        return;
+      }
+      throw err;
+    }
+  }
+
+  async dropIndex(): Promise<void> {
+    try {
+      await this.client.call("FT.DROPINDEX", config.valkey.indexName);
+    } catch {
+      // Index may not exist
+    }
+  }
+
+  // --- Memory CRUD ---
+
+  async storeMemory(
+    memory: EpisodicMemory,
+    embedding: number[],
+  ): Promise<string> {
+    const key = `betterdb:memory:${memory.memoryId}`;
+    const timestampNum = new Date(memory.timestamp).getTime();
+
+    await this.client.hset(key, {
+      memoryId: memory.memoryId,
+      project: memory.project,
+      branch: memory.branch,
+      timestamp: String(timestampNum),
+      summary: JSON.stringify(memory.summary),
+      oneLineSummary: memory.summary.oneLineSummary,
+      importanceScore: String(memory.importanceScore),
+      accessCount: String(memory.accessCount),
+      lastAccessed: memory.lastAccessed,
+      embedding: embeddingToBuffer(embedding),
+    });
+
+    return memory.memoryId;
+  }
+
+  async getMemory(memoryId: string): Promise<EpisodicMemory | null> {
+    const key = `betterdb:memory:${memoryId}`;
+    const data = await this.client.hgetall(key);
+
+    if (!data || Object.keys(data).length === 0) {
+      return null;
+    }
+
+    return this.parseMemoryHash(data);
+  }
+
+  async getMemoryEmbedding(memoryId: string): Promise<number[] | null> {
+    const key = `betterdb:memory:${memoryId}`;
+    const raw = await this.client.hgetBuffer(key, "embedding");
+    if (!raw) return null;
+    return bufferToEmbedding(raw);
+  }
+
+  async updateImportance(memoryId: string, score: number): Promise<void> {
+    const key = `betterdb:memory:${memoryId}`;
+    await this.client.hset(key, "importanceScore", String(score));
+  }
+
+  async incrementAccess(memoryId: string): Promise<void> {
+    const key = `betterdb:memory:${memoryId}`;
+    await this.client.hincrby(key, "accessCount", 1);
+    await this.client.hset(key, "lastAccessed", new Date().toISOString());
+  }
+
+  async deleteMemory(memoryId: string): Promise<void> {
+    const key = `betterdb:memory:${memoryId}`;
+    await this.client.del(key);
+  }
+
+  async listMemoryIds(
+    project?: string,
+    minImportance?: number,
+  ): Promise<string[]> {
+    const ids: string[] = [];
+    let cursor = "0";
+
+    do {
+      const [nextCursor, keys] = await this.client.scan(
+        cursor,
+        "MATCH",
+        "betterdb:memory:*",
+        "COUNT",
+        "100",
+      );
+      cursor = nextCursor;
+
+      for (const key of keys) {
+        // Skip keys that don't look like memory content hashes
+        const memoryId = key.replace("betterdb:memory:", "");
+        if (!memoryId || memoryId.includes(":")) continue;
+
+        if (project || minImportance !== undefined) {
+          const data = await this.client.hmget(
+            key,
+            "project",
+            "importanceScore",
+          );
+          const [proj, importance] = data;
+
+          if (project && proj !== project) continue;
+          if (
+            minImportance !== undefined &&
+            Number(importance ?? 0) < minImportance
+          ) {
+            continue;
+          }
+        }
+
+        ids.push(memoryId);
+      }
+    } while (cursor !== "0");
+
+    return ids;
+  }
+
+  // --- Search ---
+
+  async searchMemories(
+    embedding: number[],
+    project: string,
+    topK: number,
+  ): Promise<EpisodicMemory[]> {
+    const buf = embeddingToBuffer(embedding);
+
+    const result = (await this.client.call(
+      "FT.SEARCH",
+      config.valkey.indexName,
+      `@project:{${project.replace(/[^a-zA-Z0-9_-]/g, "\\$&")}}=>[KNN ${topK} @embedding $vec AS score]`,
+      "PARAMS",
+      "2",
+      "vec",
+      buf,
+      "DIALECT",
+      "2",
+    )) as unknown[];
+
+    return this.parseSearchResults(result);
+  }
+
+  // --- Knowledge ---
+
+  async storeKnowledge(entry: KnowledgeEntry): Promise<void> {
+    const key = `betterdb:knowledge:${entry.project}:${entry.topic}`;
+    await this.client.hset(key, {
+      entryId: entry.entryId,
+      project: entry.project,
+      topic: entry.topic,
+      fact: entry.fact,
+      confidence: String(entry.confidence),
+      sourceMemoryIds: JSON.stringify(entry.sourceMemoryIds),
+      lastUpdated: entry.lastUpdated,
+      accessCount: String(entry.accessCount),
+    });
+
+    await this.client.zadd(
+      `betterdb:knowledge:${entry.project}:index`,
+      Date.now(),
+      entry.topic,
+    );
+  }
+
+  async listKnowledge(project: string): Promise<KnowledgeEntry[]> {
+    const topics = await this.client.zrevrange(
+      `betterdb:knowledge:${project}:index`,
+      0,
+      -1,
+    );
+
+    const entries: KnowledgeEntry[] = [];
+    for (const topic of topics) {
+      const key = `betterdb:knowledge:${project}:${topic}`;
+      const data = await this.client.hgetall(key);
+      if (!data || Object.keys(data).length === 0) continue;
+
+      const parsed = KnowledgeEntrySchema.safeParse({
+        ...data,
+        confidence: Number(data["confidence"] ?? 0),
+        accessCount: Number(data["accessCount"] ?? 0),
+        sourceMemoryIds: JSON.parse(data["sourceMemoryIds"] ?? "[]"),
+      });
+
+      if (parsed.success) {
+        entries.push(parsed.data);
+      }
+    }
+
+    return entries;
+  }
+
+  // --- Queues ---
+
+  async pushCompressQueue(memoryId: string): Promise<void> {
+    await this.client.rpush("betterdb:compress_queue", memoryId);
+  }
+
+  async popCompressQueue(count: number): Promise<string[]> {
+    const items: string[] = [];
+    for (let i = 0; i < count; i++) {
+      const item = await this.client.lpop("betterdb:compress_queue");
+      if (!item) break;
+      items.push(item);
+    }
+    return items;
+  }
+
+  async pushIngestQueue(
+    rawTranscript: string,
+    sessionMeta: object,
+  ): Promise<void> {
+    await this.client.rpush(
+      "betterdb:ingest_queue",
+      JSON.stringify({ transcript: rawTranscript, meta: sessionMeta }),
+    );
+  }
+
+  async popIngestQueue(
+    count: number,
+  ): Promise<Array<{ transcript: string; meta: Record<string, unknown> }>> {
+    const items: Array<{
+      transcript: string;
+      meta: Record<string, unknown>;
+    }> = [];
+    for (let i = 0; i < count; i++) {
+      const raw = await this.client.lpop("betterdb:ingest_queue");
+      if (!raw) break;
+      items.push(JSON.parse(raw));
+    }
+    return items;
+  }
+
+  // --- Aging Metadata ---
+
+  async getLastAgingRun(): Promise<Date | null> {
+    const stored = await this.client.get("betterdb:meta:lastAgingRun");
+    if (!stored) return null;
+    return new Date(stored);
+  }
+
+  async setLastAgingRun(timestamp: Date): Promise<void> {
+    await this.client.set(
+      "betterdb:meta:lastAgingRun",
+      timestamp.toISOString(),
+    );
+  }
+
+  // --- Lifecycle ---
+
+  async quit(): Promise<void> {
+    await this.client.quit();
+  }
+
+  // --- Internal Helpers ---
+
+  private parseMemoryHash(
+    data: Record<string, string>,
+  ): EpisodicMemory | null {
+    try {
+      const timestamp = data["timestamp"];
+      const parsed = EpisodicMemorySchema.safeParse({
+        memoryId: data["memoryId"],
+        project: data["project"],
+        branch: data["branch"],
+        timestamp: timestamp
+          ? new Date(Number(timestamp)).toISOString()
+          : new Date().toISOString(),
+        summary: JSON.parse(data["summary"] ?? "{}"),
+        importanceScore: Number(data["importanceScore"] ?? 0),
+        accessCount: Number(data["accessCount"] ?? 0),
+        lastAccessed:
+          data["lastAccessed"] ?? new Date().toISOString(),
+      });
+
+      return parsed.success ? parsed.data : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private parseSearchResults(result: unknown[]): EpisodicMemory[] {
+    if (!Array.isArray(result) || result.length < 1) return [];
+
+    const totalCount = result[0] as number;
+    if (totalCount === 0) return [];
+
+    const memories: EpisodicMemory[] = [];
+
+    // FT.SEARCH returns: [count, key1, [field1, val1, ...], key2, ...]
+    for (let i = 1; i < result.length; i += 2) {
+      const fields = result[i + 1] as string[] | undefined;
+      if (!Array.isArray(fields)) continue;
+
+      const data: Record<string, string> = {};
+      for (let j = 0; j < fields.length; j += 2) {
+        const key = fields[j];
+        const val = fields[j + 1];
+        if (typeof key === "string" && typeof val === "string") {
+          data[key] = val;
+        }
+      }
+
+      const memory = this.parseMemoryHash(data);
+      if (memory) {
+        memories.push(memory);
+      }
+    }
+
+    return memories;
+  }
+}
+
+// --- Singleton Factory ---
+
+let clientInstance: ValkeyClient | null = null;
+
+export async function getValkeyClient(): Promise<ValkeyClient> {
+  if (clientInstance) return clientInstance;
+
+  const retryDelays = [100, 500, 2000];
+  let lastError: Error | null = null;
+
+  for (const delay of retryDelays) {
+    try {
+      const redis = new Redis(config.valkey.url, {
+        maxRetriesPerRequest: 3,
+        lazyConnect: true,
+      });
+      await redis.connect();
+      clientInstance = new ValkeyClient(redis);
+      return clientInstance;
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+
+  throw new Error(
+    `Failed to connect to Valkey at ${config.valkey.url} after 3 attempts: ${lastError?.message}`,
+  );
+}
+
+export function resetValkeyClient(): void {
+  clientInstance = null;
+}

package/src/config.ts

@@ -0,0 +1,67 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Load saved config from ~/.betterdb/memory.json as fallback for env vars.
+ * This allows compiled binaries (hooks, MCP server) to work without
+ * requiring env vars to be set — config is saved during `install`.
+ */
+const _fileConfig: Record<string, string> = (() => {
+  const home = process.env["HOME"] ?? process.env["USERPROFILE"] ?? "";
+  const p = join(home, ".betterdb", "memory.json");
+  if (!existsSync(p)) return {};
+  try {
+    const data: unknown = JSON.parse(readFileSync(p, "utf-8"));
+    if (typeof data !== "object" || data === null) return {};
+    const result: Record<string, string> = {};
+    for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+      if (typeof v === "string") result[k] = v;
+      else if (typeof v === "number") result[k] = String(v);
+    }
+    return result;
+  } catch {
+    return {};
+  }
+})();
+
+/** Read a config value: env var takes priority, then ~/.betterdb/memory.json. */
+function env(key: string): string | undefined {
+  return Bun.env[key] ?? _fileConfig[key];
+}
+
+export const config = {
+  valkey: {
+    url: env("BETTERDB_VALKEY_URL") ?? "redis://localhost:6379",
+    indexName: env("BETTERDB_VALKEY_INDEX_NAME") ?? "betterdb-memory-index",
+  },
+  ollama: {
+    url: env("BETTERDB_OLLAMA_URL") ?? "http://localhost:11434",
+    embedModel: env("BETTERDB_EMBED_MODEL") ?? "mxbai-embed-large",
+    summarizeModel: env("BETTERDB_SUMMARIZE_MODEL") ?? "mistral:7b",
+    embedDim: Number(env("BETTERDB_EMBED_DIM") ?? 1024),
+  },
+  memory: {
+    maxContextMemories: Number(env("BETTERDB_MAX_CONTEXT_MEMORIES") ?? 5),
+    decayRate: Number(env("BETTERDB_DECAY_RATE") ?? 0.95),
+    compressThreshold: Number(env("BETTERDB_COMPRESS_THRESHOLD") ?? 0.3),
+    distillMinSessions: Number(env("BETTERDB_DISTILL_MIN_SESSIONS") ?? 5),
+    contextFile: env("BETTERDB_CONTEXT_FILE") ?? ".betterdb_context.md",
+    agingIntervalHours: Number(env("BETTERDB_AGING_INTERVAL_HOURS") ?? 6),
+  },
+  allowRemoteFallback: env("BETTERDB_ALLOW_REMOTE_FALLBACK") !== "false",
+  providers: {
+    embedProvider: env("BETTERDB_EMBED_PROVIDER") as
+      | "ollama" | "openai" | "voyage" | "groq" | "together"
+      | undefined,
+    summarizeProvider: env("BETTERDB_SUMMARIZE_PROVIDER") as
+      | "ollama" | "openai" | "anthropic" | "groq" | "together"
+      | undefined,
+    openaiKey: env("OPENAI_API_KEY"),
+    anthropicKey: env("ANTHROPIC_API_KEY"),
+    voyageKey: env("VOYAGE_API_KEY"),
+    groqKey: env("GROQ_API_KEY"),
+    togetherKey: env("TOGETHER_API_KEY"),
+  },
+} as const;
+
+export type Config = typeof config;

package/src/hooks/_utils.ts

@@ -0,0 +1,53 @@
+import type { HookPayload } from "../memory/schema.js";
+import { HookPayloadSchema } from "../memory/schema.js";
+
+/**
+ * Read and parse hook payload from stdin.
+ * Claude Code sends JSON on stdin for command hooks.
+ */
+export async function readPayload(): Promise<HookPayload> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of Bun.stdin.stream()) {
+    chunks.push(Buffer.from(chunk));
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) {
+    throw new Error("No payload received on stdin");
+  }
+  const json = JSON.parse(raw);
+  return HookPayloadSchema.parse(json);
+}
+
+/**
+ * Read raw JSON from stdin without schema validation.
+ * Used when the hook needs partial fields from a payload
+ * that may not match the discriminated union.
+ */
+export async function readRawPayload(): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of Bun.stdin.stream()) {
+    chunks.push(Buffer.from(chunk));
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) {
+    throw new Error("No payload received on stdin");
+  }
+  return JSON.parse(raw);
+}
+
+/**
+ * Safe wrapper for hook execution.
+ * Catches all errors → stderr. Always exits 0 to never crash Claude Code.
+ */
+export async function runHook(fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn();
+    process.exit(0);
+  } catch (err) {
+    console.error(
+      "[betterdb]",
+      err instanceof Error ? err.message : String(err),
+    );
+    process.exit(0); // Always exit 0 — never block Claude Code
+  }
+}