@levalicious/server-memory 0.0.8 → 0.0.9

package/README.md

@@ -8,33 +8,37 @@ A basic implementation of persistent memory using a local knowledge graph. This
 Entities are the primary nodes in the knowledge graph. Each entity has:
 - A unique name (identifier)
 - An entity type (e.g., "person", "organization", "event")
-- A list of observations
+- A list of observations (max 2, each max 140 characters)
+- Modification timestamps (`mtime` for any change, `obsMtime` for observation changes)
 
 Example:
 ```json
 {
   "name": "John_Smith",
   "entityType": "person",
-  "observations": ["Speaks fluent Spanish"]
+  "observations": ["Speaks fluent Spanish"],
+  "mtime": 1733423456789,
+  "obsMtime": 1733423456789
 }
 ```
 
 ### Relations
-Relations define directed connections between entities. They are always stored in active voice and describe how entities interact or relate to each other.
+Relations define directed connections between entities. They are always stored in active voice and describe how entities interact or relate to each other. Each relation has a modification timestamp (`mtime`).
 
 Example:
 ```json
 {
   "from": "John_Smith",
   "to": "Anthropic",
-  "relationType": "works_at"
+  "relationType": "works_at",
+  "mtime": 1733423456789
 }
 ```
 ### Observations
 Observations are discrete pieces of information about an entity. They are:
 
-- Stored as strings
-- Attached to specific entities
+- Stored as strings (max 140 characters each)
+- Attached to specific entities (max 2 per entity)
 - Can be added or removed independently
 - Should be atomic (one fact per observation)
 
