@j0hanz/memory-mcp 1.0.0 → 1.0.1

package/dist/instructions.md

@@ -1,14 +1,16 @@
 # MEMORY-MCP INSTRUCTIONS
 
-These instructions are available as a resource `internal://instructions` or prompt `get-help`. Load them 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: 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).
+- **Domain:** SQLite-backed persistent memory storage, full-text search, and graph recall for LLM agents.
+- **Primary Resources:** Memory entries (content + tags + metadata), directed labeled relationships between memories.
+- **Tools:**
+  - READ: `get_memory`, `search_memories`, `recall`, `retrieve_context`, `get_relationships`, `memory_stats`
+  - WRITE: `store_memory`, `store_memories`, `update_memory`, `delete_memory`, `delete_memories`, `create_relationship`, `delete_relationship`
 
 ---
 
@@ -21,103 +23,147 @@ These instructions are available as a resource `internal://instructions` or prom
 ## RESOURCES & RESOURCE LINKS
 
 - `internal://instructions`: This document.
-- `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.
+- `memory://memories/{hash}`: Retrieve a single memory by its SHA-256 hash (JSON). Supports hash auto-completion.
 
 ---
 
 ## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
 
-### WORKFLOW A: RECALL & EXPLORATION
+### WORKFLOW A: STORE AND RETRIEVE
 
-- 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.
+1. Call `store_memory` with `content`, `tags`, and optional `importance`/`memory_type` to persist a memory. Note the returned `hash`.
+2. Call `get_memory` with `hash` to retrieve it later.
+3. For bulk ingestion, call `store_memories` with up to 50 items in one atomic transaction.
+   NOTE: Storing identical content+tags is idempotent — returns the existing hash with `created: false`.
 
-### WORKFLOW B: KNOWLEDGE MANAGEMENT (STORAGE)
+### WORKFLOW B: SEARCH AND DISCOVER
 
-- 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.
+1. Call `search_memories` with a `query` string to full-text search across content and tags.
+2. Use `cursor` from the response's `nextCursor` to paginate through results.
+3. Apply filters: `min_importance`, `max_importance`, `memory_type` to narrow results.
+   NOTE: Query terms are matched individually. FTS5 phrase operators and negation are **not** supported.
 
-### WORKFLOW C: CONTEXT RETRIEVAL (RAG)
+### WORKFLOW C: GRAPH RECALL (BFS)
 
-- 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`.
+1. Call `recall` with a `query` and `depth` (0–3) to search memories and traverse relationships via BFS.
+2. Inspect the returned `memories` (all discovered nodes) and `graph` (edges connecting them).
+3. Use `depth: 0` for search-only (no traversal), `depth: 1–3` for progressively wider graph exploration.
+   NOTE: If `aborted: true` is returned, the traversal hit a safety limit. Results are still valid but incomplete.
 
-### WORKFLOW D: CLEANUP & MAINTENANCE
+### WORKFLOW D: CONTEXT WINDOW MANAGEMENT
 
-- 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.
+1. Call `retrieve_context` with a `query` and `token_budget` to get relevance-ranked memories that fit within a token limit.
+2. Choose `strategy`: `relevance` (FTS rank, default), `importance` (highest first), or `recency` (newest first).
+3. Check `truncated: true` to know if more memories matched but were excluded by the budget.
+   NOTE: Eliminates manual pagination and token counting. Use this when filling an LLM context window.
+
+### WORKFLOW E: BUILD KNOWLEDGE GRAPHS
+
+1. Call `store_memory` (or `store_memories`) to create memories and note their hashes.
+2. Call `create_relationship` with `from_hash`, `to_hash`, and `relation_type` to link them.
+3. Call `get_relationships` to inspect edges for a memory (filter by `direction`: outgoing, incoming, or both).
+4. Call `recall` with `depth: 1–3` to traverse the graph from a search query.
+   NOTE: Both endpoint memories must exist before creating a relationship.
 
 ---
 
 ## TOOL NUANCES & GOTCHAS
 
-`store_memory` / `store_memories`
+`store_memory`
+
+- Purpose: Store a single memory. Returns its SHA-256 hash.
+- Gotcha: Hash is deterministic — computed from `content` + sorted `tags`. Same content+tags always produces the same hash.
+- Gotcha: `importance` defaults to `0` if omitted. `memory_type` defaults to `general`.
 
-- 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`.
+`store_memories`
+
+- Purpose: Batch store up to 50 memories in one atomic transaction.
+- Gotcha: If the transaction fails, all items roll back. Per-item results indicate `created: true/false`.
 
 `update_memory`
 
