@betterdb/memory 0.2.0 → 0.4.1

package/src/client/providers/local.ts

@@ -0,0 +1,58 @@
+import type { SessionSummary } from "../../memory/schema.js";
+import type { ModelClient, ModelPreset } from "../model.js";
+
+// On-device embeddings via @xenova/transformers — no API key, no running
+// service. Weights (all-MiniLM-L6-v2, Apache-2.0, 384-dim) download once on
+// first use and are cached under the transformers cache dir thereafter.
+
+const MODEL_ID = "Xenova/all-MiniLM-L6-v2";
+const EMBED_DIM = 384;
+
+type FeatureExtractor = (
+  text: string,
+  options: { pooling: "mean"; normalize: boolean },
+) => Promise<{ data: Float32Array }>;
+
+interface TransformersModule {
+  pipeline(
+    task: "feature-extraction",
+    model: string,
+  ): Promise<FeatureExtractor>;
+}
+
+// Lazy singleton: the model loads once and is reused across embed calls, and
+// @xenova/transformers is only imported when local embeddings are actually used.
+let extractorPromise: Promise<FeatureExtractor> | null = null;
+
+function getExtractor(): Promise<FeatureExtractor> {
+  if (!extractorPromise) {
+    extractorPromise = import("@xenova/transformers").then((mod) =>
+      (mod as unknown as TransformersModule).pipeline(
+        "feature-extraction",
+        MODEL_ID,
+      ),
+    );
+  }
+  return extractorPromise;
+}
+
+export class LocalEmbedClient implements ModelClient {
+  readonly embedDim = EMBED_DIM;
+  readonly preset: ModelPreset = {
+    embedModel: MODEL_ID,
+    summarizeModel: "n/a",
+    embedDim: EMBED_DIM,
+  };
+
+  async embed(text: string): Promise<number[]> {
+    const extract = await getExtractor();
+    const output = await extract(text, { pooling: "mean", normalize: true });
+    return Array.from(output.data);
+  }
+
+  async summarize(_transcript: string): Promise<SessionSummary> {
+    throw new Error(
+      "Local embeddings provider does not summarize — configure a summarize provider (Ollama, Anthropic, OpenAI, Groq, or Together)",
+    );
+  }
+}

package/src/client/valkey.ts

@@ -31,6 +31,15 @@ export class ValkeyClient {
     this.client = client;
   }
 
+  /**
+   * The underlying iovalkey connection. Exposed so the episodic-vector path
+   * (PluginMemoryStore) can share this single connection instead of opening a
+   * second one — its `.call()` satisfies MemoryStoreClient.
+   */
+  get redis(): Redis {
+    return this.client;
+  }
+
   // --- Index Management ---
 
   async assertEmbedDim(expectedDim: number, providerLabel?: string): Promise<void> {

package/src/config.ts

@@ -46,16 +46,39 @@ export const config = {
   },
   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),
   },
