@j0hanz/memdb 1.2.5 → 1.2.6

package/README.md

@@ -161,7 +161,7 @@ Search memories by content and tags.
 | :-------- | :----- | :------- | :------ | :---------------------------------------- |
 | `query`   | string | Yes      | -       | Search query (1-1000 chars, max 50 terms) |
 
-**Returns:** Array of search results (`Memory` + `relevance`).
+**Returns:** Array of search results (`Memory` + `relevance`, includes `tags`).
 
 Notes:
 
@@ -177,7 +177,11 @@ Retrieve a specific memory by its hash.
 | :-------- | :----- | :------- | :------ | :------------------ |
 | `hash`    | string | Yes      | -       | MD5 hash (32 chars) |
 
-**Returns:** `Memory`.
+**Returns:** `Memory` (includes `tags`).
+
+Notes:
+
+- Updates `accessed_at` on read.
 
 ### `delete_memory`
 
@@ -242,6 +246,7 @@ All memory-shaped responses include:
 - `id`: integer ID
 - `content`: original content string
 - `summary`: optional summary (currently unset by tools)
+- `tags`: string array
 - `created_at`: timestamp string
 - `accessed_at`: timestamp string
 - `hash`: MD5 hash

package/dist/core/db.d.ts

@@ -1,5 +1,5 @@
 import { DatabaseSync, type StatementSync } from 'node:sqlite';
-import { type Memory, type SearchResult } from '../types.js';
+import { type Memory, type Relationship, type SearchResult } from '../types.js';
 export type DbRow = Record<string, unknown>;
 export declare const db: DatabaseSync;
 export declare const closeDb: () => void;
@@ -12,5 +12,7 @@ export declare const executeRun: (stmt: StatementSync, ...params: SqlParam[]) =>
 };
 export declare const withImmediateTransaction: <T>(operation: () => T) => T;
 export declare const toSafeInteger: (value: unknown, field: string) => number;
-export declare const mapRowToMemory: (row: DbRow) => Memory;
-export declare const mapRowToSearchResult: (row: DbRow) => SearchResult;
+export declare const mapRowToMemory: (row: DbRow, tags?: string[]) => Memory;
+export declare const mapRowToSearchResult: (row: DbRow, tags?: string[]) => SearchResult;
+export declare const mapRowToRelationship: (row: DbRow) => Relationship;
+export declare const loadTagsForMemoryIds: (memoryIds: readonly number[]) => Map<number, string[]>;

package/dist/core/db.js