-- 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.
+- Purpose: Replace content (and optionally tags) of an existing memory. Returns old and new hashes.
+- Gotcha: The hash changes when content or tags change. Relationships automatically cascade to the new hash.
+- Gotcha: Returns `E_CONFLICT` if a memory already exists with the new content+tags combination.
 
 `search_memories`
 
-- Purpose: FTS5 full-text search over content and tags.
-- Input: `query`, `limit` (default 20), `cursor` for pagination.
-- Limits: Max 100 results per call.
+- Purpose: Full-text search over content and tags using SQLite FTS5.
+- Input: `limit` defaults to 20, max 100. `cursor` from previous `nextCursor` for pagination.
+- Gotcha: Only alphanumeric tokens are indexed. Special characters and FTS5 operators are stripped from queries.
 
 `recall`
 
-- 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.
+- Purpose: FTS search + BFS graph traversal up to 3 hops.
+- Input: `depth` defaults to 1, max 3. `limit` defaults to 10 (seed memories), max 50.
+- Gotcha: Traversal is bounded by frontier size (default 1,000), edge count (default 5,000), and visited nodes (default 5,000). Override via `RECALL_MAX_FRONTIER_SIZE`, `RECALL_MAX_EDGE_ROWS`, `RECALL_MAX_VISITED_NODES` env vars.
 
 `retrieve_context`
 
-- Purpose: Get memories optimized for LLM context window.
-- Input: `token_budget` (default 4000).
-- Output: `memories` array and `truncated` boolean.
+- Purpose: Token-budgeted memory retrieval — fills a token budget with ranked results.
+- Input: `token_budget` defaults to 4,000, max 200,000. `strategy` defaults to `relevance`.
+- Gotcha: Token estimation uses ~4 characters per token. Internal candidate cap is 200 rows.
+
+`get_relationships`
+
+- Purpose: Retrieve all relationships for a memory with the linked memory content inlined.
+- Input: `direction` defaults to `both`. Options: `outgoing`, `incoming`, `both`.
+- Gotcha: Returns `E_NOT_FOUND` if the source memory does not exist.
 
 `create_relationship`
 
-- Purpose: Link two memories.
-- Input: `from_hash`, `to_hash`, `relation_type` (e.g., related_to, causes).
-- Gotcha: Both hashes must exist.
+- Purpose: Create a directed labeled edge between two memories.
+- Input: `relation_type` is free-form. Suggested types: `related_to`, `causes`, `depends_on`, `parent_of`, `child_of`, `supersedes`, `contradicts`, `supports`, `references`.
+- Gotcha: Idempotent — re-creating an existing relationship is a no-op. Both memories must exist.
+
+`delete_memory`
+
+- Purpose: Delete a single memory and all its relationships.
+- Side effects: Cascade-deletes all relationships involving this memory.
+
+`delete_memories`
+
+- Purpose: Batch delete up to 50 memories in one atomic transaction.
+- Side effects: Cascade-deletes all relationships involving deleted memories.
+
+`memory_stats`
+
+- Purpose: Return aggregate statistics (total counts, oldest/newest timestamps, average importance, breakdown by type).
 
 ---
 
 ## CROSS-FEATURE RELATIONSHIPS
 
-- 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.
+- `store_memory` / `store_memories` produce hashes required by `get_memory`, `update_memory`, `delete_memory`, `create_relationship`, and `get_relationships`.
+- `search_memories` and `recall` share the same FTS5 index, query sanitization, and cursor pagination.
+- `recall` combines `search_memories`-style FTS seeding with BFS graph traversal from `get_relationships`-style edge queries.
+- `retrieve_context` uses the same FTS5 index but adds token budgeting and sort strategies on top.
+- `update_memory` changes a memory's hash — relationships cascade automatically via foreign keys.
+- `delete_memory` / `delete_memories` cascade-delete relationships via foreign keys.
 
 ---
 
 ## CONSTRAINTS & LIMITATIONS
 