+  recall: {
+    // Relative gate — model-agnostic (embed models compress cosine similarity
+    // into different bands, so absolute thresholds don't transfer). `floor`
+    // drops genuine noise and loosens the store's own distance gate; `margin`
+    // keeps hits within that similarity of the top match; `separation` is the
+    // top-vs-next gap above which a result is "high" confidence.
+    floor: Number(env("BETTERDB_RECALL_FLOOR") ?? 0.5),
+    margin: Number(env("BETTERDB_RECALL_MARGIN") ?? 0.05),
+    separation: Number(env("BETTERDB_RECALL_SEPARATION") ?? 0.04),
+    // Over-fetch pool sizes: rung-1 (project) and rung-2/3 (wider / cross).
+    poolK: Number(env("BETTERDB_RECALL_POOL_K") ?? 10),
+    poolKWide: Number(env("BETTERDB_RECALL_POOL_K_WIDE") ?? 20),
+    // Allow the ladder / search_context to fall back to cross-project scope.
+    allowCrossProject: env("BETTERDB_ALLOW_CROSS_PROJECT") !== "false",
+    // Composite recall scoring, owned by @betterdb/agent-memory: a weighted
+    // blend of semantic similarity, recency (half-life decay), and importance.
+    // Recency is the ONE time-decay in the system — it replaces the old, unused
+    // per-day `decayRate`. `halfLifeDays` is the age at which a memory's recency
+    // term halves; weights (defaults match the store's) blend the three terms.
+    halfLifeDays: Number(env("BETTERDB_RECALL_HALF_LIFE_DAYS") ?? 7),
+    weightSimilarity: Number(env("BETTERDB_RECALL_WEIGHT_SIMILARITY") ?? 0.6),
+    weightRecency: Number(env("BETTERDB_RECALL_WEIGHT_RECENCY") ?? 0.25),
+    weightImportance: Number(env("BETTERDB_RECALL_WEIGHT_IMPORTANCE") ?? 0.15),
+  },
   allowRemoteFallback: env("BETTERDB_ALLOW_REMOTE_FALLBACK") !== "false",
   providers: {
     embedProvider: env("BETTERDB_EMBED_PROVIDER") as
-      | "ollama" | "openai" | "voyage" | "groq" | "together"
+      | "local" | "ollama" | "openai" | "voyage" | "groq" | "together"
       | undefined,
     summarizeProvider: env("BETTERDB_SUMMARIZE_PROVIDER") as
       | "ollama" | "openai" | "anthropic" | "groq" | "together"

package/src/hooks/pre-tool.ts

@@ -1,5 +1,6 @@
 import { readRawPayload, runHook } from "./_utils.js";
-import { getValkeyClient } from "../client/valkey.js";
+import { getPluginMemoryStore } from "../client/memory-store.js";
+import { getCwdProject } from "../memory/capture.js";
 import { config, isConfigured } from "../config.js";
 
 /**
@@ -23,21 +24,20 @@ runHook(async () => {
 
   if (!filePath) return;
 
-  let valkeyClient;
+  let store;
   try {
-    valkeyClient = await getValkeyClient();
+    store = await getPluginMemoryStore();
   } catch {
     return; // Valkey unavailable — skip silently
   }
 
-  // Scan for memories that reference this file
-  const memoryIds = await valkeyClient.listMemoryIds();
+  // Scan the current project's recent memories for ones that reference this
+  // file. Scope to the project and cap at 50 so this stays cheap on every tool
+  // call instead of materializing the whole store.
+  const memories = await store.listMemories(getCwdProject(), undefined, 50);
   const relevantNotes: string[] = [];
 
-  for (const id of memoryIds.slice(0, 50)) {
-    const memory = await valkeyClient.getMemory(id);
-    if (!memory) continue;
-
+  for (const memory of memories) {
     if (memory.summary.filesChanged.some((f) => f.includes(filePath) || filePath.includes(f))) {
       relevantNotes.push(
         `- ${memory.summary.oneLineSummary} (${memory.timestamp.split("T")[0]})`,
@@ -56,5 +56,5 @@ runHook(async () => {
     await Bun.write(config.memory.contextFile, existing + note);
   }
 
-  await valkeyClient.quit();
+  await store.close();
 });

package/src/hooks/session-end.ts

@@ -1,5 +1,6 @@
 import { readRawPayload, runHook } from "./_utils.js";
 import { getValkeyClient } from "../client/valkey.js";
+import { getPluginMemoryStore } from "../client/memory-store.js";
 import { createModelClient } from "../client/model.js";
 import {
   SessionCapture,
@@ -110,7 +111,6 @@ runHook(async () => {
 
   const summary = await modelClient.summarize(transcript);
   const importance = computeInitialImportance(summary);
-  const embedding = await modelClient.embed(summary.oneLineSummary);
 
   const memory: EpisodicMemory = {
     memoryId: crypto.randomUUID(),
@@ -123,7 +123,9 @@ runHook(async () => {
     lastAccessed: new Date().toISOString(),
   };
 
-  await valkeyClient.storeMemory(memory, embedding);
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  await store.storeMemory(memory);
+  await store.close();
   await valkeyClient.quit();
   await cleanup(eventFilePath);
 });

package/src/hooks/session-start.ts

@@ -1,8 +1,9 @@
 import { readRawPayload, runHook } from "./_utils.js";
-import { getValkeyClient } from "../client/valkey.js";
+import { getPluginMemoryStore } from "../client/memory-store.js";
 import { createModelClient } from "../client/model.js";
-import { SessionCapture } from "../memory/capture.js";
-import { MemoryRetriever, formatForInjection } from "../memory/retrieval.js";
+import { SessionCapture, getGitBranch } from "../memory/capture.js";
+import { formatForInjection } from "../memory/retrieval.js";
+import { escalatingRecall } from "../memory/recall.js";
 import { config, isConfigured } from "../config.js";
 
 /**
@@ -28,21 +29,32 @@ runHook(async () => {
     process.chdir(cwd);
   }
 
-  let valkeyClient;
+  const modelClient = await createModelClient();
+
+  let store;
   try {
-    valkeyClient = await getValkeyClient();
+    store = await getPluginMemoryStore((t) => modelClient.embed(t));
   } catch {
     return; // Valkey unreachable — skip silently
   }
 
-  const modelClient = await createModelClient();
-
   const capture = new SessionCapture();
   const queryContext = await capture.getQueryContext();
 
-  const retriever = new MemoryRetriever(valkeyClient, modelClient);
   const project = queryContext.split("\n")[0]?.replace("Project: ", "") ?? "unknown";
-  const memories = await retriever.retrieve(queryContext, project);
+  const branch = getGitBranch();
+  // Project+branch-scoped, threshold-gated recall (no cross-project auto-inject
+  // at startup — nothing to consent to yet). Only memories clearing the
+  // relevance bar are injected, so we stop padding context with irrelevant
+  // top-N filler.
+  const result = await escalatingRecall(store, queryContext, {
+    project,
+    ...(branch !== "unknown" ? { branch } : {}),
+    crossProjectRequested: false,
+  });
+  const memories = result.hits
+    .slice(0, config.memory.maxContextMemories)
+    .map((h) => h.memory);
 
   if (memories.length > 0) {
     const formatted = formatForInjection(memories);
@@ -52,5 +64,5 @@ runHook(async () => {
     process.stdout.write(formatted);
   }
 
-  await valkeyClient.quit();
+  await store.close();
 });

package/src/index.ts

@@ -13,7 +13,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 
-const VERSION = "0.1.0";
+const VERSION = "0.4.1";
 const HOME = process.env["HOME"] ?? process.env["USERPROFILE"] ?? "";
 const BETTERDB_DIR = join(HOME, ".betterdb");
 const BIN_DIR = join(BETTERDB_DIR, "bin");
@@ -36,12 +36,19 @@ Usage:
   betterdb-memory <command>
 
 Commands:
-  install        Compile binaries, register hooks + MCP server
-  uninstall      Remove hooks, MCP server, and compiled binaries
-  status         Check health of Valkey and model providers
-  maintain       Run aging/compression pipeline manually
-  docker-valkey  Manage Docker Valkey container [start|stop|status|remove]
-  version        Print version
+  install          Compile binaries, register hooks + MCP server
+  uninstall        Remove hooks, MCP server, and compiled binaries
+  status           Check health of Valkey and model providers
+  maintain         Run aging/consolidation pipeline manually
+  forget           Bulk-delete memories by scope (dry run; pass --apply)
+                   Flags: --project <name> (default: cwd) | --all-projects
+                          --branch <name> --tags <a,b> --apply
+  migrate          Move legacy betterdb:memory:* memories into the MemoryStore
+                   (dry run; pass --apply to perform)
+  ingest-claude-md Ingest a CLAUDE.md / MEMORY.md file into the store [path]
+  setup-index      Create the episodic vector index (recovery after install)
+  docker-valkey    Manage Docker Valkey container [start|stop|status|remove]
+  version          Print version
 
 Environment:
   BETTERDB_VALKEY_URL   Valkey connection (default: redis://localhost:6379)
@@ -64,6 +71,18 @@ switch (command) {
   case "maintain":
     await runMaintain();
     break;
+  case "forget":
+    await runForget(process.argv.slice(3));
+    break;
+  case "migrate":
+    await runMigrate(process.argv.includes("--apply"));
+    break;
+  case "ingest-claude-md":
+    await runIngestClaudeMd(process.argv[3]);
+    break;
+  case "setup-index":
+    await runSetupIndex();
+    break;
   case "docker-valkey": {
     const action = process.argv[3] ?? "start";
     const port = process.argv[4] ?? "6379";
@@ -215,10 +234,16 @@ async function runInstall() {
   console.log("\nSetting up Valkey index...");
   try {
     const { getValkeyClient } = await import("./client/valkey.js");
-    const embedDim = Number(Bun.env["BETTERDB_EMBED_DIM"] ?? readConfigValue("BETTERDB_EMBED_DIM") ?? "1024");
+    const { getPluginMemoryStore } = await import("./client/memory-store.js");
+    const { createModelClient } = await import("./client/model.js");
     const client = await getValkeyClient();
-    await client.ensureIndex(embedDim);
+    const modelClient = await createModelClient();
+    // Record the active provider/dimension so a later provider swap is caught.
+    await client.assertEmbedDim(modelClient.embedDim, modelClient.preset.embedModel);
+    const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+    await store.ensureIndex();
     console.log("  Valkey index ready");
+    await store.close();
     await client.quit();
   } catch (err) {
     console.log(`  WARNING: Index setup failed (${err instanceof Error ? err.message : String(err)})`);
@@ -331,9 +356,19 @@ async function runStatus() {
   try {
     const { config } = await import("./config.js");
     const { getValkeyClient } = await import("./client/valkey.js");
+    const { getPluginMemoryStore } = await import("./client/memory-store.js");
     const client = await getValkeyClient();
-    const memoryIds = await client.listMemoryIds();
-    console.log(`OK (${memoryIds.length} memories, ${config.valkey.url})`);
+    const store = await getPluginMemoryStore();
+    const stats = await store.stats();
+    console.log(`OK (${stats.itemCount} memories, ${config.valkey.url})`);
+    const w = stats.config.weights;
+    const halfLifeDays = Math.round(stats.config.halfLifeSeconds / 86400);
+    console.log(
+      `  Recall scoring: half-life ${halfLifeDays}d · ` +
+        `weights sim/rec/imp ${w.similarity}/${w.recency}/${w.importance}` +
+        (stats.evictions > 0 ? ` · ${stats.evictions} evictions` : ""),
+    );
+    await store.close();
     await client.quit();
   } catch (err) {
     console.log(`FAILED (${err instanceof Error ? err.message : String(err)})`);
@@ -418,30 +453,292 @@ async function runMaintain() {
   console.log("BetterDB Memory for Claude Code — Maintenance\n");
 
   const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
   const { createModelClient } = await import("./client/model.js");
   const { AgingPipeline } = await import("./memory/aging.js");
 
   const valkeyClient = await getValkeyClient();
   const modelClient = await createModelClient();
-  const pipeline = new AgingPipeline(valkeyClient, modelClient);
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  const pipeline = new AgingPipeline(valkeyClient, store, modelClient);
+
+  const memories = await store.listMemories();
+  console.log(`Total memories: ${memories.length}`);
+
+  await pipeline.runFullPipeline();
+
+  console.log("\nAging pipeline complete.");
+  await store.close();
+  await valkeyClient.quit();
+}
+
+// ---------------------------------------------------------------------------
+// forget (bulk delete by scope: project / branch / tags)
+// ---------------------------------------------------------------------------
+
+async function runForget(argv: string[]) {
+  console.log("BetterDB Memory for Claude Code — Forget by scope\n");
+
+  const flag = (name: string): string | undefined => {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+  };
+  const apply = argv.includes("--apply");
+  const allProjects = argv.includes("--all-projects");
+  const branch = flag("branch");
+  const tags = flag("tags")?.split(",").map((t) => t.trim()).filter(Boolean);
+
+  const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
+  const { getCwdProject } = await import("./memory/capture.js");
+
+  const project = allProjects ? undefined : (flag("project") ?? getCwdProject());
+
+  // Refuse an unbounded delete: --all-projects must be narrowed by branch/tags.
+  if (project === undefined && branch === undefined && (!tags || tags.length === 0)) {
+    console.error("Refusing to delete every memory. Narrow --all-projects with --branch or --tags.");
+    process.exit(1);
+  }
+
+  const scopeDesc = [
+    project !== undefined ? `project=${project}` : "all projects",
+    branch !== undefined ? `branch=${branch}` : null,
+    tags && tags.length > 0 ? `tags=${tags.join(",")}` : null,
+  ].filter(Boolean).join(", ");
+  console.log(`Scope: ${scopeDesc}`);
+
+  const valkeyClient = await getValkeyClient();
+  const store = await getPluginMemoryStore();
+
+  const scope = {
+    ...(project !== undefined ? { project } : {}),
+    ...(branch !== undefined ? { branch } : {}),
+    ...(tags && tags.length > 0 ? { tags } : {}),
+  };
+
+  // Preview through the SAME native scope filter forgetByScope deletes with, so
+  // the dry-run count is exactly what --apply will remove (older memories
+  // without native tags are matched identically by both paths).
+  const candidates = await store.listByScope(scope);
+
+  console.log(`Matched ${candidates.length} memories.`);
+  for (const m of candidates.slice(0, 5)) {
+    console.log(`  - [${m.branch}] ${m.summary.oneLineSummary.slice(0, 70)}`);
+  }
+  if (candidates.length > 5) console.log(`  ... and ${candidates.length - 5} more`);
+
+  if (!apply) {
+    console.log("\nDry run — re-run with --apply to delete.");
+    await store.close();
+    await valkeyClient.quit();
+    return;
+  }
+
+  const deleted = await store.forgetByScope(scope);
+  console.log(`\nDeleted ${deleted} memories.`);
+
+  await store.close();
+  await valkeyClient.quit();
+}
+
+// ---------------------------------------------------------------------------
+// setup-index (recovery path: build the MemoryStore episodic vector index)
+// ---------------------------------------------------------------------------
+
+async function runSetupIndex() {
+  const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
+  const { createModelClient } = await import("./client/model.js");
+
+  const client = await getValkeyClient();
+  const modelClient = await createModelClient();
+  // Record the active provider/dimension so a later provider swap is caught.
+  await client.assertEmbedDim(modelClient.embedDim, modelClient.preset.embedModel);
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  await store.ensureIndex();
+  console.log("Index ready: betterdb:mem:idx");
+
+  await store.close();
+  await client.quit();
+}
+
+// ---------------------------------------------------------------------------
+// migrate (legacy betterdb:memory:* -> MemoryStore betterdb:mem:*)
+// ---------------------------------------------------------------------------
+
+async function runMigrate(apply: boolean) {
+  console.log("BetterDB Memory for Claude Code — Migrate legacy memories\n");
+
+  const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
+  const { createModelClient } = await import("./client/model.js");
+
+  const valkeyClient = await getValkeyClient();
+  const legacyIds = await valkeyClient.listMemoryIds();
+  console.log(`Found ${legacyIds.length} legacy memories under betterdb:memory:*`);
+
+  if (legacyIds.length === 0) {
+    console.log("Nothing to migrate.");
+    await valkeyClient.quit();
+    return;
+  }
 
-  const memoryIds = await valkeyClient.listMemoryIds();
-  console.log(`Total memories: ${memoryIds.length}`);
+  if (!apply) {
+    console.log("\nDry run — re-run with --apply to migrate.");
+    console.log("Each legacy memory is re-embedded and written to betterdb:mem:*,");
+    console.log("and knowledge entries are re-pointed to the new memory ids.");
+    console.log("The legacy index is dropped only after the new count is verified;");
+    console.log("legacy hashes are left in place for you to delete once satisfied.");
+    await valkeyClient.quit();
+    return;
+  }
 
-  // Group by project
+  const modelClient = await createModelClient();
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  await store.ensureIndex();
+
+  // Baseline so we can verify the store actually grew by the migrated count,
+  // not just that its total happens to exceed it (pre-existing memories).
+  const beforeCount = (await store.listMemories()).length;
+
+  let migrated = 0;
+  let failed = 0;
+  // MemoryStore.remember mints a fresh id, so track legacy -> new so we can
+  // re-point knowledge entries that reference the old episodic ids.
+  const idMap = new Map<string, string>();
   const projects = new Set<string>();
-  for (const id of memoryIds) {
+  for (const id of legacyIds) {
     const memory = await valkeyClient.getMemory(id);
-    if (memory) projects.add(memory.project);
+    if (!memory) {
+      failed++;
+      continue;
+    }
+    try {
+      const newId = await store.storeMemory(memory);
+      idMap.set(id, newId);
+      projects.add(memory.project);
+      migrated++;
+      if (migrated % 10 === 0) {
+        console.log(`  Migrated ${migrated}/${legacyIds.length}...`);
+      }
+    } catch (err) {
+      console.error(`  Failed to migrate ${id}:`, err instanceof Error ? err.message : String(err));
+      failed++;
+    }
   }
 
+  // Re-point distilled knowledge so sourceMemoryIds keep referencing real
+  // episodic memories under the new ids. storeKnowledge upserts by
+  // project:topic, so re-storing overwrites in place.
+  let remappedKnowledge = 0;
   for (const project of projects) {
-    console.log(`\nRunning decay for project: ${project}`);
-    await pipeline.runDecay(project);
+    for (const entry of await valkeyClient.listKnowledge(project)) {
+      const remapped = entry.sourceMemoryIds.map((sid) => idMap.get(sid) ?? sid);
+      if (remapped.some((sid, i) => sid !== entry.sourceMemoryIds[i])) {
+        await valkeyClient.storeKnowledge({ ...entry, sourceMemoryIds: remapped });
+        remappedKnowledge++;
+      }
+    }
+  }
+  if (remappedKnowledge > 0) {
+    console.log(`Re-pointed ${remappedKnowledge} knowledge entries to new memory ids.`);
   }
 
-  await valkeyClient.setLastAgingRun(new Date());
-  console.log("\nAging pipeline complete.");
+  // Verify before dropping the legacy index: the store must have grown by the
+  // number we successfully migrated (not merely exceed it, which pre-existing
+  // memories would satisfy even if rows failed to copy).
+  const afterCount = (await store.listMemories()).length;
+  const grew = afterCount - beforeCount;
+  console.log(`\nMigrated: ${migrated}, failed: ${failed}, store grew by ${grew} (now ${afterCount}).`);
+
+  if (migrated > 0 && grew >= migrated) {
+    await valkeyClient.dropIndex();
+    console.log("Verified — dropped the legacy index (betterdb-memory-index).");
+    console.log("Legacy hashes (betterdb:memory:*) remain; delete them manually when ready.");
+  } else {
+    console.log("Count mismatch — left the legacy index in place. Re-run after investigating.");
+  }
+
+  await store.close();
+  await valkeyClient.quit();
+}
+
+// ---------------------------------------------------------------------------
+// ingest-claude-md (ingest a CLAUDE.md / MEMORY.md file into the store)
+// ---------------------------------------------------------------------------
+
+async function runIngestClaudeMd(pathArg?: string) {
+  console.log("BetterDB Memory for Claude Code — Ingest markdown memory file\n");
+
+  const candidates = pathArg
+    ? [pathArg]
+    : [
+        join(process.cwd(), "CLAUDE.md"),
+        join(process.cwd(), "MEMORY.md"),
+        join(HOME, ".claude", "CLAUDE.md"),
+      ];
+
+  const filePath = candidates.find((p) => existsSync(p));
+  if (!filePath) {
+    console.error(`No memory file found. Looked in:\n  ${candidates.join("\n  ")}`);
+    process.exit(1);
+  }
+  console.log(`Reading ${filePath}`);
+
+  const content = readFileSync(filePath, "utf-8");
+  // Split into paragraph-sized chunks on blank lines so each becomes an
+  // independently recallable memory; cap length to keep embeddings sane.
+  const MAX_CHUNK = 480;
+  const chunks = content
+    .split(/\n\s*\n/)
+    .map((c) => c.trim())
+    .filter((c) => c.length > 0)
+    .map((c) => (c.length > MAX_CHUNK ? c.slice(0, MAX_CHUNK) : c));
+
+  if (chunks.length === 0) {
+    console.log("File is empty — nothing to ingest.");
+    process.exit(0);
+  }
+
+  const { getValkeyClient } = await import("./client/valkey.js");
+  const { getPluginMemoryStore } = await import("./client/memory-store.js");
+  const { createModelClient } = await import("./client/model.js");
+  const { getCwdProject } = await import("./memory/capture.js");
+  const { SessionSummarySchema } = await import("./memory/schema.js");
+
+  const valkeyClient = await getValkeyClient();
+  const modelClient = await createModelClient();
+  const store = await getPluginMemoryStore((t) => modelClient.embed(t));
+  await store.ensureIndex();
+
+  const project = getCwdProject();
+  const timestamp = new Date().toISOString();
+  let stored = 0;
+
+  for (const chunk of chunks) {
+    const summary = SessionSummarySchema.parse({
+      decisions: [],
+      patterns: [],
+      problemsSolved: [],
+      openThreads: [],
+      filesChanged: [],
+      oneLineSummary: chunk,
+    });
+    await store.storeMemory({
+      memoryId: crypto.randomUUID(),
+      project,
+      branch: "claude-md",
+      timestamp,
+      summary,
+      importanceScore: 0.6,
+      accessCount: 0,
+      lastAccessed: timestamp,
+    });
+    stored++;
+  }
+
+  console.log(`\nIngested ${stored} chunks from ${filePath} into project "${project}".`);
+  await store.close();
   await valkeyClient.quit();
 }