@j0hanz/memdb 1.2.4 → 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);
 };