@j0hanz/memory-mcp 0.1.0

package/README.md

@@ -0,0 +1,363 @@
+# Memory MCP
+
+<!-- markdownlint-disable MD033 -->
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](https://github.com/j0hanz/memory-mcp/blob/master/package.json) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://github.com/j0hanz/memory-mcp/blob/master/package.json) [![TypeScript](https://img.shields.io/badge/TypeScript-5.9%2B-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://github.com/j0hanz/memory-mcp/blob/master/package.json)
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=memory-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fmemory-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=memory-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fmemory-mcp%40latest%22%5D%7D&quality=insiders)
+
+A SQLite-backed MCP server for persistent memory storage, full-text retrieval, and relationship graph traversal.
+
+## Overview
+
+Memory MCP provides a local, persistent memory layer for MCP-enabled assistants. It supports SHA-256-addressed memory items, FTS5-powered search, graph relationships, BFS recall, an `internal://instructions` resource, and a `get-help` prompt.
+
+## Key Features
+
+- 12 MCP tools for CRUD, batch operations, search, recall, relationships, and stats.
+- Full-text search over content and tags via SQLite FTS5.
+- Graph recall with BFS traversal and bounded frontier size.
+- Strict Zod input validation with typed output envelopes.
+- Resource support with URI-template completion for memory hashes.
+- stdio transport with clean shutdown handling (`SIGINT`, `SIGTERM`).
+
+## Requirements
+
+- Node.js `>=24`.
+- SQLite with FTS5 support (required at startup).
+- Any MCP client that supports stdio command servers.
+
+## Quick Start
+
+Use the npm package directly with `npx`:
+
+```json
+{
+  "mcpServers": {
+    "memory-mcp": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/memory-mcp@latest"]
+    }
+  }
+}
+```
+
+> [!TIP]
+> The server uses stdio transport only; no HTTP endpoint is exposed.
+
+## Client Configuration
+
+<details>
+<summary><b>Install in VS Code</b></summary>
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=memory-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fmemory-mcp%40latest%22%5D%7D)
+
+Workspace file `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "memory-mcp": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/memory-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in Claude Desktop / Claude Code</b></summary>
+
+`claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory-mcp": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/memory-mcp@latest"]
+    }
+  }
+}
+```
+
+CLI:
+
+```bash
+claude mcp add memory-mcp -- npx -y @j0hanz/memory-mcp@latest
+```
+
+</details>
+
+<details>
+<summary><b>Install in Cursor</b></summary>
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory-mcp": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/memory-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+## MCP Surface
+
+### Tools Summary
+
+| Tool                  | Category | Notes                                   |
+| --------------------- | -------- | --------------------------------------- |
+| `store_memory`        | Write    | Idempotent by content+sorted tags hash  |
+| `store_memories`      | Write    | Batch (1-50), transaction-wrapped       |
+| `get_memory`          | Read     | Hash lookup                             |
+| `update_memory`       | Write    | Returns `old_hash` + `new_hash`         |
+| `delete_memory`       | Write    | Cascades relationship deletion          |
+| `delete_memories`     | Write    | Batch (1-50), transaction-wrapped       |
+| `search_memories`     | Read     | FTS5 query + cursor pagination          |
+| `create_relationship` | Write    | Idempotent edge creation                |
+| `delete_relationship` | Write    | Deletes exact directed edge             |
+| `get_relationships`   | Read     | Direction filter + linked memory fields |
+| `recall`              | Read     | Search + BFS traversal (`depth` 0-3)    |
+| `memory_stats`        | Read     | Store aggregates and type breakdown     |
+
+### `store_memory`
+
+Purpose: Store one memory and return its SHA-256 hash.
+
+| Name          | Type       | Required | Default   | Description                                                                        |
+| ------------- | ---------- | -------- | --------- | ---------------------------------------------------------------------------------- |
+| `content`     | `string`   | Yes      | —         | Memory content (1-100000 chars)                                                    |
+| `tags`        | `string[]` | Yes      | —         | 1-100 tags, each max 50, no whitespace                                             |
+| `memory_type` | enum       | No       | `general` | `general`, `fact`, `plan`, `decision`, `reflection`, `lesson`, `error`, `gradient` |
+| `importance`  | `integer`  | No       | `0`       | Priority 0-10                                                                      |
+
+Returns: `{ ok, result: { hash, created } }`.
+
+### `store_memories`
+
+Purpose: Store multiple memories in one call (max 50 items).
+
+| Name    | Type                     | Required | Default | Description                                                                                   |
+| ------- | ------------------------ | -------- | ------- | --------------------------------------------------------------------------------------------- |
+| `items` | `Array<StoreMemoryItem>` | Yes      | —       | 1-50 memory items, each with `content`, `tags`, optional `memory_type`, optional `importance` |
+
+Returns: `{ ok, result: { items, succeeded, failed } }`.
+
+### `get_memory`
+
+Purpose: Retrieve one memory by hash.
+
+| Name   | Type     | Required | Default | Description                   |
+| ------ | -------- | -------- | ------- | ----------------------------- |
+| `hash` | `string` | Yes      | —       | 64-char lowercase SHA-256 hex |
+
+Returns: `{ ok, result: Memory }` or `{ ok: false, error }` (`E_NOT_FOUND`).
+
+### `update_memory`
+
+Purpose: Update content and optionally tags for an existing memory.
+
+| Name      | Type       | Required | Default       | Description          |
+| --------- | ---------- | -------- | ------------- | -------------------- |
+| `hash`    | `string`   | Yes      | —             | Existing memory hash |
+| `content` | `string`   | Yes      | —             | Replacement content  |
+| `tags`    | `string[]` | No       | existing tags | Replacement tags     |
+
+Returns: `{ ok, result: { old_hash, new_hash } }`.
+
+### `delete_memory`
+
+Purpose: Delete one memory by hash.
+
+| Name   | Type     | Required | Default | Description |
+| ------ | -------- | -------- | ------- | ----------- |
+| `hash` | `string` | Yes      | —       | Memory hash |
+
+Returns: `{ ok, result: { hash, deleted } }`.
+
+### `delete_memories`
+
+Purpose: Delete multiple memories by hash.
+
+| Name     | Type       | Required | Default | Description        |
+| -------- | ---------- | -------- | ------- | ------------------ |
+| `hashes` | `string[]` | Yes      | —       | 1-50 memory hashes |
+
+Returns: `{ ok, result: { items, succeeded, failed } }`.
+
+### `search_memories`
+
+Purpose: FTS5 search over content and tags with cursor pagination.
+
+| Name     | Type      | Required | Default | Description                 |
+| -------- | --------- | -------- | ------- | --------------------------- |
+| `query`  | `string`  | Yes      | —       | Search text (1-1000 chars)  |
+| `limit`  | `integer` | No       | `20`    | Result cap per page (1-100) |
+| `cursor` | `string`  | No       | —       | Pagination cursor           |
+
+Returns: `{ ok, result: { memories, total_returned, nextCursor? } }`.
+
+### `create_relationship`
+
+Purpose: Create a directed relationship between two memories.
+
+| Name            | Type     | Required | Default | Description                            |
+| --------------- | -------- | -------- | ------- | -------------------------------------- |
+| `from_hash`     | `string` | Yes      | —       | Source memory hash                     |
+| `to_hash`       | `string` | Yes      | —       | Target memory hash                     |
+| `relation_type` | `string` | Yes      | —       | Edge label (1-50 chars, no whitespace) |
+
+Returns: `{ ok, result: { created } }`.
+
+### `delete_relationship`
+
+Purpose: Delete one directed relationship edge.
+
+| Name            | Type     | Required | Default | Description       |
+| --------------- | -------- | -------- | ------- | ----------------- |
+| `from_hash`     | `string` | Yes      | —       | Source hash       |
+| `to_hash`       | `string` | Yes      | —       | Target hash       |
+| `relation_type` | `string` | Yes      | —       | Relationship type |
+
+Returns: `{ ok, result: { deleted } }` or `{ ok: false, error }` (`E_NOT_FOUND`).
+
+### `get_relationships`
+
+Purpose: Retrieve relationships for a memory, optionally filtered by direction.
+
+| Name        | Type     | Required | Default | Description                       |
+| ----------- | -------- | -------- | ------- | --------------------------------- |
+| `hash`      | `string` | Yes      | —       | Memory hash                       |
+| `direction` | enum     | No       | `both`  | `outgoing`, `incoming`, or `both` |
+
+Returns: `{ ok, result: { relationships, count } }`.
+
+### `recall`
+
+Purpose: Search memories, then traverse connected graph edges up to `depth` hops.
+
+| Name     | Type      | Required | Default | Description              |
+| -------- | --------- | -------- | ------- | ------------------------ |
+| `query`  | `string`  | Yes      | —       | Seed search query        |
+| `depth`  | `integer` | No       | `1`     | BFS hops (0-3)           |
+| `limit`  | `integer` | No       | `10`    | Seed memory count (1-50) |
+| `cursor` | `string`  | No       | —       | Pagination cursor        |
+
+Returns: `{ ok, result: { memories, graph, depth_reached, nextCursor? } }`.
+
+Each item in the `graph` array uses this shape:
+
+```json
+{ "from_hash": "...", "to_hash": "...", "relation_type": "..." }
+```
+
+### `memory_stats`
+
+Purpose: Return aggregate memory and relationship stats.
+
+| Name     | Type | Required | Default | Description        |
+| -------- | ---- | -------- | ------- | ------------------ |
+| _(none)_ | —    | —        | —       | Empty input object |
+
+Returns: `{ ok, result: { memories, relationships, by_type } }`.
+
+### Resources
+
+| URI                        | Type            | Description                                           |
+| -------------------------- | --------------- | ----------------------------------------------------- |
+| `internal://instructions`  | Static resource | Markdown usage guide for all tools                    |
+| `memory://memories/{hash}` | URI template    | Returns one memory as JSON; hash completion supported |
+
+### Prompts
+
+| Name       | Arguments | Purpose                                |
+| ---------- | --------- | -------------------------------------- |
+| `get-help` | none      | Returns memory tool usage instructions |
+
+## Configuration
+
+### Environment Variables
+
+| Variable         | Description               | Default     | Required |
+| ---------------- | ------------------------- | ----------- | -------- |
+| `MEMORY_DB_PATH` | SQLite database file path | `memory.db` | No       |
+
+> [!IMPORTANT]
+> If `MEMORY_DB_PATH` is relative (including the default `memory.db`), it resolves from the process working directory.
+
+### Limits and Constraints
+
+| Item                    | Value                                            |
+| ----------------------- | ------------------------------------------------ |
+| Content length          | 1-100000 chars                                   |
+| Tag count               | 1-100 per memory                                 |
+| Tag length              | 1-50 chars, no whitespace                        |
+| Hash format             | 64-char lowercase hex SHA-256                    |
+| Search query length     | 1-1000 chars                                     |
+| `search_memories.limit` | 1-100 (default 20)                               |
+| `recall.depth`          | 0-3 (default 1)                                  |
+| `recall.limit`          | 1-50 (default 10)                                |
+| Batch size              | 1-50 items (`store_memories`, `delete_memories`) |
+| Recall frontier guard   | Max 1000 nodes per hop                           |
+| SQLite busy timeout     | 5000 ms                                          |
+
+> [!NOTE]
+> Cursor values are base64url-encoded offsets. Treat them as opaque tokens.
+
+## Security
+
+- Transport is stdio-only (`StdioServerTransport`), with no HTTP endpoints.
+- Fatal process errors are written to `stderr` in the entrypoint.
+- Inputs are validated with strict Zod schemas and bounded field constraints.
+- Hashes are validated against lowercase SHA-256 hex format.
+- Search input is tokenized to alphanumeric terms before FTS `MATCH` execution (non-alphanumeric characters act as delimiters).
+- SQLite foreign keys are enabled; relationship rows cascade on memory delete.
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Core scripts:
+
+| Script       | Command              | Purpose                                                              |
+| ------------ | -------------------- | -------------------------------------------------------------------- |
+| `build`      | `npm run build`      | Clean, compile, validate instructions, copy assets, chmod executable |
+| `dev`        | `npm run dev`        | TypeScript watch mode                                                |
+| `dev:run`    | `npm run dev:run`    | Run built server with `.env` and file watch                          |
+| `start`      | `npm run start`      | Start built server                                                   |
+| `test`       | `npm run test`       | Full build + tests via task runner                                   |
+| `test:fast`  | `npm run test:fast`  | Run TS tests directly with Node test runner                          |
+| `lint`       | `npm run lint`       | ESLint checks                                                        |
+| `type-check` | `npm run type-check` | Strict TypeScript checks                                             |
+| `inspector`  | `npm run inspector`  | Build and open MCP Inspector against stdio server                    |
+
+Inspect with MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## Troubleshooting
+
+- If startup fails with FTS5 errors, use Node.js 24+ with SQLite FTS5 support.
+- If a request fails with `E_INVALID_CURSOR`, retry without the cursor.
+- If stdio clients fail to connect, ensure no custom stdout logging is added to the server process.
+- If memory or relationship lookups fail, confirm hashes exist via `search_memories` first.
+
+## License
+
+- **MIT**
+
+<!-- markdownlint-enable MD033 -->

