@levalicious/server-memory 0.0.10 → 0.0.12

package/README.md

@@ -108,11 +108,12 @@ Example:
 
 - **search_nodes**
   - Search for nodes using a regex pattern
-  - Input: `query` (string), `entityCursor` (number, optional), `relationCursor` (number, optional)
-  - Searches across:
-    - Entity names
-    - Entity types
-    - Observation content
+  - Input: 
+    - `query` (string): Regex pattern to search
+    - `sortBy` (string, optional): Sort field ("mtime", "obsMtime", or "name")
+    - `sortDir` (string, optional): Sort direction ("asc" or "desc")
+    - `entityCursor` (number, optional), `relationCursor` (number, optional)
+  - Searches across entity names, types, and observation content
   - Returns matching entities and their relations (paginated)
 
 - **open_nodes_filtered**
@@ -132,9 +133,15 @@ Example:
   - Silently skips non-existent nodes (paginated)
 
 - **get_neighbors**
-  - Get neighboring entities connected to a specific entity within a given depth
-  - Input: `entityName` (string), `depth` (number, default: 0), `withEntities` (boolean, default: false), `entityCursor` (number, optional), `relationCursor` (number, optional)
-  - Returns relations (and optionally entities) connected within specified depth (paginated)
+  - Get names of neighboring entities connected to a specific entity within a given depth
+  - Input: 
+    - `entityName` (string): The entity to find neighbors for
+    - `depth` (number, default: 1): Maximum traversal depth
+    - `sortBy` (string, optional): Sort field ("mtime", "obsMtime", or "name")
+    - `sortDir` (string, optional): Sort direction ("asc" or "desc")
+    - `cursor` (number, optional): Pagination cursor
+  - Returns neighbor names with timestamps (paginated)
+  - Use `open_nodes` to get full entity data for neighbors
 
 - **find_path**
   - Find a path between two entities in the knowledge graph
@@ -143,7 +150,11 @@ Example:
 
 - **get_entities_by_type**
   - Get all entities of a specific type
-  - Input: `entityType` (string), `cursor` (number, optional)
+  - Input: 
+    - `entityType` (string): Type to filter by
+    - `sortBy` (string, optional): Sort field ("mtime", "obsMtime", or "name")
+    - `sortDir` (string, optional): Sort direction ("asc" or "desc")
+    - `cursor` (number, optional)
   - Returns all entities matching the specified type (paginated)
 
 - **get_entity_types**
@@ -163,8 +174,11 @@ Example:
 
 - **get_orphaned_entities**
   - Get entities that have no relations (orphaned entities)
-  - Input: `strict` (boolean, default: false), `cursor` (number, optional)
-  - In strict mode, returns entities not connected to 'Self' entity (directly or indirectly)
+  - Input: 
+    - `strict` (boolean, default: false): If true, returns entities not connected to 'Self' entity
+    - `sortBy` (string, optional): Sort field ("mtime", "obsMtime", or "name")
+    - `sortDir` (string, optional): Sort direction ("asc" or "desc")
+    - `cursor` (number, optional)
   - Returns entities with no connections (paginated)
 
 - **validate_graph**
@@ -172,22 +186,22 @@ Example:
   - No input required
   - Returns missing entities referenced in relations and observation limit violations
 
-- **evaluate_bcl**
-  - Evaluate a Binary Combinatory Logic (BCL) program
-  - Input: `program` (string), `maxSteps` (number, default: 1000000)
-  - BCL syntax: T:=00|01|1TT where 00=K, 01=S, 1=application
-  - Returns evaluation result with halt status
-
-- **add_bcl_term**
-  - Add a BCL term to the constructor, maintaining valid syntax
-  - Input: `term` (string)
-  - Valid values: '1' or 'App' (application), '00' or 'K' (K combinator), '01' or 'S' (S combinator)
-  - Returns completion status
-
-- **clear_bcl_term**
-  - Clear the current BCL term being constructed and reset the constructor state
-  - No input required
-  - Resets BCL constructor
+- **decode_timestamp**
+  - Decode a millisecond timestamp to human-readable UTC format
+  - Input:
+    - `timestamp` (number, optional): Millisecond timestamp to decode. If omitted, returns current time
+    - `relative` (boolean, optional): If true, include relative time (e.g., "3 days ago")
+  - Returns timestamp, ISO 8601 string, formatted UTC string, and optional relative time
+  - Useful for interpreting `mtime`/`obsMtime` values from entities
+
+- **random_walk**
+  - Perform a random walk from a starting entity, following random relations
+  - Input:
+    - `start` (string): Name of the entity to start the walk from
+    - `depth` (number, default: 3): Number of hops to take
+    - `seed` (string, optional): Seed for reproducible walks
+  - Returns the terminal entity name and the path taken
+  - Useful for serendipitous exploration of the knowledge graph
 
 - **sequentialthinking**
   - Record a thought in the knowledge graph

