@j0hanz/memdb 1.3.0 → 1.4.0

package/dist/core/relationships.js

@@ -1,4 +1,4 @@
-import { executeAll, executeGet, executeRun, mapRowToRelationship, prepareCached, requireMemoryIdByHash, toSafeInteger, withImmediateTransaction, } from './db.js';
+import { mapRowToRelationship, requireMemoryIdByHash, sqlAll, sqlGet, sqlRun, toSafeInteger, withImmediateTransaction, } from './db.js';
 const buildNotFoundMessage = (hash) => `Memory not found: ${hash}`;
 export const createRelationship = (input) => withImmediateTransaction(() => {
     const fromId = requireMemoryIdByHash(input.from_hash, buildNotFoundMessage(input.from_hash));
@@ -6,57 +6,70 @@ export const createRelationship = (input) => withImmediateTransaction(() => {
     if (fromId === toId) {
         throw new Error('Cannot create self-referential relationship');
     }
-    const stmtInsertRelationship = prepareCached(`
-  INSERT OR IGNORE INTO relationships (from_memory_id, to_memory_id, relation_type)
-  VALUES (?, ?, ?)
-  RETURNING id
-`);
-    const inserted = executeGet(stmtInsertRelationship, fromId, toId, input.relation_type);
+    const inserted = sqlGet `
+      INSERT OR IGNORE INTO relationships
+        (from_memory_id, to_memory_id, relation_type)
+      VALUES (${fromId}, ${toId}, ${input.relation_type})
+      RETURNING id
+    `;
     if (inserted) {
         return { id: toSafeInteger(inserted.id, 'id'), isNew: true };
     }
-    const stmtFindRelationshipId = prepareCached(`
-  SELECT id FROM relationships
-  WHERE from_memory_id = ? AND to_memory_id = ? AND relation_type = ?
-`);
-    const existing = executeGet(stmtFindRelationshipId, fromId, toId, input.relation_type);
+    const existing = sqlGet `
+      SELECT id FROM relationships
+      WHERE from_memory_id = ${fromId}
+        AND to_memory_id = ${toId}
+        AND relation_type = ${input.relation_type}
+    `;
     if (!existing) {
         throw new Error('Failed to resolve relationship id');
     }
     return { id: toSafeInteger(existing.id, 'id'), isNew: false };
 });
-const buildGetRelationshipsQuery = (direction) => {
-    const baseSelect = `
-    SELECT r.id, r.relation_type, r.created_at,
-           mf.hash as from_hash, mt.hash as to_hash
-    FROM relationships r
-    JOIN memories mf ON r.from_memory_id = mf.id
-    JOIN memories mt ON r.to_memory_id = mt.id
-  `;
-    const orderBy = ' ORDER BY r.relation_type, mf.hash, mt.hash, r.created_at, r.id';
-    switch (direction) {
-        case 'outgoing':
-            return `${baseSelect} WHERE mf.hash = ?${orderBy}`;
-        case 'incoming':
-            return `${baseSelect} WHERE mt.hash = ?${orderBy}`;
-        case 'both':
-            return `${baseSelect} WHERE mf.hash = ? OR mt.hash = ?${orderBy}`;
-    }
-};
 export const getRelationships = (input) => {
     const direction = input.direction ?? 'both';
-    const stmt = prepareCached(buildGetRelationshipsQuery(direction));
-    const params = direction === 'both' ? [input.hash, input.hash] : [input.hash];
-    const rows = executeAll(stmt, ...params);
+    const rows = (() => {
+        switch (direction) {
+            case 'outgoing':
+                return sqlAll `
+          SELECT r.id, r.relation_type, r.created_at,
+                 mf.hash as from_hash, mt.hash as to_hash
+          FROM relationships r
+          JOIN memories mf ON r.from_memory_id = mf.id
+          JOIN memories mt ON r.to_memory_id = mt.id
+          WHERE mf.hash = ${input.hash}
+          ORDER BY r.relation_type, mf.hash, mt.hash, r.created_at, r.id
+        `;
+            case 'incoming':
+                return sqlAll `
+          SELECT r.id, r.relation_type, r.created_at,
+                 mf.hash as from_hash, mt.hash as to_hash
+          FROM relationships r
+          JOIN memories mf ON r.from_memory_id = mf.id
+          JOIN memories mt ON r.to_memory_id = mt.id
+          WHERE mt.hash = ${input.hash}
+          ORDER BY r.relation_type, mf.hash, mt.hash, r.created_at, r.id
+        `;
+            case 'both':
+                return sqlAll `
+          SELECT r.id, r.relation_type, r.created_at,
+                 mf.hash as from_hash, mt.hash as to_hash
+          FROM relationships r
+          JOIN memories mf ON r.from_memory_id = mf.id
+          JOIN memories mt ON r.to_memory_id = mt.id
+          WHERE mf.hash = ${input.hash} OR mt.hash = ${input.hash}
+          ORDER BY r.relation_type, mf.hash, mt.hash, r.created_at, r.id
+        `;
+        }
+    })();
     return rows.map(mapRowToRelationship);
 };
 export const deleteRelationship = (input) => {
-    const stmtDeleteRelationship = prepareCached(`
-  DELETE FROM relationships
-  WHERE from_memory_id = (SELECT id FROM memories WHERE hash = ?)
-    AND to_memory_id = (SELECT id FROM memories WHERE hash = ?)
-    AND relation_type = ?
-`);
-    const result = executeRun(stmtDeleteRelationship, input.from_hash, input.to_hash, input.relation_type);
+    const result = sqlRun `
+    DELETE FROM relationships
+    WHERE from_memory_id = (SELECT id FROM memories WHERE hash = ${input.from_hash})
+      AND to_memory_id = (SELECT id FROM memories WHERE hash = ${input.to_hash})
+      AND relation_type = ${input.relation_type}
+  `;
     return { changes: toSafeInteger(result.changes, 'changes') };
 };

package/dist/core/search.js

@@ -1,20 +1,41 @@
-import { executeAll, loadTagsForMemoryIds, mapRowToRelationship, mapRowToSearchResult, prepareCached, toSafeInteger, } from './db.js';
+import { getErrorMessage } from '../error-utils.js';
+import { throwIfAborted } from './abort.js';
+import { executeAll, loadTagsForMemoryIds, mapRowToRelationship, mapRowToSearchResult, prepareCached, sqlAll, } from './db.js';
 const MAX_QUERY_TOKENS = 50;
 const DEFAULT_LIMIT = 100;
 const MAX_RECALL_DEPTH = 3;
 const MAX_RECALL_MEMORIES = 50;
 const RECENCY_DECAY_DAYS = 7;
 const RECENCY_WEIGHT = 0.15;
-const throwIfAborted = (signal) => {
-    if (signal && typeof signal.throwIfAborted === 'function') {
-        signal.throwIfAborted();
+const CASE_FOLD_LOCALE = 'en-US';
+// Hoisted regex for performance
+const WHITESPACE_REGEX = /\s+/;
+const QUOTE_GLOBAL_REGEX = /"/g;
+const QUERY_SEGMENTER = typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, { granularity: 'word' })
+    : undefined;
+const normalizeTagToken = (token) => token.normalize('NFKC').toLocaleLowerCase(CASE_FOLD_LOCALE);
+const splitOnWhitespace = (query) => {
+    const trimmed = query.trim();
+    if (trimmed.length === 0)
+        return [];
+    return trimmed.split(WHITESPACE_REGEX);
+};
+const segmentQuery = (query) => {
+    if (!QUERY_SEGMENTER)
+        return splitOnWhitespace(query);
+    const tokens = [];
+    for (const segment of QUERY_SEGMENTER.segment(query.trim())) {
+        if (!segment.isWordLike)
+            continue;
+        const token = segment.segment.trim();
+        if (token.length > 0)
+            tokens.push(token);
     }
+    return tokens;
 };
 const tokenizeQuery = (query) => {
-    const parts = query
-        .trim()
-        .split(/\s+/)
-        .filter((w) => w.length > 0);
+    const parts = segmentQuery(query);
     if (parts.length === 0)
         return [];
     if (parts.length > MAX_QUERY_TOKENS) {
@@ -22,9 +43,37 @@ const tokenizeQuery = (query) => {
     }
     return parts;
 };
-const escapeFtsToken = (token) => `"${token.replace(/"/g, '""')}"`;
-const buildFtsQuery = (tokens) => tokens.length === 0 ? '""' : tokens.map(escapeFtsToken).join(' OR ');
-const buildSearchQuery = (tokens) => {
+const normalizeTokensForTags = (tokens) => {
+    const len = tokens.length;
+    const normalized = [];
+    for (let i = 0; i < len; i++) {
+        const t = tokens[i];
+        if (!t)
+            continue;
+        const token = normalizeTagToken(t);
+        if (token.length > 0)
+            normalized.push(token);
+    }
+    return normalized;
+};
+const escapeFtsToken = (token) => `"${token.replace(QUOTE_GLOBAL_REGEX, '""')}"`;
+const buildFtsQuery = (tokens) => {
+    const len = tokens.length;
+    if (len === 0)
+        return '""';
+    const first = tokens[0];
+    if (!first)
+        return '""';
+    let query = escapeFtsToken(first);
+    for (let i = 1; i < len; i++) {
+        const val = tokens[i];
+        if (val) {
+            query += ` OR ${escapeFtsToken(val)}`;
+        }
+    }
+    return query;
+};
+const buildSearchQuery = (tokens, tagTokens) => {
     const ftsQuery = buildFtsQuery(tokens);
     const relevanceExpr = '1.0 / (1.0 + abs(bm25(memories_fts)))';
     const recencyBoost = `MAX(0.0, (${RECENCY_DECAY_DAYS}.0 - julianday('now') + julianday(created_at)) / ${RECENCY_DECAY_DAYS}.0) * ${RECENCY_WEIGHT}`;
@@ -53,7 +102,10 @@ const buildSearchQuery = (tokens) => {
     ORDER BY relevance DESC
     LIMIT ?
   `;
-    return { sql, params: [ftsQuery, JSON.stringify(tokens), DEFAULT_LIMIT] };
+    return {
+        sql,
+        params: [ftsQuery, JSON.stringify(tagTokens), DEFAULT_LIMIT],
+    };
 };
 const INDEX_MISSING_TOKENS = [
     'no such module: fts5',
@@ -62,7 +114,6 @@ const INDEX_MISSING_TOKENS = [
 const QUERY_INVALID_TOKENS = ['fts5', 'syntax error'];
 const isSearchIndexMissing = (message) => INDEX_MISSING_TOKENS.some((token) => message.includes(token));
 const isSearchQueryInvalid = (message) => QUERY_INVALID_TOKENS.some((token) => message.includes(token));
-const getErrorMessage = (err) => err instanceof Error ? err.message : String(err);
 const toSearchError = (err) => {
     const message = getErrorMessage(err);
     if (isSearchIndexMissing(message)) {
@@ -85,19 +136,37 @@ const executeSearch = (sql, params) => {
 };
 const enrichSearchResultsWithTags = (rows, signal) => {
     throwIfAborted(signal);
-    const ids = rows.map((row) => toSafeInteger(row.id, 'id'));
+    const count = rows.length;
+    if (count === 0)
+        return [];
+    const ids = new Array(count);
+    for (let i = 0; i < count; i++) {
+        const row = rows[i];
+        if (!row)
+            throw new Error('Unreachable');
+        // Fast cast for internal DB use; strict validation happens in mapRowToSearchResult
+        ids[i] = Number(row.id);
+    }
     const tagsById = loadTagsForMemoryIds(ids);
-    return rows.map((row) => {
-        const id = toSafeInteger(row.id, 'id');
-        return mapRowToSearchResult(row, tagsById.get(id) ?? []);
-    });
+    const results = new Array(count);
+    for (let i = 0; i < count; i++) {
+        const row = rows[i];
+        const id = ids[i];
+        if (!row || id === undefined)
+            throw new Error('Unreachable');
+        // Map tags safely; id validation happens inside mapRowToSearchResult
+        const tags = tagsById.get(id);
+        results[i] = mapRowToSearchResult(row, tags ?? []);
+    }
+    return results;
 };
 export const searchMemories = (input, signal) => {
     throwIfAborted(signal);
     const tokens = tokenizeQuery(input.query);
     if (tokens.length === 0)
         throw new Error('Query cannot be empty');
-    const { sql, params } = buildSearchQuery(tokens);
+    const tagTokens = normalizeTokensForTags(tokens);
+    const { sql, params } = buildSearchQuery(tokens, tagTokens);
     const rows = executeSearch(sql, params);
     throwIfAborted(signal);
     return enrichSearchResultsWithTags(rows, signal);
@@ -109,68 +178,56 @@ const normalizeRecallDepth = (depth) => {
     const asInt = Math.trunc(raw);
     return Math.min(Math.max(0, asInt), MAX_RECALL_DEPTH);
 };
-const buildRecallQuery = () => `
-  WITH RECURSIVE connected(memory_id, depth) AS (
-    -- Seed memories from search results
-    SELECT m.id, 0
-    FROM memories m
-    WHERE m.id IN (SELECT value FROM json_each(?))
-
-    UNION
-
-    -- Follow relationships (both directions) up to max depth
-    SELECT 
-      CASE 
-        WHEN r.from_memory_id = c.memory_id THEN r.to_memory_id
-        ELSE r.from_memory_id
-      END,
-      c.depth + 1
-    FROM relationships r
-    JOIN connected c ON (r.from_memory_id = c.memory_id OR r.to_memory_id = c.memory_id)
-    WHERE c.depth < ?
-  ),
-  unique_memories AS (
-    SELECT DISTINCT memory_id, MIN(depth) as min_depth
-    FROM connected
-    GROUP BY memory_id
-    ORDER BY min_depth
-    LIMIT ?
-  )
-  SELECT m.*, 1.0 / (1.0 + um.min_depth) as relevance
-  FROM memories m
-  JOIN unique_memories um ON m.id = um.memory_id
-  ORDER BY um.min_depth, m.created_at DESC
-`;
-const buildRelationshipsQuery = () => `
-  WITH ids(id) AS (SELECT value FROM json_each(?))
-  SELECT r.id, r.relation_type, r.created_at,
-         mf.hash as from_hash, mt.hash as to_hash
-  FROM relationships r
-  JOIN ids a ON r.from_memory_id = a.id
-  JOIN ids b ON r.to_memory_id = b.id
-  JOIN memories mf ON r.from_memory_id = mf.id
-  JOIN memories mt ON r.to_memory_id = mt.id
-  ORDER BY r.relation_type, mf.hash, mt.hash, r.created_at, r.id
-`;
-const executeWithSql = (sql, params) => {
-    const stmt = prepareCached(sql);
-    return executeAll(stmt, ...params);
-};
 const executeRecall = (seedIds, depth) => {
     if (seedIds.length === 0)
         return [];
-    const sql = buildRecallQuery();
-    return executeWithSql(sql, [
-        JSON.stringify(seedIds),
-        depth,
-        MAX_RECALL_MEMORIES,
-    ]);
+    return sqlAll `
+    WITH RECURSIVE connected(memory_id, depth) AS (
+      -- Seed memories from search results
+      SELECT m.id, 0
+      FROM memories m
+      WHERE m.id IN (SELECT value FROM json_each(${JSON.stringify(seedIds)}))
+
+      UNION
+
+      -- Follow relationships (both directions) up to max depth
+      SELECT 
+        CASE 
+          WHEN r.from_memory_id = c.memory_id THEN r.to_memory_id
+          ELSE r.from_memory_id
+        END,
+        c.depth + 1
+      FROM relationships r
+      JOIN connected c ON (r.from_memory_id = c.memory_id OR r.to_memory_id = c.memory_id)
+      WHERE c.depth < ${depth}
+    ),
+    unique_memories AS (
+      SELECT DISTINCT memory_id, MIN(depth) as min_depth
+      FROM connected
+      GROUP BY memory_id
+      ORDER BY min_depth
+      LIMIT ${MAX_RECALL_MEMORIES}
+    )
+    SELECT m.*, 1.0 / (1.0 + um.min_depth) as relevance
+    FROM memories m
+    JOIN unique_memories um ON m.id = um.memory_id
+    ORDER BY um.min_depth, m.created_at DESC
+  `;
 };
 const loadRelationshipsForMemoryIds = (memoryIds) => {
     if (memoryIds.length === 0)
         return [];
-    const sql = buildRelationshipsQuery();
-    const rows = executeWithSql(sql, [JSON.stringify(memoryIds)]);
+    const rows = sqlAll `
+    WITH ids(id) AS (SELECT value FROM json_each(${JSON.stringify(memoryIds)}))
+    SELECT r.id, r.relation_type, r.created_at,
+           mf.hash as from_hash, mt.hash as to_hash
+    FROM relationships r
+    JOIN ids a ON r.from_memory_id = a.id
+    JOIN ids b ON r.to_memory_id = b.id
+    JOIN memories mf ON r.from_memory_id = mf.id
+    JOIN memories mt ON r.to_memory_id = mt.id
+    ORDER BY r.relation_type, mf.hash, mt.hash, r.created_at, r.id
+  `;
     return rows.map(mapRowToRelationship);
 };
 const emptyRecallResult = (depth) => ({
@@ -185,14 +242,29 @@ const recallAtDepthZero = (searchResults, depth) => {
 };
 const recallAtPositiveDepth = (searchResults, depth, signal) => {
     throwIfAborted(signal);
-    const seedIds = searchResults.map((m) => m.id);
+    const len = searchResults.length;
+    const seedIds = new Array(len);
+    for (let i = 0; i < len; i++) {
+        const res = searchResults[i];
+        if (!res)
+            throw new Error('Unreachable');
+        seedIds[i] = res.id;
+    }
     const recallRows = executeRecall(seedIds, depth);
     throwIfAborted(signal);
     const memories = enrichSearchResultsWithTags(recallRows, signal);
     if (memories.length === 0)
         return emptyRecallResult(depth);
     throwIfAborted(signal);
-    const relationships = loadRelationshipsForMemoryIds(memories.map((m) => m.id));
+    const memLen = memories.length;
+    const memIds = new Array(memLen);
+    for (let i = 0; i < memLen; i++) {
+        const mem = memories[i];
+        if (!mem)
+            throw new Error('Unreachable');
+        memIds[i] = mem.id;
+    }
+    const relationships = loadRelationshipsForMemoryIds(memIds);
     return { memories, relationships, depth };
 };
 export const recallMemories = (input, signal) => {

package/dist/error-utils.d.ts

@@ -0,0 +1 @@
+export declare const getErrorMessage: (error: unknown) => string;

package/dist/error-utils.js

@@ -0,0 +1,28 @@
+import { getSystemErrorMessage, getSystemErrorName, inspect } from 'node:util';
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+const toErrnoInfo = (error) => {
+    if (typeof error.code === 'string' && error.code.length > 0) {
+        return `${error.code}: ${error.message}`;
+    }
+    if (typeof error.errno === 'number') {
+        try {
+            const name = getSystemErrorName(error.errno);
+            const message = getSystemErrorMessage(error.errno);
+            return `${name}: ${message}`;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+};
+const inspectValue = (value) => inspect(value, { breakLength: 120, colors: false, compact: 3, depth: 2 });
+export const getErrorMessage = (error) => {
+    if (error instanceof Error) {
+        const errnoInfo = toErrnoInfo(error);
+        return errnoInfo ?? error.message;
+    }
+    if (isNonEmptyString(error))
+        return error;
+    return inspectValue(error);
+};

package/dist/index.js

@@ -1,18 +1,30 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import { findPackageJSON } from 'node:module';
 import process from 'node:process';
 import { McpServer, ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SUPPORTED_PROTOCOL_VERSIONS } from '@modelcontextprotocol/sdk/types.js';
-import pkg from '../package.json' with { type: 'json' };
 import { closeDb, initDb } from './core/db.js';
 import { attachProtocolLogger, logger } from './logger.js';
 import { ProtocolVersionGuardTransport } from './protocol-version-guard.js';
 import { BatchRejectingStdioServerTransport } from './stdio-transport.js';
 import { registerAllTools } from './tools.js';
-const readPackageVersion = () => {
-    const { version } = pkg;
-    return Promise.resolve(typeof version === 'string' ? version : undefined);
+const readPackageVersion = async () => {
+    const packageJsonPath = findPackageJSON('..', import.meta.url);
+    if (!packageJsonPath)
+        return undefined;
+    try {
+        const raw = await readFile(packageJsonPath, {
+            encoding: 'utf-8',
+            signal: AbortSignal.timeout(2000),
+        });
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === 'string' ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
 };
 const toNonEmptyTrimmedOrUndefined = (text) => {
     const trimmed = text.trim();
@@ -113,7 +125,7 @@ const closeServerResources = async () => {
 };
 const clearTimerAndExit = (timer, code) => {
     clearTimeout(timer);
-    process.exit(code);
+    process.exitCode = code;
 };
 const exitWithShutdownTimer = (timer, code, error) => {
     if (error !== undefined) {
@@ -176,19 +188,22 @@ const main = async () => {
 const registerSignalHandlers = () => {
     const signals = ['SIGTERM', 'SIGINT', 'SIGBREAK'];
     for (const signal of signals) {
-        process.on(signal, () => {
+        process.once(signal, () => {
             shutdown(signal);
         });
     }
 };
+const handleFatalError = (message, error) => {
+    logger.error(message, error);
+    closeDb();
+    process.exit(1);
+};
 const registerProcessHandlers = () => {
-    process.on('uncaughtException', (err, origin) => {
-        logger.error(`Uncaught exception (${origin}):`, err);
-        process.exit(1);
+    process.once('uncaughtException', (err, origin) => {
+        handleFatalError(`Uncaught exception (${origin}):`, err);
     });
-    process.on('unhandledRejection', (reason) => {
-        logger.error('Unhandled rejection:', reason);
-        process.exit(1);
+    process.once('unhandledRejection', (reason) => {
+        handleFatalError('Unhandled rejection:', reason);
     });
 };
 void main();

package/dist/instructions.md

@@ -1,59 +1,55 @@
-# memdb Instructions
+# memdb INSTRUCTIONS
 
-> Guidance for the Agent: These instructions are available as a resource (`internal://instructions`) or prompt (`get-help`). Load them when you are unsure about tool usage.
+> Available as resource `internal://instructions`. Load when unsure about tool usage.
 
-## 1. Core Capability
+## CORE CAPABILITY
 
-- **Domain:** Local SQLite-backed memory store with vector-like text search and graph relationships.
-- **Primary Resources:** `Memory`, `Relationship`, `Stats`.
+- 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).
 
-## 2. The "Golden Path" Workflows (Critical)
+## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
 
-_Describe the standard order of operations using ONLY tools that exist._
+### WORKFLOW A: Recall & Exploration
 
-### Workflow A: Recall & Exploration
+1. `search_memories` with `{ query }` — find memories by content/tags.
+2. `recall` with `{ query, depth }` — traverse graph connections from hits.
+3. `get_memory` with `{ hash }` — exact retrieval using hash from results.
+   NOTE: Never guess hashes. Always search first.
 
-1. Call `search_memories` to find entry points by content/tags.
-2. Call `recall` (depth 1–2) to traverse the knowledge graph from relevant hits.
-3. Call `get_memory` using the `hash` (SHA-256) for exact retrieval.
-   > Constraint: Never guess hashes. Always search or recall first.
+### WORKFLOW B: Knowledge Management
 
-### Workflow B: Knowledge Management
+1. `store_memory` or `store_memories` (batch ≤50) to persist content with tags.
+2. `create_relationship` to link memories via `{ from_hash, to_hash, relation_type }`.
+3. `update_memory` with `{ hash, content }` to revise — returns new hash.
+4. `delete_memory` / `delete_memories` — confirm with user first.
 
-1. Call `store_memory` (single) or `store_memories` (batch) to add context.
-2. Call `create_relationship` to link related memories (directed).
-3. Call `update_memory` to revise; this changes the hash.
-4. Call `delete_memory` only with user confirmation.
+## TOOL NUANCES & GOTCHAS
 
-## 3. Tool Nuances & Gotchas
+`search_memories` — `query` 1–1000 chars. Broaden if no results.
 
-_Do NOT repeat JSON schema. Focus on behavior and pitfalls._
+`recall` — `depth` 0–3 (default 1). Higher depth = more latency. 0 = no traversal.
 
-- **`search_memories`**
-  - **Purpose:** Full-text search over content and tags.
-  - **Inputs:** `query` string (required).
-  - **Common failure modes:** Empty results for too-specific queries; try broader terms.
+`store_memory` / `store_memories` — `content` ≤100K, `tags` 1–100 (no whitespace, ≤50 chars), optional `importance` 0–10, optional `memory_type` (general|fact|plan|decision|reflection|lesson|error|gradient). Idempotent. Batch supports partial success.
 
-- **`recall`**
-  - **Purpose:** Graph traversal starting from a defined query.
-  - **Inputs:** `query` string; `depth` (default 1, max 3 recommended).
-  - **Latency:** Higher depth increases time/token usage significantly.
+`update_memory` — `hash` must exist. New `content` required, `tags` optional. Changes the hash.
 
-- **`store_memory` / `store_memories`**
-  - **Purpose:** Persist new information.
-  - **Inputs:** `content` (text), `tags` (array of strings).
-  - **Side effects:** Writes to DB. Idempotent if content/tags identical (same hash).
+`get_memory` — `hash`: 64 hex chars (SHA-256). E_NOT_FOUND if missing.
 
-- **`update_memory`**
-  - **Inputs:** `hash` (must exist), new `content`/`tags`.
-  - **Side effects:** Creating a new memory hash; effectively a "move" + "create".
+`create_relationship` — `from_hash`, `to_hash`, `relation_type` (e.g. related_to, causes, depends_on). Both hashes must exist. Idempotent.
 
-- **`create_relationship`**
-  - **Inputs:** `from_hash`, `to_hash`, `relation_type` (e.g., "related_to").
-  - **Constraint:** Both hashes must exist.
+`get_relationships` — `hash` required, `direction` optional (outgoing|incoming|both).
 
-## 4. Error Handling Strategy
+`delete_memory` / `delete_memories` / `delete_relationship` — Destructive. E_NOT_FOUND if missing.
 
-- **`E_NOT_FOUND`**: The hash doesn't exist. Re-run search/recall.
-- **`E_TIMEOUT`**: Operation took too long (>5s default). Reduce batch size or depth.
-- **`E_INVALID_ARG`**: Check inputs against schema (e.g. valid hashes).
+`memory_stats` — No input. Returns counts and timestamps.
+
+## ERROR HANDLING STRATEGY
+
+- `E_NOT_FOUND`: Hash missing. Search/recall first.
+- `E_TIMEOUT`: Reduce batch size or recall depth.
+- Validation error: 64-char hex hash, non-empty content, no whitespace in tags.
+
+## RESOURCES
+
+- `internal://instructions`: This document.

package/dist/logger.js

@@ -1,4 +1,5 @@
 import { format } from 'node:util';
+import { getToolContext } from './async-context.js';
 import { config } from './config.js';
 const LEVELS = {
     error: 0,
@@ -18,12 +19,15 @@ const toProtocolLogLevel = (level) => {
     }
 };
 const formatLogMessage = (msg, args) => args.length === 0 ? msg : format(msg, ...args);
+const formatContextPrefix = (context) => context ? `[tool:${context.toolName}] ` : '';
 const createWriter = (level) => (msg, ...args) => {
     if (LEVELS[level] > threshold)
         return;
-    console.error(`[${level.toUpperCase()}] ${msg}`, ...args);
     const formatted = formatLogMessage(msg, args);
-    protocolLogSink?.(toProtocolLogLevel(level), formatted);
+    const context = getToolContext();
+    const withContext = `${formatContextPrefix(context)}${formatted}`;
+    console.error(`[${level.toUpperCase()}] ${withContext}`);
+    protocolLogSink?.(toProtocolLogLevel(level), withContext);
 };
 export const attachProtocolLogger = (sink) => {
     protocolLogSink = sink;