package/dist/assets/logo.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke-width="0.8" stroke-linecap="round"
+    stroke-linejoin="round" role="img" aria-label="icon">
+    <style>
+        path,
+        circle,
+        rect,
+        line,
+        polyline,
+        polygon {
+            stroke: #111111;
+        }
+
+        @media (prefers-color-scheme: dark) {
+
+            path,
+            circle,
+            rect,
+            line,
+            polyline,
+            polygon {
+                stroke: #eeeeee;
+            }
+        }
+    </style>
+
+    <rect x="5" y="2" width="14" height="20" rx="2" />
+
+    <path d="M9 7H15" />
+    <path d="M9 12H15" />
+    <path d="M9 17H15" />
+
+    <path d="M3 6H5" />
+    <path d="M3 18H5" />
+    <path d="M19 6H21" />
+    <path d="M19 18H21" />
+</svg>

package/dist/completions/index.d.ts

@@ -0,0 +1,3 @@
+import type { TypedDb } from '../db/typed.js';
+export declare function createHashCompletionCallback(db: TypedDb): (value: string) => string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/completions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/completions/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAQ9C,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,OAAO,GACV,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,CAQ7B"}

package/dist/completions/index.js

@@ -0,0 +1,17 @@
+const HASH_MAX_LENGTH = 64;
+const HASH_COMPLETION_LIMIT = 101;
+const HASH_COMPLETION_SQL = `SELECT hash FROM memories WHERE hash LIKE ? ESCAPE '\\' ORDER BY hash LIMIT ${HASH_COMPLETION_LIMIT}`;
+// Returns a completion callback for the `hash` URI variable.
+export function createHashCompletionCallback(db) {
+    return (value) => {
+        const escapedPrefix = escapeLikePattern(value.slice(0, HASH_MAX_LENGTH));
+        const rows = db
+            .prepare(HASH_COMPLETION_SQL)
+            .all(`${escapedPrefix}%`);
+        return rows.map((r) => r.hash);
+    };
+}
+function escapeLikePattern(value) {
+    return value.replace(/[%_\\]/g, '\\$&');
+}
+//# sourceMappingURL=index.js.map

