@j0hanz/memory-mcp 0.1.0 → 0.1.1

package/README.md

@@ -2,34 +2,37 @@
 
 <!-- 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)
+[![npm version](https://img.shields.io/npm/v/@j0hanz/memory-mcp?style=flat-square&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@j0hanz/memory-mcp) [![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)
 
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=memory-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovbWVtb3J5LW1jcEBsYXRlc3QiXX0=)
+
 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.
+Memory MCP provides a local, persistent memory layer for MCP-enabled assistants. It stores SHA-256-addressed memory items in SQLite with FTS5-powered full-text search, a directed relationship graph, BFS recall traversal, and token-budget-aware context retrieval — all accessible over stdio transport with no external dependencies.
 
 ## 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`).
+- **13 MCP tools** for CRUD, batch operations, FTS5 search, BFS graph recall, token-budget context retrieval, relationships, and stats.
+- **Full-text search** over content and tags via SQLite FTS5 with importance and type filters.
+- **Graph recall** with BFS traversal, bounded frontier, and MCP progress notifications per hop.
+- **Token-budget retrieval** (`retrieve_context`) selects memories that fit a caller-specified token budget — no manual pagination needed.
+- **Strict Zod input validation** with typed output envelopes and SHA-256 hash addressing.
+- **Resource support** with `internal://instructions` (Markdown guide) and `memory://memories/{hash}` URI template with hash auto-completion.
+- **stdio transport** with clean shutdown handling (`SIGINT`, `SIGTERM`) and no HTTP endpoints.
 
 ## Requirements
 
 - Node.js `>=24`.
-- SQLite with FTS5 support (required at startup).
+- SQLite with FTS5 support (verified at startup).
 - Any MCP client that supports stdio command servers.
 
 ## Quick Start
 
-Use the npm package directly with `npx`:
+Use the npm package directly with `npx` — no installation required:
 
 ```json
 {
@@ -43,7 +46,13 @@ Use the npm package directly with `npx`:
 ```
 
 > [!TIP]
-> The server uses stdio transport only; no HTTP endpoint is exposed.
+> The server uses stdio transport only; no HTTP endpoint is exposed. Stdout must not be polluted by custom logging.
+
+Or run with Docker:
+
+```bash
+docker run --rm -i ghcr.io/j0hanz/memory-mcp:latest
+```
 
 ## Client Configuration
 
@@ -65,6 +74,45 @@ Workspace file `.vscode/mcp.json`:
 }
 ```
 
+CLI:
+
+```bash
+code --add-mcp '{"name":"memory-mcp","command":"npx","args":["-y","@j0hanz/memory-mcp@latest"]}'
+```
+
+</details>
+
+<details>
+<summary><b>Install in VS Code Insiders</b></summary>
+
+[![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)
+
+CLI:
+
+```bash
+code-insiders --add-mcp '{"name":"memory-mcp","command":"npx","args":["-y","@j0hanz/memory-mcp@latest"]}'
+```
+
+</details>
+
+<details>
+<summary><b>Install in Cursor</b></summary>
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=memory-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovbWVtb3J5LW1jcEBsYXRlc3QiXX0=)
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory-mcp": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/memory-mcp@latest"]
+    }
+  }
+}
+```
+
 </details>
 
 <details>
@@ -92,9 +140,9 @@ claude mcp add memory-mcp -- npx -y @j0hanz/memory-mcp@latest
 </details>
 
 <details>
-<summary><b>Install in Cursor</b></summary>
+<summary><b>Install in Windsurf</b></summary>
 
