@j0hanz/memdb 1.0.10 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # memdb
 
-A SQLite-backed MCP memory server (on-disk by default, in-memory optional).
+A SQLite-backed MCP memory server with local workspace storage.
 
 [![npm version](https://img.shields.io/npm/v/@j0hanz/memdb.svg)](https://www.npmjs.com/package/@j0hanz/memdb)
 
@@ -12,13 +12,12 @@ A SQLite-backed MCP memory server (on-disk by default, in-memory optional).
 
 ## Features
 
-| Feature           | Description                                                       |
-| :---------------- | :---------------------------------------------------------------- |
-| Memory Storage    | Store text memories with tags, importance, and type               |
-| Full-Text Search  | FTS5-backed tokenized search with relevance ranking               |
-| Graph Connections | Link memories and traverse relationships                          |
-| Stats             | Memory, tag, and relationship counts + activity range             |
-| Local Privacy     | All data stored locally in SQLite (`.memdb/memory.db` by default) |
+| Feature          | Description                                                       |
+| :--------------- | :---------------------------------------------------------------- |
+| Memory Storage   | Store text memories with tags                                     |
+| Full-Text Search | FTS5-backed tokenized search with relevance ranking               |
+| Stats            | Memory and tag counts + activity range                            |
+| Local Privacy    | All data stored locally in SQLite (`.memdb/memory.db` by default) |
 
 ## Quick Start
 
@@ -58,25 +57,21 @@ npm install
 npm run build
 ```
 
-## Configuration
+## Storage
 
-The server uses a local SQLite database at `<cwd>/.memdb/memory.db` by default.
-The path is resolved to an absolute path unless you use `:memory:`.
+The server uses a local SQLite database at `<cwd>/.memdb/memory.db`. The
+directory is created automatically when needed. All data remains local to your
+workspace.
 
-### Environment Variables
+> **Tip:** Add `.memdb/` to your `.gitignore` to keep your memory database out of
+> version control:
+>
+> ```bash
+> echo ".memdb/" >> .gitignore
+> ```
 
-- `MEMDB_PATH`: Override the database path (`:memory:` for in-memory).
-- `MEMDB_LOG_LEVEL`: `info`, `warn`, or `error` (default: `info`).
-- `MEMDB_SHUTDOWN_TIMEOUT`: Shutdown timeout in ms (1000-60000, default: `5000`).
-
-### CLI Flags
-
-- `--db <path>`: Override the database path.
-- `--memory`: Use in-memory database (`:memory:`).
-- `--log-level <level>`: `info`, `warn`, or `error`.
-- `--shutdown-timeout <ms>`: Shutdown timeout in ms (1000-60000).
-
-Precedence: CLI flags > environment variables > defaults.
+To completely reset or remove all stored memories, simply delete the `.memdb/`
+folder. The server will create a fresh database on the next run.
 
 ## Tool Response Format
 
@@ -117,35 +112,36 @@ Example `content[0].text`:
 
 ### `store_memory`
 
-Store a new memory with optional tags and metadata.
+Store a new memory with tags.
 
-| Parameter    | Type     | Required | Default   | Description                                |
-| :----------- | :------- | :------- | :-------- | :----------------------------------------- |
-| `content`    | string   | Yes      | -         | The content of the memory (1-100000 chars) |
-| `tags`       | string[] | No       | -         | Tags (max 100, each 1-50 chars)            |
-| `importance` | number   | No       | `0`       | Importance score (0-10)                    |
-| `memoryType` | string   | No       | `general` | Type of memory (1-50 chars)                |
+| Parameter | Type     | Required | Default | Description                                         |
+| :-------- | :------- | :------- | :------ | :-------------------------------------------------- |
+| `content` | string   | Yes      | -       | The content of the memory (1-100000 chars)          |
+| `tags`    | string[] | Yes      | -       | Tags (1-100 tags, no whitespace, max 50 chars each) |
 
 **Returns:** `{ id, hash, isNew }`
 
 Notes:
 
 - Content is deduplicated by MD5 hash. Storing the same content again returns the same hash with `isNew: false`.
+- Tags must not contain whitespace. Use hyphens for compound words (e.g., `api-design`, `error-handling`).
 
 ### `search_memories`
 
-Full-text search with filters.
+Search memories by content and tags.
 
-| Parameter      | Type     | Required | Default | Description                       |
-| :------------- | :------- | :------- | :------ | :-------------------------------- |
-| `query`        | string   | Yes      | -       | Search query (1-1000 chars)       |
-| `limit`        | number   | No       | `10`    | Maximum number of results (1-100) |
-| `offset`       | number   | No       | `0`     | Pagination offset (0-1000)        |
-| `tags`         | string[] | No       | -       | Filter by tags (max 50)           |
-| `minRelevance` | number   | No       | -       | Minimum relevance score (0-1)     |
+| Parameter | Type   | Required | Default | Description                               |
+| :-------- | :----- | :------- | :------ | :---------------------------------------- |
+| `query`   | string | Yes      | -       | Search query (1-1000 chars, max 50 terms) |
 
 **Returns:** Array of search results (`Memory` + `relevance`).
 
+Notes:
+
+- Searches both memory content (full-text) and tags.
+- Returns up to 100 results, ranked by relevance.
+- Content matches rank higher than tag matches.
+
 ### `get_memory`
 
 Retrieve a specific memory by its hash.
@@ -166,58 +162,31 @@ Delete a memory by its hash.
 
 **Returns:** `{ deleted: true }`.
 
-### `link_memories`
-
-Create a relationship between two memories.
-
-| Parameter      | Type   | Required | Default | Description                          |
-| :------------- | :----- | :------- | :------ | :----------------------------------- |
-| `fromHash`     | string | Yes      | -       | Hash of the source memory (32 chars) |
-| `toHash`       | string | Yes      | -       | Hash of the target memory (32 chars) |
-| `relationType` | string | Yes      | -       | Type of relationship (1-50 chars)    |
-
-**Returns:** `{ linked: true }`.
-
-Notes:
-
-- Linking the same relation again is a no-op (idempotent).
-- Returns an error if either memory hash does not exist.
-
-### `get_related`
-
-Get memories related to a given memory.
-
-| Parameter      | Type   | Required | Default    | Description                    |
-| :------------- | :----- | :------- | :--------- | :----------------------------- |
-| `hash`         | string | Yes      | -          | Hash of the memory (32 chars)  |
-| `relationType` | string | No       | -          | Filter by relationship type    |
-| `depth`        | number | No       | `1`        | Traversal depth (1-3)          |
-| `direction`    | string | No       | `outgoing` | `outgoing`, `incoming`, `both` |
-
-**Returns:** Array of related memories (`Memory` + `relation_type`, `depth`).
-
 ### `memory_stats`
 
-Get database statistics and memory type breakdown.
+Get database statistics.
 
 _No parameters required._
 
-**Returns:** `{ memoryCount, relationshipCount, tagCount, memoryTypes, oldestMemory, newestMemory }`.
+**Returns:** `{ memoryCount, tagCount, oldestMemory, newestMemory }`.
 
 ### `update_memory`
 
-Update memory metadata (content cannot be changed).
+Update the content of a memory. Returns the new hash since changing content changes the hash.
 
-| Parameter    | Type     | Required | Default | Description                                 |
-| :----------- | :------- | :------- | :------ | :------------------------------------------ |
-| `hash`       | string   | Yes      | -       | MD5 hash (32 chars)                         |
-| `importance` | number   | No       | -       | New importance score (0-10)                 |
-| `memoryType` | string   | No       | -       | New memory type (1-50 chars)                |
-| `tags`       | string[] | No       | -       | Replace all tags (max 100, each 1-50 chars) |
-| `addTags`    | string[] | No       | -       | Tags to add (max 100, each 1-50 chars)      |
-| `removeTags` | string[] | No       | -       | Tags to remove (max 100, each 1-50 chars)   |
+| Parameter | Type     | Required | Default | Description                             |
+| :-------- | :------- | :------- | :------ | :-------------------------------------- |
+| `hash`    | string   | Yes      | -       | MD5 hash of memory to update (32 chars) |
+| `content` | string   | Yes      | -       | New content (1-100000 chars)            |
+| `tags`    | string[] | No       | -       | Replace tags (max 100, each 1-50 chars) |
 
-**Returns:** `{ updated: true, hash }`.
+**Returns:** `{ updated: true, oldHash, newHash }`.
+
+Notes:
+
+- If `tags` is omitted, existing tags are preserved.
+- If `tags` is provided, it replaces all existing tags for the memory.
+- Updating to content that already exists in another memory returns an error.
 
 ### Memory Fields
 
@@ -226,8 +195,6 @@ All memory-shaped responses include:
 - `id`: integer ID
 - `content`: original content string
 - `summary`: optional summary (currently unset by tools)
-- `importance`: integer 0-10
-- `memory_type`: string
 - `created_at`: timestamp string
 - `accessed_at`: timestamp string
 - `hash`: MD5 hash
@@ -283,32 +250,26 @@ Add to your `claude_desktop_config.json`:
 
 ## Limits & Constraints
 
-| Constraint                    | Value         | Description                                                                   |
-| :---------------------------- | :------------ | :---------------------------------------------------------------------------- |
-| **Max content length**        | 100,000 chars | Maximum characters in memory content                                          |
-| **Max query length**          | 1,000 chars   | Maximum characters in search query                                            |
-| **Max search terms**          | 50            | Maximum whitespace-separated terms per query                                  |
-| **Max search results**        | 100           | Maximum results returned from `search_memories`                               |
-| **Default search limit**      | 10            | Default `limit` for `search_memories`                                         |
-| **Max search offset**         | 1,000         | Maximum `offset` for `search_memories`                                        |
-| **Max tags per memory**       | 100           | Maximum number of tags when storing a memory                                  |
-| **Max tag length**            | 50 chars      | Maximum characters per tag                                                    |
-| **Max tags in search filter** | 50            | Maximum tags when filtering search results                                    |
-| **Max related memories**      | 1,000         | Maximum results from `get_related` queries                                    |
-| **Max traversal depth**       | 3             | Maximum depth for relationship traversal                                      |
-| **Importance range**          | 0-10          | Allowed range for `importance`                                                |
-| **Min relevance range**       | 0-1           | Allowed range for `minRelevance`                                              |
-| **Hash length**               | 32 chars      | MD5 hash length                                                               |
-| **Search mode**               | Tokenized OR  | Whitespace-split terms are quoted and OR'ed; FTS5 operators are not supported |
+| Constraint              | Value         | Description                                                                   |
+| :---------------------- | :------------ | :---------------------------------------------------------------------------- |
+| **Max content length**  | 100,000 chars | Maximum characters in memory content                                          |
+| **Max query length**    | 1,000 chars   | Maximum characters in search query                                            |
+| **Max search terms**    | 50            | Maximum whitespace-separated terms per query                                  |
+| **Max search results**  | 100           | Maximum results returned from `search_memories`                               |
+| **Min tags per memory** | 1             | At least one tag is required                                                  |
+| **Max tags per memory** | 100           | Maximum number of tags when storing a memory                                  |
+| **Max tag length**      | 50 chars      | Maximum characters per tag                                                    |
+| **Tag format**          | No whitespace | Tags cannot contain spaces or tabs; use hyphens for compound words            |
+| **Hash length**         | 32 chars      | MD5 hash length                                                               |
+| **Search mode**         | Tokenized OR  | Whitespace-split terms are quoted and OR'ed; FTS5 operators are not supported |
 
 ### Notes
 
 - **Content deduplication**: Memories are deduplicated using MD5 hashes.
 - **Search errors**: If FTS5 is unavailable, `search_memories` returns an error indicating the index is missing. Invalid query syntax returns an error with details.
 - **Search tokenization**: Queries are split on whitespace (max 50 terms); whitespace-only queries are rejected.
-- **Tag behavior**: Tags are de-duplicated per memory; exceeding tag limits throws an error.
-- **Bidirectional depth**: `get_related` with `direction: "both"` caps traversal depth at 2.
-- **Local storage**: All data is stored locally in `.memdb/memory.db` unless `:memory:` is used.
+- **Tag requirements**: At least one tag is required. Tags cannot contain whitespace; use hyphens for compound words (e.g., `api-design`).
+- **Local storage**: All data is stored locally in `.memdb/memory.db`.
 
 ## Development
 
@@ -338,28 +299,29 @@ Add to your `claude_desktop_config.json`:
 
 ```text
 src/
-|-- index.ts          # Server entry point (stdio transport)
-|-- core/             # SQLite setup + memory CRUD/search/relations
-|   |-- database.ts   # DB init + schema sync
-|   |-- memory-create.ts
-|   |-- memory-read.ts
-|   |-- memory-search.ts
-|   |-- memory-relations.ts
-|   |-- memory-updates.ts
-|   |-- memory-stats.ts
-|-- tools/            # Tool registration + handlers
-|   |-- definitions/  # Tool metadata + handlers
-|-- schemas/          # Zod input/output schemas
-|   |-- inputs.ts
-|   |-- outputs.ts
-|-- lib/              # Error/response helpers
-|-- types/            # TypeScript types
-`-- utils/            # Config + logger
+|-- index.ts                 # Server entry point (stdio transport)
+|-- config.ts                # CLI/env configuration
+|-- logger.ts                # stderr logger with level filtering
+|-- protocol-version-guard.ts # Reject unsupported MCP protocol versions
+|-- tools.ts                 # Tool registration + handlers
+|-- schemas.ts               # Zod input/output schemas
+|-- types.ts                 # Shared TypeScript types
+`-- core/                     # SQLite setup + memory CRUD/search
+    |-- db.ts                 # DB init + schema + helpers
+    |-- memory-read.ts        # Read + delete + stats
+    |-- memory-write.ts       # Create + update + tag handling
+    `-- search.ts             # FTS + tag search
 
 tests/
 `-- *.test.ts         # Node.js test runner tests
 ```
 
+## Troubleshooting
+
+- **`node:sqlite` / `DatabaseSync` not found**: Ensure Node.js >= 22.0.0.
+- **Search errors about FTS5**: FTS5 must be available; the server creates the
+  virtual table automatically, but your SQLite build must include FTS5 support.
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+export declare const config: {
+    dbPath: string;
+    logLevel: "info";
+};

package/dist/config.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import process from 'node:process';
+const DEFAULT_DB_PATH = path.join(process.cwd(), '.memdb', 'memory.db');
+const DEFAULT_LOG_LEVEL = 'info';
+const resolveDbPath = (env) => {
+    if (env.MEMDB_PATH === ':memory:')
+        return ':memory:';
+    return path.resolve(DEFAULT_DB_PATH);
+};
+export const config = {
+    dbPath: resolveDbPath(process.env),
+    logLevel: DEFAULT_LOG_LEVEL,
+};

package/dist/core/database-schema.d.ts

@@ -1,3 +1,2 @@
 export declare const SCHEMA_SQL = "\n  PRAGMA foreign_keys = ON;\n  PRAGMA journal_mode = WAL;\n  PRAGMA synchronous = NORMAL;\n\n  CREATE TABLE IF NOT EXISTS memories (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    content TEXT NOT NULL,\n    summary TEXT,\n    importance INTEGER DEFAULT 0,\n    memory_type TEXT DEFAULT 'general',\n    created_at TEXT DEFAULT CURRENT_TIMESTAMP,\n    accessed_at TEXT DEFAULT CURRENT_TIMESTAMP,\n    hash TEXT UNIQUE NOT NULL\n  ) STRICT;\n\n  CREATE TABLE IF NOT EXISTS tags (\n    memory_id INTEGER NOT NULL,\n    tag TEXT NOT NULL,\n    PRIMARY KEY (memory_id, tag),\n    FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE\n  ) STRICT;\n\n  CREATE INDEX IF NOT EXISTS idx_tags_tag_memory_id ON tags(tag, memory_id);\n\n  CREATE TABLE IF NOT EXISTS relationships (\n    id INTEGER PRIMARY KEY AUTOINCREMENT,\n    from_memory_id INTEGER NOT NULL,\n    to_memory_id INTEGER NOT NULL,\n    relation_type TEXT NOT NULL,\n    created_at TEXT DEFAULT CURRENT_TIMESTAMP,\n    FOREIGN KEY (from_memory_id) REFERENCES memories(id) ON DELETE CASCADE,\n    FOREIGN KEY (to_memory_id) REFERENCES memories(id) ON DELETE CASCADE,\n    UNIQUE(from_memory_id, to_memory_id, relation_type)\n  ) STRICT;\n\n  CREATE INDEX IF NOT EXISTS idx_relationships_to_memory_id ON relationships(to_memory_id);\n\n  CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(\n    content,\n    summary,\n    content_rowid='id'\n  );\n\n  CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN\n    INSERT INTO memories_fts(rowid, content, summary)\n    VALUES (new.id, new.content, new.summary);\n  END;\n\n  CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN\n    DELETE FROM memories_fts WHERE rowid = old.id;\n    INSERT INTO memories_fts(rowid, content, summary)\n    VALUES (new.id, new.content, new.summary);\n  END;\n\n  CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN\n    DELETE FROM memories_fts WHERE rowid = old.id;\n  END;\n";
 export declare const FTS_SYNC_SQL = "\n  INSERT INTO memories_fts(rowid, content, summary)\n  SELECT id, content, summary FROM memories\n  WHERE id NOT IN (SELECT rowid FROM memories_fts);\n";
-//# sourceMappingURL=database-schema.d.ts.map

package/dist/core/database-schema.js

@@ -62,4 +62,3 @@ export const FTS_SYNC_SQL = `
   SELECT id, content, summary FROM memories
   WHERE id NOT IN (SELECT rowid FROM memories_fts);
 `;
-//# sourceMappingURL=database-schema.js.map

package/dist/core/database.d.ts

@@ -1,4 +1,3 @@
 import { DatabaseSync } from 'node:sqlite';
 export declare const db: DatabaseSync;
 export declare const closeDb: () => void;
-//# sourceMappingURL=database.d.ts.map

package/dist/core/database.js

@@ -41,4 +41,3 @@ export const closeDb = () => {
         return;
     db.close();
 };
-//# sourceMappingURL=database.js.map

package/dist/core/db.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseSync, type StatementSync } from 'node:sqlite';
+import type { Memory, SearchResult } from '../types.js';
+export type DbRow = Record<string, unknown>;
+export declare const db: DatabaseSync;
+export declare const closeDb: () => void;
+export type SqlParam = string | number | bigint | null | Uint8Array;
+export declare const prepareCached: (sql: string) => StatementSync;
+export declare const executeAll: (stmt: StatementSync, ...params: SqlParam[]) => DbRow[];
+export declare const executeGet: (stmt: StatementSync, ...params: SqlParam[]) => DbRow | undefined;
+export declare const executeRun: (stmt: StatementSync, ...params: SqlParam[]) => {
+    changes: number | bigint;
+};
+export declare const withImmediateTransaction: <T>(operation: () => T) => T;
+export declare const toSafeInteger: (value: unknown, field: string) => number;
+export declare const mapRowToMemory: (row: DbRow) => Memory;
+export declare const mapRowToSearchResult: (row: DbRow) => SearchResult;

package/dist/core/db.js

@@ -0,0 +1,225 @@
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { config } from '../config.js';
+const SCHEMA_SQL = `
+  PRAGMA foreign_keys = ON;
+  PRAGMA journal_mode = WAL;
+  PRAGMA synchronous = NORMAL;
+
+  CREATE TABLE IF NOT EXISTS memories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    content TEXT NOT NULL,
+    summary TEXT,
+    importance INTEGER DEFAULT 0,
+    memory_type TEXT DEFAULT 'general',
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    accessed_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    hash TEXT UNIQUE NOT NULL
+  ) STRICT;
+
+  CREATE TABLE IF NOT EXISTS tags (
+    memory_id INTEGER NOT NULL,
+    tag TEXT NOT NULL,
+    PRIMARY KEY (memory_id, tag),
+    FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+  ) STRICT;
+
+  CREATE INDEX IF NOT EXISTS idx_tags_tag_memory_id ON tags(tag, memory_id);
+
+  CREATE TABLE IF NOT EXISTS relationships (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_memory_id INTEGER NOT NULL,
+    to_memory_id INTEGER NOT NULL,
+    relation_type TEXT NOT NULL,
+    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (from_memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+    FOREIGN KEY (to_memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+    UNIQUE(from_memory_id, to_memory_id, relation_type)
+  ) STRICT;
+
+  CREATE INDEX IF NOT EXISTS idx_relationships_to_memory_id ON relationships(to_memory_id);
+
+  CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+    content,
+    summary,
+    content_rowid='id'
+  );
+
+  CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, content, summary)
+    VALUES (new.id, new.content, new.summary);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+    DELETE FROM memories_fts WHERE rowid = old.id;
+    INSERT INTO memories_fts(rowid, content, summary)
+    VALUES (new.id, new.content, new.summary);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+    DELETE FROM memories_fts WHERE rowid = old.id;
+  END;
+`;
+const FTS_SYNC_SQL = `
+  INSERT INTO memories_fts(rowid, content, summary)
+  SELECT id, content, summary FROM memories
+  WHERE id NOT IN (SELECT rowid FROM memories_fts);
+`;
+const ensureDbDirectory = async (dbPath) => {
+    if (dbPath === ':memory:')
+        return;
+    await mkdir(path.dirname(dbPath), { recursive: true });
+};
+const isEnableDefensive = (value) => {
+    return typeof value === 'function';
+};
+const enableDefensiveMode = (database) => {
+    const enableDefensive = Reflect.get(database, 'enableDefensive');
+    if (!isEnableDefensive(enableDefensive))
+        return;
+    enableDefensive(true);
+};
+const initializeSchema = (database) => {
+    database.exec(SCHEMA_SQL);
+    database.exec(FTS_SYNC_SQL);
+};
+const createDatabase = (dbPath) => {
+    const database = new DatabaseSync(dbPath, {
+        timeout: 5000,
+        enableForeignKeyConstraints: true,
+        allowExtension: false,
+    });
+    enableDefensiveMode(database);
+    initializeSchema(database);
+    return database;
+};
+try {
+    await ensureDbDirectory(config.dbPath);
+}
+catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[ERROR] Failed to create database directory: ${message}`);
+    throw err;
+}
+export const db = createDatabase(config.dbPath);
+export const closeDb = () => {
+    if (!db.isOpen)
+        return;
+    db.close();
+};
+const MAX_CACHED_STATEMENTS = 200;
+const statementCache = new Map();
+const statementCacheOrder = [];
+const enforceStatementCacheLimit = () => {
+    if (statementCacheOrder.length <= MAX_CACHED_STATEMENTS)
+        return;
+    const oldestSql = statementCacheOrder.shift();
+    if (!oldestSql)
+        return;
+    statementCache.delete(oldestSql);
+};
+const isDbRow = (value) => {
+    return typeof value === 'object' && value !== null;
+};
+const toDbRowArray = (value) => {
+    if (!Array.isArray(value)) {
+        throw new Error('Expected rows array');
+    }
+    const rows = [];
+    for (const row of value) {
+        if (!isDbRow(row)) {
+            throw new Error('Invalid row');
+        }
+        rows.push(row);
+    }
+    return rows;
+};
+const toDbRowOrUndefined = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (!isDbRow(value)) {
+        throw new Error('Invalid row');
+    }
+    return value;
+};
+const toRunResult = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        throw new Error('Invalid run result');
+    }
+    const changes = Reflect.get(value, 'changes');
+    if (typeof changes !== 'number' && typeof changes !== 'bigint') {
+        throw new Error('Invalid run result');
+    }
+    return { changes };
+};
+export const prepareCached = (sql) => {
+    const cached = statementCache.get(sql);
+    if (cached)
+        return cached;
+    const stmt = db.prepare(sql);
+    statementCache.set(sql, stmt);
+    statementCacheOrder.push(sql);
+    enforceStatementCacheLimit();
+    return stmt;
+};
+export const executeAll = (stmt, ...params) => toDbRowArray(stmt.all(...params));
+export const executeGet = (stmt, ...params) => toDbRowOrUndefined(stmt.get(...params));
+export const executeRun = (stmt, ...params) => toRunResult(stmt.run(...params));
+export const withImmediateTransaction = (operation) => {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const result = operation();
+        db.exec('COMMIT');
+        return result;
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+};
+const createFieldError = (field) => new Error(`Invalid ${field}`);
+const toNumber = (value, field) => {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'bigint') {
+        const numeric = Number(value);
+        if (Number.isFinite(numeric))
+            return numeric;
+    }
+    throw createFieldError(field);
+};
+export const toSafeInteger = (value, field) => {
+    const numeric = toNumber(value, field);
+    if (!Number.isSafeInteger(numeric)) {
+        throw createFieldError(field);
+    }
+    return numeric;
+};
+const toString = (value, field) => {
+    if (typeof value === 'string')
+        return value;
+    throw createFieldError(field);
+};
+const toOptionalString = (value, field) => {
+    if (value === null || value === undefined)
+        return undefined;
+    return toString(value, field);
+};
+const toOptionalNumber = (value, field) => {
+    if (value === null || value === undefined)
+        return undefined;
+    return toNumber(value, field);
+};
+export const mapRowToMemory = (row) => ({
+    id: toSafeInteger(row.id, 'id'),
+    content: toString(row.content, 'content'),
+    summary: toOptionalString(row.summary, 'summary'),
+    created_at: toString(row.created_at, 'created_at'),
+    accessed_at: toString(row.accessed_at, 'accessed_at'),
+    hash: toString(row.hash, 'hash'),
+});
+export const mapRowToSearchResult = (row) => ({
+    ...mapRowToMemory(row),
+    relevance: toOptionalNumber(row.relevance, 'relevance') ?? 0,
+});