package/dist/index.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
+// Workaround: Node 24 segfaults on exit when any N-API addon is loaded,
+// even a bare no-op module. This is a confirmed Node bug, not ours.
+// Force a clean exit to avoid the cosmetic segfault.
+// process.on('exit', () => { process._exit(0); });
 const server = createServer();
 const transport = new StdioServerTransport();
 server.connect(transport).catch((error) => {

package/dist/scripts/migrate-jsonl.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * migrate-jsonl.ts — Convert a JSONL knowledge graph to binary (GraphFile + StringTable).
+ *
+ * Usage:
+ *   npx tsx scripts/migrate-jsonl.ts [path/to/memory.json]
+ *
+ * If no path given, defaults to ~/.local/share/memory/vscode.json
+ *
+ * Creates:
+ *   <base>.graph   — binary graph store
+ *   <base>.strings — binary string table
+ *
+ * The original .json file is NOT modified or deleted.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { StringTable } from '../src/stringtable.js';
+import { GraphFile, DIR_FORWARD, DIR_BACKWARD } from '../src/graphfile.js';
+async function migrate(jsonlPath) {
+    const dir = path.dirname(jsonlPath);
+    const base = path.basename(jsonlPath, path.extname(jsonlPath));
+    const graphPath = path.join(dir, `${base}.graph`);
+    const strPath = path.join(dir, `${base}.strings`);
+    // Safety: don't clobber existing binary files
+    if (fs.existsSync(graphPath) || fs.existsSync(strPath)) {
+        console.error(`ERROR: Binary files already exist:\n  ${graphPath}\n  ${strPath}`);
+        console.error('Delete them first if you want to re-migrate.');
+        process.exit(1);
+    }
+    console.log(`Source: ${jsonlPath}`);
+    console.log(`Target: ${graphPath}`);
+    console.log(`        ${strPath}`);
+    console.log();
+    // --- Pass 1: Parse JSONL, collect entities and relations ---
+    const entities = [];
+    const relations = [];
+    let lineNum = 0;
+    let parseErrors = 0;
+    const fileStream = fs.createReadStream(jsonlPath, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+    for await (const line of rl) {
+        lineNum++;
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const obj = JSON.parse(trimmed);
+            if (obj.type === 'entity') {
+                entities.push(obj);
+            }
+            else if (obj.type === 'relation') {
+                relations.push(obj);
+            }
+        }
+        catch (e) {
+            parseErrors++;
+            if (parseErrors <= 5) {
+                console.warn(`  WARN: parse error on line ${lineNum}: ${e.message}`);
+            }
+        }
+    }
+    console.log(`Parsed: ${entities.length} entities, ${relations.length} relations`);
+    if (parseErrors > 0) {
+        console.warn(`  (${parseErrors} lines had parse errors — skipped)`);
+    }
+    // --- Pass 2: Build binary store ---
+    // Start with a generous initial size to reduce remaps.
+    // Rough estimate: 64B per entity + ~200B string overhead per entity + 24B per adj entry
+    const estimatedSize = Math.max(65536, entities.length * 300 + relations.length * 100);
+    const st = new StringTable(strPath, estimatedSize);
+    const gf = new GraphFile(graphPath, st, estimatedSize);
+    // Create all entities first, build name→offset map
+    const nameToOffset = new Map();
+    let created = 0;
+    let skippedDuplicates = 0;
+    for (const e of entities) {
+        if (nameToOffset.has(e.name)) {
+            skippedDuplicates++;
+            continue;
+        }
+        const mtime = BigInt(e.mtime ?? 0);
+        const obsMtime = BigInt(e.obsMtime ?? 0);
+        const rec = gf.createEntity(e.name, e.entityType, mtime, obsMtime);
+        // Add observations (max 2)
+        const obs = e.observations.slice(0, 2);
+        for (const o of obs) {
+            // Truncate to 140 chars if needed
+            const truncated = o.length > 140 ? o.substring(0, 140) : o;
+            gf.addObservation(rec.offset, truncated, obsMtime);
+        }
+        // Fix timestamps (addObservation clobbers mtime)
+        if (obs.length > 0) {
+            const updated = gf.readEntity(rec.offset);
+            updated.mtime = mtime;
+            updated.obsMtime = obsMtime;
+            gf.updateEntity(updated);
+        }
+        nameToOffset.set(e.name, rec.offset);
+        created++;
+        if (created % 1000 === 0) {
+            process.stdout.write(`  Entities: ${created}/${entities.length}\r`);
+        }
+    }
+    console.log(`  Entities: ${created} created, ${skippedDuplicates} duplicates skipped`);
+    // Create all relations
+    let relCreated = 0;
+    let relSkipped = 0;
+    for (const r of relations) {
+        const fromOffset = nameToOffset.get(r.from);
+        const toOffset = nameToOffset.get(r.to);
+        if (fromOffset === undefined || toOffset === undefined) {
+            relSkipped++;
+            continue;
+        }
+        const mtime = BigInt(r.mtime ?? 0);
+        const relTypeId = Number(st.intern(r.relationType));
+        // Forward edge on 'from'
+        const forwardEntry = {
+            targetOffset: toOffset,
+            direction: DIR_FORWARD,
+            relTypeId,
+            mtime,
+        };
+        gf.addEdge(fromOffset, forwardEntry);
+        // Backward edge on 'to' (intern again to bump refcount)
+        const relTypeId2 = Number(st.intern(r.relationType));
+        const backwardEntry = {
+            targetOffset: fromOffset,
+            direction: DIR_BACKWARD,
+            relTypeId: relTypeId2,
+            mtime,
+        };
+        gf.addEdge(toOffset, backwardEntry);
+        relCreated++;
+        if (relCreated % 1000 === 0) {
+            process.stdout.write(`  Relations: ${relCreated}/${relations.length}\r`);
+        }
+    }
+    console.log(`  Relations: ${relCreated} created, ${relSkipped} skipped (missing endpoints)`);
+    // Sync and close
+    gf.sync();
+    st.sync();
+    // Report sizes
+    const graphSize = fs.statSync(graphPath).size;
+    const strSize = fs.statSync(strPath).size;
+    const jsonlSize = fs.statSync(jsonlPath).size;
+    console.log();
+    console.log(`File sizes:`);
+    console.log(`  JSONL:   ${(jsonlSize / 1024 / 1024).toFixed(2)} MB`);
+    console.log(`  Graph:   ${(graphSize / 1024 / 1024).toFixed(2)} MB`);
+    console.log(`  Strings: ${(strSize / 1024 / 1024).toFixed(2)} MB`);
+    console.log(`  Binary total: ${((graphSize + strSize) / 1024 / 1024).toFixed(2)} MB`);
+    gf.close();
+    st.close();
+    console.log();
+    console.log('Migration complete. Original JSONL file preserved.');
+}
+// --- Main ---
+const inputPath = process.argv[2] || path.join(process.env.HOME || process.env.USERPROFILE || '.', '.local', 'share', 'memory', 'vscode.json');
+if (!fs.existsSync(inputPath)) {
+    console.error(`ERROR: File not found: ${inputPath}`);
+    process.exit(1);
+}
+migrate(inputPath).catch(err => {
+    console.error('Migration failed:', err);
+    process.exit(1);
+});

package/dist/scripts/verify-migration.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * Quick verification that binary files are readable after migration.
+ */
+import { StringTable } from '../src/stringtable.js';
+import { GraphFile, DIR_FORWARD } from '../src/graphfile.js';
+import * as path from 'path';
+const inputPath = process.argv[2] || path.join(process.env.HOME || '.', '.local', 'share', 'memory', 'vscode.json');
+const dir = path.dirname(inputPath);
+const base = path.basename(inputPath, path.extname(inputPath));
+const graphPath = path.join(dir, `${base}.graph`);
+const strPath = path.join(dir, `${base}.strings`);
+const st = new StringTable(strPath);
+const gf = new GraphFile(graphPath, st);
+const offsets = gf.getAllEntityOffsets();
+console.log(`Entity count: ${offsets.length}`);
+// Sample first 5 entities
+console.log('\nSample entities:');
+for (const off of offsets.slice(0, 5)) {
+    const rec = gf.readEntity(off);
+    const name = st.get(BigInt(rec.nameId));
+    const type = st.get(BigInt(rec.typeId));
+    const obs = [];
+    if (rec.obs0Id)
+        obs.push(st.get(BigInt(rec.obs0Id)));
+    if (rec.obs1Id)
+        obs.push(st.get(BigInt(rec.obs1Id)));
+    console.log(`  ${name} [${type}] obs=${obs.length} mtime=${Number(rec.mtime)}`);
+}
+// Count total relations
+let relCount = 0;
+for (const off of offsets) {
+    const edges = gf.getEdges(off);
+    relCount += edges.filter(e => e.direction === DIR_FORWARD).length;
+}
+console.log(`\nRelation count (forward edges): ${relCount}`);
+gf.close();
+st.close();
+console.log('\nVerification passed.');