@@ -67,23 +67,18 @@ const FTS_SYNC_SQL = `
   WHERE id NOT IN (SELECT rowid FROM memories_fts);
 `;
 const withTimeout = async (promise, ms, message) => {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => {
-        controller.abort();
-    }, ms);
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            reject(new Error(message));
+        }, ms);
+    });
     try {
-        const result = await Promise.race([
-            promise,
-            new Promise((_, reject) => {
-                controller.signal.addEventListener('abort', () => {
-                    reject(new Error(message));
-                });
-            }),
-        ]);
-        return result;
+        return await Promise.race([promise, timeoutPromise]);
     }
     finally {
-        clearTimeout(timeout);
+        if (timeout)
+            clearTimeout(timeout);
     }
 };
 const ensureDbDirectory = async (dbPath) => {
@@ -146,26 +141,22 @@ const enforceStatementCacheLimit = () => {
 const isDbRow = (value) => {
     return typeof value === 'object' && value !== null;
 };
+const assertDbRow = (value) => {
+    if (!isDbRow(value)) {
+        throw new Error('Invalid row');
+    }
+    return value;
+};
 const toDbRowArray = (value) => {
     if (!Array.isArray(value)) {
         throw new Error('Expected rows array');
     }
-    const rows = [];
-    for (const row of value) {
-        if (!isDbRow(row)) {
-            throw new Error('Invalid row');
-        }
-        rows.push(row);
-    }
-    return rows;
+    return value.map(assertDbRow);
 };
 const toDbRowOrUndefined = (value) => {
     if (value === undefined)
         return undefined;
-    if (!isDbRow(value)) {
-        throw new Error('Invalid row');
-    }
-    return value;
+    return assertDbRow(value);
 };
 const toRunResult = (value) => {
     if (typeof value !== 'object' || value === null) {
@@ -206,13 +197,18 @@ export const withImmediateTransaction = (operation) => {
     }
 };
 const createFieldError = (field) => new Error(`Invalid ${field}`);
+const assertFiniteNumber = (value, field) => {
+    if (!Number.isFinite(value)) {
+        throw createFieldError(field);
+    }
+    return value;
+};
 const toNumber = (value, field) => {
-    if (typeof value === 'number' && Number.isFinite(value))
-        return value;
+    if (typeof value === 'number') {
+        return assertFiniteNumber(value, field);
+    }
     if (typeof value === 'bigint') {
-        const numeric = Number(value);
-        if (Number.isFinite(numeric))
-            return numeric;
+        return assertFiniteNumber(Number(value), field);
     }
     throw createFieldError(field);
 };
@@ -246,17 +242,68 @@ const toOptionalNumber = (value, field) => {
         return undefined;
     return toNumber(value, field);
 };
-export const mapRowToMemory = (row) => ({
+export const mapRowToMemory = (row, tags = []) => ({
     id: toSafeInteger(row.id, 'id'),
     content: toString(row.content, 'content'),
     summary: toOptionalString(row.summary, 'summary'),
+    tags,
     importance: toSafeInteger(row.importance ?? 0, 'importance'),
     memory_type: toMemoryType(row.memory_type ?? 'general', 'memory_type'),
     created_at: toString(row.created_at, 'created_at'),
     accessed_at: toString(row.accessed_at, 'accessed_at'),
     hash: toString(row.hash, 'hash'),
 });
-export const mapRowToSearchResult = (row) => ({
-    ...mapRowToMemory(row),
+export const mapRowToSearchResult = (row, tags = []) => ({
+    ...mapRowToMemory(row, tags),
     relevance: toOptionalNumber(row.relevance, 'relevance') ?? 0,
 });
+export const mapRowToRelationship = (row) => ({
+    id: toSafeInteger(row.id, 'id'),
+    from_hash: toString(row.from_hash, 'from_hash'),
+    to_hash: toString(row.to_hash, 'to_hash'),
+    relation_type: toString(row.relation_type, 'relation_type'),
+    created_at: toString(row.created_at, 'created_at'),
+});
+const tagsSelectStatements = [];
+const getSelectTagsStatement = (idCount) => {
+    const cached = tagsSelectStatements[idCount];
+    if (cached)
+        return cached;
+    const placeholders = Array.from({ length: idCount }, () => '?').join(', ');
+    const stmt = db.prepare(`SELECT memory_id, tag FROM tags WHERE memory_id IN (${placeholders}) ORDER BY memory_id, tag`);
+    tagsSelectStatements[idCount] = stmt;
+    return stmt;
+};
+const dedupeIds = (ids) => {
+    const seen = new Set();
+    const unique = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        unique.push(id);
+    }
+    return unique;
+};
+const pushToMapArray = (map, key, value) => {
+    const existing = map.get(key);
+    if (existing) {
+        existing.push(value);
+        return;
+    }
+    map.set(key, [value]);
+};
+export const loadTagsForMemoryIds = (memoryIds) => {
+    const uniqueIds = dedupeIds(memoryIds);
+    if (uniqueIds.length === 0)
+        return new Map();
+    const stmt = getSelectTagsStatement(uniqueIds.length);
+    const rows = executeAll(stmt, ...uniqueIds);
+    const tagsById = new Map();
+    for (const row of rows) {
+        const memoryId = toSafeInteger(row.memory_id, 'memory_id');
+        const tag = toString(row.tag, 'tag');
+        pushToMapArray(tagsById, memoryId, tag);
+    }
+    return tagsById;
+};

package/dist/core/memory-read.js

@@ -1,36 +1,48 @@
-import { db, executeGet, executeRun, mapRowToMemory, toSafeInteger, withImmediateTransaction, } from './db.js';
+import { db, executeGet, executeRun, loadTagsForMemoryIds, mapRowToMemory, toSafeInteger, withImmediateTransaction, } from './db.js';
 const stmtGetMemoryByHash = db.prepare('SELECT * FROM memories WHERE hash = ?');
+const stmtTouchMemoryByHash = db.prepare('UPDATE memories SET accessed_at = CURRENT_TIMESTAMP WHERE hash = ?');
 const stmtDeleteMemoryByHash = db.prepare('DELETE FROM memories WHERE hash = ?');
 export const getMemory = (hash) => {
-    const row = executeGet(stmtGetMemoryByHash, hash);
-    return row ? mapRowToMemory(row) : undefined;
+    return withImmediateTransaction(() => {
+        executeRun(stmtTouchMemoryByHash, hash);
+        const row = executeGet(stmtGetMemoryByHash, hash);
+        if (!row)
+            return undefined;
+        const id = toSafeInteger(row.id, 'id');
+        const tags = loadTagsForMemoryIds([id]).get(id) ?? [];
+        return mapRowToMemory(row, tags);
+    });
 };
 export const deleteMemory = (hash) => {
     const result = executeRun(stmtDeleteMemoryByHash, hash);
     return { changes: toSafeInteger(result.changes, 'changes') };
 };
+const deleteMemoryForBatch = (hash) => {
+    try {
+        const result = deleteMemory(hash);
+        const deleted = result.changes > 0;
+        return deleted
+            ? { item: { hash, deleted: true }, succeeded: true }
+            : {
+                item: { hash, deleted: false, error: 'Memory not found' },
+                succeeded: false,
+            };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        return { item: { hash, deleted: false, error: message }, succeeded: false };
+    }
+};
 export const deleteMemories = (hashes) => {
     const results = [];
     let succeeded = 0;
     let failed = 0;
     return withImmediateTransaction(() => {
         for (const hash of hashes) {
-            try {
-                const result = deleteMemory(hash);
-                if (result.changes > 0) {
-                    results.push({ hash, deleted: true });
-                    succeeded++;
-                }
-                else {
-                    results.push({ hash, deleted: false, error: 'Memory not found' });
-                    failed++;
-                }
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : 'Unknown error';
-                results.push({ hash, deleted: false, error: message });
-                failed++;
-            }
+            const outcome = deleteMemoryForBatch(hash);
+            results.push(outcome.item);
+            succeeded += outcome.succeeded ? 1 : 0;
+            failed += outcome.succeeded ? 0 : 1;
         }
         return { results, succeeded, failed };
     });

package/dist/core/memory-write.js

@@ -89,31 +89,55 @@ const createMemoryInTransaction = (input) => {
     return { id, hash, isNew };
 };
 export const createMemories = (items) => {
+    return withImmediateTransaction(() => createMemoriesInTransaction(items));
+};
+const withSavepoint = (name, fn) => {
+    db.exec(`SAVEPOINT ${name}`);
+    try {
+        const result = fn();
+        db.exec(`RELEASE ${name}`);
+        return result;
+    }
+    catch (err) {
+        db.exec(`ROLLBACK TO ${name}`);
+        db.exec(`RELEASE ${name}`);
+        throw err;
+    }
+};
+const createMemoriesInTransaction = (items) => {
     const results = [];
     let succeeded = 0;
     let failed = 0;
-    return withImmediateTransaction(() => {
-        for (let i = 0; i < items.length; i++) {
-            const item = items[i];
-            if (!item)
-                continue;
-            db.exec('SAVEPOINT mem_item');
-            try {
-                const { hash, isNew } = createMemoryInTransaction(item);
-                results.push({ ok: true, index: i, hash, isNew });
-                succeeded++;
-                db.exec('RELEASE mem_item');
-            }
-            catch (err) {
-                db.exec('ROLLBACK TO mem_item');
-                db.exec('RELEASE mem_item');
-                const message = err instanceof Error ? err.message : 'Unknown error';
-                results.push({ ok: false, index: i, error: message });
-                failed++;
-            }
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (!item)
+            continue;
+        const result = processCreateMemoriesItem(i, item);
+        results.push(result);
+        if (result.ok) {
+            succeeded++;
         }
-        return { results, succeeded, failed };
-    });
+        else {
+            failed++;
+        }
+    }
+    return { results, succeeded, failed };
+};
+const processCreateMemoriesItem = (index, item) => {
+    const savepointName = `mem_item_${index}`;
+    try {
+        const created = withSavepoint(savepointName, () => createMemoryInTransaction(item));
+        return {
+            ok: true,
+            index,
+            hash: created.hash,
+            isNew: created.isNew,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error';
+        return { ok: false, index, error: message };
+    }
 };
 const stmtDeleteTagsForMemory = db.prepare('DELETE FROM tags WHERE memory_id = ?');
 const stmtUpdateContent = db.prepare('UPDATE memories SET content = ?, hash = ? WHERE id = ?');
@@ -121,6 +145,14 @@ const replaceTags = (memoryId, tags) => {
     executeRun(stmtDeleteTagsForMemory, memoryId);
     insertTags(memoryId, normalizeTags(tags, MAX_TAGS));
 };
+const assertNoDuplicateOnUpdate = (oldHash, newHash) => {
+    if (newHash === oldHash)
+        return;
+    const existingId = findMemoryIdByHash(newHash);
+    if (existingId !== undefined) {
+        throw new Error('Content already exists as another memory');
+    }
+};
 export const updateMemory = (hash, options) => {
     const memoryId = findMemoryIdByHash(hash);
     if (memoryId === undefined)
@@ -128,12 +160,7 @@ export const updateMemory = (hash, options) => {
     return withImmediateTransaction(() => {
         const newHash = buildHash(options.content);
         // Check if new content would create a duplicate
-        if (newHash !== hash) {
-            const existingId = findMemoryIdByHash(newHash);
-            if (existingId !== undefined) {
-                throw new Error('Content already exists as another memory');
-            }
-        }
+        assertNoDuplicateOnUpdate(hash, newHash);
         // Update content and hash
         executeRun(stmtUpdateContent, options.content, newHash, memoryId);
         // Update tags if provided, otherwise preserve existing tags

package/dist/core/relationships.js

@@ -1,4 +1,4 @@
-import { db, executeAll, executeGet, executeRun, toSafeInteger, withImmediateTransaction, } from './db.js';
+import { db, executeAll, executeGet, executeRun, mapRowToRelationship, toSafeInteger, withImmediateTransaction, } from './db.js';
 const stmtFindMemoryIdByHash = db.prepare('SELECT id FROM memories WHERE hash = ?');
 const findMemoryIdByHash = (hash) => {
     const row = executeGet(stmtFindMemoryIdByHash, hash);
@@ -13,18 +13,6 @@ const requireMemoryId = (hash) => {
     }
     return id;
 };
-const toString = (value, field) => {
-    if (typeof value === 'string')
-        return value;
-    throw new Error(`Invalid ${field}`);
-};
-const mapRowToRelationship = (row) => ({
-    id: toSafeInteger(row.id, 'id'),
-    from_hash: toString(row.from_hash, 'from_hash'),
-    to_hash: toString(row.to_hash, 'to_hash'),
-    relation_type: toString(row.relation_type, 'relation_type'),
-    created_at: toString(row.created_at, 'created_at'),
-});
 const stmtInsertRelationship = db.prepare(`
   INSERT OR IGNORE INTO relationships (from_memory_id, to_memory_id, relation_type)
   VALUES (?, ?, ?)
@@ -60,13 +48,14 @@ const buildGetRelationshipsQuery = (direction) => {
     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 = ?`;
+            return `${baseSelect} WHERE mf.hash = ?${orderBy}`;
         case 'incoming':
-            return `${baseSelect} WHERE mt.hash = ?`;
+            return `${baseSelect} WHERE mt.hash = ?${orderBy}`;
         case 'both':
-            return `${baseSelect} WHERE mf.hash = ? OR mt.hash = ?`;
+            return `${baseSelect} WHERE mf.hash = ? OR mt.hash = ?${orderBy}`;
     }
 };
 const stmtGetRelationships = {

package/dist/core/search.js

@@ -1,4 +1,4 @@
-import { db, executeAll, mapRowToSearchResult, prepareCached, toSafeInteger, } from './db.js';
+import { db, executeAll, loadTagsForMemoryIds, mapRowToRelationship, mapRowToSearchResult, prepareCached, toSafeInteger, } from './db.js';
 const MAX_QUERY_TOKENS = 50;
 const DEFAULT_LIMIT = 100;
 const RECENCY_DECAY_DAYS = 7;
@@ -65,25 +65,16 @@ 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 SEARCH_ERROR_MAP = [
-    {
-        matches: isSearchIndexMissing,
-        build: () => new Error('Search index unavailable. Ensure FTS5 is enabled and the index is ' +
-            'initialized.'),
-    },
-    {
-        matches: isSearchQueryInvalid,
-        build: (message) => new Error('Invalid search query syntax. Check for unbalanced quotes or special ' +
-            'characters. ' +
-            `Details: ${message}`),
-    },
-];
 const toSearchError = (err) => {
     const message = getErrorMessage(err);
-    for (const mapping of SEARCH_ERROR_MAP) {
-        if (mapping.matches(message)) {
-            return mapping.build(message);
-        }
+    if (isSearchIndexMissing(message)) {
+        return new Error('Search index unavailable. Ensure FTS5 is enabled and the index is ' +
+            'initialized.');
+    }
+    if (isSearchQueryInvalid(message)) {
+        return new Error('Invalid search query syntax. Check for unbalanced quotes or special ' +
+            'characters. ' +
+            `Details: ${message}`);
     }
     return undefined;
 };
@@ -93,13 +84,17 @@ const executeSearch = (sql, params) => {
         return executeAll(stmt, ...params);
     }
     catch (err) {
-        const mappedError = toSearchError(err);
-        if (mappedError) {
-            throw mappedError;
-        }
-        throw err;
+        throw toSearchError(err) ?? err;
     }
 };
+const mapRowsToSearchResultsWithTags = (rows) => {
+    const ids = rows.map((row) => toSafeInteger(row.id, 'id'));
+    const tagsById = loadTagsForMemoryIds(ids);
+    return rows.map((row) => {
+        const id = toSafeInteger(row.id, 'id');
+        return mapRowToSearchResult(row, tagsById.get(id) ?? []);
+    });
+};
 export const searchMemories = (input) => {
     const tokens = tokenizeQuery(input.query);
     if (tokens.length === 0) {
@@ -107,22 +102,10 @@ export const searchMemories = (input) => {
     }
     const { sql, params } = buildSearchQuery(tokens);
     const rows = executeSearch(sql, params);
-    return rows.map((row) => mapRowToSearchResult(row));
+    return mapRowsToSearchResultsWithTags(rows);
 };
 const MAX_RECALL_DEPTH = 3;
 const MAX_RECALL_MEMORIES = 50;
-const toString = (value, field) => {
-    if (typeof value === 'string')
-        return value;
-    throw new Error(`Invalid ${field}`);
-};
-const mapRowToRelationship = (row) => ({
-    id: toSafeInteger(row.id, 'id'),
-    from_hash: toString(row.from_hash, 'from_hash'),
-    to_hash: toString(row.to_hash, 'to_hash'),
-    relation_type: toString(row.relation_type, 'relation_type'),
-    created_at: toString(row.created_at, 'created_at'),
-});
 const buildRecallQuery = (seedCount, depth) => {
     const seedPlaceholders = Array.from({ length: seedCount }, () => '?').join(', ');
     const safeDepth = Math.min(Math.max(0, depth), MAX_RECALL_DEPTH);
@@ -166,30 +149,53 @@ const buildRelationshipsQuery = (memoryCount) => {
     JOIN memories mt ON r.to_memory_id = mt.id
     WHERE r.from_memory_id IN (${placeholders})
       AND r.to_memory_id IN (${placeholders})
+    ORDER BY r.relation_type, mf.hash, mt.hash, r.created_at, r.id
   `;
     return { sql };
 };
+const executeWithSql = (sql, params) => {
+    const stmt = db.prepare(sql);
+    return executeAll(stmt, ...params);
+};
+const executeRecall = (seedIds, depth) => {
+    const { sql } = buildRecallQuery(seedIds.length, depth);
+    return executeWithSql(sql, seedIds);
+};
+const loadRelationshipsForMemoryIds = (memoryIds) => {
+    const { sql } = buildRelationshipsQuery(memoryIds.length);
+    const rows = executeWithSql(sql, [...memoryIds, ...memoryIds]);
+    return rows.map(mapRowToRelationship);
+};
+const getRecallDepth = (depth) => depth ?? 1;
+const emptyRecallResult = (depth) => ({
+    memories: [],
+    relationships: [],
+    depth,
+});
+const recallAtDepthZero = (searchResults, depth) => {
+    if (depth !== 0)
+        return undefined;
+    return { memories: searchResults, relationships: [], depth };
+};
+const recallAtPositiveDepth = (searchResults, depth) => {
+    const seedIds = searchResults.map((m) => m.id);
+    const recallRows = executeRecall(seedIds, depth);
+    const memories = mapRowsToSearchResultsWithTags(recallRows);
+    if (memories.length === 0) {
+        return emptyRecallResult(depth);
+    }
+    const relationships = loadRelationshipsForMemoryIds(memories.map((m) => m.id));
+    return { memories, relationships, depth };
+};
 export const recallMemories = (input) => {
-    const depth = input.depth ?? 1;
     const searchResults = searchMemories({ query: input.query });
     if (searchResults.length === 0) {
-        return { memories: [], relationships: [], depth };
-    }
-    if (depth === 0) {
-        return { memories: searchResults, relationships: [], depth };
+        return emptyRecallResult(getRecallDepth(input.depth));
     }
-    const seedIds = searchResults.map((m) => m.id);
-    const { sql: recallSql } = buildRecallQuery(seedIds.length, depth);
-    const recallStmt = db.prepare(recallSql);
-    const recallRows = executeAll(recallStmt, ...seedIds);
-    const memories = recallRows.map(mapRowToSearchResult);
-    const allMemoryIds = memories.map((m) => m.id);
-    if (allMemoryIds.length === 0) {
-        return { memories: [], relationships: [], depth };
+    const depth = getRecallDepth(input.depth);
+    const depthZeroResult = recallAtDepthZero(searchResults, depth);
+    if (depthZeroResult) {
+        return depthZeroResult;
     }
-    const { sql: relSql } = buildRelationshipsQuery(allMemoryIds.length);
-    const relStmt = db.prepare(relSql);
-    const relRows = executeAll(relStmt, ...allMemoryIds, ...allMemoryIds);
-    const relationships = relRows.map(mapRowToRelationship);
-    return { memories, relationships, depth };
+    return recallAtPositiveDepth(searchResults, depth);
 };

package/dist/index.js

@@ -19,22 +19,38 @@ const readPackageVersion = async () => {
     const version = Reflect.get(parsed, 'version');
     return typeof version === 'string' ? version : undefined;
 };
-const readServerInstructions = async () => {
+const toNonEmptyTrimmedOrUndefined = (text) => {
+    const trimmed = text.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+};
+const readTextFileOrUndefined = async (url) => {
     try {
-        const text = await readFile(new URL('./instructions.md', import.meta.url), {
+        return await readFile(url, {
             encoding: 'utf-8',
             signal: AbortSignal.timeout(5000),
         });
-        const trimmed = text.trim();
-        return trimmed.length > 0 ? trimmed : undefined;
     }
     catch {
         return undefined;
     }
 };
-const packageVersion = await readPackageVersion();
-const serverInstructions = (await readServerInstructions()) ??
-    'A Memory MCP Server for AI Assistants using node:sqlite';
+const readServerInstructions = async () => {
+    const text = await readTextFileOrUndefined(new URL('./instructions.md', import.meta.url));
+    if (!text)
+        return undefined;
+    return toNonEmptyTrimmedOrUndefined(text);
+};
+const loadServerMetadata = async () => {
+    const [packageVersion, instructions] = await Promise.all([
+        readPackageVersion(),
+        readServerInstructions(),
+    ]);
+    return {
+        packageVersion,
+        instructions: instructions ?? 'A Memory MCP Server for AI Assistants using node:sqlite',
+    };
+};
+const { packageVersion, instructions: serverInstructions } = await loadServerMetadata();
 const server = new McpServer({ name: 'memdb', version: packageVersion ?? '0.0.0' }, {
     instructions: serverInstructions,
     capabilities: { tools: {} },
@@ -42,7 +58,7 @@ const server = new McpServer({ name: 'memdb', version: packageVersion ?? '0.0.0'
 const patchToolErrorResults = (target) => {
     const targetUnknown = target;
     const existing = Reflect.get(targetUnknown, 'createToolError');
-    if (existing !== undefined && typeof existing !== 'function')
+    if (typeof existing !== 'function')
         return;
     const createToolError = (message) => {
         const structured = {
@@ -62,34 +78,57 @@ registerAllTools(server);
 let transport;
 let shuttingDown = false;
 const SHUTDOWN_TIMEOUT = 5000;
-async function shutdown(signal) {
-    if (shuttingDown)
-        return;
-    shuttingDown = true;
-    logger.info(`Received ${signal}, shutting down gracefully...`);
-    const forceExitTimer = setTimeout(() => {
+const createShutdownTimer = () => {
+    return setTimeout(() => {
         logger.warn('Shutdown timeout exceeded, forcing exit');
         process.exit(1);
     }, SHUTDOWN_TIMEOUT);
-    try {
-        closeDb();
-        await transport?.close();
-        clearTimeout(forceExitTimer);
-        process.exit(0);
-    }
-    catch (err) {
-        logger.error('Error during shutdown:', err);
-        clearTimeout(forceExitTimer);
-        process.exit(1);
+};
+const closeServerResources = async () => {
+    closeDb();
+    await transport?.close();
+};
+const clearTimerAndExit = (timer, code) => {
+    clearTimeout(timer);
+    process.exit(code);
+};
+const exitWithShutdownTimer = (timer, code, error) => {
+    if (error !== undefined) {
+        logger.error('Error during shutdown:', error);
     }
+    clearTimerAndExit(timer, code);
+};
+const beginShutdown = (signal) => {
+    logger.info(`Received ${signal}, shutting down gracefully...`);
+    const forceExitTimer = createShutdownTimer();
+    void closeServerResources()
+        .then(() => {
+        exitWithShutdownTimer(forceExitTimer, 0);
+    })
+        .catch((err) => {
+        exitWithShutdownTimer(forceExitTimer, 1, err);
+    });
+};
+function shutdown(signal) {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    beginShutdown(signal);
 }
+const createTransport = () => {
+    const stdioTransport = new BatchRejectingStdioServerTransport();
+    const supportedProtocolVersions = SUPPORTED_PROTOCOL_VERSIONS.filter((version) => version !== '2025-03-26');
+    return new ProtocolVersionGuardTransport(stdioTransport, supportedProtocolVersions);
+};
+const connectServer = async (transportToUse) => {
+    transport = transportToUse;
+    await server.connect(transportToUse);
+    logger.info('Memory MCP Server running on stdio');
+};
 const main = async () => {
     try {
-        const stdioTransport = new BatchRejectingStdioServerTransport();
-        const guardedTransport = new ProtocolVersionGuardTransport(stdioTransport, SUPPORTED_PROTOCOL_VERSIONS);
-        transport = guardedTransport;
-        await server.connect(guardedTransport);
-        logger.info('Memory MCP Server running on stdio');
+        const guardedTransport = createTransport();
+        await connectServer(guardedTransport);
     }
     catch (error) {
         logger.error('Failed to start server', error);
@@ -99,7 +138,9 @@ const main = async () => {
 const registerSignalHandlers = () => {
     const signals = ['SIGTERM', 'SIGINT', 'SIGBREAK'];
     for (const signal of signals) {
-        process.on(signal, () => void shutdown(signal));
+        process.on(signal, () => {
+            shutdown(signal);
+        });
     }
 };
 const registerProcessHandlers = () => {

package/dist/instructions.md

@@ -24,6 +24,7 @@ Use this server to store and retrieve persistent memories (facts, decisions, les
   - `tags` (1–100 items, no whitespace, `kebab-case`)
   - `importance` (0–10, 10=critical)
   - `memory_type` (`general`, `fact`, `plan`, `decision`, `reflection`, `lesson`, `error`, `gradient`)
+  - `accessed_at` is updated when you call `get_memory`
 - **Relationship:** Directed edge (`from_hash` → `to_hash`) with a typed label (`relation_type`).
 
 ## Workflows
@@ -71,6 +72,7 @@ Full-text + tag search.
 - **Use when:** Discovering what exists; start here before mutating.
 - **Args:** `query` (1–1,000 chars).
 - **Returns:** Array of `Memory` + `relevance`, up to 100 results.
+- **Returns:** Array of `Memory` + `relevance`, up to 100 results (includes `tags`).
 - **Notes:** Content matches rank higher than tag matches.
 
 ### get_memory
@@ -79,7 +81,8 @@ Fetch a single memory by hash.
 
 - **Use when:** You need verbatim content after search identified a hash.
 - **Args:** `hash` (32 hex chars).
-- **Returns:** `Memory` object.
+- **Returns:** `Memory` object (includes `tags`).
+- **Notes:** Updates `accessed_at` on read.
 
 ### update_memory
 
@@ -136,7 +139,7 @@ Search + traverse relationships to return a connected cluster.
 
 - **Use when:** You need broader context beyond keyword matches.
 - **Args:** `query`, `depth` (opt, 0–3; default 1).
-- **Returns:** `{ memories, relationships, depth }`.
+- **Returns:** `{ memories, relationships, depth }` where `memories` include `tags`.
 
 ### memory_stats
 

package/dist/protocol-version-guard.d.ts

@@ -14,4 +14,7 @@ export declare class ProtocolVersionGuardTransport implements Transport {
     send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
     close(): Promise<void>;
     private handleMessage;
+    private handleInitialize;
+    private handleInitializedNotification;
+    private handleBeforeReady;
 }

package/dist/protocol-version-guard.js

@@ -82,35 +82,46 @@ export class ProtocolVersionGuardTransport {
         }
         const initializeInfo = getInitializeInfo(message);
         if (initializeInfo) {
-            if (this.sawInitialize) {
-                void this.inner.send(createLifecycleError(initializeInfo.id, 'Invalid request: initialize already received'), { relatedRequestId: initializeInfo.id });
-                return;
-            }
-            if (!this.supportedVersions.includes(initializeInfo.protocolVersion)) {
-                void this.inner.send(createUnsupportedVersionError(initializeInfo.id, initializeInfo.protocolVersion, this.supportedVersions), { relatedRequestId: initializeInfo.id });
-                return;
-            }
-            this.sawInitialize = true;
-            this.onmessage(message, extra);
+            this.handleInitialize(message, initializeInfo, extra);
             return;
         }
         if (isInitializedNotification(message)) {
-            if (this.sawInitialize && !this.ready) {
-                this.ready = true;
-                this.onmessage(message, extra);
-            }
+            this.handleInitializedNotification(message, extra);
             return;
         }
         if (!this.sawInitialize || !this.ready) {
-            if (isJSONRPCRequest(message)) {
-                void this.inner.send(createLifecycleError(message.id, 'Invalid request: initialize must be sent before other requests'), { relatedRequestId: message.id });
-            }
-            else if (isJSONRPCResultResponse(message) ||
-                isJSONRPCErrorResponse(message)) {
-                this.onmessage(message, extra);
-            }
+            this.handleBeforeReady(message, extra);
+            return;
+        }
+        this.onmessage(message, extra);
+    }
+    handleInitialize(message, initializeInfo, extra) {
+        if (this.sawInitialize) {
+            void this.inner.send(createLifecycleError(initializeInfo.id, 'Invalid request: initialize already received'), { relatedRequestId: initializeInfo.id });
+            return;
+        }
+        if (!this.supportedVersions.includes(initializeInfo.protocolVersion)) {
+            void this.inner.send(createUnsupportedVersionError(initializeInfo.id, initializeInfo.protocolVersion, this.supportedVersions), { relatedRequestId: initializeInfo.id });
             return;
         }
+        this.sawInitialize = true;
+        this.onmessage(message, extra);
+    }
+    handleInitializedNotification(message, extra) {
+        if (!this.sawInitialize)
+            return;
+        if (this.ready)
+            return;
+        this.ready = true;
         this.onmessage(message, extra);
     }
+    handleBeforeReady(message, extra) {
+        if (isJSONRPCRequest(message)) {
+            void this.inner.send(createLifecycleError(message.id, 'Invalid request: initialize must be sent before other requests'), { relatedRequestId: message.id });
+            return;
+        }
+        if (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) {
+            this.onmessage(message, extra);
+        }
+    }
 }

package/dist/stdio-transport.d.ts

@@ -25,5 +25,8 @@ export declare class BatchRejectingStdioServerTransport implements Transport {
     private handleBatch;
     private handleNonBatch;
     private handleLine;
+    private handleLineSafely;
+    private drainReadBuffer;
+    private handleReadBufferError;
     private processReadBuffer;
 }

package/dist/stdio-transport.js

@@ -47,21 +47,32 @@ class LineBuffer {
     }
     buildLineBuffer(chunkIndex, newlineIndex, lineLength) {
         const lineBuffer = Buffer.allocUnsafe(lineLength);
+        const writeOffset = this.copyChunksBeforeIndex(lineBuffer, chunkIndex);
+        this.copyChunkPrefix(lineBuffer, chunkIndex, newlineIndex, writeOffset);
+        return lineBuffer;
+    }
+    copyChunksBeforeIndex(target, chunkIndex) {
         let writeOffset = 0;
         for (let i = 0; i < chunkIndex; i++) {
             const part = this.chunks[i];
             if (!part)
                 continue;
-            part.copy(lineBuffer, writeOffset);
+            part.copy(target, writeOffset);
             writeOffset += part.length;
         }
+        return writeOffset;
+    }
+    copyChunkPrefix(target, chunkIndex, newlineIndex, writeOffset) {
         const chunk = this.chunks[chunkIndex];
-        if (chunk && newlineIndex > 0) {
-            chunk.copy(lineBuffer, writeOffset, 0, newlineIndex);
-        }
-        return lineBuffer;
+        if (!chunk || newlineIndex <= 0)
+            return;
+        chunk.copy(target, writeOffset, 0, newlineIndex);
     }
     consumeLine(chunkIndex, newlineIndex, lineLength) {
+        this.chunks = this.buildRemainingChunks(chunkIndex, newlineIndex);
+        this.totalLength -= lineLength + 1;
+    }
+    buildRemainingChunks(chunkIndex, newlineIndex) {
         const remaining = [];
         const chunk = this.chunks[chunkIndex];
         if (chunk) {
@@ -75,8 +86,7 @@ class LineBuffer {
                 continue;
             remaining.push(tail);
         }
-        this.chunks = remaining;
-        this.totalLength -= lineLength + 1;
+        return remaining;
     }
     clear() {
         this.chunks = [];
@@ -95,24 +105,17 @@ const getRequestIdResult = (value) => {
     }
     return { ok: false, reason: 'invalid-type' };
 };
-const invalidRequestError = (id) => id === undefined
-    ? {
-        jsonrpc: '2.0',
-        error: {
-            code: -32600,
-            message: 'Invalid request',
-        },
-    }
-    : {
-        jsonrpc: '2.0',
-        id,
-        error: {
-            code: -32600,
-            message: 'Invalid request',
-        },
-    };
+const invalidRequestError = (id) => ({
+    jsonrpc: '2.0',
+    id,
+    error: {
+        code: -32600,
+        message: 'Invalid request',
+    },
+});
 const parseError = () => ({
     jsonrpc: '2.0',
+    id: null,
     error: {
         code: -32700,
         message: 'Parse error',
@@ -183,7 +186,7 @@ export class BatchRejectingStdioServerTransport {
         void this.send(invalidRequestError(id));
     }
     sendInvalidRequestUnknownId() {
-        void this.send(invalidRequestError());
+        void this.send(invalidRequestError(null));
     }
     sendParseError() {
         void this.send(parseError());
@@ -231,20 +234,29 @@ export class BatchRejectingStdioServerTransport {
         }
         this.onmessage(parsed.data);
     }
+    handleLineSafely(line) {
+        try {
+            this.handleLine(line);
+        }
+        catch (error) {
+            this.onerror(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    drainReadBuffer() {
+        for (let line = this.readBuffer.readLine(); line !== null; line = this.readBuffer.readLine()) {
+            this.handleLineSafely(line);
+        }
+    }
+    handleReadBufferError() {
+        this.readBuffer.clear();
+        this.sendParseError();
+    }
     processReadBuffer() {
         try {
-            for (let line = this.readBuffer.readLine(); line !== null; line = this.readBuffer.readLine()) {
-                try {
-                    this.handleLine(line);
-                }
-                catch (error) {
-                    this.onerror(error instanceof Error ? error : new Error(String(error)));
-                }
-            }
+            this.drainReadBuffer();
         }
         catch {
-            this.readBuffer.clear();
-            this.sendParseError();
+            this.handleReadBufferError();
         }
     }
 }

package/dist/tools.js

@@ -17,10 +17,11 @@ const defaultDeps = {
     deleteRelationship,
     recallMemories,
 };
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
 const getErrorMessage = (error) => {
     if (error instanceof Error)
         return error.message;
-    if (typeof error === 'string' && error.length > 0)
+    if (isNonEmptyString(error))
         return error;
     return 'Unknown error';
 };
@@ -43,132 +44,142 @@ const ok = (result) => {
         structuredContent: structured,
     };
 };
+const runHandlerSafely = async (code, handler, params) => {
+    try {
+        return await handler(params);
+    }
+    catch (err) {
+        return createErrorResponse(code, getErrorMessage(err));
+    }
+};
 const wrapHandler = (code, handler) => {
-    return async (params) => {
-        try {
-            return await handler(params);
-        }
-        catch (err) {
-            return createErrorResponse(code, getErrorMessage(err));
-        }
-    };
+    return async (params) => runHandlerSafely(code, handler, params);
 };
 const normalizeHash = (hash) => hash.toLowerCase();
-const buildCoreTools = (deps) => [
-    {
-        name: 'store_memory',
-        options: {
-            title: 'Store Memory',
-            description: 'Store a new memory with tags',
-            inputSchema: StoreMemoryInputSchema,
-            outputSchema: DefaultOutputSchema,
-            annotations: { idempotentHint: true },
-        },
-        handler: wrapHandler('E_STORE_MEMORY', async (params) => {
-            const input = StoreMemoryInputSchema.parse(params);
-            const result = await deps.createMemory({
-                content: input.content,
-                tags: input.tags,
-                ...(input.importance !== undefined && { importance: input.importance }),
-                ...(input.memory_type !== undefined && {
-                    memory_type: input.memory_type,
-                }),
-            });
-            return ok(result);
-        }),
+const toCreateMemoryInput = (input) => ({
+    content: input.content,
+    tags: input.tags,
+    ...(input.importance === undefined ? {} : { importance: input.importance }),
+    ...(input.memory_type === undefined
+        ? {}
+        : { memory_type: input.memory_type }),
+});
+const buildStoreMemoryTool = (deps) => ({
+    name: 'store_memory',
+    options: {
+        title: 'Store Memory',
+        description: 'Store a new memory with tags',
+        inputSchema: StoreMemoryInputSchema,
+        outputSchema: DefaultOutputSchema,
+        annotations: { idempotentHint: true },
     },
-    {
-        name: 'store_memories',
-        options: {
-            title: 'Store Multiple Memories',
-            description: 'Store multiple memories in a single batch operation. Returns per-item results with partial success support.',
-            inputSchema: StoreMemoriesInputSchema,
-            outputSchema: DefaultOutputSchema,
-            annotations: { idempotentHint: true },
-        },
-        handler: wrapHandler('E_STORE_MEMORIES', async (params) => {
-            const input = StoreMemoriesInputSchema.parse(params);
-            const items = input.items.map((item) => ({
-                content: item.content,
-                tags: item.tags,
-                ...(item.importance !== undefined && { importance: item.importance }),
-                ...(item.memory_type !== undefined && {
-                    memory_type: item.memory_type,
-                }),
-            }));
-            const result = await deps.createMemories(items);
-            return ok(result);
-        }),
+    handler: wrapHandler('E_STORE_MEMORY', async (params) => {
+        const input = StoreMemoryInputSchema.parse(params);
+        const result = await deps.createMemory(toCreateMemoryInput({
+            content: input.content,
+            tags: input.tags,
+            importance: input.importance,
+            memory_type: input.memory_type,
+        }));
+        return ok(result);
+    }),
+});
+const buildStoreMemoriesTool = (deps) => ({
+    name: 'store_memories',
+    options: {
+        title: 'Store Multiple Memories',
+        description: 'Store multiple memories in a single batch operation. Returns per-item results with partial success support.',
+        inputSchema: StoreMemoriesInputSchema,
+        outputSchema: DefaultOutputSchema,
+        annotations: { idempotentHint: true },
     },
-    {
-        name: 'get_memory',
-        options: {
-            title: 'Get Memory',
-            description: 'Retrieve memory by hash',
-            inputSchema: GetMemoryInputSchema,
-            outputSchema: DefaultOutputSchema,
-            annotations: { readOnlyHint: true },
-        },
-        handler: wrapHandler('E_GET_MEMORY', async (params) => {
-            const input = GetMemoryInputSchema.parse(params);
-            const result = await deps.getMemory(normalizeHash(input.hash));
-            if (!result) {
-                return createErrorResponse('E_NOT_FOUND', 'Memory not found');
-            }
-            return ok(result);
-        }),
+    handler: wrapHandler('E_STORE_MEMORIES', async (params) => {
+        const input = StoreMemoriesInputSchema.parse(params);
+        const items = input.items.map((item) => toCreateMemoryInput({
+            content: item.content,
+            tags: item.tags,
+            importance: item.importance,
+            memory_type: item.memory_type,
+        }));
+        const result = await deps.createMemories(items);
+        return ok(result);
+    }),
+});
+const buildGetMemoryTool = (deps) => ({
+    name: 'get_memory',
+    options: {
+        title: 'Get Memory',
+        description: 'Retrieve memory by hash',
+        inputSchema: GetMemoryInputSchema,
+        outputSchema: DefaultOutputSchema,
     },
-    {
-        name: 'delete_memory',
-        options: {
-            title: 'Delete Memory',
-            description: 'Delete by hash',
-            inputSchema: DeleteMemoryInputSchema,
-            outputSchema: DefaultOutputSchema,
-            annotations: { destructiveHint: true },
-        },
-        handler: wrapHandler('E_DELETE_MEMORY', async (params) => {
-            const input = DeleteMemoryInputSchema.parse(params);
-            const result = await deps.deleteMemory(normalizeHash(input.hash));
-            if (result.changes === 0) {
-                return createErrorResponse('E_NOT_FOUND', 'Memory not found');
-            }
-            return ok({ deleted: true });
-        }),
+    handler: wrapHandler('E_GET_MEMORY', async (params) => {
+        const input = GetMemoryInputSchema.parse(params);
+        const result = await deps.getMemory(normalizeHash(input.hash));
+        if (!result) {
+            return createErrorResponse('E_NOT_FOUND', 'Memory not found');
+        }
+        return ok(result);
+    }),
+});
+const buildDeleteMemoryTool = (deps) => ({
+    name: 'delete_memory',
+    options: {
+        title: 'Delete Memory',
+        description: 'Delete by hash',
+        inputSchema: DeleteMemoryInputSchema,
+        outputSchema: DefaultOutputSchema,
+        annotations: { destructiveHint: true },
     },
-    {
-        name: 'delete_memories',
-        options: {
-            title: 'Delete Multiple Memories',
-            description: 'Delete multiple memories by hash in a single batch operation. Returns per-item results with partial success support.',
-            inputSchema: DeleteMemoriesInputSchema,
-            outputSchema: DefaultOutputSchema,
-            annotations: { destructiveHint: true },
-        },
-        handler: wrapHandler('E_DELETE_MEMORIES', async (params) => {
-            const input = DeleteMemoriesInputSchema.parse(params);
-            const result = await deps.deleteMemories(input.hashes.map(normalizeHash));
-            return ok(result);
-        }),
+    handler: wrapHandler('E_DELETE_MEMORY', async (params) => {
+        const input = DeleteMemoryInputSchema.parse(params);
+        const result = await deps.deleteMemory(normalizeHash(input.hash));
+        if (result.changes === 0) {
+            return createErrorResponse('E_NOT_FOUND', 'Memory not found');
+        }
+        return ok({ deleted: true });
+    }),
+});
+const buildDeleteMemoriesTool = (deps) => ({
+    name: 'delete_memories',
+    options: {
+        title: 'Delete Multiple Memories',
+        description: 'Delete multiple memories by hash in a single batch operation. Returns per-item results with partial success support.',
+        inputSchema: DeleteMemoriesInputSchema,
+        outputSchema: DefaultOutputSchema,
+        annotations: { destructiveHint: true },
     },
-    {
-        name: 'update_memory',
-        options: {
-            title: 'Update Memory',
-            description: 'Update memory content. Returns new hash since content change affects the hash.',
-            inputSchema: UpdateMemoryInputSchema,
-            outputSchema: DefaultOutputSchema,
-            annotations: { idempotentHint: true },
-        },
-        handler: wrapHandler('E_UPDATE_MEMORY', async (params) => {
-            const input = UpdateMemoryInputSchema.parse(params);
-            const result = await deps.updateMemory(normalizeHash(input.hash), {
-                content: input.content,
-                tags: input.tags,
-            });
-            return ok(result);
-        }),
+    handler: wrapHandler('E_DELETE_MEMORIES', async (params) => {
+        const input = DeleteMemoriesInputSchema.parse(params);
+        const result = await deps.deleteMemories(input.hashes.map(normalizeHash));
+        return ok(result);
+    }),
+});
+const buildUpdateMemoryTool = (deps) => ({
+    name: 'update_memory',
+    options: {
+        title: 'Update Memory',
+        description: 'Update memory content. Returns new hash since content change affects the hash.',
+        inputSchema: UpdateMemoryInputSchema,
+        outputSchema: DefaultOutputSchema,
+        annotations: { idempotentHint: true },
     },
+    handler: wrapHandler('E_UPDATE_MEMORY', async (params) => {
+        const input = UpdateMemoryInputSchema.parse(params);
+        const result = await deps.updateMemory(normalizeHash(input.hash), {
+            content: input.content,
+            tags: input.tags,
+        });
+        return ok(result);
+    }),
+});
+const buildCoreTools = (deps) => [
+    buildStoreMemoryTool(deps),
+    buildStoreMemoriesTool(deps),
+    buildGetMemoryTool(deps),
+    buildDeleteMemoryTool(deps),
+    buildDeleteMemoriesTool(deps),
+    buildUpdateMemoryTool(deps),
 ];
 const buildSearchTools = (deps) => [
     {

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export interface Memory {
     readonly id: number;
     readonly content: string;
     readonly summary: string | undefined;
+    readonly tags: string[];
     readonly importance: number;
     readonly memory_type: MemoryType;
     readonly created_at: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/memdb",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "mcpName": "io.github.j0hanz/memdb",
   "description": "A SQLite-backed MCP memory server with local workspace storage.",
   "type": "module",