@levalicious/server-memory 0.0.7 → 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';
@@ -13,6 +14,83 @@ 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;
+export const MAX_CHARS = 2048;
+function paginateItems(items, cursor = 0, maxChars = MAX_CHARS) {
+    const result = [];
+    let i = cursor;
+    // Calculate overhead for wrapper: {"items":[],"nextCursor":null,"totalCount":123}
+    const wrapperTemplate = { items: [], nextCursor: null, totalCount: items.length };
+    let overhead = JSON.stringify(wrapperTemplate).length;
+    let charCount = overhead;
+    while (i < items.length) {
+        const itemJson = JSON.stringify(items[i]);
+        const addedChars = itemJson.length + (result.length > 0 ? 1 : 0); // +1 for comma
+        if (charCount + addedChars > maxChars) {
+            break;
+        }
+        result.push(items[i]);
+        charCount += addedChars;
+        i++;
+    }
+    // Update nextCursor - recalculate if we stopped early (cursor digits may differ from null)
+    const nextCursor = i < items.length ? i : null;
+    return {
+        items: result,
+        nextCursor,
+        totalCount: items.length
+    };
+}
+function paginateGraph(graph, entityCursor = 0, relationCursor = 0) {
+    // Build incrementally, measuring actual serialized size
+    const entityCount = graph.entities.length;
+    const relationCount = graph.relations.length;
+    // Start with empty result to measure base overhead
+    const emptyResult = {
+        entities: { items: [], nextCursor: null, totalCount: entityCount },
+        relations: { items: [], nextCursor: null, totalCount: relationCount }
+    };
+    let currentSize = JSON.stringify(emptyResult).length;
+    const resultEntities = [];
+    const resultRelations = [];
+    let entityIdx = entityCursor;
+    let relationIdx = relationCursor;
+    // Add entities until we hit the limit
+    while (entityIdx < graph.entities.length) {
+        const entity = graph.entities[entityIdx];
+        const entityJson = JSON.stringify(entity);
+        const addedChars = entityJson.length + (resultEntities.length > 0 ? 1 : 0);
+        if (currentSize + addedChars > MAX_CHARS) {
+            break;
+        }
+        resultEntities.push(entity);
+        currentSize += addedChars;
+        entityIdx++;
+    }
+    // Add relations with remaining space
+    while (relationIdx < graph.relations.length) {
+        const relation = graph.relations[relationIdx];
+        const relationJson = JSON.stringify(relation);
+        const addedChars = relationJson.length + (resultRelations.length > 0 ? 1 : 0);
+        if (currentSize + addedChars > MAX_CHARS) {
+            break;
+        }
+        resultRelations.push(relation);
+        currentSize += addedChars;
+        relationIdx++;
+    }
+    return {
+        entities: {
+            items: resultEntities,
+            nextCursor: entityIdx < graph.entities.length ? entityIdx : null,
+            totalCount: entityCount
+        },
+        relations: {
+            items: resultRelations,
+            nextCursor: relationIdx < graph.relations.length ? relationIdx : null,
+            totalCount: relationCount
+        }
+    };
+}
 // The KnowledgeGraphManager class contains all operations to interact with the knowledge graph
 export class KnowledgeGraphManager {
     bclCtr = 0;
@@ -79,7 +157,10 @@ export class KnowledgeGraphManager {
                     }
                 }
             }
-            const newEntities = entities.filter(e => !graph.entities.some(existingEntity => existingEntity.name === e.name));
+            const now = Date.now();
+            const newEntities = entities
+                .filter(e => !graph.entities.some(existingEntity => existingEntity.name === e.name))
+                .map(e => ({ ...e, mtime: now, obsMtime: e.observations.length > 0 ? now : undefined }));
             graph.entities.push(...newEntities);
             await this.saveGraph(graph);
             return newEntities;
