@jungjaehoon/mama-core 1.3.3 → 1.4.0

package/README.md

@@ -74,12 +74,40 @@ const mamaApi = require('@jungjaehoon/mama-core/mama-api');
   - CRUD operations for decisions
   - Vector similarity search
 
-### Core API
+### Memory API
 
-- **mama-api** - High-level API interface
+- **memory/api** - Scoped memory operations
+  - `saveMemory(input)` - Save typed memory with scopes and optional event_date (preference, fact, decision, lesson, constraint)
+  - `recallMemory(query, options)` - Truth-aware recall with scope filtering
+  - `buildProfile(scopes)` - Build memory profile (static/dynamic/evidence)
+  - `ingestMemory(input)` - Ingest raw content as memory
+  - `ingestConversation(input)` - Decompose conversations into typed memory units via optional LLM extraction
+  - `evolveMemory(input)` - Resolve graph edges between memories
+  - `buildMemoryBootstrap(params)` - Build memory agent bootstrap context
+  - `createAuditAck(input)` - Create audit acknowledgment
+  - `recordMemoryAudit(input)` - Record channel audit with state management
+
+- **memory/truth-store** - Truth projection layer
+  - `projectMemoryTruth(row)` - Write truth projection
+  - `queryRelevantTruth(params)` - Query current truth with scope/query filtering
+  - `queryTruthByTopic(topic)` - Get truth rows for a topic
+
+- **memory/evolution-engine** - Graph edge resolution
+  - `resolveMemoryEvolution(input)` - Determine supersedes/builds_on edges
+
+- **memory/extraction-prompt** - LLM extraction for conversation ingestion
+  - `buildExtractionPrompt(messages)` - Build structured prompt for memory extraction
+  - `parseExtractionResponse(response)` - Parse LLM JSON response into typed units
+
+- **memory/channel-summary-state-store** - Channel state management
+  - `recordChannelAudit(input)` - Accumulate audit outcomes into channel state
+
+### Core API (Legacy)
+
+- **mama-api** - High-level API interface (wraps memory API)
   - `save(decision)` - Save decision
   - `recall(topic)` - Retrieve decision history
-  - `suggest(query)` - Semantic search
+  - `suggest(query)` - Semantic search with hybrid FTS5 + vector + recency
   - `updateOutcome(id, outcome)` - Update decision outcome
 
 - **decision-tracker** - Decision graph management
@@ -125,12 +153,15 @@ pnpm test:watch
 
 ## Test Coverage
 
-- 35 unit tests
+- 72 unit tests across 17 test files
 - 100% passing
 - Tests cover:
-  - Config loader
-  - Database initialization
-  - Module exports
+  - Config loader, database initialization, module exports
+  - Memory API (save, recall, profile)
+  - Truth store, evolution engine, scope schema
+  - Channel summary, channel summary state
+  - Event store, finding store, bootstrap builder
+  - Legacy shim compatibility
 
 ## Architecture
 
@@ -139,23 +170,40 @@ MAMA Core uses CommonJS modules and is designed to be shared across multiple pac
 ```
 packages/mama-core/
 ├── src/
-│   ├── index.js              # Main exports
-│   ├── embeddings.js         # Embedding generation
-│   ├── db-manager.js         # Database management
-│   ├── mama-api.js           # High-level API
-│   └── db-adapter/           # Database adapter
-├── db/migrations/            # SQLite migrations
-└── tests/                    # Unit tests
+│   ├── index.ts              # Main exports
+│   ├── embeddings.ts         # Embedding generation
+│   ├── db-manager.ts         # Database management
+│   ├── mama-api.ts           # High-level API (wraps memory API)
+│   ├── db-adapter/           # Database adapter (SQLite)
+│   └── memory/               # Memory infrastructure
+│       ├── types.ts          # MemoryRecord, MemoryScopeRef, RecallBundle, etc.
+│       ├── api.ts            # saveMemory, recallMemory, buildProfile, etc.
+│       ├── truth-store.ts    # Truth projection layer
+│       ├── extraction-prompt.ts  # LLM extraction prompt + parser
+│       ├── evolution-engine.ts  # Graph edge resolution
+│       ├── scope-store.ts    # Scope management
+│       ├── event-store.ts    # Audit event persistence
+│       ├── finding-store.ts  # Audit finding persistence
+│       ├── channel-summary-store.ts       # Channel summaries
+│       ├── channel-summary-state-store.ts # Channel state reducer
+│       ├── bootstrap-builder.ts           # Memory agent bootstrap
+│       └── profile-builder.ts             # Profile classification
+├── db/migrations/            # SQLite migrations (001-023)
+└── tests/                    # 16 test files, 59 tests
 ```
 
 ## Migration Files
 