@@ -44,8 +48,7 @@ Example:
   "entityName": "John_Smith",
   "observations": [
     "Speaks fluent Spanish",
-    "Graduated in 2019",
-    "Prefers morning meetings"
+    "Graduated in 2019"
   ]
 }
 ```
@@ -59,7 +62,7 @@ Example:
     - Each object contains:
       - `name` (string): Entity identifier
       - `entityType` (string): Type classification
-      - `observations` (string[]): Associated observations
+      - `observations` (string[]): Associated observations (max 2, each max 140 chars)
   - Ignores entities with existing names
 
 - **create_relations**
@@ -76,9 +79,9 @@ Example:
   - Input: `observations` (array of objects)
     - Each object contains:
       - `entityName` (string): Target entity
-      - `contents` (string[]): New observations to add
+      - `contents` (string[]): New observations to add (each max 140 chars)
   - Returns added observations per entity
-  - Fails if entity doesn't exist
+  - Fails if entity doesn't exist or would exceed 2 observations
 
 - **delete_entities**
   - Remove entities and their relations
@@ -103,42 +106,45 @@ Example:
       - `relationType` (string): Relationship type
   - Silent operation if relation doesn't exist
 
-- **read_graph**
-  - Read the entire knowledge graph
-  - No input required
-  - Returns complete graph structure with all entities and relations
-
 - **search_nodes**
-  - Search for nodes based on query
-  - Input: `query` (string)
+  - Search for nodes using a regex pattern
+  - Input: `query` (string), `entityCursor` (number, optional), `relationCursor` (number, optional)
   - Searches across:
     - Entity names
     - Entity types
     - Observation content
-  - Returns matching entities and their relations
+  - Returns matching entities and their relations (paginated)
+
+- **open_nodes_filtered**
+  - Retrieve specific nodes by name with filtered relations
+  - Input: `names` (string[]), `entityCursor` (number, optional), `relationCursor` (number, optional)
+  - Returns:
+    - Requested entities
+    - Only relations where both endpoints are in the requested set
+  - Silently skips non-existent nodes (paginated)
 
 - **open_nodes**
   - Retrieve specific nodes by name
-  - Input: `names` (string[])
+  - Input: `names` (string[]), `entityCursor` (number, optional), `relationCursor` (number, optional)
   - Returns:
     - Requested entities
-    - Relations between requested entities
-  - Silently skips non-existent nodes
+    - Relations originating from requested entities
+  - 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: 1)
-  - Returns entities connected within specified 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)
 
 - **find_path**
   - Find a path between two entities in the knowledge graph
-  - Input: `fromEntity` (string), `toEntity` (string), `maxDepth` (number, default: 5)
-  - Returns path between entities if one exists
+  - Input: `fromEntity` (string), `toEntity` (string), `maxDepth` (number, default: 5), `cursor` (number, optional)
+  - Returns path between entities if one exists (paginated)
 
 - **get_entities_by_type**
   - Get all entities of a specific type
-  - Input: `entityType` (string)
-  - Returns all entities matching the specified type
+  - Input: `entityType` (string), `cursor` (number, optional)
+  - Returns all entities matching the specified type (paginated)
 
 - **get_entity_types**
   - Get all unique entity types in the knowledge graph
@@ -156,14 +162,15 @@ Example:
   - Returns entity count, relation count, entity types count, relation types count
 
 - **get_orphaned_entities**
-  - Get entities that have no relations
-  - No input required
-  - Returns entities with no connections
+  - 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)
+  - Returns entities with no connections (paginated)
 
 - **validate_graph**
-  - Validate the knowledge graph and return missing entities referenced in relations
+  - Validate the knowledge graph
   - No input required
-  - Returns list of missing entities
+  - Returns missing entities referenced in relations and observation limit violations
 
 - **evaluate_bcl**
   - Evaluate a Binary Combinatory Logic (BCL) program
@@ -182,6 +189,12 @@ Example:
   - No input required
   - Resets BCL constructor
 
+- **sequentialthinking**
+  - Record a thought in the knowledge graph
+  - Input: `observations` (string[], max 2, each max 140 chars), `previousCtxId` (string, optional)
+  - Creates a Thought entity and links it to the previous thought if provided
+  - Returns the new thought's context ID for chaining
+
 # Usage with Claude Desktop
 
 ### Setup

package/dist/server.js

@@ -2,6 +2,7 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { promises as fs } from 'fs';
+import { randomBytes } from 'crypto';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import lockfile from 'proper-lockfile';
@@ -382,14 +383,44 @@ export class KnowledgeGraphManager {
             relationTypes: relationTypes.size
         };
     }
-    async getOrphanedEntities() {
+    async getOrphanedEntities(strict = false) {
         const graph = await this.loadGraph();
-        const connectedEntityNames = new Set();
+        if (!strict) {
+            // Simple mode: entities with no relations at all
+            const connectedEntityNames = new Set();
+            graph.relations.forEach(r => {
+                connectedEntityNames.add(r.from);
+                connectedEntityNames.add(r.to);
+            });
+            return graph.entities.filter(e => !connectedEntityNames.has(e.name));
+        }
+        // Strict mode: entities not connected to "Self" (directly or indirectly)
+        // Build adjacency list (bidirectional)
+        const neighbors = new Map();
+        graph.entities.forEach(e => neighbors.set(e.name, new Set()));
         graph.relations.forEach(r => {
-            connectedEntityNames.add(r.from);
-            connectedEntityNames.add(r.to);
+            neighbors.get(r.from)?.add(r.to);
+            neighbors.get(r.to)?.add(r.from);
         });
-        return graph.entities.filter(e => !connectedEntityNames.has(e.name));
+        // BFS from Self to find all connected entities
+        const connectedToSelf = new Set();
+        const queue = ['Self'];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (connectedToSelf.has(current))
+                continue;
+            connectedToSelf.add(current);
+            const currentNeighbors = neighbors.get(current);
+            if (currentNeighbors) {
+                for (const neighbor of currentNeighbors) {
+                    if (!connectedToSelf.has(neighbor)) {
+                        queue.push(neighbor);
+                    }
+                }
+            }
+        }
+        // Return entities not connected to Self (excluding Self itself if it exists)
+        return graph.entities.filter(e => !connectedToSelf.has(e.name));
     }
     async validateGraph() {
         const graph = await this.loadGraph();
@@ -596,9 +627,9 @@ export class KnowledgeGraphManager {
                     throw new Error(`Observation exceeds 140 characters (${obs.length} chars): "${obs.substring(0, 50)}..."`);
                 }
             }
-            // Generate new context ID
+            // Generate new context ID (24-char hex)
             const now = Date.now();
-            const ctxId = `thought_${now}_${Math.random().toString(36).substring(2, 8)}`;
+            const ctxId = randomBytes(12).toString('hex');
             // Create thought entity
             const thoughtEntity = {
                 name: ctxId,
@@ -897,10 +928,11 @@ export function createServer(memoryFilePath) {
                 },
                 {
                     name: "get_orphaned_entities",
-                    description: "Get entities that have no relations (orphaned entities). Results are paginated (max 512 chars).",
+                    description: "Get entities that have no relations (orphaned entities). In strict mode, returns entities not connected to 'Self' entity. Results are paginated (max 512 chars).",
                     inputSchema: {
                         type: "object",
                         properties: {
+                            strict: { type: "boolean", description: "If true, returns entities not connected to 'Self' (directly or indirectly). Default: false" },
                             cursor: { type: "number", description: "Cursor for pagination" },
                         },
                     },
@@ -1024,7 +1056,7 @@ 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();
+                const entities = await knowledgeGraphManager.getOrphanedEntities(args.strict ?? false);
                 return { content: [{ type: "text", text: JSON.stringify(paginateItems(entities, args.cursor ?? 0)) }] };
             }
             case "validate_graph":

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

@@ -441,6 +441,32 @@ describe('MCP Memory Server E2E Tests', () => {
             expect(result.items).toHaveLength(1);
             expect(result.items[0].name).toBe('Orphan');
         });
+        it('should find entities not connected to Self in strict mode', async () => {
+            await callTool(client, 'create_entities', {
+                entities: [
+                    { name: 'Self', entityType: 'Agent', observations: [] },
+                    { name: 'ConnectedToSelf', entityType: 'Node', observations: [] },
+                    { name: 'IndirectlyConnected', entityType: 'Node', observations: [] },
+                    { name: 'Island1', entityType: 'Node', observations: [] },
+                    { name: 'Island2', entityType: 'Node', observations: [] }
+                ]
+            });
+            await callTool(client, 'create_relations', {
+                relations: [
+                    { from: 'Self', to: 'ConnectedToSelf', relationType: 'knows' },
+                    { from: 'ConnectedToSelf', to: 'IndirectlyConnected', relationType: 'links' },
+                    { from: 'Island1', to: 'Island2', relationType: 'links' } // Connected to each other but not to Self
+                ]
+            });
+            // Non-strict: Island1 and Island2 are connected, so not orphaned
+            const nonStrict = await callTool(client, 'get_orphaned_entities', {});
+            expect(nonStrict.items).toHaveLength(0);
+            // Strict: Island1 and Island2 are not connected to Self
+            const strict = await callTool(client, 'get_orphaned_entities', { strict: true });
+            expect(strict.items).toHaveLength(2);
+            const names = strict.items.map(e => e.name).sort();
+            expect(names).toEqual(['Island1', 'Island2']);
+        });
         it('should validate graph and report violations', async () => {
             // Directly write invalid data to test validation
             const invalidData = [
@@ -486,7 +512,7 @@ describe('MCP Memory Server E2E Tests', () => {
             const result = await callTool(client, 'sequentialthinking', {
                 observations: ['First thought observation']
             });
-            expect(result.ctxId).toMatch(/^thought_\d+_[a-z0-9]+$/);
+            expect(result.ctxId).toMatch(/^[0-9a-f]{24}$/);
         });
         it('should chain thoughts with relations', async () => {
             // Create first thought
@@ -511,7 +537,7 @@ describe('MCP Memory Server E2E Tests', () => {
                 previousCtxId: 'nonexistent_thought',
                 observations: ['Orphaned thought']
             });
-            expect(result.ctxId).toMatch(/^thought_\d+_[a-z0-9]+$/);
+            expect(result.ctxId).toMatch(/^[0-9a-f]{24}$/);
             // Verify no relations were created
             const neighbors = await callTool(client, 'get_neighbors', {
                 entityName: result.ctxId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levalicious/server-memory",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "MCP server for enabling memory for Claude through a knowledge graph",
   "license": "MIT",
   "author": "Levalicious",