-`~/.cursor/mcp.json`:
+MCP config:
 
 ```json
 {
@@ -109,6 +157,41 @@ claude mcp add memory-mcp -- npx -y @j0hanz/memory-mcp@latest
 
 </details>
 
+<details>
+<summary><b>Run with Docker</b></summary>
+
+```bash
+# Pull and run (stdio mode)
+docker run --rm -i \
+  -e MEMORY_DB_PATH=/data/memory.db \
+  -v memory-data:/data \
+  ghcr.io/j0hanz/memory-mcp:latest
+```
+
+MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "memory-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "MEMORY_DB_PATH=/data/memory.db",
+        "-v",
+        "memory-data:/data",
+        "ghcr.io/j0hanz/memory-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+</details>
+
 ## MCP Surface
 
 ### Tools Summary
@@ -116,210 +199,286 @@ claude mcp add memory-mcp -- npx -y @j0hanz/memory-mcp@latest
 | Tool                  | Category | Notes                                   |
 | --------------------- | -------- | --------------------------------------- |
 | `store_memory`        | Write    | Idempotent by content+sorted tags hash  |
-| `store_memories`      | Write    | Batch (1-50), transaction-wrapped       |
+| `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_memories`     | Write    | Batch (1–50), transaction-wrapped       |
+| `search_memories`     | Read     | FTS5 + importance/type filters + cursor |
+| `create_relationship` | Write    | Idempotent directed 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)    |
+| `recall`              | Read     | FTS5 seed + BFS traversal (depth 0–3)   |
+| `retrieve_context`    | Read     | Token-budget-aware context retrieval    |
 | `memory_stats`        | Read     | Store aggregates and type breakdown     |
 
+---
+
 ### `store_memory`
 
-Purpose: Store one memory and return its SHA-256 hash.
+Store a new memory with content, tags, and optional type/importance. Idempotent — storing the same content+tags returns the existing hash with `created: false`.
 
 | Name          | Type       | Required | Default   | Description                                                                        |
 | ------------- | ---------- | -------- | --------- | ---------------------------------------------------------------------------------- |
-| `content`     | `string`   | Yes      | —         | Memory content (1-100000 chars)                                                    |
-| `tags`        | `string[]` | Yes      | —         | 1-100 tags, each max 50, no whitespace                                             |
+| `content`     | `string`   | Yes      | —         | Memory content (1–100000 chars)                                                    |
+| `tags`        | `string[]` | Yes      | —         | 1–100 tags, each max 50 chars, no whitespace                                       |
 | `memory_type` | enum       | No       | `general` | `general`, `fact`, `plan`, `decision`, `reflection`, `lesson`, `error`, `gradient` |
-| `importance`  | `integer`  | No       | `0`       | Priority 0-10                                                                      |
+| `importance`  | `integer`  | No       | `0`       | Priority 0–10                                                                      |
+
+Returns: `{ ok, result: { hash, created } }`
 
-Returns: `{ ok, result: { hash, created } }`.
+---
 
 ### `store_memories`
 
-Purpose: Store multiple memories in one call (max 50 items).
+Store multiple memories in one transaction (max 50 items).
+
+| Name    | Type                     | Required | Description                                                                            |
+| ------- | ------------------------ | -------- | -------------------------------------------------------------------------------------- |
+| `items` | `Array<StoreMemoryItem>` | Yes      | 1–50 items, each with `content`, `tags`, optional `memory_type`, optional `importance` |
 
-| 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 } }`
 
-Returns: `{ ok, result: { items, succeeded, failed } }`.
+---
 
 ### `get_memory`
 
-Purpose: Retrieve one memory by hash.
+Retrieve one memory by its SHA-256 hash.
 
-| Name   | Type     | Required | Default | Description                   |
-| ------ | -------- | -------- | ------- | ----------------------------- |
-| `hash` | `string` | Yes      | —       | 64-char lowercase SHA-256 hex |
+| Name   | Type     | Required | Description                   |
+| ------ | -------- | -------- | ----------------------------- |
+| `hash` | `string` | Yes      | 64-char lowercase SHA-256 hex |
 
-Returns: `{ ok, result: Memory }` or `{ ok: false, error }` (`E_NOT_FOUND`).
+Returns: `{ ok, result: Memory }` or `{ ok: false, error }` on `E_NOT_FOUND`.
+
+---
 
 ### `update_memory`
 
-Purpose: Update content and optionally tags for an existing memory.
+Update content and optionally tags for an existing memory. Returns both hashes.
 
 | Name      | Type       | Required | Default       | Description          |
 | --------- | ---------- | -------- | ------------- | -------------------- |
 | `hash`    | `string`   | Yes      | —             | Existing memory hash |
 | `content` | `string`   | Yes      | —             | Replacement content  |