-Database migrations are included in `db/migrations/`:
+Database migrations are included in `db/migrations/` (001-023):
 
-- 001-initial-decision-graph.sql
-- 002-add-error-patterns.sql
-- 003-add-validation-fields.sql
-- (and more...)
+- 001-013: Core schema (decisions, embeddings, graph edges)
+- 014: Add is_static column
+- 015: FTS5 full-text search index
+- 016: Memory kind/status/summary columns
+- 017-018: Memory scopes and scope bindings
+- 019-020: Memory events and audit findings
+- 021: Memory truth projection
+- 022-023: Channel summaries and state
 
 ## License
 

package/db/migrations/001-initial-decision-graph.sql

@@ -100,7 +100,12 @@ CREATE TABLE IF NOT EXISTS sessions (
   -- Timestamps
   started_at INTEGER DEFAULT (unixepoch() * 1000),
   last_active_at INTEGER DEFAULT (unixepoch() * 1000),
+  last_active TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
   ended_at INTEGER,
+  status TEXT DEFAULT 'active',
+  pid INTEGER,
+  client_id TEXT,
 
   CHECK (action_count >= 0),
   CHECK (decision_count >= 0)

package/db/migrations/014-add-is-static-column.sql

@@ -0,0 +1,5 @@
+-- Add is_static column for user profile (long-term preferences vs current work)
+ALTER TABLE decisions ADD COLUMN is_static INTEGER DEFAULT 0;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (14, 'Add is_static column for user profile preferences');

package/db/migrations/015-add-fts5-search.sql

@@ -0,0 +1,34 @@
+-- FTS5 virtual table for keyword search
+CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts USING fts5(
+  topic, decision, reasoning,
+  content='decisions',
+  content_rowid='rowid'
+);
+
+-- Sync triggers for external content table
+CREATE TRIGGER IF NOT EXISTS decisions_ai AFTER INSERT ON decisions BEGIN
+  INSERT INTO decisions_fts(rowid, topic, decision, reasoning)
+  VALUES (new.rowid, new.topic, new.decision, new.reasoning);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_ad BEFORE DELETE ON decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, topic, decision, reasoning)
+  VALUES('delete', old.rowid, old.topic, old.decision, old.reasoning);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_au BEFORE UPDATE ON decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, topic, decision, reasoning)
+  VALUES('delete', old.rowid, old.topic, old.decision, old.reasoning);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_au2 AFTER UPDATE ON decisions BEGIN
+  INSERT INTO decisions_fts(rowid, topic, decision, reasoning)
+  VALUES (new.rowid, new.topic, new.decision, new.reasoning);
+END;
+
+-- Backfill existing decisions into FTS index
+INSERT INTO decisions_fts(rowid, topic, decision, reasoning)
+  SELECT rowid, topic, decision, reasoning FROM decisions;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (15, 'Add FTS5 keyword search with sync triggers');

package/db/migrations/016-add-memory-v2-columns.sql

@@ -0,0 +1,14 @@
+ALTER TABLE decisions ADD COLUMN kind TEXT DEFAULT 'decision'
+  CHECK (kind IN ('decision', 'preference', 'constraint', 'lesson', 'fact'));
+
+ALTER TABLE decisions ADD COLUMN status TEXT DEFAULT 'active'
+  CHECK (status IN ('active', 'superseded', 'contradicted', 'stale'));
+
+ALTER TABLE decisions ADD COLUMN summary TEXT;
+
+UPDATE decisions
+SET summary = decision
+WHERE summary IS NULL;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (16, 'Add memory v2 kind/status/summary columns');