package/dist/core/memory-create.d.ts

@@ -5,4 +5,3 @@ export declare const createMemory: (input: {
     importance?: number;
     memoryType?: string;
 }) => MemoryInsertResult;
-//# sourceMappingURL=memory-create.d.ts.map

package/dist/core/memory-create.js

@@ -4,24 +4,31 @@ import { findMemoryIdByHash, insertTags } from './memory-db.js';
 import { toSafeInteger } from './row-mappers.js';
 import { executeGet, withImmediateTransaction } from './sqlite.js';
 import { normalizeTags } from './tags.js';
-const buildHash = (content) => crypto.createHash('md5').update(content).digest('hex');
+const MAX_TAGS = 100;
+const buildHash = (content) => {
+    // eslint-disable-next-line sonarjs/hashing -- MD5 used for non-security deduplication only.
+    return crypto.createHash('md5').update(content).digest('hex');
+};
 const stmtInsertMemory = db.prepare('INSERT OR IGNORE INTO memories (content, importance, memory_type, hash) ' +
     'VALUES (?, ?, ?, ?) RETURNING id');
+const requireMemoryId = (id) => {
+    if (id === undefined) {
+        throw new Error('Failed to resolve memory id');
+    }
+    return id;
+};
 const resolveMemoryId = (input) => {
     const inserted = executeGet(stmtInsertMemory, input.content, input.importance, input.memoryType, input.hash);
     if (inserted) {
         return { id: toSafeInteger(inserted.id, 'id'), isNew: true };
     }
-    const id = findMemoryIdByHash(input.hash);
-    if (id === undefined) {
-        throw new Error('Failed to resolve memory id');
-    }
+    const id = requireMemoryId(findMemoryIdByHash(input.hash));
     return { id, isNew: false };
 };
 export const createMemory = (input) => withImmediateTransaction(() => {
     const { content, tags = [], importance = 0, memoryType = 'general', } = input;
     const hash = buildHash(content);
-    const normalizedTags = normalizeTags(tags, 100);
+    const normalizedTags = normalizeTags(tags, MAX_TAGS);
     const { id, isNew } = resolveMemoryId({
         content,
         importance,
@@ -31,4 +38,3 @@ export const createMemory = (input) => withImmediateTransaction(() => {
     insertTags(id, normalizedTags);
     return { id, hash, isNew };
 });
-//# sourceMappingURL=memory-create.js.map

package/dist/core/memory-db.d.ts

@@ -1,3 +1,2 @@
 export declare const findMemoryIdByHash: (hash: string) => number | undefined;
 export declare const insertTags: (memoryId: number, tags: readonly string[]) => void;
-//# sourceMappingURL=memory-db.d.ts.map

package/dist/core/memory-db.js

@@ -29,4 +29,3 @@ export const insertTags = (memoryId, tags) => {
     const stmt = getInsertTagsStatement(tags.length);
     executeRun(stmt, ...params);
 };
-//# sourceMappingURL=memory-db.js.map

package/dist/core/memory-read.d.ts

@@ -1,4 +1,4 @@
-import type { Memory, StatementResult } from '../types/index.js';
+import type { Memory, MemoryStats, StatementResult } from '../types.js';
 export declare const getMemory: (hash: string) => Memory | undefined;
 export declare const deleteMemory: (hash: string) => StatementResult;
-//# sourceMappingURL=memory-read.d.ts.map
+export declare const getStats: () => MemoryStats;