package/dist/completions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/completions/index.ts"],"names":[],"mappings":"AAGA,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAClC,MAAM,mBAAmB,GAAG,+EAA+E,qBAAqB,EAAE,CAAC;AAEnI,6DAA6D;AAC7D,MAAM,UAAU,4BAA4B,CAC1C,EAAW;IAEX,OAAO,CAAC,KAAa,EAAY,EAAE;QACjC,MAAM,aAAa,GAAG,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC;QACzE,MAAM,IAAI,GAAG,EAAE;aACZ,OAAO,CAAU,mBAAmB,CAAC;aACrC,GAAG,CAAC,GAAG,aAAa,GAAG,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC"}

package/dist/db/index.d.ts

@@ -0,0 +1,6 @@
+import { DatabaseSync, type SQLTagStore } from 'node:sqlite';
+import { type TypedDb } from './typed.js';
+export declare function initDatabase(path: string): DatabaseSync;
+export declare function initTypedDatabase(path: string): TypedDb;
+export declare function createStatementCache(db: DatabaseSync): SQLTagStore;
+//# sourceMappingURL=index.d.ts.map

package/dist/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AA2FzD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAWvD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,YAAY,GAAG,WAAW,CAElE"}

package/dist/db/index.js

@@ -0,0 +1,102 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { createTypedDb } from './typed.js';
+const SQLITE_TIMEOUT_MS = 5000;
+const STATEMENT_CACHE_SIZE = 1000;
+const FTS5_CHECK_SQL = 'CREATE VIRTUAL TABLE IF NOT EXISTS __fts5_check USING fts5(x); DROP TABLE __fts5_check;';
+const FTS5_REQUIRED_MESSAGE = 'SQLite FTS5 extension is not available. memory-mcp requires a SQLite build with FTS5 support.';
+const SCHEMA_SQL = `
+  CREATE TABLE IF NOT EXISTS memories (
+    hash TEXT PRIMARY KEY NOT NULL,
+    content TEXT NOT NULL,
+    tags TEXT NOT NULL DEFAULT '[]',
+    memory_type TEXT NOT NULL DEFAULT 'general',
+    importance INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  ) STRICT;
+
+  CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+    content,
+    tags,
+    content='memories',
+    content_rowid='rowid'
+  );
+
+  CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, content, tags)
+      VALUES (new.rowid, new.content, new.tags);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content, tags)
+      VALUES ('delete', old.rowid, old.content, old.tags);
+    INSERT INTO memories_fts(rowid, content, tags)
+      VALUES (new.rowid, new.content, new.tags);
+  END;
+
+  CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content, tags)
+      VALUES ('delete', old.rowid, old.content, old.tags);
+  END;
+
+  CREATE TABLE IF NOT EXISTS relationships (
+    from_hash TEXT NOT NULL REFERENCES memories(hash) ON DELETE CASCADE,
+    to_hash TEXT NOT NULL REFERENCES memories(hash) ON DELETE CASCADE,
+    relation_type TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (from_hash, to_hash, relation_type)
+  ) STRICT;
+
+  CREATE INDEX IF NOT EXISTS idx_memories_importance
+    ON memories(importance DESC);
+
+  CREATE INDEX IF NOT EXISTS idx_memories_created
+    ON memories(created_at DESC);
+
+  CREATE INDEX IF NOT EXISTS idx_relationships_from
+    ON relationships(from_hash);
+
+  CREATE INDEX IF NOT EXISTS idx_relationships_to
+    ON relationships(to_hash);
+`;
+function assertFts5Available(db) {
+    try {
+        db.exec(FTS5_CHECK_SQL);
+    }
+    catch {
+        throw new Error(FTS5_REQUIRED_MESSAGE);
+    }
+}
+function ensureParentDir(path) {
+    const isInMemoryPath = path === ':memory:';
+    if (isInMemoryPath) {
+        return;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+}
+function configureDatabase(db) {
+    // Enable defensive mode (SQLite v3.39+ / Node 24.12+: prevents deliberate DB corruption)
+    db.exec('PRAGMA defensive = ON');
+    // Verify FTS5 support
+    assertFts5Available(db);
+    db.exec(SCHEMA_SQL);
+}
+export function initDatabase(path) {
+    ensureParentDir(path);
+    const db = new DatabaseSync(path, {
+        enableForeignKeyConstraints: true,
+        timeout: SQLITE_TIMEOUT_MS,
+    });
+    configureDatabase(db);
+    return db;
+}
+export function initTypedDatabase(path) {
+    const db = initDatabase(path);
+    return createTypedDb(db);
+}
+export function createStatementCache(db) {
+    return db.createTagStore(STATEMENT_CACHE_SIZE);
+}
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAoB,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAgB,MAAM,YAAY,CAAC;AAEzD,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAC/B,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAClC,MAAM,cAAc,GAClB,yFAAyF,CAAC;AAC5F,MAAM,qBAAqB,GACzB,+FAA+F,CAAC;AAElG,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDlB,CAAC;AAEF,SAAS,mBAAmB,CAAC,EAAgB;IAC3C,IAAI,CAAC;QACH,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,IAAY;IACnC,MAAM,cAAc,GAAG,IAAI,KAAK,UAAU,CAAC;IAC3C,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO;IACT,CAAC;IACD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,iBAAiB,CAAC,EAAgB;IACzC,yFAAyF;IACzF,EAAE,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IAEjC,sBAAsB;IACtB,mBAAmB,CAAC,EAAE,CAAC,CAAC;IAExB,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,eAAe,CAAC,IAAI,CAAC,CAAC;IAEtB,MAAM,EAAE,GAAG,IAAI,YAAY,CAAC,IAAI,EAAE;QAChC,2BAA2B,EAAE,IAAI;QACjC,OAAO,EAAE,iBAAiB;KAC3B,CAAC,CAAC;IAEH,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAEtB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,aAAa,CAAC,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,EAAgB;IACnD,OAAO,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;AACjD,CAAC"}

package/dist/db/typed.d.ts

@@ -0,0 +1,15 @@
+import type { DatabaseSync, SQLInputValue, StatementResultingChanges } from 'node:sqlite';
+export interface TypedStatement<T> {
+    all(...params: SQLInputValue[]): T[];
+    get(...params: SQLInputValue[]): T | undefined;
+    run(...params: SQLInputValue[]): StatementResultingChanges;
+}
+export declare class TypedDb {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    prepare<T>(sql: string): TypedStatement<T>;
+    exec(sql: string): void;
+    close(): void;
+}
+export declare function createTypedDb(db: DatabaseSync): TypedDb;
+//# sourceMappingURL=typed.d.ts.map

package/dist/db/typed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed.d.ts","sourceRoot":"","sources":["../../src/db/typed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,yBAAyB,EAC1B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,GAAG,CAAC,GAAG,MAAM,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,CAAC;IACrC,GAAG,CAAC,GAAG,MAAM,EAAE,aAAa,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;IAC/C,GAAG,CAAC,GAAG,MAAM,EAAE,aAAa,EAAE,GAAG,yBAAyB,CAAC;CAC5D;AAED,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC;IAS1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIvB,KAAK,IAAI,IAAI;CAGd;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,OAAO,CAEvD"}

package/dist/db/typed.js

@@ -0,0 +1,24 @@
+export class TypedDb {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    prepare(sql) {
+        const stmt = this.db.prepare(sql);
+        return {
+            all: (...params) => stmt.all(...params),
+            get: (...params) => stmt.get(...params),
+            run: (...params) => stmt.run(...params),
+        };
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    close() {
+        this.db.close();
+    }
+}
+export function createTypedDb(db) {
+    return new TypedDb(db);
+}
+//# sourceMappingURL=typed.js.map

package/dist/db/typed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed.js","sourceRoot":"","sources":["../../src/db/typed.ts"],"names":[],"mappings":"AAYA,MAAM,OAAO,OAAO;IACW;IAA7B,YAA6B,EAAgB;QAAhB,OAAE,GAAF,EAAE,CAAc;IAAG,CAAC;IAEjD,OAAO,CAAI,GAAW;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,OAAO;YACL,GAAG,EAAE,CAAC,GAAG,MAAuB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAQ;YAC/D,GAAG,EAAE,CAAC,GAAG,MAAuB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAkB;YACzE,GAAG,EAAE,CAAC,GAAG,MAAuB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;SACzD,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,GAAW;QACd,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;CACF;AAED,MAAM,UAAU,aAAa,CAAC,EAAgB;IAC5C,OAAO,IAAI,OAAO,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import process from 'node:process';
+import { initTypedDatabase } from './db/index.js';
+import { createServer } from './server.js';
+const MEMORY_DB_PATH = process.env['MEMORY_DB_PATH'] ?? 'memory.db';
+const SHUTDOWN_SIGNALS = ['SIGINT', 'SIGTERM'];
+const SHUTDOWN_TIMEOUT_MS = 3000;
+const FORCED_EXIT_CODE = 1;
+const CLEAN_EXIT_CODE = 0;
+function formatFatalError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function registerShutdownHandlers(shutdown) {
+    for (const signal of SHUTDOWN_SIGNALS) {
+        process.on(signal, shutdown);
+    }
+}
+function scheduleForcedShutdown() {
+    const timer = setTimeout(() => {
+        process.stderr.write('Shutdown timed out, forcing exit.\n');
+        process.exit(FORCED_EXIT_CODE);
+    }, SHUTDOWN_TIMEOUT_MS);
+    timer.unref();
+    return timer;
+}
+async function runShutdown(server, db) {
+    const timer = scheduleForcedShutdown();
+    try {
+        await server.close();
+    }
+    catch {
+        // ignore close errors
+    }
+    db.close();
+    clearTimeout(timer);
+    process.exit(CLEAN_EXIT_CODE);
+}
+function createShutdownHandler(server, db) {
+    let isShuttingDown = false;
+    return () => {
+        if (isShuttingDown)
+            return;
+        isShuttingDown = true;
+        void runShutdown(server, db);
+    };
+}
+async function main() {
+    const db = initTypedDatabase(MEMORY_DB_PATH);
+    const server = createServer(db);
+    const transport = new StdioServerTransport();
+    const shutdown = createShutdownHandler(server, db);
+    registerShutdownHandlers(shutdown);
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${formatFatalError(err)}\n`);
+    process.exit(FORCED_EXIT_CODE);
+});
+//# 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;AAEjF,OAAO,OAAO,MAAM,cAAc,CAAC;AAEnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,WAAW,CAAC;AACpE,MAAM,gBAAgB,GAAqB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AACjE,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACjC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAC3B,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,SAAS,gBAAgB,CAAC,GAAY;IACpC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,wBAAwB,CAAC,QAAoB;IACpD,KAAK,MAAM,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACtC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB;IAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;QAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;QAC5D,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACjC,CAAC,EAAE,mBAAmB,CAAC,CAAC;IACxB,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,MAAuC,EACvC,EAAwC;IAExC,MAAM,KAAK,GAAG,sBAAsB,EAAE,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;IACD,EAAE,CAAC,KAAK,EAAE,CAAC;IACX,YAAY,CAAC,KAAK,CAAC,CAAC;IACpB,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,qBAAqB,CAC5B,MAAuC,EACvC,EAAwC;IAExC,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,OAAO,GAAG,EAAE;QACV,IAAI,cAAc;YAAE,OAAO;QAC3B,cAAc,GAAG,IAAI,CAAC;QACtB,KAAK,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC/B,CAAC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,GAAG,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;IAChC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,qBAAqB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnD,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAEnC,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;AACjC,CAAC,CAAC,CAAC"}