@gnldev/rag 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { InMemoryVectorStore, indexDocuments, tokenize, keywordScore } from './vector-store.js';
+export type { VectorStore, VectorDoc, VectorItem, VectorMatch, Embed, QueryOptions, DeleteWhere } from './vector-store.js';
+export { PostgresVectorStore } from './postgres-vector-store.js';
+export type { PostgresVectorStoreOptions, PoolLike } from './postgres-vector-store.js';
+export { createRagTool } from './rag-tool.js';
+export { llmReranker } from './rerank.js';
+export type { Reranker } from './rerank.js';
+export { SemanticMemory } from './semantic-memory.js';
+export type { SemanticMemoryOptions } from './semantic-memory.js';
+export { chunkText, chunkDocuments } from './chunk.js';
+export type { ChunkOptions, Chunk } from './chunk.js';
+export { GraphRag } from './graph-rag.js';
+export type { GraphRagOptions } from './graph-rag.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+// @gnldev/rag — vector store + RAG tool for AI SDK agents.
+// Automatically replayable/exactly-once when used as a tool inside runDurable (thanks to durableTool).
+export { InMemoryVectorStore, indexDocuments, tokenize, keywordScore } from './vector-store.js';
+export { PostgresVectorStore } from './postgres-vector-store.js';
+export { createRagTool } from './rag-tool.js';
+export { llmReranker } from './rerank.js';
+export { SemanticMemory } from './semantic-memory.js';
+export { chunkText, chunkDocuments } from './chunk.js';
+export { GraphRag } from './graph-rag.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,uGAAuG;AACvG,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEhG,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEvD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["// @gnldev/rag — vector store + RAG tool for AI SDK agents.\n// Automatically replayable/exactly-once when used as a tool inside runDurable (thanks to durableTool).\nexport { InMemoryVectorStore, indexDocuments, tokenize, keywordScore } from './vector-store.js';\nexport type { VectorStore, VectorDoc, VectorItem, VectorMatch, Embed, QueryOptions, DeleteWhere } from './vector-store.js';\nexport { PostgresVectorStore } from './postgres-vector-store.js';\nexport type { PostgresVectorStoreOptions, PoolLike } from './postgres-vector-store.js';\nexport { createRagTool } from './rag-tool.js';\nexport { llmReranker } from './rerank.js';\nexport type { Reranker } from './rerank.js';\nexport { SemanticMemory } from './semantic-memory.js';\nexport type { SemanticMemoryOptions } from './semantic-memory.js';\nexport { chunkText, chunkDocuments } from './chunk.js';\nexport type { ChunkOptions, Chunk } from './chunk.js';\nexport { GraphRag } from './graph-rag.js';\nexport type { GraphRagOptions } from './graph-rag.js';\n"]}

package/dist/postgres-vector-store.d.ts

@@ -0,0 +1,50 @@
+import type { VectorStore, VectorItem, VectorMatch, QueryOptions, DeleteWhere } from './vector-store.js';
+/** Minimal pg.Pool surface — injectable for tests/custom setups (same pattern as PostgresJournal). */
+export interface PoolLike {
+    query: (sql: string, params?: unknown[]) => Promise<{
+        rows: any[];
+    }>;
+    end?: () => Promise<void>;
+}
+export interface PostgresVectorStoreOptions {
+    /** pg connection string (a Pool is built from this if `pool` isn't given). */
+    connectionString?: string;
+    /** Bring your own `pg.Pool` (test/custom setup); if given, `pg` isn't imported. */
+    pool?: PoolLike;
+    /** Table name (default `gnl_vectors`). */
+    table?: string;
+    /** Embedding dimension; inferred from the first upsert/query vector if not given. */
+    dimension?: number;
+    /** Similarity index (default 'hnsw'); 'none' → no index is created. */
+    index?: 'hnsw' | 'ivfflat' | 'none';
+}
+/**
+ * Production VectorStore: Postgres + pgvector. SAME interface as `InMemoryVectorStore` → drop-in.
+ * `pg` is an optional peer dependency; it's only loaded lazily via `createRequire` when `pool` isn't
+ * given (bundlers can't see it statically). Single table: (id PK, text, embedding vector(dim), metadata jsonb, created_at).
+ * Cosine: pgvector `<=>` distance; score = `1 - distance` (higher = better, same as InMemoryVectorStore).
+ *
+ * Correctness: runs durable-wrapped inside `createRagTool` → the query result is journaled →
+ * the pg query does NOT RE-RUN on resume/replay. Even if ANN/HNSW is approximate, the result comes back from the journal.
+ */
+export declare class PostgresVectorStore implements VectorStore {
+    private pool;
+    private table;
+    private dimension?;
+    private index;
+    private ready?;
+    constructor(opts?: PostgresVectorStoreOptions);
+    /** Sets up the extension+table+index (idempotent) using the first vector's dimension; then caches it. */
+    private ensureReady;
+    upsert(items: VectorItem[]): Promise<void>;
+    /**
+     * 7.2: opts is backward compatible. namespace + metadata filter (jsonb `@>` containment) + minScore
+     * are applied in SQL. NOTE: hybrid keyword blending (`opts.text`/`keywordWeight`) is NOT SUPPORTED
+     * in pg (would require a tsvector/BM25 setup) — InMemoryVectorStore has full hybrid; pg here is
+     * limited to vector + minScore (keywordWeight is IGNORED even if given). This is a documented, deliberate limit.
+     */
+    query(embedding: number[], topK: number, opts?: QueryOptions): Promise<VectorMatch[]>;
+    /** 7.2: delete by id/filter/namespace (count deleted via RETURNING). Empty where → deletes nothing. */
+    delete(where: DeleteWhere): Promise<number>;
+    close(): Promise<void>;
+}

package/dist/postgres-vector-store.js