-| `tags`    | `string[]` | No       | existing tags | Replacement tags     |
+| `tags`    | `string[]` | No       | Existing tags | Replacement tags     |
+
+Returns: `{ ok, result: { old_hash, new_hash } }`
 
-Returns: `{ ok, result: { old_hash, new_hash } }`.
+---
 
 ### `delete_memory`
 
-Purpose: Delete one memory by hash.
+Delete one memory by hash. Cascades to related relationship rows.
+
+| Name   | Type     | Required | Description |
+| ------ | -------- | -------- | ----------- |
+| `hash` | `string` | Yes      | Memory hash |
 
-| Name   | Type     | Required | Default | Description |
-| ------ | -------- | -------- | ------- | ----------- |
-| `hash` | `string` | Yes      | —       | Memory hash |
+Returns: `{ ok, result: { hash, deleted } }`
 
-Returns: `{ ok, result: { hash, deleted } }`.
+---
 
 ### `delete_memories`
 
-Purpose: Delete multiple memories by hash.
+Delete multiple memories by hash in one transaction.
 
-| Name     | Type       | Required | Default | Description        |
-| -------- | ---------- | -------- | ------- | ------------------ |
-| `hashes` | `string[]` | Yes      | —       | 1-50 memory hashes |
+| Name     | Type       | Required | Description        |
+| -------- | ---------- | -------- | ------------------ |
+| `hashes` | `string[]` | Yes      | 1–50 memory hashes |
 
-Returns: `{ ok, result: { items, succeeded, failed } }`.
+Returns: `{ ok, result: { items, succeeded, failed } }`
+
+---
 
 ### `search_memories`
 
-Purpose: FTS5 search over content and tags with cursor pagination.
+Full-text search over memory content and tags using FTS5. Supports importance and type filters with cursor pagination.
+
+| Name             | Type      | Required | Default | Description                                               |
+| ---------------- | --------- | -------- | ------- | --------------------------------------------------------- |
+| `query`          | `string`  | Yes      | —       | Search text (1–1000 chars)                                |
+| `limit`          | `integer` | No       | `20`    | Results per page (1–100)                                  |
+| `cursor`         | `string`  | No       | —       | Pagination cursor from previous response                  |
+| `min_importance` | `integer` | No       | —       | Only return memories with importance >= this value (0–10) |
+| `max_importance` | `integer` | No       | —       | Only return memories with importance <= this value (0–10) |
+| `memory_type`    | enum      | No       | —       | Filter by memory type                                     |
 
-| 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? } }`
 
-Returns: `{ ok, result: { memories, total_returned, nextCursor? } }`.
+---
 
 ### `create_relationship`
 
-Purpose: Create a directed relationship between two memories.
+Create a directed relationship edge between two memories. Idempotent.
+
+Suggested `relation_type` values: `related_to`, `causes`, `depends_on`, `parent_of`, `child_of`, `supersedes`, `contradicts`, `supports`, `references`.
 
-| 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) |
+| Name            | Type     | Required | 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, free-form) |
 
-Returns: `{ ok, result: { created } }`.
+Returns: `{ ok, result: { created } }`
+
+---
 
 ### `delete_relationship`
 
-Purpose: Delete one directed relationship edge.
+Delete one directed relationship edge.
+
+| Name            | Type     | Required | Description       |
+| --------------- | -------- | -------- | ----------------- |
+| `from_hash`     | `string` | Yes      | Source hash       |
+| `to_hash`       | `string` | Yes      | Target hash       |
+| `relation_type` | `string` | Yes      | Relationship type |
 
-| 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 }` on `E_NOT_FOUND`.
 
-Returns: `{ ok, result: { deleted } }` or `{ ok: false, error }` (`E_NOT_FOUND`).
+---
 
 ### `get_relationships`
 
