@levalicious/server-memory 0.0.9 → 0.0.11

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/server.js

@@ -14,6 +14,44 @@ const DEFAULT_MEMORY_FILE_PATH = process.env.MEMORY_FILE_PATH
         ? process.env.MEMORY_FILE_PATH
         : path.join(path.dirname(fileURLToPath(import.meta.url)), process.env.MEMORY_FILE_PATH)
     : defaultMemoryPath;
+/**
+ * Sort entities by the specified field and direction.
+ * Returns a new array (does not mutate input).
+ * If sortBy is undefined, returns the original array (no sorting - preserves insertion order).
+ */
+function sortEntities(entities, sortBy, sortDir) {
+    if (!sortBy)
+        return entities; // No sorting - preserve current behavior
+    const dir = sortDir ?? (sortBy === "name" ? "asc" : "desc");
+    const mult = dir === "asc" ? 1 : -1;
+    return [...entities].sort((a, b) => {
+        if (sortBy === "name") {
+            return mult * a.name.localeCompare(b.name);
+        }
+        // For timestamps, treat undefined as 0 (oldest)
+        const aVal = a[sortBy] ?? 0;
+        const bVal = b[sortBy] ?? 0;
+        return mult * (aVal - bVal);
+    });
+}
+/**
+ * Sort neighbors by the specified field and direction.
+ * If sortBy is undefined, returns the original array (no sorting).
+ */
+function sortNeighbors(neighbors, sortBy, sortDir) {
+    if (!sortBy)
+        return neighbors;
+    const dir = sortDir ?? (sortBy === "name" ? "asc" : "desc");
+    const mult = dir === "asc" ? 1 : -1;
+    return [...neighbors].sort((a, b) => {
+        if (sortBy === "name") {
+            return mult * a.name.localeCompare(b.name);
+        }
+        const aVal = a[sortBy] ?? 0;
+        const bVal = b[sortBy] ?? 0;
+        return mult * (aVal - bVal);
+    });
+}
 export const MAX_CHARS = 2048;
 function paginateItems(items, cursor = 0, maxChars = MAX_CHARS) {
     const result = [];
@@ -93,8 +131,6 @@ function paginateGraph(graph, entityCursor = 0, relationCursor = 0) {
 }
 // The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
 export class KnowledgeGraphManager {
-    bclCtr = 0;
-    bclTerm = "";
     memoryFilePath;
     constructor(memoryFilePath = DEFAULT_MEMORY_FILE_PATH) {
         this.memoryFilePath = memoryFilePath;
@@ -254,7 +290,7 @@ export class KnowledgeGraphManager {
         });
     }
     // Regex-based search function
-    async searchNodes(query) {
+    async searchNodes(query, sortBy, sortDir) {
         const graph = await this.loadGraph();
         let regex;
         try {
@@ -272,7 +308,7 @@ export class KnowledgeGraphManager {
         // Filter relations to only include those between filtered entities
         const filteredRelations = graph.relations.filter(r => filteredEntityNames.has(r.from) && filteredEntityNames.has(r.to));
         const filteredGraph = {
-            entities: filteredEntities,
+            entities: sortEntities(filteredEntities, sortBy, sortDir),
             relations: filteredRelations,
         };
         return filteredGraph;
@@ -305,25 +341,21 @@ export class KnowledgeGraphManager {
         };
         return filteredGraph;
     }
-    async getNeighbors(entityName, depth = 1, withEntities = false) {
+    async getNeighbors(entityName, depth = 1, sortBy, sortDir) {
         const graph = await this.loadGraph();
         const visited = new Set();
-        const resultEntities = new Map();
-        const resultRelations = new Map(); // Deduplicate relations
-        const relationKey = (r) => `${r.from}|${r.relationType}|${r.to}`;
+        const neighborNames = new Set();
         const traverse = (currentName, currentDepth) => {
             if (currentDepth > depth || visited.has(currentName))
                 return;
             visited.add(currentName);
-            if (withEntities) {
-                const entity = graph.entities.find(e => e.name === currentName);
-                if (entity) {
-                    resultEntities.set(currentName, entity);
-                }
-            }
             // Find all relations involving this entity
             const connectedRelations = graph.relations.filter(r => r.from === currentName || r.to === currentName);
-            connectedRelations.forEach(r => resultRelations.set(relationKey(r), r));
+            // Collect neighbor names
+            connectedRelations.forEach(r => {
+                const neighborName = r.from === currentName ? r.to : r.from;
+                neighborNames.add(neighborName);
+            });
             if (currentDepth < depth) {
                 // Traverse to connected entities
                 connectedRelations.forEach(r => {
@@ -333,10 +365,19 @@ export class KnowledgeGraphManager {
             }
         };
         traverse(entityName, 0);
-        return {
-            entities: Array.from(resultEntities.values()),
-            relations: Array.from(resultRelations.values())
-        };
+        // Remove the starting entity from neighbors (it's not its own neighbor)
+        neighborNames.delete(entityName);
+        // Build neighbor objects with timestamps
+        const entityMap = new Map(graph.entities.map(e => [e.name, e]));
+        const neighbors = Array.from(neighborNames).map(name => {
+            const entity = entityMap.get(name);
+            return {
+                name,
+                mtime: entity?.mtime,
+                obsMtime: entity?.obsMtime,
+            };
+        });
+        return sortNeighbors(neighbors, sortBy, sortDir);
     }
     async findPath(fromEntity, toEntity, maxDepth = 5) {
         const graph = await this.loadGraph();
@@ -358,9 +399,10 @@ export class KnowledgeGraphManager {
         };
         return dfs(fromEntity, toEntity, [], 0) || [];
     }
-    async getEntitiesByType(entityType) {
+    async getEntitiesByType(entityType, sortBy, sortDir) {
         const graph = await this.loadGraph();
-        return graph.entities.filter(e => e.entityType === entityType);
+        const filtered = graph.entities.filter(e => e.entityType === entityType);
+        return sortEntities(filtered, sortBy, sortDir);
     }
     async getEntityTypes() {
         const graph = await this.loadGraph();
@@ -383,7 +425,7 @@ export class KnowledgeGraphManager {
             relationTypes: relationTypes.size
         };
     }
-    async getOrphanedEntities(strict = false) {
+    async getOrphanedEntities(strict = false, sortBy, sortDir) {
         const graph = await this.loadGraph();
         if (!strict) {
             // Simple mode: entities with no relations at all
@@ -392,7 +434,8 @@ export class KnowledgeGraphManager {
                 connectedEntityNames.add(r.from);
                 connectedEntityNames.add(r.to);
             });
-            return graph.entities.filter(e => !connectedEntityNames.has(e.name));
+            const orphans = graph.entities.filter(e => !connectedEntityNames.has(e.name));
+            return sortEntities(orphans, sortBy, sortDir);
         }
         // Strict mode: entities not connected to "Self" (directly or indirectly)
         // Build adjacency list (bidirectional)
@@ -420,7 +463,8 @@ export class KnowledgeGraphManager {
             }
         }
         // Return entities not connected to Self (excluding Self itself if it exists)
-        return graph.entities.filter(e => !connectedToSelf.has(e.name));
+        const orphans = graph.entities.filter(e => !connectedToSelf.has(e.name));
+        return sortEntities(orphans, sortBy, sortDir);
     }
     async validateGraph() {
         const graph = await this.loadGraph();
@@ -457,163 +501,96 @@ export class KnowledgeGraphManager {
             observationViolations
         };
     }
-    // BCL (Binary Combinatory Logic) evaluator
-    async evaluateBCL(program, maxSteps) {
-        let stepCount = 0;
-        let max_size = program.length;
-        let mode = 0;
-        let ctr = 1;
-        let t0 = program;
-        let t1 = '';
-        let t2 = '';
-        let t3 = '';
-        let t4 = '';
-        while (stepCount < maxSteps) {
-            if (t0.length == 0)
-                break;
-            let b = t0[0];
-            t0 = t0.slice(1);
-            if (mode === 0) {
-                t1 += b;
-                let size = t1.length + t0.length;
-                if (size > max_size)
-                    max_size = size;
-                if (t1.slice(-4) === '1100') {
-                    mode = 1;
-                    t1 = t1.slice(0, -4);
-                }
-                else if (t1.slice(-5) === '11101') {
-                    mode = 3;
-                    t1 = t1.slice(0, -5);
-                }
-            }
-            else if (mode === 1) {
-                t2 += b;
-                if (b == '1') {
-                    ctr += 1;
-                }
-                else if (b == '0') {
-                    ctr -= 1;
-                    t2 += t0[0];
-                    t0 = t0.slice(1);
-                }
-                if (ctr === 0) {
-                    mode = 2;
-                    ctr = 1;
-                }
-            }
-            else if (mode === 2) {
-                if (b == '1') {
-                    ctr += 1;
-                }
-                else if (b == '0') {
-                    ctr -= 1;
-                    t0 = t0.slice(1);
-                }
-                if (ctr === 0) {
-                    t0 = t2 + t0;
-                    t2 = '';
-                    mode = 0;
-                    ctr = 1;
-                    stepCount += 1;
-                }
-            }
-            else if (mode === 3) {
-                t2 += b;
-                if (b == '1') {
-                    ctr += 1;
-                }
-                else if (b == '0') {
-                    ctr -= 1;
-                    t2 += t0[0];
-                    t0 = t0.slice(1);
-                }
-                if (ctr === 0) {
-                    mode = 4;
-                    ctr = 1;
-                }
+    async randomWalk(start, depth = 3, seed) {
+        const graph = await this.loadGraph();
+        // Verify start entity exists
+        const startEntity = graph.entities.find(e => e.name === start);
+        if (!startEntity) {
+            throw new Error(`Start entity not found: ${start}`);
+        }
+        // Create seeded RNG if seed provided, otherwise use crypto.randomBytes
+        let rngState = seed ? this.hashSeed(seed) : null;
+        const random = () => {
+            if (rngState !== null) {
+                // Simple seeded PRNG (xorshift32)
+                rngState ^= rngState << 13;
+                rngState ^= rngState >>> 17;
+                rngState ^= rngState << 5;
+                return (rngState >>> 0) / 0xFFFFFFFF;
             }
-            else if (mode === 4) {
-                t3 += b;
-                if (b == '1') {
-                    ctr += 1;
-                }
-                else if (b == '0') {
-                    ctr -= 1;
-                    t3 += t0[0];
-                    t0 = t0.slice(1);
-                }
-                if (ctr === 0) {
-                    mode = 5;
-                    ctr = 1;
-                }
+            else {
+                return randomBytes(4).readUInt32BE() / 0xFFFFFFFF;
             }
-            else if (mode === 5) {
-                t4 += b;
-                if (b == '1') {
-                    ctr += 1;
-                }
-                else if (b == '0') {
-                    ctr -= 1;
-                    t4 += t0[0];
-                    t0 = t0.slice(1);
-                }
-                if (ctr === 0) {
-                    t0 = '11' + t2 + t4 + '1' + t3 + t4 + t0;
-                    t2 = '';
-                    t3 = '';
-                    t4 = '';
-                    mode = 0;
-                    ctr = 1;
-                    stepCount += 1;
-                }
+        };
+        const path = [start];
+        let current = start;
+        for (let i = 0; i < depth; i++) {
+            // Get unique neighbors (both directions)
+            const neighbors = new Set();
+            for (const rel of graph.relations) {
+                if (rel.from === current && rel.to !== current)
+                    neighbors.add(rel.to);
+                if (rel.to === current && rel.from !== current)
+                    neighbors.add(rel.from);
             }
+            // Filter to only existing entities
+            const validNeighbors = Array.from(neighbors).filter(n => graph.entities.some(e => e.name === n));
+            if (validNeighbors.length === 0)
+                break; // Dead end
+            // Pick random neighbor (uniform over entities)
+            const idx = Math.floor(random() * validNeighbors.length);
+            current = validNeighbors[idx];
+            path.push(current);
         }
-        const halted = stepCount < maxSteps;
-        return {
-            result: t1,
-            info: `${stepCount} steps, max size ${max_size}`,
-            halted,
-            errored: halted && mode != 0,
-        };
+        return { entity: current, path };
     }
-    async addBCLTerm(term) {
-        const termset = ["1", "00", "01"];
-        if (!term || term.trim() === "") {
-            throw new Error("BCL term cannot be empty");
-        }
-        // Term can be 1, 00, 01, or K, S, App (application)
-        const validTerms = ["1", "App", "00", "K", "01", "S"];
-        if (!validTerms.includes(term)) {
-            throw new Error(`Invalid BCL term: ${term}\nExpected one of: ${validTerms.join(", ")}`);
-        }
-        let processedTerm = 0;
-        if (term === "00" || term === "K")
-            processedTerm = 1;
-        else if (term === "01" || term === "S")
-            processedTerm = 2;
-        this.bclTerm += termset[processedTerm];
-        if (processedTerm === 0) {
-            if (this.bclCtr === 0)
-                this.bclCtr += 1;
-            this.bclCtr += 1;
-        }
-        else {
-            this.bclCtr -= 1;
-        }
-        if (this.bclCtr <= 0) {
-            const constructedProgram = this.bclTerm;
-            this.bclCtr = 0;
-            this.bclTerm = "";
-            return `Constructed Program: ${constructedProgram}`;
-        }
-        else {
-            return `Need ${this.bclCtr} more term(s) to complete the program.`;
+    hashSeed(seed) {
+        // Simple string hash to 32-bit integer
+        let hash = 0;
+        for (let i = 0; i < seed.length; i++) {
+            const char = seed.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash = hash & hash; // Convert to 32-bit integer
         }
+        return hash || 1; // Ensure non-zero for xorshift
     }
-    async clearBCLTerm() {
-        this.bclCtr = 0;
-        this.bclTerm = "";
+    decodeTimestamp(timestamp, relative = false) {
+        const ts = timestamp ?? Date.now();
+        const date = new Date(ts);
+        const result = {
+            timestamp: ts,
+            iso8601: date.toISOString(),
+            formatted: date.toUTCString(),
+        };
+        if (relative) {
+            const now = Date.now();
+            const diffMs = now - ts;
+            const diffSec = Math.abs(diffMs) / 1000;
+            const diffMin = diffSec / 60;
+            const diffHour = diffMin / 60;
+            const diffDay = diffHour / 24;
+            let relStr;
+            if (diffSec < 60) {
+                relStr = `${Math.floor(diffSec)} seconds`;
+            }
+            else if (diffMin < 60) {
+                relStr = `${Math.floor(diffMin)} minutes`;
+            }
+            else if (diffHour < 24) {
+                relStr = `${Math.floor(diffHour)} hours`;
+            }
+            else if (diffDay < 30) {
+                relStr = `${Math.floor(diffDay)} days`;
+            }
+            else if (diffDay < 365) {
+                relStr = `${Math.floor(diffDay / 30)} months`;
+            }
+            else {
+                relStr = `${Math.floor(diffDay / 365)} years`;
+            }
+            result.relative = diffMs >= 0 ? `${relStr} ago` : `in ${relStr}`;
+        }
+        return result;
     }
     async addThought(observations, previousCtxId) {
         return this.withLock(async () => {
@@ -668,7 +645,7 @@ export function createServer(memoryFilePath) {
                 sizes: ["any"]
             }
         ],
-        version: "0.0.4",
+        version: "0.0.11",
     }, {
         capabilities: {
             tools: {},
@@ -821,6 +798,8 @@ export function createServer(memoryFilePath) {
                         type: "object",
                         properties: {
                             query: { type: "string", description: "Regex pattern to match against entity names, types, and observations." },
+                            sortBy: { type: "string", enum: ["mtime", "obsMtime", "name"], description: "Sort field for entities. Omit for insertion order." },
+                            sortDir: { type: "string", enum: ["asc", "desc"], description: "Sort direction. Default: desc for timestamps, asc for name." },
                             entityCursor: { type: "number", description: "Cursor for entity pagination (from previous response's nextCursor)" },
                             relationCursor: { type: "number", description: "Cursor for relation pagination" },
                         },
@@ -863,15 +842,15 @@ export function createServer(memoryFilePath) {
                 },
                 {
                     name: "get_neighbors",
-                    description: "Get neighboring entities connected to a specific entity within a given depth. Results are paginated (max 512 chars).",
+                    description: "Get names of neighboring entities connected to a specific entity within a given depth. Returns neighbor names with timestamps for sorting. Use open_nodes to get full entity data. Results are paginated (max 512 chars).",
                     inputSchema: {
                         type: "object",
                         properties: {
                             entityName: { type: "string", description: "The name of the entity to find neighbors for" },
-                            depth: { type: "number", description: "Maximum depth to traverse (default: 0)", default: 0 },
-                            withEntities: { type: "boolean", description: "If true, include full entity data. Default returns only relations for lightweight structure exploration.", default: false },
-                            entityCursor: { type: "number", description: "Cursor for entity pagination" },
-                            relationCursor: { type: "number", description: "Cursor for relation pagination" },
+                            depth: { type: "number", description: "Maximum depth to traverse (default: 1)", default: 1 },
+                            sortBy: { type: "string", enum: ["mtime", "obsMtime", "name"], description: "Sort field for neighbors. Omit for arbitrary order." },
+                            sortDir: { type: "string", enum: ["asc", "desc"], description: "Sort direction. Default: desc for timestamps, asc for name." },
+                            cursor: { type: "number", description: "Cursor for pagination" },
                         },
                         required: ["entityName"],
                     },
@@ -897,6 +876,8 @@ export function createServer(memoryFilePath) {
                         type: "object",
                         properties: {
                             entityType: { type: "string", description: "The type of entities to retrieve" },
+                            sortBy: { type: "string", enum: ["mtime", "obsMtime", "name"], description: "Sort field for entities. Omit for insertion order." },
+                            sortDir: { type: "string", enum: ["asc", "desc"], description: "Sort direction. Default: desc for timestamps, asc for name." },
                             cursor: { type: "number", description: "Cursor for pagination" },
                         },
                         required: ["entityType"],
@@ -933,6 +914,8 @@ export function createServer(memoryFilePath) {
                         type: "object",
                         properties: {
                             strict: { type: "boolean", description: "If true, returns entities not connected to 'Self' (directly or indirectly). Default: false" },
+                            sortBy: { type: "string", enum: ["mtime", "obsMtime", "name"], description: "Sort field for entities. Omit for insertion order." },
+                            sortDir: { type: "string", enum: ["asc", "desc"], description: "Sort direction. Default: desc for timestamps, asc for name." },
                             cursor: { type: "number", description: "Cursor for pagination" },
                         },
                     },
@@ -946,37 +929,27 @@ export function createServer(memoryFilePath) {
                     },
                 },
                 {
-                    name: "evaluate_bcl",
-                    description: "Evaluate a Binary Combinatory Logic (BCL) program",
+                    name: "decode_timestamp",
+                    description: "Decode a millisecond timestamp to human-readable UTC format. If no timestamp provided, returns the current time. Use this to interpret mtime/obsMtime values from entities.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            program: { type: "string", description: "The BCL program as a binary string (syntax: T:=00|01|1TT) 00=K, 01=S, 1=application." },
-                            maxSteps: { type: "number", description: "Maximum number of reduction steps to perform (default: 1000000)", default: 1000000 },
+                            timestamp: { type: "number", description: "Millisecond timestamp to decode. If omitted, returns current time." },
+                            relative: { type: "boolean", description: "If true, include relative time (e.g., '3 days ago'). Default: false" },
                         },
-                        required: ["program"],
                     },
                 },
                 {
-                    name: "add_bcl_term",
-                    description: "Add a BCL term to the constructor, maintaining valid syntax. Returns completion status.",
+                    name: "random_walk",
+                    description: "Perform a random walk from a starting entity, following random relations. Returns the terminal entity name and the path taken. Useful for serendipitous exploration of the knowledge graph.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            term: {
-                                type: "string",
-                                description: "BCL term to add. Valid values: '1' or 'App' (application), '00' or 'K' (K combinator), '01' or 'S' (S combinator)"
-                            },
+                            start: { type: "string", description: "Name of the entity to start the walk from." },
+                            depth: { type: "number", description: "Number of steps to take. Default: 3" },
+                            seed: { type: "string", description: "Optional seed for reproducible walks." },
                         },
-                        required: ["term"],
-                    },
-                },
-                {
-                    name: "clear_bcl_term",
-                    description: "Clear the current BCL term being constructed and reset the constructor state",
-                    inputSchema: {
-                        type: "object",
-                        properties: {},
+                        required: ["start"],
                     },
                 },
                 {
@@ -1026,7 +999,7 @@ Use this to build chains of reasoning that persist in the graph. Each thought ca
                 await knowledgeGraphManager.deleteRelations(args.relations);
                 return { content: [{ type: "text", text: "Relations deleted successfully" }] };
             case "search_nodes": {
-                const graph = await knowledgeGraphManager.searchNodes(args.query);
+                const graph = await knowledgeGraphManager.searchNodes(args.query, args.sortBy, args.sortDir);
                 return { content: [{ type: "text", text: JSON.stringify(paginateGraph(graph, args.entityCursor ?? 0, args.relationCursor ?? 0)) }] };
             }
             case "open_nodes_filtered": {
@@ -1038,15 +1011,15 @@ Use this to build chains of reasoning that persist in the graph. Each thought ca
                 return { content: [{ type: "text", text: JSON.stringify(paginateGraph(graph, args.entityCursor ?? 0, args.relationCursor ?? 0)) }] };
             }
             case "get_neighbors": {
-                const graph = await knowledgeGraphManager.getNeighbors(args.entityName, args.depth, args.withEntities);
-                return { content: [{ type: "text", text: JSON.stringify(paginateGraph(graph, args.entityCursor ?? 0, args.relationCursor ?? 0)) }] };
+                const neighbors = await knowledgeGraphManager.getNeighbors(args.entityName, args.depth ?? 1, args.sortBy, args.sortDir);
+                return { content: [{ type: "text", text: JSON.stringify(paginateItems(neighbors, args.cursor ?? 0)) }] };
             }
             case "find_path": {
                 const path = await knowledgeGraphManager.findPath(args.fromEntity, args.toEntity, args.maxDepth);
                 return { content: [{ type: "text", text: JSON.stringify(paginateItems(path, args.cursor ?? 0)) }] };
             }
             case "get_entities_by_type": {
-                const entities = await knowledgeGraphManager.getEntitiesByType(args.entityType);
+                const entities = await knowledgeGraphManager.getEntitiesByType(args.entityType, args.sortBy, args.sortDir);
                 return { content: [{ type: "text", text: JSON.stringify(paginateItems(entities, args.cursor ?? 0)) }] };
             }
             case "get_entity_types":
@@ -1056,18 +1029,17 @@ Use this to build chains of reasoning that persist in the graph. Each thought ca
             case "get_stats":
                 return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.getStats(), null, 2) }] };
             case "get_orphaned_entities": {
-                const entities = await knowledgeGraphManager.getOrphanedEntities(args.strict ?? false);
+                const entities = await knowledgeGraphManager.getOrphanedEntities(args.strict ?? false, args.sortBy, args.sortDir);
                 return { content: [{ type: "text", text: JSON.stringify(paginateItems(entities, args.cursor ?? 0)) }] };
             }
             case "validate_graph":
                 return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.validateGraph(), null, 2) }] };
-            case "evaluate_bcl":
-                return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.evaluateBCL(args.program, args.maxSteps), null, 2) }] };
-            case "add_bcl_term":
-                return { content: [{ type: "text", text: await knowledgeGraphManager.addBCLTerm(args.term) }] };
-            case "clear_bcl_term":
-                await knowledgeGraphManager.clearBCLTerm();
-                return { content: [{ type: "text", text: "BCL term constructor cleared successfully" }] };
+            case "decode_timestamp":
+                return { content: [{ type: "text", text: JSON.stringify(knowledgeGraphManager.decodeTimestamp(args.timestamp, args.relative ?? false)) }] };
+            case "random_walk": {
+                const result = await knowledgeGraphManager.randomWalk(args.start, args.depth ?? 3, args.seed);
+                return { content: [{ type: "text", text: JSON.stringify(result) }] };
+            }
             case "sequentialthinking": {
                 const result = await knowledgeGraphManager.addThought(args.observations, args.previousCtxId);
                 return { content: [{ type: "text", text: JSON.stringify(result) }] };

package/dist/tests/memory-server.test.js

@@ -283,64 +283,43 @@ describe('MCP Memory Server E2E Tests', () => {
                 ]
             });
         });
-        it('should get neighbors at depth 0 (relations only by default)', async () => {
+        it('should get immediate neighbors at depth 0', async () => {
             const result = await callTool(client, 'get_neighbors', {
                 entityName: 'Root',
                 depth: 0
             });
-            expect(result.entities.items).toHaveLength(0); // withEntities defaults to false
-            expect(result.relations.items).toHaveLength(2); // Root's direct relations
+            // depth 0 returns immediate neighbors only
+            expect(result.items).toHaveLength(2);
+            const names = result.items.map(n => n.name);
+            expect(names).toContain('Child1');
+            expect(names).toContain('Child2');
         });
-        it('should get neighbors with entities when requested', async () => {
-            // Accumulate all entities across pagination
-            const allEntities = [];
-            let entityCursor = 0;
-            while (entityCursor !== null) {
-                const result = await callTool(client, 'get_neighbors', {
-                    entityName: 'Root',
-                    depth: 1,
-                    withEntities: true,
-                    entityCursor
-                });
-                allEntities.push(...result.entities.items);
-                entityCursor = result.entities.nextCursor;
-            }
-            expect(allEntities).toHaveLength(3);
-            expect(allEntities.map(e => e.name)).toContain('Root');
-            expect(allEntities.map(e => e.name)).toContain('Child1');
-            expect(allEntities.map(e => e.name)).toContain('Child2');
+        it('should get neighbors at depth 1 (includes neighbors of neighbors)', async () => {
+            const result = await callTool(client, 'get_neighbors', {
+                entityName: 'Root',
+                depth: 1
+            });
+            // depth 1: Child1, Child2 (immediate) + Grandchild (neighbor of Child1)
+            expect(result.items).toHaveLength(3);
+            const names = result.items.map(n => n.name);
+            expect(names).toContain('Child1');
+            expect(names).toContain('Child2');
+            expect(names).toContain('Grandchild');
         });
         it('should traverse to specified depth', async () => {
-            // Collect all entities and relations using pagination
-            const allEntities = [];
-            const allRelations = [];
-            let entityCursor = 0;
-            let relationCursor = 0;
-            // Paginate through all results
-            while (entityCursor !== null || relationCursor !== null) {
-                const result = await callTool(client, 'get_neighbors', {
-                    entityName: 'Root',
-                    depth: 2,
-                    withEntities: true,
-                    // Pass large cursor to skip when done, 0 to fetch
-                    entityCursor: entityCursor !== null ? entityCursor : 999999,
-                    relationCursor: relationCursor !== null ? relationCursor : 999999
-                });
-                // Collect entities if we still need them
-                if (entityCursor !== null) {
-                    allEntities.push(...result.entities.items);
-                    entityCursor = result.entities.nextCursor;
-                }
-                // Collect relations if we still need them
-                if (relationCursor !== null) {
-                    allRelations.push(...result.relations.items);
-                    relationCursor = result.relations.nextCursor;
-                }
-            }
-            expect(allEntities).toHaveLength(4); // All nodes
-            expect(allRelations).toHaveLength(3); // All relations
+            const result = await callTool(client, 'get_neighbors', {
+                entityName: 'Root',
+                depth: 2
+            });
+            // At depth 2 from Root: same as depth 1 since graph is small
+            // Child1, Child2, Grandchild (Root is excluded as starting point)
+            expect(result.items).toHaveLength(3);
+            const names = result.items.map(n => n.name);
+            expect(names).toContain('Child1');
+            expect(names).toContain('Child2');
+            expect(names).toContain('Grandchild');
         });
-        it('should deduplicate relations in traversal', async () => {
+        it('should deduplicate neighbors in traversal', async () => {
             // Add a bidirectional relation
             await callTool(client, 'create_relations', {
                 relations: [{ from: 'Child2', to: 'Root', relationType: 'child_of' }]
@@ -349,10 +328,10 @@ describe('MCP Memory Server E2E Tests', () => {
                 entityName: 'Root',
                 depth: 1
             });
-            // Each unique relation should appear only once
-            const relationKeys = result.relations.items.map(r => `${r.from}|${r.relationType}|${r.to}`);
-            const uniqueKeys = [...new Set(relationKeys)];
-            expect(relationKeys.length).toBe(uniqueKeys.length);
+            // Each neighbor should appear only once
+            const names = result.items.map(n => n.name);
+            const uniqueNames = [...new Set(names)];
+            expect(names.length).toBe(uniqueNames.length);
         });
         it('should find path between entities', async () => {
             const result = await callTool(client, 'find_path', {
@@ -478,35 +457,6 @@ describe('MCP Memory Server E2E Tests', () => {
             expect(result.missingEntities).toContain('Missing');
         });
     });
-    describe('BCL Evaluator', () => {
-        it('should evaluate K combinator (identity for first arg)', async () => {
-            // K = 00, evaluating K applied to two args should return first
-            // This is a simplified test - BCL semantics are complex
-            const result = await callTool(client, 'evaluate_bcl', {
-                program: '00',
-                maxSteps: 100
-            });
-            expect(result.halted).toBe(true);
-        });
-        it('should construct BCL terms incrementally', async () => {
-            let result = await callTool(client, 'add_bcl_term', { term: 'App' });
-            expect(result).toContain('more term');
-            result = await callTool(client, 'add_bcl_term', { term: 'K' });
-            expect(result).toContain('more term');
-            result = await callTool(client, 'add_bcl_term', { term: 'S' });
-            expect(result).toContain('Constructed Program');
-        });
-        it('should clear BCL constructor state', async () => {
-            await callTool(client, 'add_bcl_term', { term: 'App' });
-            await callTool(client, 'clear_bcl_term', {});
-            // After clearing, we should need to start fresh
-            const result = await callTool(client, 'add_bcl_term', { term: 'K' });
-            expect(result).toContain('Constructed Program');
-        });
-        it('should reject invalid BCL terms', async () => {
-            await expect(callTool(client, 'add_bcl_term', { term: 'invalid' })).rejects.toThrow(/Invalid BCL term/);
-        });
-    });
     describe('Sequential Thinking', () => {
         it('should create a thought and return ctxId', async () => {
             const result = await callTool(client, 'sequentialthinking', {
@@ -524,13 +474,13 @@ describe('MCP Memory Server E2E Tests', () => {
                 previousCtxId: first.ctxId,
                 observations: ['Following up']
             });
-            // Verify the chain via relations
+            // Verify the chain via neighbors
             const neighbors = await callTool(client, 'get_neighbors', {
                 entityName: first.ctxId,
                 depth: 1
             });
-            // Should have 'follows' relation from first to second
-            expect(neighbors.relations.items.some(r => r.from === first.ctxId && r.to === second.ctxId && r.relationType === 'follows')).toBe(true);
+            // Second thought should be a neighbor of first
+            expect(neighbors.items.some(n => n.name === second.ctxId)).toBe(true);
         });
         it('should ignore invalid previousCtxId gracefully', async () => {
             const result = await callTool(client, 'sequentialthinking', {
@@ -538,12 +488,12 @@ describe('MCP Memory Server E2E Tests', () => {
                 observations: ['Orphaned thought']
             });
             expect(result.ctxId).toMatch(/^[0-9a-f]{24}$/);
-            // Verify no relations were created
+            // Verify no neighbors (no valid relations were created)
             const neighbors = await callTool(client, 'get_neighbors', {
                 entityName: result.ctxId,
                 depth: 1
             });
-            expect(neighbors.relations.totalCount).toBe(0);
+            expect(neighbors.items).toHaveLength(0);
         });
         it('should enforce observation limits on thoughts', async () => {
             await expect(callTool(client, 'sequentialthinking', {
@@ -562,4 +512,408 @@ describe('MCP Memory Server E2E Tests', () => {
             expect(thought.obsMtime).toBeDefined();
         });
     });
+    describe('Timestamp Decoding', () => {
+        it('should decode a specific timestamp', async () => {
+            const result = await callTool(client, 'decode_timestamp', {
+                timestamp: 1735200000000 // Known timestamp
+            });
+            expect(result.timestamp).toBe(1735200000000);
+            expect(result.iso8601).toBe('2024-12-26T08:00:00.000Z');
+            expect(result.formatted).toContain('2024');
+        });
+        it('should return current time when no timestamp provided', async () => {
+            const before = Date.now();
+            const result = await callTool(client, 'decode_timestamp', {});
+            const after = Date.now();
+            expect(result.timestamp).toBeGreaterThanOrEqual(before);
+            expect(result.timestamp).toBeLessThanOrEqual(after);
+        });
+        it('should include relative time when requested', async () => {
+            const oneHourAgo = Date.now() - 3600000;
+            const result = await callTool(client, 'decode_timestamp', {
+                timestamp: oneHourAgo,
+                relative: true
+            });
+            expect(result.relative).toContain('hour');
+            expect(result.relative).toContain('ago');
+        });
+        it('should handle future timestamps', async () => {
+            const oneHourFromNow = Date.now() + 3600000;
+            const result = await callTool(client, 'decode_timestamp', {
+                timestamp: oneHourFromNow,
+                relative: true
+            });
+            expect(result.relative).toContain('in');
+        });
+    });
+    describe('Random Walk', () => {
+        beforeEach(async () => {
+            // Create a small graph for walking
+            await callTool(client, 'create_entities', {
+                entities: [
+                    { name: 'Center', entityType: 'Node', observations: ['Hub node'] },
+                    { name: 'North', entityType: 'Node', observations: ['North node'] },
+                    { name: 'South', entityType: 'Node', observations: ['South node'] },
+                    { name: 'East', entityType: 'Node', observations: ['East node'] },
+                    { name: 'Isolated', entityType: 'Node', observations: ['No connections'] },
+                ]
+            });
+            await callTool(client, 'create_relations', {
+                relations: [
+                    { from: 'Center', to: 'North', relationType: 'connects' },
+                    { from: 'Center', to: 'South', relationType: 'connects' },
+                    { from: 'Center', to: 'East', relationType: 'connects' },
+                    { from: 'North', to: 'South', relationType: 'connects' },
+                ]
+            });
+        });
+        it('should perform a walk and return path', async () => {
+            const result = await callTool(client, 'random_walk', {
+                start: 'Center',
+                depth: 2
+            });
+            expect(result.path[0]).toBe('Center');
+            expect(result.path.length).toBeGreaterThanOrEqual(1);
+            expect(result.path.length).toBeLessThanOrEqual(3);
+            expect(result.entity).toBe(result.path[result.path.length - 1]);
+        });
+        it('should terminate early at dead ends', async () => {
+            const result = await callTool(client, 'random_walk', {
+                start: 'Isolated',
+                depth: 5
+            });
+            expect(result.path).toEqual(['Isolated']);
+            expect(result.entity).toBe('Isolated');
+        });
+        it('should produce reproducible walks with same seed', async () => {
+            const result1 = await callTool(client, 'random_walk', {
+                start: 'Center',
+                depth: 3,
+                seed: 'test-seed-123'
+            });
+            const result2 = await callTool(client, 'random_walk', {
+                start: 'Center',
+                depth: 3,
+                seed: 'test-seed-123'
+            });
+            expect(result1.path).toEqual(result2.path);
+        });
+        it('should throw on non-existent start entity', async () => {
+            await expect(callTool(client, 'random_walk', { start: 'NonExistent', depth: 2 })).rejects.toThrow(/not found/);
+        });
+    });
+    describe('Sorting', () => {
+        // Helper to create entities with controlled timestamps
+        async function createEntitiesWithDelay(entities) {
+            for (const entity of entities) {
+                await callTool(client, 'create_entities', { entities: [entity] });
+                // Small delay to ensure distinct mtime values
+                await new Promise(resolve => setTimeout(resolve, 10));
+            }
+        }
+        describe('search_nodes sorting', () => {
+            beforeEach(async () => {
+                // Create entities with distinct timestamps
+                await createEntitiesWithDelay([
+                    { name: 'Alpha', entityType: 'Letter', observations: ['First letter'] },
+                    { name: 'Beta', entityType: 'Letter', observations: ['Second letter'] },
+                    { name: 'Gamma', entityType: 'Letter', observations: ['Third letter'] }
+                ]);
+            });
+            it('should preserve insertion order when sortBy is omitted', async () => {
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Letter'
+                });
+                const names = result.entities.items.map(e => e.name);
+                expect(names).toEqual(['Alpha', 'Beta', 'Gamma']);
+            });
+            it('should sort by name ascending', async () => {
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Letter',
+                    sortBy: 'name',
+                    sortDir: 'asc'
+                });
+                const names = result.entities.items.map(e => e.name);
+                expect(names).toEqual(['Alpha', 'Beta', 'Gamma']);
+            });
+            it('should sort by name descending', async () => {
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Letter',
+                    sortBy: 'name',
+                    sortDir: 'desc'
+                });
+                const names = result.entities.items.map(e => e.name);
+                expect(names).toEqual(['Gamma', 'Beta', 'Alpha']);
+            });
+            it('should sort by mtime descending by default', async () => {
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Letter',
+                    sortBy: 'mtime'
+                });
+                const names = result.entities.items.map(e => e.name);
+                // Gamma was created last, so should be first when sorted desc
+                expect(names).toEqual(['Gamma', 'Beta', 'Alpha']);
+            });
+            it('should sort by mtime ascending when specified', async () => {
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Letter',
+                    sortBy: 'mtime',
+                    sortDir: 'asc'
+                });
+                const names = result.entities.items.map(e => e.name);
+                // Alpha was created first, so should be first when sorted asc
+                expect(names).toEqual(['Alpha', 'Beta', 'Gamma']);
+            });
+            it('should sort by obsMtime', async () => {
+                // Update observation on Alpha to make it have most recent obsMtime
+                await callTool(client, 'delete_observations', {
+                    deletions: [{ entityName: 'Alpha', observations: ['First letter'] }]
+                });
+                await callTool(client, 'add_observations', {
+                    observations: [{ entityName: 'Alpha', contents: ['Updated'] }]
+                });
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Letter|Updated',
+                    sortBy: 'obsMtime'
+                });
+                const names = result.entities.items.map(e => e.name);
+                // Alpha should be first because its obsMtime was just updated
+                expect(names[0]).toBe('Alpha');
+            });
+        });
+        describe('get_entities_by_type sorting', () => {
+            beforeEach(async () => {
+                await createEntitiesWithDelay([
+                    { name: 'Zebra', entityType: 'Animal', observations: ['Striped'] },
+                    { name: 'Aardvark', entityType: 'Animal', observations: ['Nocturnal'] },
+                    { name: 'Monkey', entityType: 'Animal', observations: ['Clever'] }
+                ]);
+            });
+            it('should preserve insertion order when sortBy is omitted', async () => {
+                const result = await callTool(client, 'get_entities_by_type', {
+                    entityType: 'Animal'
+                });
+                const names = result.items.map(e => e.name);
+                expect(names).toEqual(['Zebra', 'Aardvark', 'Monkey']);
+            });
+            it('should sort by name ascending (default for name)', async () => {
+                const result = await callTool(client, 'get_entities_by_type', {
+                    entityType: 'Animal',
+                    sortBy: 'name'
+                });
+                const names = result.items.map(e => e.name);
+                expect(names).toEqual(['Aardvark', 'Monkey', 'Zebra']);
+            });
+            it('should sort by name descending', async () => {
+                const result = await callTool(client, 'get_entities_by_type', {
+                    entityType: 'Animal',
+                    sortBy: 'name',
+                    sortDir: 'desc'
+                });
+                const names = result.items.map(e => e.name);
+                expect(names).toEqual(['Zebra', 'Monkey', 'Aardvark']);
+            });
+            it('should sort by mtime descending (default for mtime)', async () => {
+                const result = await callTool(client, 'get_entities_by_type', {
+                    entityType: 'Animal',
+                    sortBy: 'mtime'
+                });
+                const names = result.items.map(e => e.name);
+                // Monkey was created last
+                expect(names).toEqual(['Monkey', 'Aardvark', 'Zebra']);
+            });
+            it('should sort by mtime ascending', async () => {
+                const result = await callTool(client, 'get_entities_by_type', {
+                    entityType: 'Animal',
+                    sortBy: 'mtime',
+                    sortDir: 'asc'
+                });
+                const names = result.items.map(e => e.name);
+                // Zebra was created first
+                expect(names).toEqual(['Zebra', 'Aardvark', 'Monkey']);
+            });
+        });
+        describe('get_orphaned_entities sorting', () => {
+            beforeEach(async () => {
+                // Create orphaned entities (no relations)
+                await createEntitiesWithDelay([
+                    { name: 'Orphan_Z', entityType: 'Orphan', observations: ['Alone'] },
+                    { name: 'Orphan_A', entityType: 'Orphan', observations: ['Solo'] },
+                    { name: 'Orphan_M', entityType: 'Orphan', observations: ['Isolated'] }
+                ]);
+            });
+            it('should preserve insertion order when sortBy is omitted', async () => {
+                const result = await callTool(client, 'get_orphaned_entities', {});
+                const names = result.items.map(e => e.name);
+                expect(names).toEqual(['Orphan_Z', 'Orphan_A', 'Orphan_M']);
+            });
+            it('should sort by name ascending', async () => {
+                const result = await callTool(client, 'get_orphaned_entities', {
+                    sortBy: 'name'
+                });
+                const names = result.items.map(e => e.name);
+                expect(names).toEqual(['Orphan_A', 'Orphan_M', 'Orphan_Z']);
+            });
+            it('should sort by name descending', async () => {
+                const result = await callTool(client, 'get_orphaned_entities', {
+                    sortBy: 'name',
+                    sortDir: 'desc'
+                });
+                const names = result.items.map(e => e.name);
+                expect(names).toEqual(['Orphan_Z', 'Orphan_M', 'Orphan_A']);
+            });
+            it('should sort by mtime descending (default)', async () => {
+                const result = await callTool(client, 'get_orphaned_entities', {
+                    sortBy: 'mtime'
+                });
+                const names = result.items.map(e => e.name);
+                // Orphan_M was created last
+                expect(names).toEqual(['Orphan_M', 'Orphan_A', 'Orphan_Z']);
+            });
+            it('should work with strict mode and sorting', async () => {
+                // Create Self and connect one orphan to it
+                await callTool(client, 'create_entities', {
+                    entities: [{ name: 'Self', entityType: 'Agent', observations: [] }]
+                });
+                await callTool(client, 'create_relations', {
+                    relations: [{ from: 'Self', to: 'Orphan_A', relationType: 'knows' }]
+                });
+                const result = await callTool(client, 'get_orphaned_entities', {
+                    strict: true,
+                    sortBy: 'name'
+                });
+                const names = result.items.map(e => e.name);
+                // Orphan_A is now connected to Self, so only M and Z are orphaned
+                expect(names).toEqual(['Orphan_M', 'Orphan_Z']);
+            });
+        });
+        describe('get_neighbors sorting', () => {
+            beforeEach(async () => {
+                // Create a hub with neighbors created at different times
+                await callTool(client, 'create_entities', {
+                    entities: [{ name: 'Hub', entityType: 'Center', observations: [] }]
+                });
+                await createEntitiesWithDelay([
+                    { name: 'Neighbor_Z', entityType: 'Node', observations: ['First'] },
+                    { name: 'Neighbor_A', entityType: 'Node', observations: ['Second'] },
+                    { name: 'Neighbor_M', entityType: 'Node', observations: ['Third'] }
+                ]);
+                // Connect all to Hub
+                await callTool(client, 'create_relations', {
+                    relations: [
+                        { from: 'Hub', to: 'Neighbor_Z', relationType: 'connects' },
+                        { from: 'Hub', to: 'Neighbor_A', relationType: 'connects' },
+                        { from: 'Hub', to: 'Neighbor_M', relationType: 'connects' }
+                    ]
+                });
+            });
+            it('should return unsorted neighbors when sortBy is omitted', async () => {
+                const result = await callTool(client, 'get_neighbors', {
+                    entityName: 'Hub'
+                });
+                expect(result.items).toHaveLength(3);
+                // Just verify all neighbors are present
+                const names = result.items.map(n => n.name);
+                expect(names).toContain('Neighbor_Z');
+                expect(names).toContain('Neighbor_A');
+                expect(names).toContain('Neighbor_M');
+            });
+            it('should sort neighbors by name ascending', async () => {
+                const result = await callTool(client, 'get_neighbors', {
+                    entityName: 'Hub',
+                    sortBy: 'name'
+                });
+                const names = result.items.map(n => n.name);
+                expect(names).toEqual(['Neighbor_A', 'Neighbor_M', 'Neighbor_Z']);
+            });
+            it('should sort neighbors by name descending', async () => {
+                const result = await callTool(client, 'get_neighbors', {
+                    entityName: 'Hub',
+                    sortBy: 'name',
+                    sortDir: 'desc'
+                });
+                const names = result.items.map(n => n.name);
+                expect(names).toEqual(['Neighbor_Z', 'Neighbor_M', 'Neighbor_A']);
+            });
+            it('should sort neighbors by mtime descending (default)', async () => {
+                const result = await callTool(client, 'get_neighbors', {
+                    entityName: 'Hub',
+                    sortBy: 'mtime'
+                });
+                const names = result.items.map(n => n.name);
+                // Neighbor_M was created last
+                expect(names).toEqual(['Neighbor_M', 'Neighbor_A', 'Neighbor_Z']);
+            });
+            it('should sort neighbors by mtime ascending', async () => {
+                const result = await callTool(client, 'get_neighbors', {
+                    entityName: 'Hub',
+                    sortBy: 'mtime',
+                    sortDir: 'asc'
+                });
+                const names = result.items.map(n => n.name);
+                // Neighbor_Z was created first
+                expect(names).toEqual(['Neighbor_Z', 'Neighbor_A', 'Neighbor_M']);
+            });
+            it('should include mtime and obsMtime in neighbor objects', async () => {
+                const result = await callTool(client, 'get_neighbors', {
+                    entityName: 'Hub',
+                    sortBy: 'name'
+                });
+                // Each neighbor should have timestamp fields
+                for (const neighbor of result.items) {
+                    expect(neighbor.mtime).toBeDefined();
+                    expect(neighbor.obsMtime).toBeDefined();
+                    expect(typeof neighbor.mtime).toBe('number');
+                    expect(typeof neighbor.obsMtime).toBe('number');
+                }
+            });
+            it('should sort by obsMtime after observation update', async () => {
+                // Update observation on Neighbor_Z to make it have most recent obsMtime
+                await callTool(client, 'delete_observations', {
+                    deletions: [{ entityName: 'Neighbor_Z', observations: ['First'] }]
+                });
+                await callTool(client, 'add_observations', {
+                    observations: [{ entityName: 'Neighbor_Z', contents: ['Updated recently'] }]
+                });
+                const result = await callTool(client, 'get_neighbors', {
+                    entityName: 'Hub',
+                    sortBy: 'obsMtime'
+                });
+                const names = result.items.map(n => n.name);
+                // Neighbor_Z should be first because its obsMtime was just updated
+                expect(names[0]).toBe('Neighbor_Z');
+            });
+        });
+        describe('sorting with pagination', () => {
+            it('should maintain sort order across paginated results', async () => {
+                // Create many entities to force pagination
+                const entities = [];
+                for (let i = 0; i < 20; i++) {
+                    entities.push({
+                        name: `Entity_${String(i).padStart(2, '0')}`,
+                        entityType: 'Numbered',
+                        observations: [`Number ${i}`]
+                    });
+                }
+                await callTool(client, 'create_entities', { entities });
+                // Fetch all pages sorted by name descending
+                const allEntities = [];
+                let entityCursor = 0;
+                while (entityCursor !== null) {
+                    const result = await callTool(client, 'search_nodes', {
+                        query: 'Numbered',
+                        sortBy: 'name',
+                        sortDir: 'desc',
+                        entityCursor
+                    });
+                    allEntities.push(...result.entities.items);
+                    entityCursor = result.entities.nextCursor;
+                }
+                // Verify all entities are in descending order
+                const names = allEntities.map(e => e.name);
+                const sortedNames = [...names].sort().reverse();
+                expect(names).toEqual(sortedNames);
+            });
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levalicious/server-memory",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "MCP server for enabling memory for Claude through a knowledge graph",
   "license": "MIT",
   "author": "Levalicious",
@@ -15,18 +15,19 @@
   ],
   "scripts": {
     "build": "tsc && shx chmod +x dist/*.js",
-    "prepare": "npm run build",
+    "prepare": "husky && npm run build",
     "watch": "tsc --watch",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.24.0",
+    "@modelcontextprotocol/sdk": "1.25.1",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^24",
+    "@types/node": "^25",
     "@types/proper-lockfile": "^4.1.4",
+    "husky": "^9.1.7",
     "jest": "^30.2.0",
     "shx": "^0.4.0",
     "ts-jest": "^29.4.5",