@dex-ai/memory 0.3.3

package/README.md

@@ -0,0 +1,164 @@
+# @dex-ai/memory-sqlite
+
+SQLite-backed memory Extension for [`@dex-ai/sdk`](https://github.com/klxdev/dex-ai-sdk). Three memory types — **episodic**, **semantic**, **procedural** — in one extension, one SQLite file.
+
+## Install
+
+```bash
+bun add @dex-ai/memory-sqlite
+# optional: default local embedder (ONNX via Transformers.js)
+bun add @xenova/transformers
+```
+
+`@xenova/transformers` is an optional peer dep. Skip it if you pass your own `embed()` function.
+
+## Usage
+
+```ts
+import { DexAgent } from '@dex-ai/runtime';
+import { openai } from '@dex-ai/openai';
+import { memoryExtensionSqlite } from '@dex-ai/memory-sqlite';
+
+const agent = new DexAgent({
+  provider: openai({ modelId: 'gpt-4.1' }),
+  extensions: [
+    memoryExtensionSqlite({
+      path: '~/.dex/memory.db',
+      userId: 'alice',
+
+      // Optional: a cheaper model for memory's summarize + extract calls.
+      llm: { model: 'gpt-4o-mini' },
+
+      // Optional: bring your own embedder (e.g. a remote endpoint).
+      // If omitted, a local Transformers.js embedder (all-MiniLM-L6-v2) is used.
+      // embed: async (texts) => await myRemoteEmbedder(texts),
+    }),
+  ],
+});
+```
+
+## What lives where
+
+### Episodic memory — past turns, auto-summarized
+
+Every `generate()` iteration, the extension fires a background task:
+1. Summarize the turn's new messages into 1-3 sentences via the LLM.
+2. Embed the summary and write both to SQLite.
+
+Background writes are tracked; `agent.dispose()` awaits them.
+
+At recall time (`onRequest`), the extension fetches:
+- The last **3 most-recent** episodes for the user.
+- The **3 most-similar** episodes via sqlite-vec cosine against the user's last message.
+- De-duplicated by id, sorted newest-first.
+
+### Semantic memory — durable facts
+
+Facts are `(subject, predicate, object)` tuples, unique by `(userId, subject, predicate)`. Written in two ways:
+
+**Automatic extraction** at each iteration stop: the LLM extracts durable claims from the turn and upserts them.
+
+**Model-driven** via tools:
+- `memory.remember_fact({ subject, predicate, object })` — upsert by key.
+- `memory.forget_fact({ subject, predicate })` — delete by key.
+
+At recall time, **all of the user's facts** are injected as a synthetic system message. The set is typically small (tens to low hundreds); if it grows we'll add top-k filtering later.
+
+### Procedural memory — runbooks
+
+Long-form how-to content. Stored by unique `title`, tagged, with an embedding over `title + body`.
+
+**Tools**:
+- `memory.store_procedure({ title, body, tags? })` — upsert by title.
+- `memory.list_procedures({ query?, tag?, limit? })` — with `query`, returns vector-ranked results; with `tag`, filters; with neither, returns most-recently-updated.
+- `memory.get_procedure({ title })` — fetch full body.
+
+**Auto-inject**: at recall time, the extension does a vector similarity lookup against the user's last message. If the top match scores above the threshold (default 0.5), its full body is prepended to the prompt as a synthetic system message.
+
+## LLM configuration
+
+```ts
+memoryExtensionSqlite({
+  // ...
+  llm: {
+    provider: customProvider,   // optional — overrides the agent's provider entirely
+    model: 'gpt-4o-mini',       // optional — passes via providerOptions.model per call
+  },
+});
+```
+
+Resolution rule:
+
+1. If `llm.provider` is set, use it.
+2. Otherwise use the agent's provider (captured from `actx.provider` in `onAgentStart`).
+3. If `llm.model` is set, it's passed via `providerOptions.model` on every memory-internal request. Providers that merge `providerOptions` over the default body — like `@dex-ai/openai` — honor this override per-call. Providers that don't merge `providerOptions` require passing a full `llm.provider` instance.
+
+## Extension options
+
+```ts
+interface MemoryExtensionSqliteOptions {
+  path: string;                      // SQLite file path or ':memory:'
+  userId: string;                    // owner for episodic + semantic (procedural is global)
+
+  llm?: { provider?: Provider; model?: string };
+  embed?: (texts: string[]) => Promise<number[][]>; // 384-dim
+
+  episodicRecent?: number;           // default 3
+  episodicSimilar?: number;          // default 3
+  proceduralThreshold?: number;      // default 0.5
+  autoWrite?: boolean;               // default true; set false to disable auto-summarize+extract
+}
+```
+
+## Injected prompt shape
+
+When memory is available, the extension prepends a single synthetic system message to each provider request. Example:
+
+```
+Recent context:
+- 5m ago: discussed the auth flow; chose JWT over session cookies.
+- 1d ago: debugged a test flake in session-sqlite.
+
+Known facts:
+- user prefers TypeScript
+- project uses PostgreSQL 15
+- user is on macOS
+
+Relevant runbook — deploy-dex (similarity 0.71):
+1. bun run typecheck
+2. bun run test
+3. git tag vX.Y.Z && git push --tags
+```
+
+This message is **not** persisted to `actx.messages` — it's a per-turn rewrite via the `onRequest` reducer, which never mutates the agent's canonical history.
+
+## Requirements + gotchas
+
+- **sqlite-vec**: loaded via the `sqlite-vec` npm package (ships prebuilt binaries for macOS, Linux, Windows). Extension construction throws if the binary isn't loadable for your platform.
+- **Transformers.js first-run download**: ~25 MB ONNX model, cached in `~/.cache/huggingface`. Initial `embed()` takes 10-30s; subsequent calls are fast.
+- **Background writes are fire-and-forget.** If the process is killed mid-turn, that turn's memory may not be persisted. `agent.dispose()` awaits in-flight writes normally.
+- **Prompt quality of auto-extraction** depends on the configured model. Cheap models (gpt-4o-mini, Haiku) work but may produce noisier facts. Review with `memory.list_facts` (or just inspect the DB) occasionally and use `memory.forget_fact` to prune.
+- **Procedural is global**, not user-scoped, in v0.1. If you need per-user runbooks, open an issue and we'll add a user_id column.
+
+## Schema
+
+```
+episodic         id | user_id | summary | metadata(JSON) | created_at
+episodic_vec     id | embedding(FLOAT[384])       -- sqlite-vec
+
+semantic         id | user_id | subject | predicate | object | source | created_at | updated_at
+                 UNIQUE (user_id, subject, predicate)
+
+procedural       id | title(UNIQUE) | body | tags(JSON) | created_at | updated_at
+procedural_vec   id | embedding(FLOAT[384])       -- sqlite-vec
+
+_schema_migrations  name(PK) | applied_at
+```
+
+## Testing
+
+```bash
+bun test
+```
+
+33 tests as of v0.1: schema/migrations, each memory type's read/write path, LLM helpers, and two end-to-end tests that exercise the full Agent + Extension flow.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dex-ai/memory",
+  "version": "0.3.3",
+  "description": "SQLite-backed memory Extension for @dex-ai/sdk — episodic, semantic, and procedural memory in one package.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "@dex-ai/sdk": "^0.1.2",
+    "@xenova/transformers": "^2.17.2",
+    "sqlite-vec": "^0.1.7-alpha.2"
+  },
+  "peerDependencies": {
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "@types/bun": "latest",
+    "bun-types": "latest",
+    "zod": "^3.23.8",
+    "@xenova/transformers": "^2.17.2",
+    "@changesets/cli": "^2.29.0"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/_fakes.ts

@@ -0,0 +1,148 @@
+/**
+ * Test fixtures: a deterministic fake embedder and a scriptable Model/Extension.
+ * No Transformers.js; no network; fully offline.
+ */
+import type {
+	Extension,
+	FinishReason,
+	Message,
+	Model,
+	ModelRequest,
+	ResponseMeta,
+	StreamPart,
+	Usage,
+} from "@dex-ai/sdk";
+import { EMBED_DIMS } from "./db";
+import type { Embedder } from "./embedder";
+
+const USAGE: Usage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+const FIN: FinishReason = "stop";
+
+/**
+ * Deterministic hashed embedder — same input -> same vector.
+ */
+export function fakeEmbedder(): Embedder {
+	return async (texts: string[]): Promise<number[][]> => {
+		return texts.map((t) => hashToVec(t, EMBED_DIMS));
+	};
+}
+
+function hashToVec(text: string, dims: number): number[] {
+	let seed = 0x811c9dc5;
+	for (let i = 0; i < text.length; i++) {
+		seed ^= text.charCodeAt(i);
+		seed = Math.imul(seed, 0x01000193) >>> 0;
+	}
+	const vec = new Array<number>(dims);
+	let x = seed || 1;
+	for (let i = 0; i < dims; i++) {
+		x = Math.imul(x, 48271) >>> 0;
+		vec[i] = ((x & 0xffff) / 0xffff) * 2 - 1;
+	}
+	let sq = 0;
+	for (const v of vec) sq += v * v;
+	const norm = Math.sqrt(sq) || 1;
+	return vec.map((v) => v / norm);
+}
+
+/* ------------------------------------------------------------------ */
+/* Scripted model + extension                                          */
+/* ------------------------------------------------------------------ */
+
+export type FakeStep =
+	| { kind: "tool-call"; toolName: string; input: unknown; toolCallId?: string }
+	| { kind: "text"; text: string };
+
+export const FAKE_PROVIDER = "scripted";
+export const FAKE_MODEL = "scripted-1";
+
+/**
+ * A Model whose stream() plays a scripted sequence of steps.
+ * Used both for the main generate loop and for summarize/extractFacts.
+ */
+export function scriptedModel(opts: {
+	steps?: FakeStep[];
+	generateReplies?: string[];
+}): Model {
+	const stepQueue: FakeStep[] = (opts.steps ?? []).slice();
+	const replyQueue: string[] = (opts.generateReplies ?? []).slice();
+	let callCount = 0;
+
+	return {
+		id: FAKE_MODEL,
+		async *stream(_r: ModelRequest): AsyncIterable<StreamPart> {
+			callCount += 1;
+
+			// stepQueue is for the main generate loop (tool calls + text responses).
+			// replyQueue is for side-calls (summarize, extractFacts) that happen outside the main loop.
+			let step: FakeStep;
+			if (stepQueue.length > 0) {
+				step = stepQueue.shift()!;
+			} else if (replyQueue.length > 0) {
+				step = { kind: "text", text: replyQueue.shift()! };
+			} else {
+				step = { kind: "text", text: "done" };
+			}
+
+			const meta: ResponseMeta = {
+				providerName: FAKE_PROVIDER,
+				modelId: FAKE_MODEL,
+				startedAt: Date.now(),
+			};
+			yield { type: "response-start", meta };
+			yield { type: "message-start", role: "assistant" };
+
+			let finish: FinishReason;
+			if (step.kind === "text") {
+				yield { type: "text-delta", delta: step.text };
+				yield {
+					type: "message-stop",
+					message: {
+						role: "assistant",
+						content: [{ type: "text", text: step.text }],
+					},
+				};
+				finish = "stop";
+			} else {
+				const toolCallId = step.toolCallId ?? `call-${callCount}`;
+				yield {
+					type: "tool-call",
+					toolCallId,
+					toolName: step.toolName,
+					input: step.input,
+				};
+				yield {
+					type: "message-stop",
+					message: {
+						role: "assistant",
+						content: [
+							{
+								type: "tool-call",
+								toolCallId,
+								toolName: step.toolName,
+								input: step.input,
+							},
+						],
+					},
+				};
+				finish = "tool-calls";
+			}
+			yield { type: "finish", reason: finish, usage: USAGE };
+			yield { type: "response-stop", meta, usage: USAGE, finishReason: finish };
+		},
+	};
+}
+
+/**
+ * Wrap a scriptedModel into an Extension for use with Agent.create/Agent.create.
+ */
+export function scriptedProviderExtension(opts: {
+	steps?: FakeStep[];
+	generateReplies?: string[];
+}): Extension {
+	const model = scriptedModel(opts);
+	return {
+		name: FAKE_PROVIDER,
+		models: [model],
+	};
+}

package/src/db.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test';
+import { MemoryDb, EMBED_DIMS } from './db';
+
+describe('MemoryDb', () => {
+  test('opens, loads sqlite-vec, runs migrations', () => {
+    const db = new MemoryDb({ path: ':memory:' });
+    // All four base tables should exist.
+    const tables = db.db
+      .prepare("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+      .all()
+      .map((r) => (r as { name: string }).name);
+    expect(tables).toContain('episodic');
+    expect(tables).toContain('semantic');
+    expect(tables).toContain('procedural');
+    expect(tables).toContain('_schema_migrations');
+    // vec virtual tables exist too (they show up as 'episodic_vec'/'procedural_vec').
+    expect(tables).toContain('episodic_vec');
+    expect(tables).toContain('procedural_vec');
+    db.close();
+  });
+
+  test('migrations idempotent across constructors for the same file', async () => {
+    // :memory: isn't shareable — use a temp file.
+    const { mkdtemp, rm } = await import('node:fs/promises');
+    const { tmpdir } = await import('node:os');
+    const { join } = await import('node:path');
+    const dir = await mkdtemp(join(tmpdir(), 'dex-mem-'));
+    const path = join(dir, 'mem.db');
+    try {
+      const a = new MemoryDb({ path });
+      const appliedFirst = a.db.prepare('SELECT COUNT(*) as c FROM _schema_migrations').get() as { c: number };
+      a.close();
+
+      const b = new MemoryDb({ path });
+      const appliedAgain = b.db.prepare('SELECT COUNT(*) as c FROM _schema_migrations').get() as { c: number };
+      expect(appliedAgain.c).toBe(appliedFirst.c);
+      b.close();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('EMBED_DIMS is 384', () => {
+    expect(EMBED_DIMS).toBe(384);
+  });
+});

package/src/db.ts

@@ -0,0 +1,149 @@
+/**
+ * SQLite database open + sqlite-vec load + schema migrations.
+ *
+ * One DB file, four tables plus two sqlite-vec virtual tables:
+ *   episodic, episodic_vec, semantic, procedural, procedural_vec, _schema_migrations.
+ *
+ * sqlite-vec is loaded as a SQLite extension via `db.loadExtension()`. If the
+ * extension cannot be loaded (e.g. the prebuilt binary is missing for the host
+ * platform), we throw a descriptive error at construction time so apps see it
+ * immediately rather than on first recall.
+ */
+import { Database } from 'bun:sqlite';
+import * as sqliteVec from 'sqlite-vec';
+import { existsSync, mkdirSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+
+/** Embedding dimensions — matches Xenova/all-MiniLM-L6-v2. */
+export const EMBED_DIMS = 384;
+
+export interface OpenDbOptions {
+  /** Absolute path to the DB file, or ':memory:'. Created if missing. */
+  path: string;
+  /**
+   * Optional path to the sqlite-vec loadable extension (vec0.so / vec0.dylib).
+   * When running inside a compiled binary, the normal require.resolve() won't
+   * find the .so — pass the extracted path here instead.
+   */
+  vecPath?: string;
+}
+
+const MIGRATIONS: Array<{ name: string; sql: string }> = [
+  {
+    name: '001_init',
+    sql: `
+      CREATE TABLE IF NOT EXISTS episodic (
+        id         TEXT PRIMARY KEY,
+        user_id    TEXT NOT NULL,
+        summary    TEXT NOT NULL,
+        metadata   TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_episodic_user_time ON episodic(user_id, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS semantic (
+        id         TEXT PRIMARY KEY,
+        user_id    TEXT NOT NULL,
+        subject    TEXT NOT NULL,
+        predicate  TEXT NOT NULL,
+        object     TEXT NOT NULL,
+        source     TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        UNIQUE(user_id, subject, predicate)
+      );
+      CREATE INDEX IF NOT EXISTS idx_semantic_user ON semantic(user_id);
+
+      CREATE TABLE IF NOT EXISTS procedural (
+        id         TEXT PRIMARY KEY,
+        title      TEXT NOT NULL UNIQUE,
+        body       TEXT NOT NULL,
+        tags       TEXT NOT NULL DEFAULT '[]',
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_procedural_title ON procedural(title);
+    `,
+  },
+  {
+    name: '002_vec',
+    // vec0 virtual tables. Must run AFTER sqlite-vec is loaded.
+    sql: `
+      CREATE VIRTUAL TABLE IF NOT EXISTS episodic_vec USING vec0(
+        id TEXT PRIMARY KEY,
+        embedding FLOAT[${EMBED_DIMS}]
+      );
+      CREATE VIRTUAL TABLE IF NOT EXISTS procedural_vec USING vec0(
+        id TEXT PRIMARY KEY,
+        embedding FLOAT[${EMBED_DIMS}]
+      );
+    `,
+  },
+  {
+    name: '003_semantic_vec',
+    sql: `
+      CREATE VIRTUAL TABLE IF NOT EXISTS semantic_vec USING vec0(
+        id TEXT PRIMARY KEY,
+        embedding FLOAT[${EMBED_DIMS}]
+      );
+    `,
+  },
+];
+
+function applyMigrations(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS _schema_migrations (
+      name       TEXT PRIMARY KEY,
+      applied_at INTEGER NOT NULL
+    );
+  `);
+  const already = new Set(
+    db
+      .prepare('SELECT name FROM _schema_migrations')
+      .all()
+      .map((r) => (r as { name: string }).name),
+  );
+  const record = db.prepare('INSERT INTO _schema_migrations(name, applied_at) VALUES(?, ?)');
+  for (const m of MIGRATIONS) {
+    if (already.has(m.name)) continue;
+    db.transaction(() => {
+      db.exec(m.sql);
+      record.run(m.name, Date.now());
+    })();
+  }
+}
+
+export class MemoryDb {
+  readonly db: Database;
+
+  constructor(opts: OpenDbOptions) {
+    this.db = new Database(opts.path, { create: true });
+    this.db.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;');
+
+    // Load sqlite-vec. Failure here is fatal — no point constructing the
+    // extension if vector tables won't work.
+    try {
+      if (opts.vecPath) {
+        // Compiled binary mode: load from explicit path
+        this.db.loadExtension(opts.vecPath);
+      } else {
+        // Normal mode: sqlite-vec resolves the platform-specific .so via require.resolve()
+        (sqliteVec as { load: (db: unknown) => void }).load(this.db);
+      }
+    } catch (err) {
+      this.db.close();
+      throw new Error(
+        `@dex-ai/memory-sqlite: failed to load sqlite-vec extension. ` +
+          `Ensure the sqlite-vec npm package's prebuilt binary is available for this platform. ` +
+          `Original error: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+
+    applyMigrations(this.db);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/embedder.ts

@@ -0,0 +1,60 @@
+/**
+ * Embedder interface + default local implementation.
+ *
+ * Default: Transformers.js pipeline with Xenova/all-MiniLM-L6-v2 (384-dim).
+ * - Lazy-loaded on first use (first call may take ~10-30s as it downloads the ONNX
+ *   model, ~25 MB, to ~/.cache/huggingface).
+ * - Subsequent calls are fast (batched, ~50-100ms per text on modern hardware).
+ *
+ * Apps can override with their own embed() function — e.g. calling a remote
+ * embeddings endpoint — by passing it into memoryExtension options.
+ */
+import { EMBED_DIMS } from './db';
+
+/** Embeds a batch of texts into fixed-dimension vectors. */
+export type Embedder = (texts: string[]) => Promise<number[][]>;
+
+/** Dimensionality the package expects. All embedders must produce this length. */
+export const EXPECTED_DIMS = EMBED_DIMS;
+
+// Guard to avoid loading Transformers.js more than once per process.
+let sharedPipelinePromise: Promise<(texts: string[]) => Promise<number[][]>> | null = null;
+
+async function loadTransformersPipeline(): Promise<(texts: string[]) => Promise<number[][]>> {
+  // Dynamic import so the dep is optional — apps that pass their own embed()
+  // never touch the Transformers.js package.
+  const mod = await import('@xenova/transformers').catch((err: unknown) => {
+    throw new Error(
+      `@dex-ai/memory-sqlite: @xenova/transformers is not installed. ` +
+        `Either install it (bun add @xenova/transformers) or pass a custom embed() function. ` +
+        `Original: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  });
+
+  const pipelineFactory = (mod as { pipeline: (task: string, model: string) => Promise<unknown> }).pipeline;
+  const pipe = (await pipelineFactory('feature-extraction', 'Xenova/all-MiniLM-L6-v2')) as (
+    input: string[] | string,
+    options?: { pooling: 'mean' | 'none'; normalize: boolean },
+  ) => Promise<{ tolist(): number[][] | number[][][]; data: Float32Array; dims: number[] }>;
+
+  return async function embed(texts: string[]): Promise<number[][]> {
+    if (texts.length === 0) return [];
+    const out = await pipe(texts, { pooling: 'mean', normalize: true });
+    const list = out.tolist();
+    return list as number[][];
+  };
+}
+
+/**
+ * Returns the default local embedder (Transformers.js / Xenova/all-MiniLM-L6-v2).
+ * First call is slow (downloads the model); subsequent calls are fast.
+ */
+export function localEmbedder(): Embedder {
+  return async (texts: string[]): Promise<number[][]> => {
+    if (sharedPipelinePromise === null) {
+      sharedPipelinePromise = loadTransformersPipeline();
+    }
+    const pipe = await sharedPipelinePromise;
+    return pipe(texts);
+  };
+}

package/src/episodic.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test';
+import { MemoryDb } from './db';
+import { EpisodicStore } from './episodic';
+import { fakeEmbedder } from './_fakes';
+
+describe('EpisodicStore', () => {
+  let db: MemoryDb;
+  let store: EpisodicStore;
+  const embed = fakeEmbedder();
+
+  beforeEach(() => {
+    db = new MemoryDb({ path: ':memory:' });
+    store = new EpisodicStore(db.db);
+  });
+
+  afterEach(() => db.close());
+
+  test('record + recall-recent returns what was written, newest first', async () => {
+    const [v1] = await embed(['first episode']);
+    await store.record({ userId: 'u', summary: 'first', embedding: v1! });
+    await new Promise((r) => setTimeout(r, 3));
+    const [v2] = await embed(['second episode']);
+    await store.record({ userId: 'u', summary: 'second', embedding: v2! });
+
+    const rec = await store.recall('u', undefined, { recentLimit: 5, similarLimit: 0 });
+    expect(rec.length).toBe(2);
+    expect(rec[0]!.summary).toBe('second');
+    expect(rec[1]!.summary).toBe('first');
+  });
+
+  test('recall filters by userId', async () => {
+    const [v] = await embed(['x']);
+    await store.record({ userId: 'alice', summary: 'for alice', embedding: v! });
+    await store.record({ userId: 'bob', summary: 'for bob', embedding: v! });
+
+    const a = await store.recall('alice', undefined, { similarLimit: 0 });
+    expect(a.length).toBe(1);
+    expect(a[0]!.summary).toBe('for alice');
+  });
+
+  test('recall includes similar matches when query vector given', async () => {
+    // Deterministic fake embedder — same text -> same vector. Recalling with
+    // the vector of stored text should find that exact episode.
+    const [vA] = await embed(['alpha']);
+    const [vB] = await embed(['beta']);
+    const [vC] = await embed(['gamma']);
+    await store.record({ userId: 'u', summary: 'alpha', embedding: vA! });
+    await store.record({ userId: 'u', summary: 'beta', embedding: vB! });
+    await store.record({ userId: 'u', summary: 'gamma', embedding: vC! });
+
+    // Query with the exact vector of 'beta' — beta should be among results.
+    const rec = await store.recall('u', vB, { recentLimit: 0, similarLimit: 2 });
+    expect(rec.length).toBeGreaterThan(0);
+    expect(rec.some((r) => r.summary === 'beta')).toBe(true);
+  });
+
+  test('recall de-dupes across recent + similar', async () => {
+    const [v] = await embed(['one-and-only']);
+    await store.record({ userId: 'u', summary: 'one-and-only', embedding: v! });
+    const rec = await store.recall('u', v, { recentLimit: 3, similarLimit: 3 });
+    expect(rec.length).toBe(1);
+  });
+});