-Purpose: Retrieve relationships for a memory, optionally filtered by direction.
+Retrieve relationships for a memory, with optional direction filter.
 
 | Name        | Type     | Required | Default | Description                       |
 | ----------- | -------- | -------- | ------- | --------------------------------- |
 | `hash`      | `string` | Yes      | —       | Memory hash                       |
 | `direction` | enum     | No       | `both`  | `outgoing`, `incoming`, or `both` |
 
-Returns: `{ ok, result: { relationships, count } }`.
+Returns: `{ ok, result: { relationships, count } }`
+
+Each relationship includes `from_hash`, `to_hash`, `relation_type`, `created_at`, `linked_hash`, `linked_content`, and `linked_tags`.
+
+---
 
 ### `recall`
 
-Purpose: Search memories, then traverse connected graph edges up to `depth` hops.
+Search memories by full-text query, then traverse the relationship graph up to `depth` hops via BFS. Emits MCP progress notifications per hop.
 
-| 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        |
+| Name             | Type      | Required | Default | Description                                                |
+| ---------------- | --------- | -------- | ------- | ---------------------------------------------------------- |
+| `query`          | `string`  | Yes      | —       | Seed search query (1–1000 chars)                           |
+| `depth`          | `integer` | No       | `1`     | BFS hops (0–3)                                             |
+| `limit`          | `integer` | No       | `10`    | Seed memory count (1–50)                                   |
+| `cursor`         | `string`  | No       | —       | Pagination cursor from previous response                   |
+| `min_importance` | `integer` | No       | —       | Seed filter: only memories with importance >= value (0–10) |
+| `max_importance` | `integer` | No       | —       | Seed filter: only memories with importance <= value (0–10) |
+| `memory_type`    | enum      | No       | —       | Seed filter: only memories of this type                    |
 
-Returns: `{ ok, result: { memories, graph, depth_reached, nextCursor? } }`.
+Returns: `{ ok, result: { memories, graph, depth_reached, aborted?, nextCursor? } }`
 
-Each item in the `graph` array uses this shape:
+Each item in `graph` uses the shape:
 
 ```json
 { "from_hash": "...", "to_hash": "...", "relation_type": "..." }
 ```
 
+> [!NOTE]
+> `aborted: true` indicates the traversal hit a safety limit (`RECALL_MAX_FRONTIER_SIZE`, `RECALL_MAX_EDGE_ROWS`, or `RECALL_MAX_VISITED_NODES`). Partial results are still returned.
+
+---
+
+### `retrieve_context`
+
+Search memories and return relevance-ranked results that fit within a caller-specified token budget. Eliminates manual pagination and token counting for context window management.
+
+| Name           | Type      | Required | Default     | Description                                                                                |
+| -------------- | --------- | -------- | ----------- | ------------------------------------------------------------------------------------------ |
+| `query`        | `string`  | Yes      | —           | Search query (1–1000 chars)                                                                |
+| `token_budget` | `integer` | No       | `4000`      | Maximum estimated tokens to return (100–200000)                                            |
+| `strategy`     | enum      | No       | `relevance` | Sort order: `relevance` (FTS rank), `importance` (highest first), `recency` (newest first) |
+
+Returns: `{ ok, result: { memories, estimated_tokens, truncated } }`
+
+> [!TIP]
+> Token estimation is approximate (content length ÷ 4). `truncated: true` means the budget was reached before all candidates were included.
+
+---
+
 ### `memory_stats`
 
-Purpose: Return aggregate memory and relationship stats.
+Return aggregate memory and relationship stats. Takes no input.
 
-| Name     | Type | Required | Default | Description        |
-| -------- | ---- | -------- | ------- | ------------------ |
-| _(none)_ | —    | —        | —       | Empty input object |
+Returns:
 
-Returns: `{ ok, result: { memories, relationships, by_type } }`.
+```json
+{
+  "ok": true,
+  "result": {
+    "memories": {
+      "total": 0,
+      "oldest": null,
+      "newest": null,
+      "avg_importance": null
+    },
+    "relationships": { "total": 0 },
+    "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 |
+| URI                        | MIME               | Description                                           |
+| -------------------------- | ------------------ | ----------------------------------------------------- |
+| `internal://instructions`  | `text/markdown`    | Markdown usage guide for all tools and workflows      |
+| `memory://memories/{hash}` | `application/json` | Returns one memory as JSON; hash completion supported |
 
 ### Prompts
 