-- 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.
+- **Transport:** stdio only.
+- **Runtime:** Node.js >= 24 with FTS5-enabled SQLite.
+- **Database path:** Set via `MEMORY_DB_PATH` env var (default: `memory.db`).
+- **Content size:** Max 100,000 characters per memory.
+- **Tags:** 1–100 tags per memory, each max 50 characters, no whitespace.
+- **Importance:** Integer 0–10 (0 = lowest, 10 = critical).
+- **Memory types:** `general`, `fact`, `plan`, `decision`, `reflection`, `lesson`, `error`, `gradient`.
+- **Search limit:** Max 100 results per query (default 20).
+- **Recall depth:** Max 3 hops (default 1). Seed limit max 50 (default 10).
+- **Retrieve context budget:** Max 200,000 tokens (default 4,000). Internal candidate cap: 200 rows.
+- **Batch operations:** Max 50 items per `store_memories` / `delete_memories` call.
+- **BFS safety limits:** Configurable via `RECALL_MAX_FRONTIER_SIZE` (default 1,000), `RECALL_MAX_EDGE_ROWS` (default 5,000), `RECALL_MAX_VISITED_NODES` (default 5,000).
 
 ---
 
 ## ERROR HANDLING STRATEGY
 
-- `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.
+- `E_NOT_FOUND`: Memory or relationship does not exist. → Call `search_memories` to find the correct hash, or verify the hash with `get_memory`.
+- `E_INVALID_CURSOR`: Pagination cursor is malformed or does not match the current query/filters. → Drop the cursor and restart pagination from the beginning.
+- `E_CONFLICT`: `update_memory` target content+tags already exists as another memory. → Call `get_memory` with the conflicting hash or choose different content/tags.
+- `E_DB_ERROR`: Database operation failed. → Check that the database file is accessible and not corrupted. Retry the operation.
+- `E_UNKNOWN`: Unexpected internal error. → Retry the operation. If persistent, inspect server logs.

package/dist/lib/errors.d.ts

@@ -1,5 +1,8 @@
 export declare const E_NOT_FOUND = "E_NOT_FOUND";
 export declare const E_INVALID_CURSOR = "E_INVALID_CURSOR";
+export declare const E_DB_ERROR = "E_DB_ERROR";
+export declare const E_CONFLICT = "E_CONFLICT";
 export declare const E_UNKNOWN = "E_UNKNOWN";
 export declare function getErrorMessage(err: unknown): string;
+export declare function rethrowMcpError(err: unknown): void;
 //# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAKpD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,SAAS,cAAc,CAAC;AAGrC,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAIpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAElD"}

package/dist/lib/errors.js

@@ -1,12 +1,19 @@
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
 export const E_NOT_FOUND = 'E_NOT_FOUND';
 export const E_INVALID_CURSOR = 'E_INVALID_CURSOR';
+export const E_DB_ERROR = 'E_DB_ERROR';
+export const E_CONFLICT = 'E_CONFLICT';
 export const E_UNKNOWN = 'E_UNKNOWN';
+const UNKNOWN_ERROR_MESSAGE = 'Unknown error occurred';
 export function getErrorMessage(err) {
     if (err instanceof Error)
         return err.message;
-    const errorAsString = typeof err === 'string' ? err : undefined;
-    if (errorAsString != null)
-        return errorAsString;
-    return 'Unknown error occurred';
+    if (typeof err === 'string')
+        return err;
+    return UNKNOWN_ERROR_MESSAGE;
+}
+export function rethrowMcpError(err) {
+    if (err instanceof McpError)
+        throw err;
 }
 //# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AACnD,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AAErC,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IAC7C,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,IAAI,aAAa,IAAI,IAAI;QAAE,OAAO,aAAa,CAAC;IAChD,OAAO,wBAAwB,CAAC;AAClC,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAE9D,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AACnD,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AACvC,MAAM,CAAC,MAAM,UAAU,GAAG,YAAY,CAAC;AACvC,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AACrC,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAEvD,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IAC7C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IACxC,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,GAAG,YAAY,QAAQ;QAAE,MAAM,GAAG,CAAC;AACzC,CAAC"}

package/dist/lib/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/lib/hash.ts"],"names":[],"mappings":"AAMA,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,CAKR"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/lib/hash.ts"],"names":[],"mappings":"AAgBA,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,CAKR"}

package/dist/lib/hash.js

@@ -1,11 +1,18 @@
 import { createHash } from 'node:crypto';
+const MEMORY_HASH_ALGORITHM = 'sha256';
 function normalizeTags(tags) {
+    if (tags.length < 2) {
+        return tags;
+    }
     return [...tags].sort();
 }
+function stableTagsJson(tags) {
+    return JSON.stringify(normalizeTags(tags));
+}
 export function computeMemoryHash(content, tags) {
-    return createHash('sha256')
+    return createHash(MEMORY_HASH_ALGORITHM)
         .update(content)
-        .update(JSON.stringify(normalizeTags(tags)))
+        .update(stableTagsJson(tags))
         .digest('hex');
 }
 //# sourceMappingURL=hash.js.map

package/dist/lib/hash.js.map

@@ -1 +1 @@
-{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/lib/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,SAAS,aAAa,CAAC,IAAuB;IAC5C,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,IAAuB;IAEvB,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,OAAO,CAAC;SACf,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;SAC3C,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/lib/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,qBAAqB,GAAG,QAAQ,CAAC;AAEvC,SAAS,aAAa,CAAC,IAAuB;IAC5C,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED,SAAS,cAAc,CAAC,IAAuB;IAC7C,OAAO,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,OAAe,EACf,IAAuB;IAEvB,OAAO,UAAU,CAAC,qBAAqB,CAAC;SACrC,MAAM,CAAC,OAAO,CAAC;SACf,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;SAC5B,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}

package/dist/lib/instructions.d.ts

@@ -0,0 +1,2 @@
+export declare function loadInstructions(): string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/lib/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/lib/instructions.ts"],"names":[],"mappings":"AAaA,wBAAgB,gBAAgB,IAAI,MAAM,CAgBzC"}

package/dist/lib/instructions.js

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const BASE_DIR = fileURLToPath(new URL('.', import.meta.url));
+const FALLBACK_INSTRUCTIONS = '# Memory instructions\n\nSee the README for usage details.';
+const INSTRUCTION_PATHS = [
+    join(BASE_DIR, '..', 'instructions.md'),
+    join(BASE_DIR, '..', '..', 'src', 'instructions.md'),
+];
+let cachedInstructions;
+export function loadInstructions() {
+    if (cachedInstructions !== undefined) {
+        return cachedInstructions;
+    }
+    for (const p of INSTRUCTION_PATHS) {
+        try {
+            cachedInstructions = readFileSync(p, 'utf8');
+            return cachedInstructions;
+        }
+        catch {
+            // try next path
+        }
+    }
+    cachedInstructions = FALLBACK_INSTRUCTIONS;
+    return cachedInstructions;
+}
+//# sourceMappingURL=instructions.js.map

package/dist/lib/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/lib/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC9D,MAAM,qBAAqB,GACzB,4DAA4D,CAAC;AAC/D,MAAM,iBAAiB,GAAG;IACxB,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,iBAAiB,CAAC;IACvC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,iBAAiB,CAAC;CACrD,CAAC;AACF,IAAI,kBAAsC,CAAC;AAE3C,MAAM,UAAU,gBAAgB;IAC9B,IAAI,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,iBAAiB,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,kBAAkB,GAAG,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAC7C,OAAO,kBAAkB,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,gBAAgB;QAClB,CAAC;IACH,CAAC;IAED,kBAAkB,GAAG,qBAAqB,CAAC;IAC3C,OAAO,kBAAkB,CAAC;AAC5B,CAAC"}

package/dist/lib/mcp-utils.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error';
+export declare function logToolEvent(server: McpServer, logger: string, data: unknown, level?: LogLevel): Promise<void>;
+export declare function notifyMemoryResourceUpdated(server: McpServer, hash: string): Promise<void>;
+export {};
+//# sourceMappingURL=mcp-utils.d.ts.map

package/dist/lib/mcp-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-utils.d.ts","sourceRoot":"","sources":["../../src/lib/mcp-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAElE,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,KAAK,GAAE,QAAiB,GACvB,OAAO,CAAC,IAAI,CAAC,CAUf;AAID,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/lib/mcp-utils.js

@@ -0,0 +1,26 @@
+export async function logToolEvent(server, logger, data, level = 'info') {
+    if (!server.isConnected()) {
+        return;
+    }
+    try {
+        await server.server.sendLoggingMessage({ level, logger, data });
+    }
+    catch {
+        // best-effort logging
+    }
+}
+const MEMORY_RESOURCE_URI_PREFIX = 'memory://memories/';
+export async function notifyMemoryResourceUpdated(server, hash) {
+    if (!server.isConnected()) {
+        return;
+    }
+    try {
+        await server.server.sendResourceUpdated({
+            uri: `${MEMORY_RESOURCE_URI_PREFIX}${hash}`,
+        });
+    }
+    catch {
+        // best-effort notification
+    }
+}
+//# sourceMappingURL=mcp-utils.js.map

package/dist/lib/mcp-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-utils.js","sourceRoot":"","sources":["../../src/lib/mcp-utils.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAiB,EACjB,MAAc,EACd,IAAa,EACb,QAAkB,MAAM;IAExB,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,sBAAsB;IACxB,CAAC;AACH,CAAC;AAED,MAAM,0BAA0B,GAAG,oBAAoB,CAAC;AAExD,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAiB,EACjB,IAAY;IAEZ,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC;YACtC,GAAG,EAAE,GAAG,0BAA0B,GAAG,IAAI,EAAE;SAC5C,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;AACH,CAAC"}

package/dist/lib/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,OAAO,CAAC;CAClB;AAwBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASnD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAM5E"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,OAAO,EAAE,OAAO,CAAC;CAClB;AAiCD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASnD;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAM5E"}

package/dist/lib/pagination.js

@@ -1,21 +1,28 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { E_INVALID_CURSOR } from './errors.js';
 const CURSOR_ENCODING = 'base64url';
+const INVALID_CURSOR_STRUCTURE_MESSAGE = 'Invalid cursor structure';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isNonNegativeInteger(value) {
+    return (typeof value === 'number' &&
+        Number.isInteger(value) &&
+        Number.isFinite(value) &&
+        value >= 0);
+}
 function isCursorPayload(value) {
-    if (typeof value !== 'object' || value === null) {
+    if (!isRecord(value)) {
         return false;
     }
     const { offset } = value;
-    return (typeof offset === 'number' &&
-        Number.isInteger(offset) &&
-        Number.isFinite(offset) &&
-        offset >= 0);
+    return isNonNegativeInteger(offset);
 }
 function parseCursorPayload(cursor) {
     const json = Buffer.from(cursor, CURSOR_ENCODING).toString();
     const parsed = JSON.parse(json);
     if (!isCursorPayload(parsed)) {
-        throw new Error('Invalid cursor structure');
+        throw new Error(INVALID_CURSOR_STRUCTURE_MESSAGE);
     }
     return parsed;
 }
@@ -35,6 +42,6 @@ export function splitPage(rows, limit) {
     if (rows.length > limit) {
         return { page: rows.slice(0, limit), hasMore: true };
     }
-    return { page: [...rows], hasMore: false };
+    return { page: rows.slice(), hasMore: false };
 }
 //# sourceMappingURL=pagination.js.map

package/dist/lib/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,eAAe,GAAG,WAAW,CAAC;AAWpC,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,KAAgC,CAAC;IACpD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;QACxB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;QACvB,MAAM,IAAI,CAAC,CACZ,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,OAAO,GAAkB,EAAE,MAAM,EAAE,CAAC;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,aAAa,EACvB,GAAG,gBAAgB,oBAAoB,CACxC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAI,IAAkB,EAAE,KAAa;IAC5D,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/lib/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,eAAe,GAAG,WAAW,CAAC;AAUpC,MAAM,gCAAgC,GAAG,0BAA0B,CAAC;AAEpE,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;QACvB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACtB,KAAK,IAAI,CAAC,CACX,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACzB,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAc;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,OAAO,GAAkB,EAAE,MAAM,EAAE,CAAC;IAC1C,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAChB,SAAS,CAAC,aAAa,EACvB,GAAG,gBAAgB,oBAAoB,CACxC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,SAAS,CAAI,IAAkB,EAAE,KAAa;IAC5D,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACvD,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC"}

package/dist/lib/search-cursor.d.ts

@@ -0,0 +1,13 @@
+import type { MemoryFilters } from './search.js';
+export type DecodedSearchCursor = {
+    mode: 'keyset';
+    rank: number;
+    hash: string;
+} | {
+    mode: 'offset';
+    offset: number;
+};
+export declare function buildSearchCursorScope(query: string, filters: MemoryFilters): string;
+export declare function encodeSearchCursor(scope: string, rank: number, hash: string): string;
+export declare function decodeSearchCursor(cursor: string, expectedScope: string): DecodedSearchCursor;
+//# sourceMappingURL=search-cursor.d.ts.map

package/dist/lib/search-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-cursor.d.ts","sourceRoot":"","sources":["../../src/lib/search-cursor.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAmBjD,MAAM,MAAM,mBAAmB,GAC3B;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AA+DN,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,aAAa,GACrB,MAAM,CAKR;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,MAAM,CASR;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,mBAAmB,CAuBrB"}

package/dist/lib/search-cursor.js

@@ -0,0 +1,89 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { createHash } from 'node:crypto';
+import { E_INVALID_CURSOR } from './errors.js';
+const CURSOR_ENCODING = 'base64url';
+const CURSOR_VERSION = 2;
+const CURSOR_KIND = 'fts-keyset';
+const CURSOR_SCOPE_HASH_LENGTH = 24;
+function invalidCursor(reason) {
+    return new McpError(ErrorCode.InvalidParams, `${E_INVALID_CURSOR}: ${reason}`);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isKeysetCursorPayload(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (value['v'] === CURSOR_VERSION &&
+        value['kind'] === CURSOR_KIND &&
+        typeof value['scope'] === 'string' &&
+        typeof value['rank'] === 'number' &&
+        Number.isFinite(value['rank']) &&
+        typeof value['hash'] === 'string' &&
+        /^[a-f0-9]{64}$/.test(value['hash']));
+}
+function isLegacyOffsetCursorPayload(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const { offset } = value;
+    return (typeof offset === 'number' &&
+        Number.isInteger(offset) &&
+        Number.isFinite(offset) &&
+        offset >= 0);
+}
+function parseCursorPayload(cursor) {
+    try {
+        const json = Buffer.from(cursor, CURSOR_ENCODING).toString();
+        return JSON.parse(json);
+    }
+    catch {
+        throw invalidCursor('malformed cursor');
+    }
+}
+function toScopeInput(query, filters) {
+    return JSON.stringify({
+        query,
+        min_importance: filters.min_importance ?? null,
+        max_importance: filters.max_importance ?? null,
+        memory_type: filters.memory_type ?? null,
+    });
+}
+export function buildSearchCursorScope(query, filters) {
+    return createHash('sha256')
+        .update(toScopeInput(query, filters))
+        .digest('hex')
+        .slice(0, CURSOR_SCOPE_HASH_LENGTH);
+}
+export function encodeSearchCursor(scope, rank, hash) {
+    const payload = {
+        v: CURSOR_VERSION,
+        kind: CURSOR_KIND,
+        scope,
+        rank,
+        hash,
+    };
+    return Buffer.from(JSON.stringify(payload)).toString(CURSOR_ENCODING);
+}
+export function decodeSearchCursor(cursor, expectedScope) {
+    const payload = parseCursorPayload(cursor);
+    if (isKeysetCursorPayload(payload)) {
+        if (payload.scope !== expectedScope) {
+            throw invalidCursor('cursor does not match current query or filters');
+        }
+        return {
+            mode: 'keyset',
+            rank: payload.rank,
+            hash: payload.hash,
+        };
+    }
+    if (isLegacyOffsetCursorPayload(payload)) {
+        return {
+            mode: 'offset',
+            offset: payload.offset,
+        };
+    }
+    throw invalidCursor('malformed cursor');
+}
+//# sourceMappingURL=search-cursor.js.map

package/dist/lib/search-cursor.js.map

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

package/dist/lib/search.d.ts

@@ -1,4 +1,6 @@
 import type { SQLInputValue } from 'node:sqlite';
+import type { TypedDb } from '../db/typed.js';
+import type { MemoryRow } from './types.js';
 export declare function sanitizeFtsQuery(query: string): string;
 export interface MemoryFilters {
     min_importance?: number;
@@ -9,6 +11,20 @@ export interface FilterClauses {
     clauses: string[];
     params: SQLInputValue[];
 }
+export type SearchCursorState = {
+    mode: 'offset';
+    offset: number;
+} | {
+    mode: 'keyset';
+    rank: number;
+    hash: string;
+};
 export declare function buildFilterClauses(filters: MemoryFilters): FilterClauses;
 export declare function buildAndWhereClause(clauses: readonly string[]): string;
+export declare function loadRankedSearchRows(db: TypedDb, query: string, limit: number, cursor: SearchCursorState | undefined, filters: MemoryFilters): MemoryRow[];
+export declare function toMemoryFilters(params: {
+    min_importance?: number | undefined;
+    max_importance?: number | undefined;
+    memory_type?: string | undefined;
+}): MemoryFilters;
 //# sourceMappingURL=search.d.ts.map

package/dist/lib/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AASjD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAgBxE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMtE"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAW5C,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAWN,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,aAAa,CAaxE;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMtE;AAuBD,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,OAAO,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,OAAO,EAAE,aAAa,GACrB,SAAS,EAAE,CAoBb;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC,GAAG,aAAa,CAUhB"}