@@ -0,0 +1,165 @@
+import { createRequire } from 'node:module';
+/**
+ * Production VectorStore: Postgres + pgvector. SAME interface as `InMemoryVectorStore` → drop-in.
+ * `pg` is an optional peer dependency; it's only loaded lazily via `createRequire` when `pool` isn't
+ * given (bundlers can't see it statically). Single table: (id PK, text, embedding vector(dim), metadata jsonb, created_at).
+ * Cosine: pgvector `<=>` distance; score = `1 - distance` (higher = better, same as InMemoryVectorStore).
+ *
+ * Correctness: runs durable-wrapped inside `createRagTool` → the query result is journaled →
+ * the pg query does NOT RE-RUN on resume/replay. Even if ANN/HNSW is approximate, the result comes back from the journal.
+ */
+export class PostgresVectorStore {
+    pool;
+    table;
+    dimension;
+    index;
+    ready;
+    constructor(opts = {}) {
+        this.table = opts.table ?? 'gnl_vectors';
+        this.dimension = opts.dimension;
+        this.index = opts.index ?? 'hnsw';
+        if (opts.pool) {
+            this.pool = opts.pool;
+        }
+        else {
+            const { Pool } = createRequire(import.meta.url)('pg');
+            this.pool = new Pool(opts.connectionString ? { connectionString: opts.connectionString } : {});
+        }
+    }
+    /** Sets up the extension+table+index (idempotent) using the first vector's dimension; then caches it. */
+    ensureReady(dim) {
+        if (!this.ready) {
+            const dimension = this.dimension ?? dim;
+            this.dimension = dimension;
+            const booting = (async () => {
+                await this.pool.query('CREATE EXTENSION IF NOT EXISTS vector');
+                await this.pool.query(`CREATE TABLE IF NOT EXISTS ${this.table} (
+             id TEXT PRIMARY KEY,
+             text TEXT NOT NULL,
+             embedding vector(${dimension}) NOT NULL,
+             metadata JSONB,
+             namespace TEXT,
+             created_at BIGINT NOT NULL
+           )`);
+                // 7.2: add the column in a backward-compatible way on old (namespace-less) tables.
+                await this.pool.query(`ALTER TABLE ${this.table} ADD COLUMN IF NOT EXISTS namespace TEXT`);
+                if (this.index === 'hnsw') {
+                    await this.pool.query(`CREATE INDEX IF NOT EXISTS ${this.table}_embedding_idx
+               ON ${this.table} USING hnsw (embedding vector_cosine_ops)`);
+                }
+                else if (this.index === 'ivfflat') {
+                    await this.pool.query(`CREATE INDEX IF NOT EXISTS ${this.table}_embedding_idx
+               ON ${this.table} USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100)`);
+                }
+            })();
+            this.ready = booting;
+            // Same reasoning as `PostgresStorage.ensureReady`, and found by looking for the same shape
+            // after CI caught it there: memoising the promise is right, memoising a REJECTED one turns a
+            // dropped connection during setup into a store that never works again, on a database that
+            // recovered seconds later. Clearing the memo lets the next `upsert`/`query` retry the DDL.
+            // `dimension` is deliberately NOT cleared — it was taken from the caller's first vector, not
+            // from the database, so it is still the right answer on the retry.
+            booting.catch(() => { if (this.ready === booting)
+                this.ready = undefined; });
+            return booting;
+        }
+        return this.ready;
+    }
+    async upsert(items) {
+        if (items.length === 0)
+            return;
+        await this.ensureReady(items[0].embedding.length);
+        for (const it of items) {
+            await this.pool.query(`INSERT INTO ${this.table} (id, text, embedding, metadata, namespace, created_at)
+           VALUES ($1, $2, $3::vector, $4, $5, $6)
+           ON CONFLICT (id) DO UPDATE SET
+             text = EXCLUDED.text,
+             embedding = EXCLUDED.embedding,
+             metadata = EXCLUDED.metadata,
+             namespace = EXCLUDED.namespace`, [it.id, it.text, toVectorLiteral(it.embedding), it.metadata ? JSON.stringify(it.metadata) : null, it.namespace ?? null, Date.now()]);
+        }
+    }
+    /**
+     * 7.2: opts is backward compatible. namespace + metadata filter (jsonb `@>` containment) + minScore
+     * are applied in SQL. NOTE: hybrid keyword blending (`opts.text`/`keywordWeight`) is NOT SUPPORTED
+     * in pg (would require a tsvector/BM25 setup) — InMemoryVectorStore has full hybrid; pg here is
+     * limited to vector + minScore (keywordWeight is IGNORED even if given). This is a documented, deliberate limit.
+     */
+    async query(embedding, topK, opts) {
+        await this.ensureReady(embedding.length);
+        const params = [toVectorLiteral(embedding)];
+        const where = [];
+        if (opts?.namespace !== undefined) {
+            params.push(opts.namespace);
+            where.push(`namespace = $${params.length}`);
+        }
+        if (opts?.filter && Object.keys(opts.filter).length > 0) {
+            params.push(JSON.stringify(opts.filter));
+            where.push(`metadata @> $${params.length}::jsonb`);
+        }
+        if (opts?.minScore !== undefined) {
+            params.push(opts.minScore);
+            where.push(`1 - (embedding <=> $1::vector) >= $${params.length}`);
+        }
+        params.push(topK);
+        const limitParam = `$${params.length}`;
+        const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';
+        const res = await this.pool.query(`SELECT id, text, metadata, namespace, 1 - (embedding <=> $1::vector) AS score
+         FROM ${this.table}
+         ${whereSql}
+         ORDER BY embedding <=> $1::vector
+         LIMIT ${limitParam}`, params);
+        return res.rows.map((r) => ({
+            id: r.id,
+            text: r.text,
+            metadata: parseMetadata(r.metadata),
+            namespace: r.namespace ?? undefined,
+            score: typeof r.score === 'number' ? r.score : Number(r.score),
+        }));
+    }
+    /** 7.2: delete by id/filter/namespace (count deleted via RETURNING). Empty where → deletes nothing. */
+    async delete(where) {
+        if (!where.ids && where.namespace === undefined && !where.filter)
+            return 0; // safe side
+        await this.ensureReady(this.dimension ?? 1);
+        const params = [];
+        const conds = [];
+        if (where.ids) {
+            params.push(where.ids);
+            conds.push(`id = ANY($${params.length})`);
+        }
+        if (where.namespace !== undefined) {
+            params.push(where.namespace);
+            conds.push(`namespace = $${params.length}`);
+        }
+        if (where.filter && Object.keys(where.filter).length > 0) {
+            params.push(JSON.stringify(where.filter));
+            conds.push(`metadata @> $${params.length}::jsonb`);
+        }
+        const res = await this.pool.query(`DELETE FROM ${this.table} WHERE ${conds.join(' AND ')} RETURNING id`, params);
+        return res.rows.length;
+    }
+    async close() {
+        if (this.pool.end)
+            await this.pool.end();
+    }
+}
+/** number[] → pgvector literal '[0.1,0.2,...]'. */
+function toVectorLiteral(v) {
+    return `[${v.join(',')}]`;
+}
+/** The JSONB column can come back from pg as either an object or a string; normalize it. */
+function parseMetadata(m) {
+    if (m == null)
+        return undefined;
+    if (typeof m === 'string') {
+        try {
+            return JSON.parse(m);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return m;
+}
+//# sourceMappingURL=postgres-vector-store.js.map

package/dist/postgres-vector-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-vector-store.js","sourceRoot":"","sources":["../src/postgres-vector-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createRequire } from 'node:module';\nimport type { VectorStore, VectorItem, VectorMatch, QueryOptions, DeleteWhere } from './vector-store.js';\n\n/** Minimal pg.Pool surface — injectable for tests/custom setups (same pattern as PostgresJournal). */\nexport interface PoolLike {\n  query: (sql: string, params?: unknown[]) => Promise<{ rows: any[] }>;\n  end?: () => Promise<void>;\n}\n\nexport interface PostgresVectorStoreOptions {\n  /** pg connection string (a Pool is built from this if `pool` isn't given). */\n  connectionString?: string;\n  /** Bring your own `pg.Pool` (test/custom setup); if given, `pg` isn't imported. */\n  pool?: PoolLike;\n  /** Table name (default `gnl_vectors`). */\n  table?: string;\n  /** Embedding dimension; inferred from the first upsert/query vector if not given. */\n  dimension?: number;\n  /** Similarity index (default 'hnsw'); 'none' → no index is created. */\n  index?: 'hnsw' | 'ivfflat' | 'none';\n}\n\n/**\n * Production VectorStore: Postgres + pgvector. SAME interface as `InMemoryVectorStore` → drop-in.\n * `pg` is an optional peer dependency; it's only loaded lazily via `createRequire` when `pool` isn't\n * given (bundlers can't see it statically). Single table: (id PK, text, embedding vector(dim), metadata jsonb, created_at).\n * Cosine: pgvector `<=>` distance; score = `1 - distance` (higher = better, same as InMemoryVectorStore).\n *\n * Correctness: runs durable-wrapped inside `createRagTool` → the query result is journaled →\n * the pg query does NOT RE-RUN on resume/replay. Even if ANN/HNSW is approximate, the result comes back from the journal.\n */\nexport class PostgresVectorStore implements VectorStore {\n  private pool: PoolLike;\n  private table: string;\n  private dimension?: number;\n  private index: 'hnsw' | 'ivfflat' | 'none';\n  private ready?: Promise<void>;\n\n  constructor(opts: PostgresVectorStoreOptions = {}) {\n    this.table = opts.table ?? 'gnl_vectors';\n    this.dimension = opts.dimension;\n    this.index = opts.index ?? 'hnsw';\n    if (opts.pool) {\n      this.pool = opts.pool;\n    } else {\n      const { Pool } = createRequire(import.meta.url)('pg') as { Pool: new (config: any) => any };\n      this.pool = new Pool(opts.connectionString ? { connectionString: opts.connectionString } : {});\n    }\n  }\n\n  /** Sets up the extension+table+index (idempotent) using the first vector's dimension; then caches it. */\n  private ensureReady(dim: number): Promise<void> {\n    if (!this.ready) {\n      const dimension = this.dimension ?? dim;\n      this.dimension = dimension;\n      const booting = (async () => {\n        await this.pool.query('CREATE EXTENSION IF NOT EXISTS vector');\n        await this.pool.query(\n          `CREATE TABLE IF NOT EXISTS ${this.table} (\n             id TEXT PRIMARY KEY,\n             text TEXT NOT NULL,\n             embedding vector(${dimension}) NOT NULL,\n             metadata JSONB,\n             namespace TEXT,\n             created_at BIGINT NOT NULL\n           )`,\n        );\n        // 7.2: add the column in a backward-compatible way on old (namespace-less) tables.\n        await this.pool.query(`ALTER TABLE ${this.table} ADD COLUMN IF NOT EXISTS namespace TEXT`);\n        if (this.index === 'hnsw') {\n          await this.pool.query(\n            `CREATE INDEX IF NOT EXISTS ${this.table}_embedding_idx\n               ON ${this.table} USING hnsw (embedding vector_cosine_ops)`,\n          );\n        } else if (this.index === 'ivfflat') {\n          await this.pool.query(\n            `CREATE INDEX IF NOT EXISTS ${this.table}_embedding_idx\n               ON ${this.table} USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100)`,\n          );\n        }\n      })();\n      this.ready = booting;\n      // Same reasoning as `PostgresStorage.ensureReady`, and found by looking for the same shape\n      // after CI caught it there: memoising the promise is right, memoising a REJECTED one turns a\n      // dropped connection during setup into a store that never works again, on a database that\n      // recovered seconds later. Clearing the memo lets the next `upsert`/`query` retry the DDL.\n      // `dimension` is deliberately NOT cleared — it was taken from the caller's first vector, not\n      // from the database, so it is still the right answer on the retry.\n      booting.catch(() => { if (this.ready === booting) this.ready = undefined; });\n      return booting;\n    }\n    return this.ready;\n  }\n\n  async upsert(items: VectorItem[]): Promise<void> {\n    if (items.length === 0) return;\n    await this.ensureReady(items[0]!.embedding.length);\n    for (const it of items) {\n      await this.pool.query(\n        `INSERT INTO ${this.table} (id, text, embedding, metadata, namespace, created_at)\n           VALUES ($1, $2, $3::vector, $4, $5, $6)\n           ON CONFLICT (id) DO UPDATE SET\n             text = EXCLUDED.text,\n             embedding = EXCLUDED.embedding,\n             metadata = EXCLUDED.metadata,\n             namespace = EXCLUDED.namespace`,\n        [it.id, it.text, toVectorLiteral(it.embedding), it.metadata ? JSON.stringify(it.metadata) : null, it.namespace ?? null, Date.now()],\n      );\n    }\n  }\n\n  /**\n   * 7.2: opts is backward compatible. namespace + metadata filter (jsonb `@>` containment) + minScore\n   * are applied in SQL. NOTE: hybrid keyword blending (`opts.text`/`keywordWeight`) is NOT SUPPORTED\n   * in pg (would require a tsvector/BM25 setup) — InMemoryVectorStore has full hybrid; pg here is\n   * limited to vector + minScore (keywordWeight is IGNORED even if given). This is a documented, deliberate limit.\n   */\n  async query(embedding: number[], topK: number, opts?: QueryOptions): Promise<VectorMatch[]> {\n    await this.ensureReady(embedding.length);\n    const params: unknown[] = [toVectorLiteral(embedding)];\n    const where: string[] = [];\n    if (opts?.namespace !== undefined) {\n      params.push(opts.namespace);\n      where.push(`namespace = $${params.length}`);\n    }\n    if (opts?.filter && Object.keys(opts.filter).length > 0) {\n      params.push(JSON.stringify(opts.filter));\n      where.push(`metadata @> $${params.length}::jsonb`);\n    }\n    if (opts?.minScore !== undefined) {\n      params.push(opts.minScore);\n      where.push(`1 - (embedding <=> $1::vector) >= $${params.length}`);\n    }\n    params.push(topK);\n    const limitParam = `$${params.length}`;\n    const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';\n    const res = await this.pool.query(\n      `SELECT id, text, metadata, namespace, 1 - (embedding <=> $1::vector) AS score\n         FROM ${this.table}\n         ${whereSql}\n         ORDER BY embedding <=> $1::vector\n         LIMIT ${limitParam}`,\n      params,\n    );\n    return res.rows.map((r) => ({\n      id: r.id,\n      text: r.text,\n      metadata: parseMetadata(r.metadata),\n      namespace: r.namespace ?? undefined,\n      score: typeof r.score === 'number' ? r.score : Number(r.score),\n    }));\n  }\n\n  /** 7.2: delete by id/filter/namespace (count deleted via RETURNING). Empty where → deletes nothing. */\n  async delete(where: DeleteWhere): Promise<number> {\n    if (!where.ids && where.namespace === undefined && !where.filter) return 0; // safe side\n    await this.ensureReady(this.dimension ?? 1);\n    const params: unknown[] = [];\n    const conds: string[] = [];\n    if (where.ids) {\n      params.push(where.ids);\n      conds.push(`id = ANY($${params.length})`);\n    }\n    if (where.namespace !== undefined) {\n      params.push(where.namespace);\n      conds.push(`namespace = $${params.length}`);\n    }\n    if (where.filter && Object.keys(where.filter).length > 0) {\n      params.push(JSON.stringify(where.filter));\n      conds.push(`metadata @> $${params.length}::jsonb`);\n    }\n    const res = await this.pool.query(\n      `DELETE FROM ${this.table} WHERE ${conds.join(' AND ')} RETURNING id`,\n      params,\n    );\n    return res.rows.length;\n  }\n\n  async close(): Promise<void> {\n    if (this.pool.end) await this.pool.end();\n  }\n}\n\n/** number[] → pgvector literal '[0.1,0.2,...]'. */\nfunction toVectorLiteral(v: number[]): string {\n  return `[${v.join(',')}]`;\n}\n\n/** The JSONB column can come back from pg as either an object or a string; normalize it. */\nfunction parseMetadata(m: unknown): Record<string, unknown> | undefined {\n  if (m == null) return undefined;\n  if (typeof m === 'string') {\n    try {\n      return JSON.parse(m) as Record<string, unknown>;\n    } catch {\n      return undefined;\n    }\n  }\n  return m as Record<string, unknown>;\n}\n"]}

package/dist/rag-tool.d.ts

@@ -0,0 +1,42 @@
+import type { Tool } from 'ai';
+import type { VectorStore, Embed } from './vector-store.js';
+import type { Reranker } from './rerank.js';
+/** One retrieved document as the tool reports it. Named so the tool's public type can be declared. */
+export interface RagHit {
+    text: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * RAG tool that an agent can call. When used inside `runDurable`, `durableTool` journals its result
+ * → **replayable & exactly-once RAG** (same documents on resume; no new embed/query call).
+ * Most RAG implementations don't give this guarantee. If `rerank` is provided, vector results are reordered
+ * by the LLM (the rerank call is also journaled → replayable).
+ */
+export declare function createRagTool(opts: {
+    store: VectorStore;
+    embed: Embed;
+    topK?: number;
+    description?: string;
+    /** LLM reranker: reorders the initially fetched `topK` results. */
+    rerank?: Reranker;
+    /** Number of results to keep after rerank. */
+    rerankTopK?: number;
+    /**
+     * The slice of the corpus this tool may retrieve from.
+     *
+     * There was no way to express this, and the tool never passed `QueryOptions` to the store at all —
+     * so `namespace`, the only isolation mechanism the store layer has, was unreachable through the one
+     * documented RAG path. Every agent built from this tool searched the whole index, and every shipped
+     * example (README, both GUIDEs, the scaffold recipe, the docs-mcp entry) does exactly that.
+     *
+     * Build one tool per organization with their namespace, or pass a function to resolve it per call.
+     */
+    namespace?: string;
+    /** Metadata narrowing, applied by the store alongside `namespace`. */
+    filter?: Record<string, unknown>;
+}): Tool<{
+    query: string;
+}, RagHit[]> & {
+    idempotent: boolean;
+};

package/dist/rag-tool.js

@@ -0,0 +1,30 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+/**
+ * RAG tool that an agent can call. When used inside `runDurable`, `durableTool` journals its result
+ * → **replayable & exactly-once RAG** (same documents on resume; no new embed/query call).
+ * Most RAG implementations don't give this guarantee. If `rerank` is provided, vector results are reordered
+ * by the LLM (the rerank call is also journaled → replayable).
+ */
+export function createRagTool(opts) {
+    // H7: read-only search — safe to re-run → idempotent (keeps retry/reclaim smooth).
+    return Object.assign(tool({
+        description: opts.description ?? 'Retrieves documents relevant to the query from the knowledge base',
+        inputSchema: z.object({ query: z.string().describe('search query') }),
+        execute: async ({ query }) => {
+            const embedding = await opts.embed(query);
+            let matches = await opts.store.query(embedding, opts.topK ?? 4, {
+                ...(opts.namespace !== undefined ? { namespace: opts.namespace } : {}),
+                ...(opts.filter !== undefined ? { filter: opts.filter } : {}),
+            });
+            if (opts.rerank)
+                matches = await opts.rerank.rerank(query, matches, opts.rerankTopK);
+            return matches.map((m) => ({
+                text: m.text,
+                score: Number(m.score.toFixed(4)),
+                ...(m.metadata ? { metadata: m.metadata } : {}),
+            }));
+        },
+    }), { idempotent: true });
+}
+//# sourceMappingURL=rag-tool.js.map

package/dist/rag-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rag-tool.js","sourceRoot":"","sources":["../src/rag-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAE1B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAyB7B;IACC,mFAAmF;IACnF,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QACxB,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,mEAAmE;QACpG,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACrE,OAAO,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;YAC3B,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1C,IAAI,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE;gBAC9D,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9D,CAAC,CAAC;YACH,IAAI,IAAI,CAAC,MAAM;gBAAE,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YACrF,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAU,EAAE,CAAC,CAAC;gBACjC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBACjC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChD,CAAC,CAAC,CAAC;QACN,CAAC;KACF,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;AAC5B,CAAC","sourcesContent":["import { tool } from 'ai';\nimport type { Tool } from 'ai';\nimport { z } from 'zod';\nimport type { VectorStore, Embed } from './vector-store.js';\nimport type { Reranker } from './rerank.js';\n\n/** One retrieved document as the tool reports it. Named so the tool's public type can be declared. */\nexport interface RagHit {\n  text: string;\n  score: number;\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * RAG tool that an agent can call. When used inside `runDurable`, `durableTool` journals its result\n * → **replayable & exactly-once RAG** (same documents on resume; no new embed/query call).\n * Most RAG implementations don't give this guarantee. If `rerank` is provided, vector results are reordered\n * by the LLM (the rerank call is also journaled → replayable).\n */\nexport function createRagTool(opts: {\n  store: VectorStore;\n  embed: Embed;\n  topK?: number;\n  description?: string;\n  /** LLM reranker: reorders the initially fetched `topK` results. */\n  rerank?: Reranker;\n  /** Number of results to keep after rerank. */\n  rerankTopK?: number;\n  /**\n   * The slice of the corpus this tool may retrieve from.\n   *\n   * There was no way to express this, and the tool never passed `QueryOptions` to the store at all —\n   * so `namespace`, the only isolation mechanism the store layer has, was unreachable through the one\n   * documented RAG path. Every agent built from this tool searched the whole index, and every shipped\n   * example (README, both GUIDEs, the scaffold recipe, the docs-mcp entry) does exactly that.\n   *\n   * Build one tool per organization with their namespace, or pass a function to resolve it per call.\n   */\n  namespace?: string;\n  /** Metadata narrowing, applied by the store alongside `namespace`. */\n  filter?: Record<string, unknown>;\n// Declared, not inferred: inference makes the emitted .d.ts name a pnpm-internal provider-utils\n// path (TS2742) — a package this one neither declares nor should. `Tool` comes from `ai`, the peer\n// we already require.\n}): Tool<{ query: string }, RagHit[]> & { idempotent: boolean } {\n  // H7: read-only search — safe to re-run → idempotent (keeps retry/reclaim smooth).\n  return Object.assign(tool({\n    description: opts.description ?? 'Retrieves documents relevant to the query from the knowledge base',\n    inputSchema: z.object({ query: z.string().describe('search query') }),\n    execute: async ({ query }) => {\n      const embedding = await opts.embed(query);\n      let matches = await opts.store.query(embedding, opts.topK ?? 4, {\n        ...(opts.namespace !== undefined ? { namespace: opts.namespace } : {}),\n        ...(opts.filter !== undefined ? { filter: opts.filter } : {}),\n      });\n      if (opts.rerank) matches = await opts.rerank.rerank(query, matches, opts.rerankTopK);\n      return matches.map((m): RagHit => ({\n        text: m.text,\n        score: Number(m.score.toFixed(4)),\n        ...(m.metadata ? { metadata: m.metadata } : {}),\n      }));\n    },\n  }), { idempotent: true });\n}\n"]}

package/dist/rerank.d.ts

@@ -0,0 +1,8 @@
+import type { VectorMatch } from './vector-store.js';
+export interface Reranker {
+    rerank(query: string, matches: VectorMatch[], topN?: number): Promise<VectorMatch[]>;
+}
+/** Reranker that asks the model to order documents by relevance. */
+export declare function llmReranker(opts: {
+    model: any;
+}): Reranker;

package/dist/rerank.js

@@ -0,0 +1,38 @@
+// LLM reranker: reorders vector results by relevance to the query. When used inside createRagTool,
+// the rerank LLM call also becomes part of the tool's result → durableTool journals it → **replayable rerank** (most RAG implementations don't have this).
+import { generateText } from 'ai';
+/** Extracts valid, deduplicated indices from the text (the model responds like "2,0,1"). */
+function parseIndices(text, n) {
+    const seen = new Set();
+    const out = [];
+    for (const m of text.matchAll(/\d+/g)) {
+        const i = Number(m[0]);
+        if (i >= 0 && i < n && !seen.has(i)) {
+            seen.add(i);
+            out.push(i);
+        }
+    }
+    return out;
+}
+/** Reranker that asks the model to order documents by relevance. */
+export function llmReranker(opts) {
+    return {
+        async rerank(query, matches, topN) {
+            if (matches.length <= 1)
+                return topN ? matches.slice(0, topN) : matches;
+            const list = matches.map((m, i) => `[${i}] ${m.text}`).join('\n');
+            const { text } = await generateText({
+                model: opts.model,
+                system: 'Give the indices of the documents most relevant to the query, ordered from most to least relevant, separated by commas. Indices only.',
+                prompt: `Query: ${query}\n\nDocuments:\n${list}`,
+            });
+            const order = parseIndices(text, matches.length);
+            const reranked = order.map((i) => matches[i]);
+            for (let i = 0; i < matches.length; i++)
+                if (!order.includes(i))
+                    reranked.push(matches[i]); // unmentioned ones go last
+            return topN ? reranked.slice(0, topN) : reranked;
+        },
+    };
+}
+//# sourceMappingURL=rerank.js.map

package/dist/rerank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.js","sourceRoot":"","sources":["../src/rerank.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,2JAA2J;AAC3J,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAOlC,4FAA4F;AAC5F,SAAS,YAAY,CAAC,IAAY,EAAE,CAAS;IAC3C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,IAAoB;IAC9C,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI;YAC/B,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;YACxE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,YAAY,CAAC;gBAClC,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,MAAM,EAAE,uIAAuI;gBAC/I,MAAM,EAAE,UAAU,KAAK,mBAAmB,IAAI,EAAE;aACjD,CAAC,CAAC;YACH,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YACjD,MAAM,QAAQ,GAAkB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC;YAC9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE;gBAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;oBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,2BAA2B;YACxH,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACnD,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// LLM reranker: reorders vector results by relevance to the query. When used inside createRagTool,\n// the rerank LLM call also becomes part of the tool's result → durableTool journals it → **replayable rerank** (most RAG implementations don't have this).\nimport { generateText } from 'ai';\nimport type { VectorMatch } from './vector-store.js';\n\nexport interface Reranker {\n  rerank(query: string, matches: VectorMatch[], topN?: number): Promise<VectorMatch[]>;\n}\n\n/** Extracts valid, deduplicated indices from the text (the model responds like \"2,0,1\"). */\nfunction parseIndices(text: string, n: number): number[] {\n  const seen = new Set<number>();\n  const out: number[] = [];\n  for (const m of text.matchAll(/\\d+/g)) {\n    const i = Number(m[0]);\n    if (i >= 0 && i < n && !seen.has(i)) {\n      seen.add(i);\n      out.push(i);\n    }\n  }\n  return out;\n}\n\n/** Reranker that asks the model to order documents by relevance. */\nexport function llmReranker(opts: { model: any }): Reranker {\n  return {\n    async rerank(query, matches, topN) {\n      if (matches.length <= 1) return topN ? matches.slice(0, topN) : matches;\n      const list = matches.map((m, i) => `[${i}] ${m.text}`).join('\\n');\n      const { text } = await generateText({\n        model: opts.model,\n        system: 'Give the indices of the documents most relevant to the query, ordered from most to least relevant, separated by commas. Indices only.',\n        prompt: `Query: ${query}\\n\\nDocuments:\\n${list}`,\n      });\n      const order = parseIndices(text, matches.length);\n      const reranked: VectorMatch[] = order.map((i) => matches[i]!);\n      for (let i = 0; i < matches.length; i++) if (!order.includes(i)) reranked.push(matches[i]!); // unmentioned ones go last\n      return topN ? reranked.slice(0, topN) : reranked;\n    },\n  };\n}\n"]}

package/dist/semantic-memory.d.ts

@@ -0,0 +1,41 @@
+import type { Memory, Journal } from '@gnldev/durable';
+import type { Embed } from './vector-store.js';
+export interface SemanticMemoryOptions {
+    journal: Journal;
+    embed: Embed;
+    /** The most recent N messages always included (default 6). */
+    recentN?: number;
+    /** Number of relevant old messages recalled based on the query (default 3). */
+    topK?: number;
+}
+/**
+ * P1.5 the same recall knobs @gnldev/durable's `RecallOptions` exposes, wired
+ * through SemanticMemory's local (journal-backed) cosine recall — `Memory.getMessages`'s `opts` is
+ * structurally wider here than the base interface (bivariant method params), so this is call-compatible
+ * with plain `{query}` callers.
+ */
+export interface SemanticGetMessagesOptions {
+    query?: string;
+    /** Minimum cosine similarity to be a candidate (default 0 — any positive score). */
+    threshold?: number;
+    /** Expand each hit with its before/after neighbors BY LOG POSITION; `n` is sugar for `{before:n,after:n}`. */
+    messageRange?: number | {
+        before: number;
+        after: number;
+    };
+    /** Metadata filter (same operator subset as `@gnldev/durable`'s `matchFilter`), applied BEFORE topK selection. */
+    filter?: Record<string, unknown>;
+}
+export declare class SemanticMemory implements Memory {
+    private journal;
+    private embed;
+    private recentN;
+    private topK;
+    constructor(opts: SemanticMemoryOptions);
+    private key;
+    private load;
+    getMessages(threadId: string, opts?: SemanticGetMessagesOptions): Promise<any[]>;
+    append(threadId: string, messages: any[]): Promise<void>;
+    getWorkingMemory(threadId: string): Promise<string | undefined>;
+    setWorkingMemory(threadId: string, value: string): Promise<void>;
+}

package/dist/semantic-memory.js

@@ -0,0 +1,90 @@
+// SemanticMemory — the semantic-recall version of @gnldev/durable's Memory. Embeds past messages and
+// stores them in the journal; when a new turn (query) arrives, retrieves relevant OLD messages via
+// vector search. Durable/replayable: the recall result falls into runDurable's input journaling
+// (frozen on resume); embeddings persist in the journal. (Most semantic-recall implementations don't come with these guarantees.)
+import { cosineSimilarity } from 'ai';
+import { matchFilter } from '@gnldev/durable';
+function normRange(r) {
+    if (r == null)
+        return { before: 0, after: 0 };
+    return typeof r === 'number' ? { before: r, after: r } : r;
+}
+function messageText(m) {
+    if (typeof m?.content === 'string')
+        return m.content || undefined;
+    if (Array.isArray(m?.content)) {
+        const t = m.content.filter((p) => typeof p?.text === 'string').map((p) => p.text).join(' ');
+        return t || undefined;
+    }
+    return undefined;
+}
+const hasNorm = (v) => !!v && v.some((x) => x !== 0);
+export class SemanticMemory {
+    journal;
+    embed;
+    recentN;
+    topK;
+    constructor(opts) {
+        this.journal = opts.journal;
+        this.embed = opts.embed;
+        this.recentN = opts.recentN ?? 6;
+        this.topK = opts.topK ?? 3;
+    }
+    key(threadId) {
+        return `sem:${threadId}:log`;
+    }
+    async load(threadId) {
+        return (await this.journal.get(this.key(threadId))) ?? [];
+    }
+    async getMessages(threadId, opts) {
+        const log = await this.load(threadId);
+        if (log.length <= this.recentN)
+            return log.map((e) => e.message);
+        const recentStart = log.length - this.recentN;
+        const recent = log.slice(recentStart);
+        if (!opts?.query)
+            return recent.map((e) => e.message);
+        const q = await this.embed(opts.query);
+        if (!hasNorm(q))
+            return recent.map((e) => e.message);
+        // P1.5 threshold + filter apply BEFORE topK slicing (a filtered-out /
+        // below-threshold candidate must not consume a topK slot) — same order as MemoryStore.recall.
+        const threshold = opts.threshold ?? 0;
+        let scored = log
+            .map((e, i) => ({ i, e, score: hasNorm(e.embedding) ? cosineSimilarity(q, e.embedding) : -1 }))
+            .filter((s) => s.i < recentStart) // candidates come from the OLDER portion only (unchanged from before P1.5)
+            .filter((s) => s.score > 0 && s.score >= threshold);
+        if (opts.filter)
+            scored = scored.filter((s) => matchFilter(s.e.metadata, opts.filter));
+        scored.sort((a, b) => b.score - a.score);
+        const hits = scored.slice(0, this.topK);
+        // messageRange: expand each hit with its before/after neighbors BY LOG POSITION, dedup overlapping
+        // windows, exclude anything already covered by `recent` (avoid duplicating a message twice).
+        const range = normRange(opts.messageRange);
+        const picked = new Map();
+        for (const h of hits) {
+            const lo = Math.max(0, h.i - range.before);
+            const hi = Math.min(log.length - 1, h.i + range.after);
+            for (let idx = lo; idx <= hi && idx < recentStart; idx++)
+                picked.set(idx, log[idx]);
+        }
+        const recalled = [...picked.entries()].sort((a, b) => a[0] - b[0]).map(([, e]) => e.message);
+        return [...recalled, ...recent.map((e) => e.message)];
+    }
+    async append(threadId, messages) {
+        const log = await this.load(threadId);
+        for (const message of messages) {
+            const text = messageText(message);
+            const embedding = text ? await this.embed(text) : undefined;
+            log.push({ message, text, embedding, metadata: message?.metadata });
+        }
+        await this.journal.put(this.key(threadId), log);
+    }
+    async getWorkingMemory(threadId) {
+        return this.journal.get(`mem:${threadId}:working`);
+    }
+    async setWorkingMemory(threadId, value) {
+        await this.journal.put(`mem:${threadId}:working`, value);
+    }
+}
+//# sourceMappingURL=semantic-memory.js.map

package/dist/semantic-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-memory.js","sourceRoot":"","sources":["../src/semantic-memory.ts"],"names":[],"mappings":"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","sourcesContent":["// SemanticMemory — the semantic-recall version of @gnldev/durable's Memory. Embeds past messages and\n// stores them in the journal; when a new turn (query) arrives, retrieves relevant OLD messages via\n// vector search. Durable/replayable: the recall result falls into runDurable's input journaling\n// (frozen on resume); embeddings persist in the journal. (Most semantic-recall implementations don't come with these guarantees.)\nimport { cosineSimilarity } from 'ai';\nimport { matchFilter } from '@gnldev/durable';\nimport type { Memory, Journal } from '@gnldev/durable';\nimport type { Embed } from './vector-store.js';\n\nexport interface SemanticMemoryOptions {\n  journal: Journal;\n  embed: Embed;\n  /** The most recent N messages always included (default 6). */\n  recentN?: number;\n  /** Number of relevant old messages recalled based on the query (default 3). */\n  topK?: number;\n}\n\n/**\n * P1.5 the same recall knobs @gnldev/durable's `RecallOptions` exposes, wired\n * through SemanticMemory's local (journal-backed) cosine recall — `Memory.getMessages`'s `opts` is\n * structurally wider here than the base interface (bivariant method params), so this is call-compatible\n * with plain `{query}` callers.\n */\nexport interface SemanticGetMessagesOptions {\n  query?: string;\n  /** Minimum cosine similarity to be a candidate (default 0 — any positive score). */\n  threshold?: number;\n  /** Expand each hit with its before/after neighbors BY LOG POSITION; `n` is sugar for `{before:n,after:n}`. */\n  messageRange?: number | { before: number; after: number };\n  /** Metadata filter (same operator subset as `@gnldev/durable`'s `matchFilter`), applied BEFORE topK selection. */\n  filter?: Record<string, unknown>;\n}\n\ninterface LogEntry {\n  message: any;\n  text?: string;\n  embedding?: number[];\n  metadata?: Record<string, unknown>;\n}\n\nfunction normRange(r?: number | { before: number; after: number }): { before: number; after: number } {\n  if (r == null) return { before: 0, after: 0 };\n  return typeof r === 'number' ? { before: r, after: r } : r;\n}\n\nfunction messageText(m: any): string | undefined {\n  if (typeof m?.content === 'string') return m.content || undefined;\n  if (Array.isArray(m?.content)) {\n    const t = m.content.filter((p: any) => typeof p?.text === 'string').map((p: any) => p.text).join(' ');\n    return t || undefined;\n  }\n  return undefined;\n}\n\nconst hasNorm = (v?: number[]): v is number[] => !!v && v.some((x) => x !== 0);\n\nexport class SemanticMemory implements Memory {\n  private journal: Journal;\n  private embed: Embed;\n  private recentN: number;\n  private topK: number;\n\n  constructor(opts: SemanticMemoryOptions) {\n    this.journal = opts.journal;\n    this.embed = opts.embed;\n    this.recentN = opts.recentN ?? 6;\n    this.topK = opts.topK ?? 3;\n  }\n\n  private key(threadId: string) {\n    return `sem:${threadId}:log`;\n  }\n  private async load(threadId: string): Promise<LogEntry[]> {\n    return (await this.journal.get<LogEntry[]>(this.key(threadId))) ?? [];\n  }\n\n  async getMessages(threadId: string, opts?: SemanticGetMessagesOptions): Promise<any[]> {\n    const log = await this.load(threadId);\n    if (log.length <= this.recentN) return log.map((e) => e.message);\n    const recentStart = log.length - this.recentN;\n    const recent = log.slice(recentStart);\n\n    if (!opts?.query) return recent.map((e) => e.message);\n    const q = await this.embed(opts.query);\n    if (!hasNorm(q)) return recent.map((e) => e.message);\n\n    // P1.5 threshold + filter apply BEFORE topK slicing (a filtered-out /\n    // below-threshold candidate must not consume a topK slot) — same order as MemoryStore.recall.\n    const threshold = opts.threshold ?? 0;\n    let scored = log\n      .map((e, i) => ({ i, e, score: hasNorm(e.embedding) ? cosineSimilarity(q, e.embedding!) : -1 }))\n      .filter((s) => s.i < recentStart) // candidates come from the OLDER portion only (unchanged from before P1.5)\n      .filter((s) => s.score > 0 && s.score >= threshold);\n    if (opts.filter) scored = scored.filter((s) => matchFilter(s.e.metadata, opts.filter!));\n    scored.sort((a, b) => b.score - a.score);\n    const hits = scored.slice(0, this.topK);\n\n    // messageRange: expand each hit with its before/after neighbors BY LOG POSITION, dedup overlapping\n    // windows, exclude anything already covered by `recent` (avoid duplicating a message twice).\n    const range = normRange(opts.messageRange);\n    const picked = new Map<number, LogEntry>();\n    for (const h of hits) {\n      const lo = Math.max(0, h.i - range.before);\n      const hi = Math.min(log.length - 1, h.i + range.after);\n      for (let idx = lo; idx <= hi && idx < recentStart; idx++) picked.set(idx, log[idx]!);\n    }\n    const recalled = [...picked.entries()].sort((a, b) => a[0] - b[0]).map(([, e]) => e.message);\n\n    return [...recalled, ...recent.map((e) => e.message)];\n  }\n\n  async append(threadId: string, messages: any[]): Promise<void> {\n    const log = await this.load(threadId);\n    for (const message of messages) {\n      const text = messageText(message);\n      const embedding = text ? await this.embed(text) : undefined;\n      log.push({ message, text, embedding, metadata: message?.metadata });\n    }\n    await this.journal.put(this.key(threadId), log);\n  }\n\n  async getWorkingMemory(threadId: string): Promise<string | undefined> {\n    return this.journal.get<string>(`mem:${threadId}:working`);\n  }\n  async setWorkingMemory(threadId: string, value: string): Promise<void> {\n    await this.journal.put(`mem:${threadId}:working`, value);\n  }\n}\n"]}