-| Name       | Arguments | Purpose                                |
-| ---------- | --------- | -------------------------------------- |
-| `get-help` | none      | Returns memory tool usage instructions |
+| Name       | Arguments | Purpose                                       |
+| ---------- | --------- | --------------------------------------------- |
+| `get-help` | none      | Returns full usage instructions for all tools |
 
 ## Configuration
 
 ### Environment Variables
 
-| Variable         | Description               | Default     | Required |
-| ---------------- | ------------------------- | ----------- | -------- |
-| `MEMORY_DB_PATH` | SQLite database file path | `memory.db` | No       |
+| Variable                   | Description                                             | Default     | Required |
+| -------------------------- | ------------------------------------------------------- | ----------- | -------- |
+| `MEMORY_DB_PATH`           | SQLite database file path                               | `memory.db` | No       |
+| `RECALL_MAX_FRONTIER_SIZE` | Max BFS frontier nodes per hop (100–50000)              | `1000`      | No       |
+| `RECALL_MAX_EDGE_ROWS`     | Max relationship rows fetched per traversal (100–50000) | `5000`      | No       |
+| `RECALL_MAX_VISITED_NODES` | Max visited nodes across entire traversal (100–50000)   | `5000`      | No       |
 
 > [!IMPORTANT]
 > If `MEMORY_DB_PATH` is relative (including the default `memory.db`), it resolves from the process working directory.
 
+> [!TIP]
+> Add `memory.db` to your `.gitignore` to keep the database out of version control — it contains local session data and should not be shared or committed.
+
 ### 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                                          |