@@ -88,9 +169,19 @@ export class KnowledgeGraphManager {
     async createRelations(relations) {
         return this.withLock(async () => {
             const graph = await this.loadGraph();
-            const newRelations = relations.filter(r => !graph.relations.some(existingRelation => existingRelation.from === r.from &&
+            const now = Date.now();
+            // Update mtime on 'from' entities when relations are added
+            const fromEntityNames = new Set(relations.map(r => r.from));
+            graph.entities.forEach(e => {
+                if (fromEntityNames.has(e.name)) {
+                    e.mtime = now;
+                }
+            });
+            const newRelations = relations
+                .filter(r => !graph.relations.some(existingRelation => existingRelation.from === r.from &&
                 existingRelation.to === r.to &&
-                existingRelation.relationType === r.relationType));
+                existingRelation.relationType === r.relationType))
+                .map(r => ({ ...r, mtime: now }));
             graph.relations.push(...newRelations);
             await this.saveGraph(graph);
             return newRelations;
@@ -116,6 +207,11 @@ export class KnowledgeGraphManager {
                     throw new Error(`Adding ${newObservations.length} observations to "${o.entityName}" would exceed limit of 2 (currently has ${entity.observations.length}).`);
                 }
                 entity.observations.push(...newObservations);
+                if (newObservations.length > 0) {
+                    const now = Date.now();
+                    entity.mtime = now;
+                    entity.obsMtime = now;
+                }
                 return { entityName: o.entityName, addedObservations: newObservations };
             });
             await this.saveGraph(graph);
@@ -133,10 +229,16 @@ export class KnowledgeGraphManager {
     async deleteObservations(deletions) {
         return this.withLock(async () => {
             const graph = await this.loadGraph();
+            const now = Date.now();
             deletions.forEach(d => {
                 const entity = graph.entities.find(e => e.name === d.entityName);
                 if (entity) {
+                    const originalLen = entity.observations.length;
                     entity.observations = entity.observations.filter(o => !d.observations.includes(o));
+                    if (entity.observations.length !== originalLen) {
+                        entity.mtime = now;
+                        entity.obsMtime = now;
+                    }
                 }
             });
             await this.saveGraph(graph);
@@ -281,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();
@@ -483,6 +615,44 @@ export class KnowledgeGraphManager {
         this.bclCtr = 0;
         this.bclTerm = "";
     }
+    async addThought(observations, previousCtxId) {
+        return this.withLock(async () => {
+            const graph = await this.loadGraph();
+            // Validate observations
+            if (observations.length > 2) {
+                throw new Error(`Thought has ${observations.length} observations. Maximum allowed is 2.`);
+            }
+            for (const obs of observations) {
+                if (obs.length > 140) {
+                    throw new Error(`Observation exceeds 140 characters (${obs.length} chars): "${obs.substring(0, 50)}..."`);
+                }
+            }
+            // Generate new context ID (24-char hex)
+            const now = Date.now();
+            const ctxId = randomBytes(12).toString('hex');
+            // Create thought entity
+            const thoughtEntity = {
+                name: ctxId,
+                entityType: "Thought",
+                observations,
+                mtime: now,
+                obsMtime: observations.length > 0 ? now : undefined,
+            };
+            graph.entities.push(thoughtEntity);
+            // Link to previous thought if it exists
+            if (previousCtxId) {
+                const prevEntity = graph.entities.find(e => e.name === previousCtxId);
+                if (prevEntity) {
+                    // Update mtime on previous entity since we're adding a relation from it
+                    prevEntity.mtime = now;
+                    // Bidirectional chain: previous -> new (follows) and new -> previous (preceded_by)
+                    graph.relations.push({ from: previousCtxId, to: ctxId, relationType: "follows", mtime: now }, { from: ctxId, to: previousCtxId, relationType: "preceded_by", mtime: now });
+                }
+            }
+            await this.saveGraph(graph);
+            return { ctxId };
+        });
+    }
 }
 /**
  * Creates a configured MCP server instance with all tools registered.
@@ -646,18 +816,20 @@ export function createServer(memoryFilePath) {
                 },
                 {
                     name: "search_nodes",
-                    description: "Search for nodes in the knowledge graph using a regex pattern",
+                    description: "Search for nodes in the knowledge graph using a regex pattern. Results are paginated (max 512 chars).",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            query: { type: "string", description: "Regex pattern to match against entity names, types, and observations. Use | for alternatives (e.g., 'Taranis|wheel'). Special regex characters must be escaped for literal matching." },
+                            query: { type: "string", description: "Regex pattern to match against entity names, types, and observations." },
+                            entityCursor: { type: "number", description: "Cursor for entity pagination (from previous response's nextCursor)" },
+                            relationCursor: { type: "number", description: "Cursor for relation pagination" },
                         },
                         required: ["query"],
                     },
                 },
                 {
                     name: "open_nodes_filtered",
-                    description: "Open specific nodes in the knowledge graph by their names, filtering relations to only those between the opened nodes",
+                    description: "Open specific nodes in the knowledge graph by their names, filtering relations to only those between the opened nodes. Results are paginated (max 512 chars).",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -666,13 +838,15 @@ export function createServer(memoryFilePath) {
                                 items: { type: "string" },
                                 description: "An array of entity names to retrieve",
                             },
+                            entityCursor: { type: "number", description: "Cursor for entity pagination" },
+                            relationCursor: { type: "number", description: "Cursor for relation pagination" },
                         },
                         required: ["names"],
                     },
                 },
                 {
                     name: "open_nodes",
-                    description: "Open specific nodes in the knowledge graph by their names",
+                    description: "Open specific nodes in the knowledge graph by their names. Results are paginated (max 512 chars).",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -681,43 +855,49 @@ export function createServer(memoryFilePath) {
                                 items: { type: "string" },
                                 description: "An array of entity names to retrieve",
                             },
+                            entityCursor: { type: "number", description: "Cursor for entity pagination" },
+                            relationCursor: { type: "number", description: "Cursor for relation pagination" },
                         },
                         required: ["names"],
                     },
                 },
                 {
                     name: "get_neighbors",
-                    description: "Get neighboring entities connected to a specific entity within a given depth",
+                    description: "Get neighboring entities connected to a specific entity within a given depth. 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" },
                         },
                         required: ["entityName"],
                     },
                 },
                 {
                     name: "find_path",
-                    description: "Find a path between two entities in the knowledge graph",
+                    description: "Find a path between two entities in the knowledge graph. Results are paginated (max 512 chars).",
                     inputSchema: {
                         type: "object",
                         properties: {
                             fromEntity: { type: "string", description: "The name of the starting entity" },
                             toEntity: { type: "string", description: "The name of the target entity" },
                             maxDepth: { type: "number", description: "Maximum depth to search (default: 5)", default: 5 },
+                            cursor: { type: "number", description: "Cursor for pagination" },
                         },
                         required: ["fromEntity", "toEntity"],
                     },
                 },
                 {
                     name: "get_entities_by_type",
-                    description: "Get all entities of a specific type",
+                    description: "Get all entities of a specific type. Results are paginated (max 512 chars).",
                     inputSchema: {
                         type: "object",
                         properties: {
                             entityType: { type: "string", description: "The type of entities to retrieve" },
+                            cursor: { type: "number", description: "Cursor for pagination" },
                         },
                         required: ["entityType"],
                     },
@@ -748,10 +928,13 @@ export function createServer(memoryFilePath) {
                 },
                 {
                     name: "get_orphaned_entities",
-                    description: "Get entities that have no relations (orphaned entities)",
+                    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: {},
+                        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" },
+                        },
                     },
                 },
                 {
@@ -796,6 +979,28 @@ export function createServer(memoryFilePath) {
                         properties: {},
                     },
                 },
+                {
+                    name: "sequentialthinking",
+                    description: `Record a thought in the knowledge graph. Creates a Thought entity with observations and links it to the previous thought if provided. Returns the new thought's context ID for chaining.
+
+Use this to build chains of reasoning that persist in the graph. Each thought can have up to 2 observations (max 140 chars each).`,
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            previousCtxId: {
+                                type: "string",
+                                description: "Context ID of the previous thought to chain from. Omit for first thought in a chain."
+                            },
+                            observations: {
+                                type: "array",
+                                items: { type: "string", maxLength: 140 },
+                                maxItems: 2,
+                                description: "Observations for this thought (max 2, each max 140 chars)"
+                            },
+                        },
+                        required: ["observations"],
+                    },
+                },
             ],
         };
     });
@@ -820,26 +1025,40 @@ export function createServer(memoryFilePath) {
             case "delete_relations":
                 await knowledgeGraphManager.deleteRelations(args.relations);
                 return { content: [{ type: "text", text: "Relations deleted successfully" }] };
-            case "search_nodes":
-                return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.searchNodes(args.query), null, 2) }] };
-            case "open_nodes_filtered":
-                return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.openNodesFiltered(args.names), null, 2) }] };
-            case "open_nodes":
-                return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.openNodes(args.names), null, 2) }] };
-            case "get_neighbors":
-                return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.getNeighbors(args.entityName, args.depth, args.withEntities), null, 2) }] };
-            case "find_path":
-                return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.findPath(args.fromEntity, args.toEntity, args.maxDepth), null, 2) }] };
-            case "get_entities_by_type":
-                return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.getEntitiesByType(args.entityType), null, 2) }] };
+            case "search_nodes": {
+                const graph = await knowledgeGraphManager.searchNodes(args.query);
+                return { content: [{ type: "text", text: JSON.stringify(paginateGraph(graph, args.entityCursor ?? 0, args.relationCursor ?? 0)) }] };
+            }
+            case "open_nodes_filtered": {
+                const graph = await knowledgeGraphManager.openNodesFiltered(args.names);
+                return { content: [{ type: "text", text: JSON.stringify(paginateGraph(graph, args.entityCursor ?? 0, args.relationCursor ?? 0)) }] };
+            }
+            case "open_nodes": {
+                const graph = await knowledgeGraphManager.openNodes(args.names);
+                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)) }] };
+            }
+            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);
+                return { content: [{ type: "text", text: JSON.stringify(paginateItems(entities, args.cursor ?? 0)) }] };
+            }
             case "get_entity_types":
                 return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.getEntityTypes(), null, 2) }] };
             case "get_relation_types":
                 return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.getRelationTypes(), null, 2) }] };
             case "get_stats":
                 return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.getStats(), null, 2) }] };
-            case "get_orphaned_entities":
-                return { content: [{ type: "text", text: JSON.stringify(await knowledgeGraphManager.getOrphanedEntities(), null, 2) }] };
+            case "get_orphaned_entities": {
+                const entities = await knowledgeGraphManager.getOrphanedEntities(args.strict ?? false);
+                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":
@@ -849,6 +1068,10 @@ export function createServer(memoryFilePath) {
             case "clear_bcl_term":
                 await knowledgeGraphManager.clearBCLTerm();
                 return { content: [{ type: "text", text: "BCL term constructor cleared successfully" }] };
+            case "sequentialthinking": {
+                const result = await knowledgeGraphManager.addThought(args.observations, args.previousCtxId);
+                return { content: [{ type: "text", text: JSON.stringify(result) }] };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

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

@@ -129,7 +129,7 @@ describe('MCP Memory Server E2E Tests', () => {
                 deletions: [{ entityName: 'TestEntity', observations: ['Delete'] }]
             });
             const result = await callTool(client, 'open_nodes', { names: ['TestEntity'] });
-            expect(result.entities[0].observations).toEqual(['Keep']);
+            expect(result.entities.items[0].observations).toEqual(['Keep']);
         });
     });
     describe('Relation Operations', () => {
@@ -192,25 +192,41 @@ describe('MCP Memory Server E2E Tests', () => {
             });
         });
         it('should search by regex pattern', async () => {
-            const result = await callTool(client, 'search_nodes', {
-                query: 'Script'
-            });
-            expect(result.entities).toHaveLength(2);
-            expect(result.entities.map(e => e.name)).toContain('JavaScript');
-            expect(result.entities.map(e => e.name)).toContain('TypeScript');
+            // Accumulate all entities across pagination
+            const allEntities = [];
+            let entityCursor = 0;
+            while (entityCursor !== null) {
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Script',
+                    entityCursor
+                });
+                allEntities.push(...result.entities.items);
+                entityCursor = result.entities.nextCursor;
+            }
+            expect(allEntities).toHaveLength(2);
+            expect(allEntities.map(e => e.name)).toContain('JavaScript');
+            expect(allEntities.map(e => e.name)).toContain('TypeScript');
         });
         it('should search with alternation', async () => {
-            const result = await callTool(client, 'search_nodes', {
-                query: 'JavaScript|Python'
-            });
-            expect(result.entities).toHaveLength(2);
+            // Accumulate all entities across pagination
+            const allEntities = [];
+            let entityCursor = 0;
+            while (entityCursor !== null) {
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'JavaScript|Python',
+                    entityCursor
+                });
+                allEntities.push(...result.entities.items);
+                entityCursor = result.entities.nextCursor;
+            }
+            expect(allEntities).toHaveLength(2);
         });
         it('should search in observations', async () => {
             const result = await callTool(client, 'search_nodes', {
                 query: 'Static'
             });
-            expect(result.entities).toHaveLength(1);
-            expect(result.entities[0].name).toBe('TypeScript');
+            expect(result.entities.items).toHaveLength(1);
+            expect(result.entities.items[0].name).toBe('TypeScript');
         });
         it('should reject invalid regex', async () => {
             await expect(callTool(client, 'search_nodes', { query: '[invalid' })).rejects.toThrow(/Invalid regex pattern/);
@@ -236,17 +252,17 @@ describe('MCP Memory Server E2E Tests', () => {
             const result = await callTool(client, 'open_nodes', {
                 names: ['A', 'B']
             });
-            expect(result.entities).toHaveLength(2);
+            expect(result.entities.items).toHaveLength(2);
             // open_nodes returns all relations where 'from' is in the requested set
             // A->B and A->C both have from='A' which is in the set
-            expect(result.relations).toHaveLength(2);
+            expect(result.relations.items).toHaveLength(2);
         });
         it('should open nodes filtered (only internal relations)', async () => {
             const result = await callTool(client, 'open_nodes_filtered', {
                 names: ['B', 'C']
             });
-            expect(result.entities).toHaveLength(2);
-            expect(result.relations).toHaveLength(0); // No relations between B and C
+            expect(result.entities.items).toHaveLength(2);
+            expect(result.relations.items).toHaveLength(0); // No relations between B and C
         });
     });
     describe('Graph Traversal', () => {
@@ -272,27 +288,57 @@ describe('MCP Memory Server E2E Tests', () => {
                 entityName: 'Root',
                 depth: 0
             });
-            expect(result.entities).toHaveLength(0); // withEntities defaults to false
-            expect(result.relations).toHaveLength(2); // Root's direct relations
+            expect(result.entities.items).toHaveLength(0); // withEntities defaults to false
+            expect(result.relations.items).toHaveLength(2); // Root's direct relations
         });
         it('should get neighbors with entities when requested', async () => {
-            const result = await callTool(client, 'get_neighbors', {
-                entityName: 'Root',
-                depth: 1,
-                withEntities: true
-            });
-            expect(result.entities.map(e => e.name)).toContain('Root');
-            expect(result.entities.map(e => e.name)).toContain('Child1');
-            expect(result.entities.map(e => e.name)).toContain('Child2');
+            // 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 traverse to specified depth', async () => {
-            const result = await callTool(client, 'get_neighbors', {
-                entityName: 'Root',
-                depth: 2,
-                withEntities: true
-            });
-            expect(result.entities).toHaveLength(4); // All nodes
-            expect(result.relations).toHaveLength(3); // All relations
+            // 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
         });
         it('should deduplicate relations in traversal', async () => {
             // Add a bidirectional relation
@@ -304,7 +350,7 @@ describe('MCP Memory Server E2E Tests', () => {
                 depth: 1
             });
             // Each unique relation should appear only once
-            const relationKeys = result.relations.map(r => `${r.from}|${r.relationType}|${r.to}`);
+            const relationKeys = result.relations.items.map(r => `${r.from}|${r.relationType}|${r.to}`);
             const uniqueKeys = [...new Set(relationKeys)];
             expect(relationKeys.length).toBe(uniqueKeys.length);
         });
@@ -313,9 +359,9 @@ describe('MCP Memory Server E2E Tests', () => {
                 fromEntity: 'Root',
                 toEntity: 'Grandchild'
             });
-            expect(result).toHaveLength(2);
-            expect(result[0].from).toBe('Root');
-            expect(result[1].to).toBe('Grandchild');
+            expect(result.items).toHaveLength(2);
+            expect(result.items[0].from).toBe('Root');
+            expect(result.items[1].to).toBe('Grandchild');
         });
         it('should return empty path when no path exists', async () => {
             await callTool(client, 'create_entities', {
@@ -325,7 +371,7 @@ describe('MCP Memory Server E2E Tests', () => {
                 fromEntity: 'Root',
                 toEntity: 'Isolated'
             });
-            expect(result).toHaveLength(0);
+            expect(result.items).toHaveLength(0);
         });
     });
     describe('Type Queries', () => {
@@ -348,8 +394,8 @@ describe('MCP Memory Server E2E Tests', () => {
             const result = await callTool(client, 'get_entities_by_type', {
                 entityType: 'Person'
             });
-            expect(result).toHaveLength(2);
-            expect(result.every(e => e.entityType === 'Person')).toBe(true);
+            expect(result.items).toHaveLength(2);
+            expect(result.items.every(e => e.entityType === 'Person')).toBe(true);
         });
         it('should get all entity types', async () => {
             const result = await callTool(client, 'get_entity_types', {});
@@ -392,8 +438,34 @@ describe('MCP Memory Server E2E Tests', () => {
                 relations: [{ from: 'Connected1', to: 'Connected2', relationType: 'links' }]
             });
             const result = await callTool(client, 'get_orphaned_entities', {});
-            expect(result).toHaveLength(1);
-            expect(result[0].name).toBe('Orphan');
+            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
@@ -435,4 +507,59 @@ describe('MCP Memory Server E2E Tests', () => {
             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', {
+                observations: ['First thought observation']
+            });
+            expect(result.ctxId).toMatch(/^[0-9a-f]{24}$/);
+        });
+        it('should chain thoughts with relations', async () => {
+            // Create first thought
+            const first = await callTool(client, 'sequentialthinking', {
+                observations: ['Starting point']
+            });
+            // Create second thought chained to first
+            const second = await callTool(client, 'sequentialthinking', {
+                previousCtxId: first.ctxId,
+                observations: ['Following up']
+            });
+            // Verify the chain via relations
+            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);
+        });
+        it('should ignore invalid previousCtxId gracefully', async () => {
+            const result = await callTool(client, 'sequentialthinking', {
+                previousCtxId: 'nonexistent_thought',
+                observations: ['Orphaned thought']
+            });
+            expect(result.ctxId).toMatch(/^[0-9a-f]{24}$/);
+            // Verify no relations were created
+            const neighbors = await callTool(client, 'get_neighbors', {
+                entityName: result.ctxId,
+                depth: 1
+            });
+            expect(neighbors.relations.totalCount).toBe(0);
+        });
+        it('should enforce observation limits on thoughts', async () => {
+            await expect(callTool(client, 'sequentialthinking', {
+                observations: ['One', 'Two', 'Three']
+            })).rejects.toThrow(/Maximum allowed is 2/);
+        });
+        it('should set mtime and obsMtime on thought entities', async () => {
+            const result = await callTool(client, 'sequentialthinking', {
+                observations: ['Timed thought']
+            });
+            const graph = await callTool(client, 'open_nodes', {
+                names: [result.ctxId]
+            });
+            const thought = graph.entities.items[0];
+            expect(thought.mtime).toBeDefined();
+            expect(thought.obsMtime).toBeDefined();
+        });
+    });
 });

package/dist/tests/test-utils.js

@@ -1,5 +1,7 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { MAX_CHARS } from "../server.js";
+export { MAX_CHARS };
 export async function createTestClient(server) {
     const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
     const client = new Client({
@@ -18,6 +20,16 @@ export async function createTestClient(server) {
         }
     };
 }
+// Read operations that should be paginated
+const PAGINATED_TOOLS = new Set([
+    'search_nodes',
+    'open_nodes',
+    'open_nodes_filtered',
+    'get_neighbors',
+    'find_path',
+    'get_entities_by_type',
+    'get_orphaned_entities',
+]);
 export async function callTool(client, name, args) {
     const result = await client.callTool({ name, arguments: args });
     const content = result.content;
@@ -26,6 +38,10 @@ export async function callTool(client, name, args) {
     }
     const first = content[0];
     if (first.type === 'text' && first.text) {
+        // Only enforce char limit on paginated read operations
+        if (PAGINATED_TOOLS.has(name) && first.text.length > MAX_CHARS) {
+            throw new Error(`Response exceeds ${MAX_CHARS} char limit: got ${first.text.length} chars`);
+        }
         try {
             return JSON.parse(first.text);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levalicious/server-memory",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "MCP server for enabling memory for Claude through a knowledge graph",
   "license": "MIT",
   "author": "Levalicious",
@@ -20,7 +20,7 @@
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.22.0",
+    "@modelcontextprotocol/sdk": "1.24.0",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {