@adamrdrew/agent-memory-mcp 1.0.0

package/README.md

@@ -0,0 +1,109 @@
+# agent-memory-mcp
+
+MCP server for persistent agent memory, backed by [LanceDB](https://lancedb.com/) with hybrid BM25 + vector search. Gives AI agents the ability to store, search, and manage memories across sessions using the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+All data stays on your machine. Embeddings are generated locally using [all-MiniLM-L6-v2](https://huggingface.co/Xenova/all-MiniLM-L6-v2) via ONNX — no API keys, no network dependencies after initial setup.
+
+## Features
+
+- **Hybrid search** — combines BM25 full-text search with cosine vector similarity via Reciprocal Rank Fusion (RRF)
+- **Local embeddings** — runs Xenova/all-MiniLM-L6-v2 locally via ONNX, no external API calls
+- **12 memory categories** — structured taxonomy for organising memories
+- **Batch operations** — store multiple memories in a single call
+- **Hardcopy backup** — optional JSON file mirror of all mutations for human-readable backup
+- **Fully local** — all data stays on disk, no network dependencies after first model download
+
+## Installation
+
+Install the package globally first. This downloads the embedding model (~80 MB) so it's ready when the server starts:
+
+```bash
+npm install -g @adamrdrew/agent-memory-mcp
+```
+
+Then add the server to your MCP client configuration.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-memory": {
+      "command": "agent-memory-mcp",
+      "env": {
+        "MEMORY_DB_PATH": "/path/to/your/memory-db"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "agent-memory": {
+    "command": "agent-memory-mcp",
+    "env": {
+      "MEMORY_DB_PATH": "/path/to/your/memory-db"
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Required | Description |
+|---|---|---|
+| `MEMORY_DB_PATH` | Yes | Path to the LanceDB database directory |
+| `EMBEDDING_MODEL` | No | HuggingFace model ID (default: `Xenova/all-MiniLM-L6-v2`) |
+| `ENABLE_HARDCOPY` | No | Set to `true` to enable JSON file backup |
+| `HARDCOPY_PATH` | If hardcopy enabled | Directory for JSON mirror files |
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `store` | Store a single memory with content, category, and tags |
+| `store_batch` | Store multiple memories in one call |
+| `search` | Search memories by meaning and/or keywords. Supports hybrid, keyword, and semantic modes |
+| `recall` | Multi-topic contextual recall — searches multiple topics in parallel and includes recent memories |
+| `find_related` | Find memories similar to a specific memory |
+| `list_recent` | List most recent memories, optionally filtered by category |
+| `update` | Update an existing memory — re-embeds automatically if content changes |
+| `delete` | Permanently remove a memory by ID |
+| `stats` | Get database statistics: total count, breakdown by category, timestamps |
+
+## Search Modes
+
+The `search` tool supports three modes:
+
+- **`hybrid`** (default) — combines BM25 keyword scoring with vector similarity using RRF reranking. Falls back to semantic-only if the full-text index is unavailable.
+- **`keyword`** — BM25 full-text search only.
+- **`semantic`** — cosine vector similarity only.
+
+All modes support filtering by category, tags, and date range.
+
+## Memory Categories
+
+`code-solution` · `bug-fix` · `architecture` · `learning` · `tool-usage` · `debugging` · `performance` · `security` · `observation` · `personal` · `relationship` · `other`
+
+## Development
+
+```bash
+git clone https://github.com/adamrdrew/agent-memory-mcp.git
+cd agent-memory-mcp
+npm install
+npm run dev          # Run with tsx (no build step)
+npm run build        # Compile TypeScript to dist/
+npm test             # Run all tests
+npm run test:watch   # Run tests in watch mode
+```
+
+## License
+
+This project is licensed under the [GNU General Public License v3.0](LICENSE).

package/dist/embedder.d.ts

@@ -0,0 +1,11 @@
+import type { Embedder } from './types.js';
+export declare class TransformersEmbedder implements Embedder {
+    private extractor;
+    private readonly modelName;
+    constructor(modelName?: string);
+    initialize(): Promise<void>;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    dimensions(): number;
+    private requireExtractor;
+}

package/dist/embedder.js

@@ -0,0 +1,38 @@
+const EMBEDDING_DIMENSIONS = 384;
+export class TransformersEmbedder {
+    extractor = null;
+    modelName;
+    constructor(modelName = 'Xenova/all-MiniLM-L6-v2') {
+        this.modelName = modelName;
+    }
+    async initialize() {
+        const { pipeline } = await import('@xenova/transformers');
+        this.extractor = await pipeline('feature-extraction', this.modelName);
+    }
+    async embed(text) {
+        const extractor = this.requireExtractor();
+        const output = await extractor(text, { pooling: 'mean', normalize: true });
+        return Array.from(output.data);
+    }
+    async embedBatch(texts) {
+        const extractor = this.requireExtractor();
+        const output = await extractor(texts, { pooling: 'mean', normalize: true });
+        const data = output.data;
+        const dim = this.dimensions();
+        const vectors = [];
+        for (let i = 0; i < texts.length; i++) {
+            vectors.push(Array.from(data.slice(i * dim, (i + 1) * dim)));
+        }
+        return vectors;
+    }
+    dimensions() {
+        return EMBEDDING_DIMENSIONS;
+    }
+    requireExtractor() {
+        if (!this.extractor) {
+            throw new Error('Embedder not initialised. Call initialize() first.');
+        }
+        return this.extractor;
+    }
+}
+//# sourceMappingURL=embedder.js.map

package/dist/embedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.js","sourceRoot":"","sources":["../src/embedder.ts"],"names":[],"mappings":"AAEA,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,MAAM,OAAO,oBAAoB;IACvB,SAAS,GAA6B,IAAI,CAAC;IAClC,SAAS,CAAS;IAEnC,YAAY,YAAoB,yBAAyB;QACvD,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAC1D,IAAI,CAAC,SAAS,GAAG,MAAM,QAAQ,CAAC,oBAAoB,EAAE,IAAI,CAAC,SAAS,CAAsB,CAAC;IAC7F,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3E,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAoB,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,MAAM,IAAI,GAAG,MAAM,CAAC,IAAoB,CAAC;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAe,EAAE,CAAC;QAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,UAAU;QACR,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IAEO,gBAAgB;QACtB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF"}

package/dist/hardcopy-store.d.ts

@@ -0,0 +1,17 @@
+import type { Memory, MemoryCategory, MemoryStore, MemoryStats, SearchFilters, SearchMode, SearchResult, StoreRequest, UpdateRequest } from './types.js';
+export declare class HardcopyMemoryStore implements MemoryStore {
+    private readonly inner;
+    private readonly hardcopyPath;
+    constructor(inner: MemoryStore, hardcopyPath: string);
+    initialize(): Promise<void>;
+    store(request: StoreRequest): Promise<Memory>;
+    storeBatch(requests: StoreRequest[]): Promise<Memory[]>;
+    update(id: string, updates: UpdateRequest): Promise<Memory>;
+    delete(id: string): Promise<void>;
+    search(query: string, mode: SearchMode, filters: SearchFilters): Promise<SearchResult[]>;
+    findRelated(memoryId: string, limit: number): Promise<SearchResult[]>;
+    listRecent(limit: number, category?: MemoryCategory): Promise<Memory[]>;
+    stats(): Promise<MemoryStats>;
+    private writeHardcopy;
+    private deleteHardcopy;
+}

package/dist/hardcopy-store.js

@@ -0,0 +1,80 @@
+import { mkdir, writeFile, unlink } from 'fs/promises';
+import { join } from 'path';
+// ── HardcopyMemoryStore ─────────────────────────────────────────
+//
+// Transparent decorator that mirrors all mutations to plain JSON
+// files on disk. One file per memory, named {id}.json. Read
+// operations delegate straight through — the hardcopy is write-only.
+//
+// Hardcopy errors are logged to stderr but never propagate.
+// The primary store is the source of truth; the hardcopy is
+// a human-readable escape hatch.
+export class HardcopyMemoryStore {
+    inner;
+    hardcopyPath;
+    constructor(inner, hardcopyPath) {
+        this.inner = inner;
+        this.hardcopyPath = hardcopyPath;
+    }
+    async initialize() {
+        await this.inner.initialize();
+        await mkdir(this.hardcopyPath, { recursive: true });
+    }
+    // ── Mutations (mirrored to disk) ────────────────────────────
+    async store(request) {
+        const memory = await this.inner.store(request);
+        await this.writeHardcopy(memory);
+        return memory;
+    }
+    async storeBatch(requests) {
+        const memories = await this.inner.storeBatch(requests);
+        await Promise.all(memories.map(m => this.writeHardcopy(m)));
+        return memories;
+    }
+    async update(id, updates) {
+        const memory = await this.inner.update(id, updates);
+        await this.writeHardcopy(memory);
+        return memory;
+    }
+    async delete(id) {
+        await this.inner.delete(id);
+        await this.deleteHardcopy(id);
+    }
+    // ── Reads (pass through) ────────────────────────────────────
+    async search(query, mode, filters) {
+        return this.inner.search(query, mode, filters);
+    }
+    async findRelated(memoryId, limit) {
+        return this.inner.findRelated(memoryId, limit);
+    }
+    async listRecent(limit, category) {
+        return this.inner.listRecent(limit, category);
+    }
+    async stats() {
+        return this.inner.stats();
+    }
+    // ── Private ─────────────────────────────────────────────────
+    async writeHardcopy(memory) {
+        try {
+            const filePath = join(this.hardcopyPath, `${memory.id}.json`);
+            await writeFile(filePath, JSON.stringify(memory, null, 2) + '\n');
+        }
+        catch (err) {
+            console.error(`[hardcopy] Failed to write ${memory.id}:`, err);
+        }
+    }
+    async deleteHardcopy(id) {
+        try {
+            const filePath = join(this.hardcopyPath, `${id}.json`);
+            await unlink(filePath);
+        }
+        catch (err) {
+            // File may not exist (e.g. hardcopy was enabled after the memory
+            // was created). That's fine — don't log ENOENT noise.
+            if (err.code !== 'ENOENT') {
+                console.error(`[hardcopy] Failed to delete ${id}:`, err);
+            }
+        }
+    }
+}
+//# sourceMappingURL=hardcopy-store.js.map

package/dist/hardcopy-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hardcopy-store.js","sourceRoot":"","sources":["../src/hardcopy-store.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { TransformersEmbedder } from './embedder.js';
+import { HardcopyMemoryStore } from './hardcopy-store.js';
+import { LanceMemoryStore } from './memory-store.js';
+import { createServer } from './server.js';
+async function main() {
+    const dbPath = process.env.MEMORY_DB_PATH;
+    if (!dbPath) {
+        console.error('MEMORY_DB_PATH environment variable is required');
+        process.exit(1);
+    }
+    const modelName = process.env.EMBEDDING_MODEL ?? 'Xenova/all-MiniLM-L6-v2';
+    // ── Compose dependencies ──
+    const embedder = new TransformersEmbedder(modelName);
+    let store = new LanceMemoryStore(dbPath, embedder);
+    if (process.env.ENABLE_HARDCOPY === 'true' && process.env.HARDCOPY_PATH) {
+        store = new HardcopyMemoryStore(store, process.env.HARDCOPY_PATH);
+        console.error(`[hardcopy] Mirroring mutations to ${process.env.HARDCOPY_PATH}`);
+    }
+    const server = createServer(store);
+    // ── Initialise (download model on first run, connect to DB) ──
+    await embedder.initialize();
+    await store.initialize();
+    // ── Start MCP transport ──
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,yBAAyB,CAAC;IAE3E,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;IACrD,IAAI,KAAK,GAAgB,IAAI,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAEhE,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QACxE,KAAK,GAAG,IAAI,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAClE,OAAO,CAAC,KAAK,CAAC,qCAAqC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAEnC,gEAAgE;IAChE,MAAM,QAAQ,CAAC,UAAU,EAAE,CAAC;IAC5B,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;IAEzB,4BAA4B;IAC5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/memory-store.d.ts

@@ -0,0 +1,33 @@
+import type { Embedder, Memory, MemoryCategory, MemoryStore, MemoryStats, SearchFilters, SearchMode, SearchResult, StoreRequest, UpdateRequest } from './types.js';
+export declare class LanceMemoryStore implements MemoryStore {
+    private readonly dbPath;
+    private readonly embedder;
+    private db;
+    private table;
+    private ftsIndexCreated;
+    private reranker;
+    constructor(dbPath: string, embedder: Embedder);
+    initialize(): Promise<void>;
+    store(request: StoreRequest): Promise<Memory>;
+    storeBatch(requests: StoreRequest[]): Promise<Memory[]>;
+    search(query: string, mode?: SearchMode, filters?: SearchFilters): Promise<SearchResult[]>;
+    findRelated(memoryId: string, limit?: number): Promise<SearchResult[]>;
+    listRecent(limit?: number, category?: MemoryCategory): Promise<Memory[]>;
+    update(id: string, updates: UpdateRequest): Promise<Memory>;
+    delete(id: string): Promise<void>;
+    stats(): Promise<MemoryStats>;
+    private semanticSearch;
+    private keywordSearch;
+    private hybridSearch;
+    /**
+     * Ensures the LanceDB table exists. If the table does not exist, it is
+     * created with `seedRow` as initial data (LanceDB requires at least one
+     * row to infer the schema). Returns `true` if the table was just created
+     * and the seed row was inserted, `false` if the table already existed.
+     * Callers MUST check the return value to avoid double-inserting the seed.
+     */
+    private ensureTable;
+    private tryCreateFtsIndex;
+    private fetchById;
+    private buildRow;
+}

package/dist/memory-store.js

@@ -0,0 +1,310 @@
+import * as lancedb from '@lancedb/lancedb';
+// ── LanceMemoryStore ───────────────────────────────────────────────
+export class LanceMemoryStore {
+    dbPath;
+    embedder;
+    db = null;
+    table = null;
+    ftsIndexCreated = false;
+    reranker = null;
+    constructor(dbPath, embedder) {
+        this.dbPath = dbPath;
+        this.embedder = embedder;
+    }
+    async initialize() {
+        this.db = await lancedb.connect(this.dbPath);
+        this.reranker = await lancedb.rerankers.RRFReranker.create(60);
+        const names = await this.db.tableNames();
+        if (names.includes('memories')) {
+            this.table = await this.db.openTable('memories');
+            // Recreate FTS index with proper config (stemming, stop words, positions).
+            // replace: true makes this idempotent; negligible cost at our scale.
+            await this.tryCreateFtsIndex();
+        }
+    }
+    // ── Storage ────────────────────────────────────────────────────
+    async store(request) {
+        const row = await this.buildRow(request);
+        const seeded = await this.ensureTable(row);
+        if (!seeded) {
+            await this.table.add([row]);
+        }
+        return rowToMemory(row);
+    }
+    async storeBatch(requests) {
+        if (requests.length === 0)
+            return [];
+        const vectors = await this.embedder.embedBatch(requests.map(r => r.content));
+        const now = new Date().toISOString();
+        const rows = requests.map((req, i) => toRow(req, vectors[i], now));
+        const seeded = await this.ensureTable(rows[0]);
+        // If the table was just created, rows[0] was already inserted as
+        // seed data (LanceDB requires initial data to infer schema).
+        const remaining = seeded ? rows.slice(1) : rows;
+        if (remaining.length > 0) {
+            await this.table.add(remaining);
+        }
+        return rows.map(rowToMemory);
+    }
+    // ── Search ─────────────────────────────────────────────────────
+    async search(query, mode = 'hybrid', filters = {}) {
+        if (!this.table)
+            return [];
+        const limit = filters.limit ?? 10;
+        switch (mode) {
+            case 'semantic':
+                return this.semanticSearch(query, filters, limit);
+            case 'keyword':
+                return this.keywordSearch(query, filters, limit);
+            case 'hybrid':
+                return this.hybridSearch(query, filters, limit);
+        }
+    }
+    async findRelated(memoryId, limit = 5) {
+        if (!this.table)
+            return [];
+        const original = await this.fetchById(memoryId);
+        if (!original)
+            throw new Error(`Memory ${memoryId} not found`);
+        const results = await this.table
+            .query()
+            .nearestTo(original.vector)
+            .distanceType('cosine')
+            .limit(limit + 1)
+            .toArray();
+        return results
+            .filter((r) => r.id !== memoryId)
+            .slice(0, limit)
+            .map(resultToSearchResult);
+    }
+    async listRecent(limit = 10, category) {
+        if (!this.table)
+            return [];
+        let q = this.table.query();
+        if (category) {
+            q = q.where(`category = '${sanitise(category)}'`);
+        }
+        const rows = await q.toArray();
+        return rows
+            .map(rowToMemory)
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+            .slice(0, limit);
+    }
+    // ── Mutation ────────────────────────────────────────────────────
+    async update(id, updates) {
+        if (!this.table)
+            throw new Error('No memories stored yet');
+        const existing = await this.fetchById(id);
+        if (!existing)
+            throw new Error(`Memory ${id} not found`);
+        const content = updates.content ?? existing.content;
+        const category = updates.category ?? existing.category;
+        const tags = updates.tags ?? JSON.parse(existing.tags);
+        const now = new Date().toISOString();
+        const vector = updates.content
+            ? await this.embedder.embed(content)
+            : existing.vector;
+        const updatedRow = {
+            id,
+            content,
+            category,
+            tags: JSON.stringify(tags),
+            created_at: existing.created_at,
+            updated_at: now,
+            vector,
+        };
+        await this.table.delete(`id = '${sanitise(id)}'`);
+        await this.table.add([updatedRow]);
+        return rowToMemory(updatedRow);
+    }
+    async delete(id) {
+        if (!this.table)
+            throw new Error('No memories stored yet');
+        await this.table.delete(`id = '${sanitise(id)}'`);
+    }
+    // ── Stats ──────────────────────────────────────────────────────
+    async stats() {
+        if (!this.table) {
+            return { totalMemories: 0, byCategory: {}, oldestMemory: null, newestMemory: null };
+        }
+        const rows = (await this.table.query().toArray());
+        const memories = rows.map(rowToMemory);
+        const byCategory = {};
+        for (const m of memories) {
+            byCategory[m.category] = (byCategory[m.category] ?? 0) + 1;
+        }
+        const sorted = [...memories].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        return {
+            totalMemories: memories.length,
+            byCategory,
+            oldestMemory: sorted[0]?.createdAt ?? null,
+            newestMemory: sorted.at(-1)?.createdAt ?? null,
+        };
+    }
+    // ── Private: search strategies ─────────────────────────────────
+    async semanticSearch(query, filters, limit) {
+        const vector = await this.embedder.embed(query);
+        const overFetch = limit * 3;
+        let search = this.table.query().nearestTo(vector).distanceType('cosine').limit(overFetch);
+        search = applyWhereClause(search, filters);
+        const rows = await search.toArray();
+        return postFilter(rows, filters).slice(0, limit).map(resultToSearchResult);
+    }
+    async keywordSearch(query, filters, limit) {
+        try {
+            const overFetch = limit * 3;
+            let search = this.table.search(query, 'fts').limit(overFetch);
+            search = applyWhereClause(search, filters);
+            const rows = await search.toArray();
+            return postFilter(rows, filters).slice(0, limit).map(resultToSearchResult);
+        }
+        catch {
+            // FTS index may not exist yet; keyword search degrades gracefully.
+            return [];
+        }
+    }
+    async hybridSearch(query, filters, limit) {
+        if (!this.ftsIndexCreated || !this.reranker) {
+            // FTS index not available — degrade to semantic-only.
+            return this.semanticSearch(query, filters, limit);
+        }
+        try {
+            const vector = await this.embedder.embed(query);
+            const overFetch = limit * 3;
+            let search = this.table
+                .query()
+                .nearestTo(vector)
+                .distanceType('cosine')
+                .fullTextSearch(query)
+                .rerank(this.reranker)
+                .limit(overFetch);
+            search = applyWhereClause(search, filters);
+            const rows = await search.toArray();
+            return postFilter(rows, filters).slice(0, limit).map(resultToSearchResult);
+        }
+        catch {
+            // Built-in hybrid can fail if FTS index is stale or missing.
+            // Fall back to semantic-only.
+            return this.semanticSearch(query, filters, limit);
+        }
+    }
+    // ── Private: table management ──────────────────────────────────
+    /**
+     * Ensures the LanceDB table exists. If the table does not exist, it is
+     * created with `seedRow` as initial data (LanceDB requires at least one
+     * row to infer the schema). Returns `true` if the table was just created
+     * and the seed row was inserted, `false` if the table already existed.
+     * Callers MUST check the return value to avoid double-inserting the seed.
+     */
+    async ensureTable(seedRow) {
+        if (this.table)
+            return false;
+        this.table = await this.db.createTable('memories', [seedRow]);
+        await this.tryCreateFtsIndex();
+        return true;
+    }
+    async tryCreateFtsIndex() {
+        if (this.ftsIndexCreated || !this.table)
+            return;
+        try {
+            await this.table.createIndex('content', {
+                config: lancedb.Index.fts({
+                    withPosition: true,
+                    stem: true,
+                    language: 'English',
+                    removeStopWords: true,
+                    asciiFolding: true,
+                }),
+                replace: true,
+            });
+            this.ftsIndexCreated = true;
+        }
+        catch {
+            // Index creation may fail on very small tables; keyword search degrades gracefully.
+        }
+    }
+    async fetchById(id) {
+        if (!this.table)
+            return null;
+        const rows = await this.table.query().where(`id = '${sanitise(id)}'`).limit(1).toArray();
+        return rows[0] ?? null;
+    }
+    async buildRow(request) {
+        const vector = await this.embedder.embed(request.content);
+        const now = new Date().toISOString();
+        return toRow(request, vector, now);
+    }
+}
+// ── Pure functions ─────────────────────────────────────────────────
+function toRow(request, vector, timestamp) {
+    return {
+        id: crypto.randomUUID(),
+        content: request.content,
+        category: request.category,
+        tags: JSON.stringify(request.tags),
+        created_at: timestamp,
+        updated_at: timestamp,
+        vector,
+    };
+}
+function rowToMemory(row) {
+    return {
+        id: row.id,
+        content: row.content,
+        category: row.category,
+        tags: JSON.parse(row.tags),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function resultToSearchResult(row) {
+    // Three possible score fields depending on search mode:
+    //   _relevance_score — from the RRF reranker (hybrid search), higher = better
+    //   _distance — from vector search (cosine: 0–2 range), lower = better
+    //   _score — from FTS/BM25 search, higher = better
+    const relevanceScore = row._relevance_score;
+    const distance = row._distance;
+    const ftsScore = row._score;
+    let score;
+    if (relevanceScore != null) {
+        score = relevanceScore;
+    }
+    else if (distance != null) {
+        score = 1 / (1 + distance);
+    }
+    else if (ftsScore != null) {
+        score = ftsScore;
+    }
+    else {
+        score = 0;
+    }
+    return { memory: rowToMemory(row), score };
+}
+function applyWhereClause(search, filters) {
+    const clauses = [];
+    if (filters.category) {
+        clauses.push(`category = '${sanitise(filters.category)}'`);
+    }
+    if (filters.after) {
+        clauses.push(`created_at >= '${sanitise(filters.after)}'`);
+    }
+    if (filters.before) {
+        clauses.push(`created_at <= '${sanitise(filters.before)}'`);
+    }
+    if (clauses.length > 0) {
+        return search.where(clauses.join(' AND '));
+    }
+    return search;
+}
+function postFilter(rows, filters) {
+    if (!filters.tags || filters.tags.length === 0)
+        return rows;
+    return rows.filter(row => {
+        const tags = JSON.parse(row.tags);
+        return filters.tags.some(t => tags.includes(t));
+    });
+}
+function sanitise(value) {
+    return value.replace(/'/g, "''");
+}
+//# sourceMappingURL=memory-store.js.map