+| 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)                                 |
+| `retrieve_context.token_budget` | 100–200000 (default 4000)                         |
+| Batch size                      | 1–50 items (`store_memories`, `delete_memories`)  |
+| Recall frontier guard           | `RECALL_MAX_FRONTIER_SIZE` (default 1000 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.
+- Transport is stdio-only (`StdioServerTransport`) — no HTTP endpoints.
+- Fatal process errors are written to `stderr`; stdout must remain clean for the MCP protocol.
+- All inputs are validated with strict Zod schemas and bounded field constraints before any database access.
+- Hashes are validated against a lowercase 64-char SHA-256 hex regex.
+- Search input is tokenized to alphanumeric terms before FTS `MATCH` execution (non-alphanumeric characters act as delimiters, preventing FTS injection).
+- SQLite foreign keys are enabled; relationship rows cascade-delete when a memory is removed.
 
 ## Development
 
@@ -340,7 +499,9 @@ Core scripts:
 | `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                                                        |
+| `lint:fix`   | `npm run lint:fix`   | ESLint auto-fix                                                      |
 | `type-check` | `npm run type-check` | Strict TypeScript checks                                             |
+| `format`     | `npm run format`     | Prettier format                                                      |
 | `inspector`  | `npm run inspector`  | Build and open MCP Inspector against stdio server                    |
 
 Inspect with MCP Inspector:
@@ -349,15 +510,45 @@ Inspect with MCP Inspector:
 npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
+## Build & Release
+
+GitHub Actions release workflow (`.github/workflows/release.yml`) handles versioning, validation, and publishing via a single `workflow_dispatch` trigger:
+
+```
+workflow_dispatch (patch / minor / major / custom)
+    │
+    ▼
+  release — bump package.json + server.json → lint → type-check → test → build → tag → GitHub Release
+    │
+    ├──► publish-npm ──► publish-mcp   (npm Trusted Publishing OIDC → MCP Registry)
+    │
+    └──► publish-docker                (GHCR, linux/amd64 + linux/arm64)
+```
+
+Trigger a release:
+
+```bash
+gh workflow run release.yml -f bump=patch
+```
+
+Or use the GitHub UI: **Actions → Release → Run workflow**.
+
+> [!NOTE]
+> npm publishing uses OIDC Trusted Publishing — no `NPM_TOKEN` secret required. MCP Registry uses GitHub OIDC. Docker uses the built-in `GITHUB_TOKEN`.
+
 ## 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.
+| Symptom                       | Cause                        | Fix                                                      |
+| ----------------------------- | ---------------------------- | -------------------------------------------------------- |
+| Startup fails with FTS5 error | Node.js build without FTS5   | Use Node.js 24+ with SQLite FTS5 support                 |
+| `E_NOT_FOUND` on `get_memory` | Hash doesn't exist           | Verify via `search_memories` first                       |
+| `E_INVALID_CURSOR`            | Stale or malformed cursor    | Retry the request without the `cursor` parameter         |
+| MCP client can't connect      | Custom stdout logging added  | Ensure nothing writes to stdout in the server process    |
+| `aborted: true` in recall     | Traversal hit a safety limit | Reduce `depth`, or tune `RECALL_MAX_*` env vars          |
+| Database locked errors        | High concurrent write load   | SQLite busy timeout is 5000 ms; reduce concurrent writes |
 
 ## License
 
-- **MIT**
+MIT
 
 <!-- markdownlint-enable MD033 -->

package/dist/assets/logo.svg

@@ -1,36 +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 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/instructions.md

@@ -1,14 +1,14 @@
-# Memory INSTRUCTIONS
+# MEMORY-MCP INSTRUCTIONS
 
-> Available as resource `internal://instructions`. Load when unsure about tool usage.
+These instructions are available as a resource `internal://instructions` or prompt `get-help`. Load them when unsure about tool usage.
 
 ---
 
 ## CORE CAPABILITY
 
 - Domain: SQLite-backed memory store with FTS5 search and knowledge graph for AI assistants.
-- Primary Resources: Memory (content+tags+hash), Relationship (directed edges).
-- Tools: `search_memories` `get_memory` `recall` `get_relationships` `memory_stats` (READ); `store_memory` `store_memories` `update_memory` `delete_memory` `delete_memories` `create_relationship` `delete_relationship` (WRITE).
+- Primary Resources: Memories (content+tags+hash), Relationships (directed edges).
+- Tools: `search_memories`, `get_memory`, `recall`, `get_relationships`, `memory_stats`, `retrieve_context` (READ); `store_memory`, `store_memories`, `update_memory`, `delete_memory`, `delete_memories`, `create_relationship`, `delete_relationship` (WRITE).
 
 ---
 
@@ -21,37 +21,39 @@
 ## RESOURCES & RESOURCE LINKS
 
 - `internal://instructions`: This document.
-- `memory://memories/{hash}`: Retrieve a single memory by SHA-256 hash (JSON). Supports hash autocompletion.
+- `memory://memories/{hash}`: Retrieve a single memory by its SHA-256 hash.
+- If a tool response includes a `resourceUri` or `resource_link`, call `resources/read` with the URI to fetch the full payload.
 
 ---
 
 ## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
 
-### WORKFLOW A: Recall & Exploration
+### WORKFLOW A: RECALL & EXPLORATION
 
-1. Call `search_memories` with `{ query }` to find memories by content/tags.
-2. Call `recall` with `{ query, depth }` to traverse graph connections from search hits.
-3. Call `get_memory` with `{ hash }` for exact retrieval using a hash from previous results.
-   NOTE: Never guess hashes. Always search first.
+- Call `search_memories` with `{ query }` to find memories by content/tags.
+- Call `recall` with `{ query, depth }` to traverse graph connections from hits.
+- Call `get_memory` with `{ hash }` for exact retrieval using hash from results.
+  NOTE: Never guess hashes. Always search first.
 
-### WORKFLOW B: Knowledge Storage
+### WORKFLOW B: KNOWLEDGE MANAGEMENT (STORAGE)
 
-1. Call `store_memory` to persist a single memory with content, tags, and optional type/importance.
-2. Call `store_memories` for batch storage (up to 50 items, atomic transaction).
-3. Call `create_relationship` to link memories via `{ from_hash, to_hash, relation_type }`.
-   NOTE: Both hashes must exist before creating a relationship.
+- Call `store_memory` or `store_memories` (batch ≤50) to persist content with tags.
+- Call `create_relationship` to link memories via `{ from_hash, to_hash, relation_type }`.
+- Call `update_memory` with `{ hash, content }` to revise — returns new hash.
+  NOTE: `update_memory` changes the hash because hash depends on content.
 
-### WORKFLOW C: Knowledge Management
+### WORKFLOW C: CONTEXT RETRIEVAL (RAG)
 
-1. Call `update_memory` with `{ hash, content }` to revise — returns a **new hash** (hash changes on content/tag update).
-2. Call `delete_memory` or `delete_memories` to remove items. Deleting a memory cascades to its relationships.
-3. Call `delete_relationship` to remove a specific edge.
-   NOTE: Confirm destructive actions with the user first.
+- Call `retrieve_context` with `{ query, token_budget }` to get relevant memories fitting a token limit.
+- Use `strategy='importance'` for high-priority items or `strategy='recency'` for latest updates.
+  NOTE: Output is truncated to fit `token_budget`.
 
-### WORKFLOW D: Diagnostics & Graph Inspection
+### WORKFLOW D: CLEANUP & MAINTENANCE
 
-1. Call `memory_stats` (no input) to get counts, timestamps, and type breakdown.
-2. Call `get_relationships` with `{ hash, direction }` to inspect a memory's connections.
+- Call `delete_memory` or `delete_memories` to remove obsolete items.
+- Call `delete_relationship` to remove specific edges.
+- Call `memory_stats` to monitor database size and health.
+  NOTE: Always confirm destructive actions (delete) with the user first.
 
 ---
 
@@ -59,86 +61,63 @@
 
 `store_memory` / `store_memories`
 
-- Idempotent: storing the same content+tags returns the existing hash with `created: false`.
-- Hash is computed from `SHA-256(content + sorted_tags)` — changing tags produces a different hash.
-- `importance`: integer 0–10 (default 0). `memory_type`: one of `general`, `fact`, `plan`, `decision`, `reflection`, `lesson`, `error`, `gradient` (default `general`).
-- Batch: `store_memories` accepts 1–50 items. All succeed or the transaction rolls back.
-
-`search_memories`
-
-- Uses FTS5 full-text search over content and tags. Results ranked by relevance.
-- `limit`: 1–100 (default 20). Returns `nextCursor` for pagination.
-- Query is sanitized to alphanumeric tokens — special characters are stripped.
-
-`recall`
-
-- Seeds from FTS5 search, then performs BFS traversal up to `depth` hops (0–3, default 1).
-- `depth: 0` returns only search results with no graph traversal.
-- `limit`: 1–50 (default 10) controls the seed count, not the total.
-- Returns all discovered `memories` and the `graph` edges connecting them.
-- BFS frontier capped at 1,000 nodes per hop to prevent unbounded memory usage.
+- Purpose: Persist memory content.
+- Input: `tags` (array, no whitespace, max 50 chars each), `importance` (0-10).
+- Output: Returns `hash` and `created` boolean.
+- Gotcha: Idempotent. Storing identical content+tags returns existing hash with `created: false`.
 
 `update_memory`
 
-- `hash` must exist (`E_NOT_FOUND` otherwise). New `content` required; `tags` optional (kept if omitted).
-- Returns `{ old_hash, new_hash }`. **The hash changes** — update references accordingly.
-- Emits a `resources/updated` notification for the old hash URI.
+- Purpose: Modify memory content.
+- Input: Requires `hash` and new `content`. `tags` optional.
+- Output: Returns `old_hash` and `new_hash`.
+- Nuance: Changing content changes the hash. The old memory is effectively replaced.
 
-`get_relationships`
+`search_memories`
 
-- `direction`: `outgoing` | `incoming` | `both` (default `both`).
-- Each relationship includes the linked memory's content and tags inline.
-- Returns `E_NOT_FOUND` if the source hash does not exist.
+- Purpose: FTS5 full-text search over content and tags.
+- Input: `query`, `limit` (default 20), `cursor` for pagination.
+- Limits: Max 100 results per call.
 
-`delete_memory` / `delete_memories`
+`recall`
 
-- Deleting a memory cascades to all its relationships (foreign key ON DELETE CASCADE).
-- Batch: `delete_memories` accepts 1–50 hashes. Atomic transaction.
-- Items not found are returned with `deleted: false` (not an error in batch mode).
+- Purpose: Graph traversal starting from search hits.
+- Input: `depth` (0-3, default 1). 0 = search only. Higher depth = more hops.
+- Gotcha: High depth may return large graphs. Use cautiously.
 
-`create_relationship` / `delete_relationship`
+`retrieve_context`
 
-- `create_relationship`: Idempotent — re-creating returns `created: false`.
-- `relation_type`: no whitespace, max 50 chars (e.g., `related_to`, `causes`, `depends_on`).
-- `delete_relationship`: Returns `E_NOT_FOUND` if the exact edge does not exist.
+- Purpose: Get memories optimized for LLM context window.
+- Input: `token_budget` (default 4000).
+- Output: `memories` array and `truncated` boolean.
 
-`memory_stats`
+`create_relationship`
 
-- No input. Returns total memories, total relationships, oldest/newest timestamps, average importance, and per-type breakdown.
+- Purpose: Link two memories.
+- Input: `from_hash`, `to_hash`, `relation_type` (e.g., related_to, causes).
+- Gotcha: Both hashes must exist.
 
 ---
 
 ## CROSS-FEATURE RELATIONSHIPS
 
-- Use `search_memories` results to obtain hashes for `get_memory`, `update_memory`, `delete_memory`, and `create_relationship`.
-- Use `recall` to discover connected memories and graph edges in a single call — combines FTS5 search with BFS traversal.
-- `update_memory` changes the hash — any relationships referencing the old hash are updated via CASCADE.
-- `memory://memories/{hash}` resource provides the same data as `get_memory` but through the MCP resource protocol.
+- Use `store_memory` to get hashes, then `create_relationship` to link them.
+- Use `search_memories` to find entry points for `recall` traversals.
+- `retrieve_context` uses the same ranking as `search_memories` but limits by token count.
 
 ---
 
 ## CONSTRAINTS & LIMITATIONS
 
-- Transport: stdio only.
-- Requires Node.js ≥ 24 with built-in `node:sqlite` and FTS5 support.
-- Database path: set via `MEMORY_DB_PATH` env var (default: `memory.db`).
-- SQLite busy timeout: 5,000 ms.
-- Content: max 100,000 characters per memory.
-- Tags: 1–100 per memory, each max 50 chars, no whitespace.
-- Hash: 64 lowercase hex characters (SHA-256).
-- Search query: 1–1,000 characters.
-- Batch operations: max 50 items per call.
-- Pagination cursors are base64url-encoded offsets — do not construct manually.
+- Content size: Max 100,000 characters per memory.
+- Batch size: Max 50 items for `store_memories` and `delete_memories`.
+- Tags: Max 100 tags per memory, no whitespace.
+- Relationships: Directed edges only.
 
 ---
 
 ## ERROR HANDLING STRATEGY
 
-- `E_NOT_FOUND`: Hash or relationship missing. → Call `search_memories` or `recall` to find valid hashes.
-- `E_DUPLICATE`: Entry already exists. → Safe to ignore for idempotent operations.
-- `E_CONSTRAINT`: Foreign key or uniqueness violation. → Verify both hashes exist before creating relationships.
-- `E_INVALID_CURSOR`: Malformed pagination cursor. → Drop the cursor and restart from the first page.
-- `E_TIMEOUT`: SQLite busy timeout exceeded (5s). → Retry after a brief delay; reduce batch size if persistent.
-- `E_UNKNOWN`: Unexpected error. → Check the error message for details; retry once.
-
----
+- `E_NOT_FOUND`: Memory hash or relationship not found. → Search/recall to find valid hashes.
+- `E_INVALID_CURSOR`: Pagination cursor invalid or expired. → Restart search without cursor.
+- `E_UNKNOWN`: Unexpected internal error. → Check input format and retry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/memory-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "mcpName": "io.github.j0hanz/memory-mcp",
   "author": "Johanz",
   "license": "MIT",