package/db/migrations/017-create-memory-scopes.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS memory_scopes (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('global', 'user', 'channel', 'project')),
+  external_id TEXT NOT NULL,
+  created_at INTEGER DEFAULT (unixepoch() * 1000),
+  UNIQUE(kind, external_id)
+);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (17, 'Create memory scopes table');

package/db/migrations/018-create-memory-scope-bindings.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS memory_scope_bindings (
+  memory_id TEXT NOT NULL,
+  scope_id TEXT NOT NULL,
+  is_primary INTEGER DEFAULT 0 CHECK (is_primary IN (0, 1)),
+  created_at INTEGER DEFAULT (unixepoch() * 1000),
+  PRIMARY KEY (memory_id, scope_id),
+  FOREIGN KEY (memory_id) REFERENCES decisions(id) ON DELETE CASCADE,
+  FOREIGN KEY (scope_id) REFERENCES memory_scopes(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_scope_bindings_scope_id
+  ON memory_scope_bindings(scope_id);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (18, 'Create memory scope bindings table');

package/db/migrations/019-create-memory-events.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS memory_events (
+  event_id TEXT PRIMARY KEY,
+  event_type TEXT NOT NULL,
+  actor TEXT NOT NULL,
+  source_turn_id TEXT,
+  memory_id TEXT,
+  topic TEXT,
+  scope_refs TEXT NOT NULL,
+  evidence_refs TEXT,
+  reason TEXT,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_events_topic_created_at
+  ON memory_events(topic, created_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (19, 'Create memory events table');

package/db/migrations/020-create-audit-findings.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS audit_findings (
+  finding_id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  severity TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  evidence_refs TEXT NOT NULL,
+  affected_memory_ids TEXT NOT NULL,
+  recommended_action TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'open',
+  created_at INTEGER NOT NULL,
+  resolved_at INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_findings_status_created_at
+  ON audit_findings(status, created_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (20, 'Create audit findings table');

package/db/migrations/021-create-memory-truth.sql

@@ -0,0 +1,20 @@
+CREATE TABLE IF NOT EXISTS memory_truth (
+  memory_id TEXT PRIMARY KEY,
+  topic TEXT NOT NULL,
+  truth_status TEXT NOT NULL,
+  effective_summary TEXT NOT NULL,
+  effective_details TEXT NOT NULL,
+  trust_score REAL NOT NULL,
+  scope_refs TEXT NOT NULL,
+  supporting_event_ids TEXT NOT NULL,
+  superseded_by TEXT,
+  contradicted_by TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_truth_topic_updated_at
+  ON memory_truth(topic, updated_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (21, 'Create memory truth projection table');

package/db/migrations/022-create-channel-summaries.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS channel_summaries (
+  channel_key TEXT PRIMARY KEY,
+  summary_markdown TEXT NOT NULL,
+  delta_hash TEXT,
+  updated_at INTEGER NOT NULL
+);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (22, 'Create channel summaries table');

package/db/migrations/023-create-channel-summary-state.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS channel_summary_state (
+  channel_key TEXT PRIMARY KEY,
+  state_json TEXT NOT NULL,
+  state_hash TEXT NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (23, 'Create channel summary state table');

package/db/migrations/024-add-event-date.sql

@@ -0,0 +1,9 @@
+-- Migration 024: Add event_date column to decisions table
+-- event_date stores the ISO 8601 date when the event actually occurred
+-- (distinct from created_at which is ingestion time)
+ALTER TABLE decisions ADD COLUMN event_date TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_decisions_event_date ON decisions(event_date);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (24, 'Add event_date column for temporal tracking');

package/dist/db-adapter/base-adapter.d.ts

@@ -47,7 +47,7 @@ export declare abstract class DatabaseAdapter {
      * @param limit - Max results
      * @returns Search results with distance
      */
-    abstract vectorSearch(embedding: Float32Array | number[], limit: number): VectorSearchResult[] | null;
+    abstract vectorSearch(embedding: Float32Array | number[], limit: number, topicPrefix?: string): VectorSearchResult[] | null;
     /**
      * Insert vector embedding
      * @param rowid - Decision rowid

package/dist/db-adapter/index.js

@@ -24,14 +24,8 @@ Object.defineProperty(exports, "DatabaseAdapter", { enumerable: true, get: funct
  * @returns Configured SQLite adapter instance
  */
 function createAdapter(config = {}) {
-    const configuredDriver = process.env.MAMA_SQLITE_DRIVER;
-    if (configuredDriver &&
-        configuredDriver !== 'node-sqlite' &&
-        configuredDriver !== 'node:sqlite' &&
-        configuredDriver !== 'auto') {
-        throw new Error(`Unsupported SQLite driver "${configuredDriver}". MAMA now requires node:sqlite.`);
-    }
-    (0, debug_logger_js_1.info)('[db-adapter] Using node:sqlite adapter');
+    // SQLiteAdapter (extends NodeSQLiteAdapter) auto-detects: better-sqlite3 (preferred, FTS5) → node:sqlite (fallback)
+    (0, debug_logger_js_1.info)('[db-adapter] Creating SQLite adapter (auto-detect driver)');
     const dbPath = config.dbPath || process.env.MAMA_DB_PATH;
     return new sqlite_adapter_js_1.SQLiteAdapter({ dbPath });
 }

package/dist/db-adapter/node-sqlite-adapter.d.ts

@@ -24,6 +24,7 @@ interface NodeSQLiteStatementLike {
 declare class NodeSQLiteConnection {
     private db;
     private connected;
+    private isBetterSQLite3;
     constructor(db: NodeSQLiteDatabaseLike);
     prepare(sql: string): NodeSQLiteStatementLike;
     exec(sql: string): void;
@@ -37,16 +38,20 @@ export declare class NodeSQLiteAdapter extends DatabaseAdapter {
     private config;
     private db;
     private _vectorSearchEnabled;
+    private vectorCache;
+    private topicCache;
     constructor(config?: SQLiteAdapterConfig);
     get vectorSearchEnabled(): boolean;
     getDbPath(): string;
     connect(): NodeSQLiteConnection;
+    reloadVectorCache(): void;
+    private loadVectorCache;
     disconnect(): void;
     isConnected(): boolean;
     prepare(sql: string): Statement;
     exec(sql: string): void;
     transaction<T>(fn: () => T): T;
-    vectorSearch(embedding: Float32Array | number[], limit?: number): VectorSearchResult[] | null;
+    vectorSearch(embedding: Float32Array | number[], limit?: number, topicPrefix?: string): VectorSearchResult[] | null;
     insertEmbedding(rowid: number, embedding: Float32Array | number[]): RunResult | null;
     getLastInsertRowid(): number;
     runMigrations(migrationsDir: string): void;

package/dist/db-adapter/node-sqlite-adapter.js

@@ -18,19 +18,34 @@ const debug_logger_js_1 = require("../debug-logger.js");
 const embeddings_js_1 = require("../embeddings.js");
 const LEGACY_DB_PATH = path_1.default.join(os_1.default.homedir(), '.spinelift', 'memories.db');
 const DEFAULT_DB_PATH = path_1.default.join(os_1.default.homedir(), '.claude', 'mama-memory.db');
+// Prefer better-sqlite3 (includes FTS5) over node:sqlite (lacks FTS5)
+let BetterSQLite3 = null;
 let DatabaseSync = null;
 try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    ({ DatabaseSync } = require('node:sqlite'));
+    const bs3 = require('better-sqlite3');
+    BetterSQLite3 = 'default' in bs3 ? bs3.default : bs3;
 }
 catch {
-    DatabaseSync = null;
+    BetterSQLite3 = null;
+}
+if (!BetterSQLite3) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        ({ DatabaseSync } = require('node:sqlite'));
+    }
+    catch {
+        DatabaseSync = null;
+    }
 }
 class NodeSQLiteConnection {
     db;
     connected = true;
+    isBetterSQLite3;
     constructor(db) {
         this.db = db;
+        // better-sqlite3 databases have a native .pragma() method
+        this.isBetterSQLite3 = typeof db.pragma === 'function';
     }
     prepare(sql) {
         return this.db.prepare(sql);
@@ -40,6 +55,11 @@ class NodeSQLiteConnection {
     }
     pragma(sql, options) {
         const query = sql.trim().replace(/^PRAGMA\s+/i, '');
+        if (this.isBetterSQLite3) {
+            // better-sqlite3 has a native pragma method that handles both read and write pragmas
+            return this.db.pragma(query, options);
+        }
+        // node:sqlite fallback: use prepare()
         const stmt = this.db.prepare(`PRAGMA ${query}`);
         if (options?.simple) {
             const row = stmt.get();
@@ -65,6 +85,8 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
     config;
     db = null;
     _vectorSearchEnabled = true;
+    vectorCache = new Map();
+    topicCache = new Map();
     constructor(config = {}) {
         super();
         this.config = config;
@@ -90,27 +112,67 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
         if (this.db) {
             return this.db;
         }
-        if (!DatabaseSync) {
-            throw new Error('node:sqlite is not available in this Node.js runtime. Use Node 22.13+.');
+        const Driver = BetterSQLite3 || DatabaseSync;
+        if (!Driver) {
+            throw new Error('No SQLite driver available. Install better-sqlite3 or use Node 22.13+ (node:sqlite).');
         }
+        const driverName = BetterSQLite3 ? 'better-sqlite3' : 'node:sqlite';
         const dbPath = this.getDbPath();
         const dbDir = path_1.default.dirname(dbPath);
         if (!fs_1.default.existsSync(dbDir)) {
             fs_1.default.mkdirSync(dbDir, { recursive: true });
-            (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Created database directory: ${dbDir}`);
+            (0, debug_logger_js_1.info)(`[sqlite-adapter] Created database directory: ${dbDir}`);
         }
-        const database = new DatabaseSync(dbPath);
+        const database = new Driver(dbPath);
         this.db = new NodeSQLiteConnection(database);
-        (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Opened database at: ${dbPath}`);
+        (0, debug_logger_js_1.info)(`[sqlite-adapter] Opened database at: ${dbPath} (driver: ${driverName})`);
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('busy_timeout = 5000');
         this.db.pragma('synchronous = NORMAL');
         this.db.pragma('cache_size = -64000');
         this.db.pragma('temp_store = MEMORY');
         this.db.pragma('foreign_keys = ON');
-        (0, debug_logger_js_1.info)('[node-sqlite-adapter] Vector search: pure TS cosine similarity (no native extensions)');
+        (0, debug_logger_js_1.info)('[sqlite-adapter] Vector search: pure TS cosine similarity (no native extensions)');
+        this.loadVectorCache();
         return this.db;
     }
+    reloadVectorCache() {
+        this.loadVectorCache();
+    }
+    loadVectorCache() {
+        if (!this.db)
+            return;
+        const tableCheck = this.db
+            .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='embeddings'`)
+            .all();
+        if (tableCheck.length === 0) {
+            this.vectorCache.clear();
+            this.topicCache.clear();
+            return;
+        }
+        const start = Date.now();
+        const rows = this.db.prepare('SELECT rowid, embedding FROM embeddings').all();
+        const CACHE_WARN_THRESHOLD = 100_000;
+        this.vectorCache.clear();
+        for (const row of rows) {
+            const vec = bytesToVector(row.embedding);
+            if (vec) {
+                this.vectorCache.set(row.rowid, vec);
+            }
+        }
+        // Load topic cache for scoped vector search
+        this.topicCache.clear();
+        const topicRows = this.db.prepare('SELECT rowid, topic FROM decisions').all();
+        for (const row of topicRows) {
+            this.topicCache.set(row.rowid, row.topic);
+        }
+        const count = this.vectorCache.size;
+        const elapsed = Date.now() - start;
+        (0, debug_logger_js_1.info)(`[node-sqlite-adapter] Vector cache loaded: ${count} embeddings in ${elapsed}ms`);
+        if (count > CACHE_WARN_THRESHOLD) {
+            (0, debug_logger_js_1.warn)(`[node-sqlite-adapter] Vector cache holds ${count} embeddings — consider LRU eviction or on-demand loading for large datasets`);
+        }
+    }
     disconnect() {
         if (this.db) {
             this.db.close();
@@ -157,53 +219,39 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
             throw error;
         }
     }
-    vectorSearch(embedding, limit = 5) {
+    vectorSearch(embedding, limit = 5, topicPrefix) {
         if (!this.isConnected()) {
             throw new Error('Database not connected');
         }
         const queryVector = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
-        const tableCheck = this.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='embeddings'`).all();
-        if (tableCheck.length === 0) {
-            throw new Error('Embeddings table missing');
-        }
         const effectiveLimit = Math.max(limit, 1);
-        const batchSize = 500;
         const bestMatches = [];
-        let offset = 0;
-        let hasMoreRows = true;
-        while (hasMoreRows) {
-            const rows = this.prepare('SELECT rowid, embedding FROM embeddings LIMIT ? OFFSET ?').all(batchSize, offset);
-            if (rows.length === 0) {
-                hasMoreRows = false;
+        let minScore = -Infinity;
+        for (const [rowid, candidate] of this.vectorCache) {
+            if (candidate.length !== queryVector.length)
                 continue;
-            }
-            for (const row of rows) {
-                const candidate = bytesToVector(row.embedding);
-                if (!candidate)
-                    continue;
-                if (candidate.length !== queryVector.length) {
-                    (0, debug_logger_js_1.warn)(`Skipping rowid ${row.rowid}: dimension mismatch (${candidate.length} vs ${queryVector.length})`);
+            // Pre-filter by topic prefix before computing similarity
+            if (topicPrefix) {
+                const topic = this.topicCache.get(rowid);
+                if (!topic || !topic.startsWith(topicPrefix))
                     continue;
-                }
-                const similarity = (0, embeddings_js_1.cosineSimilarity)(candidate, queryVector);
-                const scoredRow = {
-                    rowid: row.rowid,
-                    similarity,
-                    distance: 1 - similarity,
-                };
-                if (bestMatches.length < effectiveLimit) {
-                    bestMatches.push(scoredRow);
-                    bestMatches.sort((a, b) => (b.similarity ?? 0) - (a.similarity ?? 0));
-                    continue;
-                }
-                const weakestMatch = bestMatches[bestMatches.length - 1];
-                if ((scoredRow.similarity ?? 0) > (weakestMatch.similarity ?? 0)) {
-                    bestMatches.pop();
-                    bestMatches.push(scoredRow);
+            }
+            const similarity = (0, embeddings_js_1.cosineSimilarity)(candidate, queryVector);
+            if (bestMatches.length < effectiveLimit) {
+                bestMatches.push({ rowid, similarity, distance: 1 - similarity });
+                if (bestMatches.length === effectiveLimit) {
                     bestMatches.sort((a, b) => (b.similarity ?? 0) - (a.similarity ?? 0));
+                    minScore = bestMatches[bestMatches.length - 1].similarity ?? -Infinity;
                 }
             }
-            offset += rows.length;
+            else if (similarity > minScore) {
+                bestMatches[bestMatches.length - 1] = { rowid, similarity, distance: 1 - similarity };
+                bestMatches.sort((a, b) => (b.similarity ?? 0) - (a.similarity ?? 0));
+                minScore = bestMatches[bestMatches.length - 1].similarity ?? -Infinity;
+            }
+        }
+        if (bestMatches.length < effectiveLimit) {
+            bestMatches.sort((a, b) => (b.similarity ?? 0) - (a.similarity ?? 0));
         }
         return bestMatches;
     }
@@ -217,7 +265,13 @@ class NodeSQLiteAdapter extends base_adapter_js_1.DatabaseAdapter {
       INSERT OR REPLACE INTO embeddings(rowid, embedding)
       VALUES (?, ?)
     `);
-        return stmt.run(rowid, buffer);
+        const result = stmt.run(rowid, buffer);
+        // Keep in-memory caches in sync
+        this.vectorCache.set(rowid, vec);
+        const topicRow = this.prepare('SELECT topic FROM decisions WHERE rowid = ?').get(rowid);
+        if (topicRow)
+            this.topicCache.set(rowid, topicRow.topic);
+        return result;
     }
     getLastInsertRowid() {
         if (!this.isConnected()) {