server-memory-enhanced 3.0.0 → 3.1.0

package/dist/index.js

@@ -6,7 +6,7 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { KnowledgeGraphManager } from './lib/knowledge-graph-manager.js';
-import { EntitySchema, RelationSchema, SaveMemoryInputSchema, SaveMemoryOutputSchema, GetAnalyticsInputSchema, GetAnalyticsOutputSchema, GetObservationHistoryInputSchema, GetObservationHistoryOutputSchema, ListEntitiesInputSchema, ListEntitiesOutputSchema, ValidateMemoryInputSchema, ValidateMemoryOutputSchema, UpdateObservationInputSchema, UpdateObservationOutputSchema, ReadGraphInputSchema, SearchNodesInputSchema, OpenNodesInputSchema, QueryNodesInputSchema, GetMemoryStatsInputSchema, GetRecentChangesInputSchema, FindRelationPathInputSchema, DetectConflictsInputSchema, GetFlaggedEntitiesInputSchema, GetContextInputSchema } from './lib/schemas.js';
+import { EntitySchema, RelationSchema, SaveMemoryInputSchema, SaveMemoryOutputSchema, GetAnalyticsInputSchema, GetAnalyticsOutputSchema, GetObservationHistoryInputSchema, GetObservationHistoryOutputSchema, ListEntitiesInputSchema, ListEntitiesOutputSchema, ValidateMemoryInputSchema, ValidateMemoryOutputSchema, UpdateObservationInputSchema, UpdateObservationOutputSchema, ReadGraphInputSchema, SearchNodesInputSchema, OpenNodesInputSchema, QueryNodesInputSchema, GetMemoryStatsInputSchema, GetRecentChangesInputSchema, FindRelationPathInputSchema, DetectConflictsInputSchema, GetFlaggedEntitiesInputSchema, GetContextInputSchema, CreateEntitiesInputSchema, CreateRelationsInputSchema, AddObservationsInputSchema, DeleteEntitiesInputSchema, DeleteObservationsInputSchema, DeleteRelationsInputSchema, PruneMemoryInputSchema, BulkUpdateInputSchema, FlagForReviewInputSchema } from './lib/schemas.js';
 import { handleSaveMemory } from './lib/save-memory-handler.js';
 import { validateSaveMemoryRequest } from './lib/validation.js';
 import { JsonlStorageAdapter } from './lib/jsonl-storage-adapter.js';
@@ -115,7 +115,7 @@ server.registerTool("save_memory", {
     inputSchema: SaveMemoryInputSchema,
     outputSchema: SaveMemoryOutputSchema
 }, async (input) => {
-    const result = await handleSaveMemory(input, (entities) => knowledgeGraphManager.createEntities(entities), (relations) => knowledgeGraphManager.createRelations(relations), (threadId) => knowledgeGraphManager.getEntityNamesInThread(threadId));
+    const result = await handleSaveMemory(input, (threadId, entities) => knowledgeGraphManager.createEntities(threadId, entities), (threadId, relations) => knowledgeGraphManager.createRelations(threadId, relations), (threadId) => knowledgeGraphManager.getEntityNamesInThread(threadId));
     if (result.success) {
         // Build success message with entity names
         let successText = `✓ Successfully saved ${result.created.entities} entities and ${result.created.relations} relations.\n` +
@@ -171,14 +171,13 @@ server.registerTool("save_memory", {
 server.registerTool("create_entities", {
     title: "Create Entities",
     description: "Create multiple new entities in the knowledge graph with metadata (agent thread ID, timestamp, confidence, importance)",
-    inputSchema: {
-        entities: z.array(EntitySchemaCompat)
-    },
+    inputSchema: CreateEntitiesInputSchema,
     outputSchema: {
         entities: z.array(EntitySchemaCompat)
     }
-}, async ({ entities }) => {
-    const result = await knowledgeGraphManager.createEntities(entities);
+}, async (input) => {
+    const { threadId, entities } = input;
+    const result = await knowledgeGraphManager.createEntities(threadId, entities);
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         structuredContent: { entities: result }
@@ -188,14 +187,13 @@ server.registerTool("create_entities", {
 server.registerTool("create_relations", {
     title: "Create Relations",
     description: "Create multiple new relations between entities in the knowledge graph with metadata (agent thread ID, timestamp, confidence, importance). Relations should be in active voice",
-    inputSchema: {
-        relations: z.array(RelationSchemaCompat)
-    },
+    inputSchema: CreateRelationsInputSchema,
     outputSchema: {
         relations: z.array(RelationSchemaCompat)
     }
-}, async ({ relations }) => {
-    const result = await knowledgeGraphManager.createRelations(relations);
+}, async (input) => {
+    const { threadId, relations } = input;
+    const result = await knowledgeGraphManager.createRelations(threadId, relations);
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         structuredContent: { relations: result }
@@ -205,24 +203,16 @@ server.registerTool("create_relations", {
 server.registerTool("add_observations", {
     title: "Add Observations",
     description: "Add new observations to existing entities in the knowledge graph with metadata (agent thread ID, timestamp, confidence, importance)",
-    inputSchema: {
-        observations: z.array(z.object({
-            entityName: z.string().describe("The name of the entity to add the observations to"),
-            contents: z.array(z.string()).describe("An array of observation contents to add"),
-            agentThreadId: z.string().describe("The agent thread ID adding these observations"),
-            timestamp: z.string().describe("ISO 8601 timestamp of when the observations are added"),
-            confidence: z.number().min(0).max(1).describe("Confidence coefficient from 0 to 1"),
-            importance: z.number().min(0).max(1).describe("Importance for memory integrity if lost: 0 (not important) to 1 (critical)")
-        }))
-    },
+    inputSchema: AddObservationsInputSchema,
     outputSchema: {
         results: z.array(z.object({
             entityName: z.string(),
             addedObservations: z.array(z.string())
         }))
     }
-}, async ({ observations }) => {
-    const result = await knowledgeGraphManager.addObservations(observations);
+}, async (input) => {
+    const { threadId, observations } = input;
+    const result = await knowledgeGraphManager.addObservations(threadId, observations);
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         structuredContent: { results: result }
@@ -232,15 +222,14 @@ server.registerTool("add_observations", {
 server.registerTool("delete_entities", {
     title: "Delete Entities",
     description: "Delete multiple entities and their associated relations from the knowledge graph",
-    inputSchema: {
-        entityNames: z.array(z.string()).describe("An array of entity names to delete")
-    },
+    inputSchema: DeleteEntitiesInputSchema,
     outputSchema: {
         success: z.boolean(),
         message: z.string()
     }
-}, async ({ entityNames }) => {
-    await knowledgeGraphManager.deleteEntities(entityNames);
+}, async (input) => {
+    const { threadId, entityNames } = input;
+    await knowledgeGraphManager.deleteEntities(threadId, entityNames);
     return {
         content: [{ type: "text", text: "Entities deleted successfully" }],
         structuredContent: { success: true, message: "Entities deleted successfully" }
@@ -250,18 +239,14 @@ server.registerTool("delete_entities", {
 server.registerTool("delete_observations", {
     title: "Delete Observations",
     description: "Delete specific observations from entities in the knowledge graph",
-    inputSchema: {
-        deletions: z.array(z.object({
-            entityName: z.string().describe("The name of the entity containing the observations"),
-            observations: z.array(z.string()).describe("An array of observations to delete")
-        }))
-    },
+    inputSchema: DeleteObservationsInputSchema,
     outputSchema: {
         success: z.boolean(),
         message: z.string()
     }
-}, async ({ deletions }) => {
-    await knowledgeGraphManager.deleteObservations(deletions);
+}, async (input) => {
+    const { threadId, deletions } = input;
+    await knowledgeGraphManager.deleteObservations(threadId, deletions);
     return {
         content: [{ type: "text", text: "Observations deleted successfully" }],
         structuredContent: { success: true, message: "Observations deleted successfully" }
@@ -273,7 +258,8 @@ server.registerTool("update_observation", {
     description: "Update an existing observation by creating a new version with updated content. This maintains version history through the supersedes/superseded_by chain.",
     inputSchema: UpdateObservationInputSchema.shape,
     outputSchema: UpdateObservationOutputSchema.shape
-}, async ({ entityName, observationId, newContent, agentThreadId, timestamp, confidence, importance }) => {
+}, async (input) => {
+    const { entityName, observationId, newContent, agentThreadId, timestamp, confidence, importance } = input;
     const updatedObservation = await knowledgeGraphManager.updateObservation({
         entityName,
         observationId,
@@ -297,15 +283,14 @@ server.registerTool("update_observation", {
 server.registerTool("delete_relations", {
     title: "Delete Relations",
     description: "Delete multiple relations from the knowledge graph",
-    inputSchema: {
-        relations: z.array(RelationSchemaCompat).describe("An array of relations to delete")
-    },
+    inputSchema: DeleteRelationsInputSchema,
     outputSchema: {
         success: z.boolean(),
         message: z.string()
     }
-}, async ({ relations }) => {
-    await knowledgeGraphManager.deleteRelations(relations);
+}, async (input) => {
+    const { threadId, relations } = input;
+    await knowledgeGraphManager.deleteRelations(threadId, relations);
     return {
         content: [{ type: "text", text: "Relations deleted successfully" }],
         structuredContent: { success: true, message: "Relations deleted successfully" }
@@ -592,17 +577,14 @@ server.registerTool("detect_conflicts", {
 server.registerTool("prune_memory", {
     title: "Prune Memory",
     description: "Remove old or low-importance entities to manage memory size, with option to keep minimum number of entities",
-    inputSchema: {
-        olderThan: z.string().optional().describe("ISO 8601 timestamp - remove entities older than this"),
-        importanceLessThan: z.number().min(0).max(1).optional().describe("Remove entities with importance less than this value"),
-        keepMinEntities: z.number().optional().describe("Minimum number of entities to keep regardless of filters")
-    },
+    inputSchema: PruneMemoryInputSchema,
     outputSchema: {
         removedEntities: z.number(),
         removedRelations: z.number()
     }
-}, async (options) => {
-    const result = await knowledgeGraphManager.pruneMemory(options);
+}, async (input) => {
+    const { threadId, ...options } = input;
+    const result = await knowledgeGraphManager.pruneMemory(threadId, options);
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         structuredContent: result
@@ -612,20 +594,14 @@ server.registerTool("prune_memory", {
 server.registerTool("bulk_update", {
     title: "Bulk Update",
     description: "Efficiently update multiple entities at once with new confidence, importance, or observations",
-    inputSchema: {
-        updates: z.array(z.object({
-            entityName: z.string(),
-            confidence: z.number().min(0).max(1).optional(),
-            importance: z.number().min(0).max(1).optional(),
-            addObservations: z.array(z.string()).optional()
-        }))
-    },
+    inputSchema: BulkUpdateInputSchema,
     outputSchema: {
         updated: z.number(),
         notFound: z.array(z.string())
     }
-}, async ({ updates }) => {
-    const result = await knowledgeGraphManager.bulkUpdate(updates);
+}, async (input) => {
+    const { threadId, updates } = input;
+    const result = await knowledgeGraphManager.bulkUpdate(threadId, updates);
     return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         structuredContent: result
@@ -635,17 +611,14 @@ server.registerTool("bulk_update", {
 server.registerTool("flag_for_review", {
     title: "Flag Entity for Review",
     description: "Mark an entity for human review with a specific reason (Human-in-the-Loop)",
-    inputSchema: {
-        entityName: z.string().describe("Name of entity to flag"),
-        reason: z.string().describe("Reason for flagging"),
-        reviewer: z.string().optional().describe("Optional reviewer name")
-    },
+    inputSchema: FlagForReviewInputSchema,
     outputSchema: {
         success: z.boolean(),
         message: z.string()
     }
-}, async ({ entityName, reason, reviewer }) => {
-    await knowledgeGraphManager.flagForReview(entityName, reason, reviewer);
+}, async (input) => {
+    const { threadId, entityName, reason, reviewer } = input;
+    await knowledgeGraphManager.flagForReview(threadId, entityName, reason, reviewer);
     return {
         content: [{ type: "text", text: `Entity "${entityName}" flagged for review` }],
         structuredContent: { success: true, message: `Entity "${entityName}" flagged for review` }

package/dist/lib/collaboration/flag-manager.js

@@ -4,12 +4,13 @@
 import { randomUUID } from 'crypto';
 /**
  * Flag an entity for review
+ * Thread isolation: Only flags entities in the specified thread
  */
-export async function flagForReview(storage, entityName, reason, reviewer) {
+export async function flagForReview(storage, threadId, entityName, reason, reviewer) {
     const graph = await storage.loadGraph();
-    const entity = graph.entities.find(e => e.name === entityName);
+    const entity = graph.entities.find(e => e.name === entityName && e.agentThreadId === threadId);
     if (!entity) {
-        throw new Error(`Entity with name ${entityName} not found`);
+        throw new Error(`Entity with name ${entityName} not found in thread ${threadId}`);
     }
     // Add a special observation to mark for review
     const flagContent = `[FLAGGED FOR REVIEW: ${reason}${reviewer ? ` - Reviewer: ${reviewer}` : ''}]`;

package/dist/lib/knowledge-graph-manager.js

@@ -43,31 +43,31 @@ export class KnowledgeGraphManager {
         await this.initializePromise;
     }
     // Entity Operations
-    async createEntities(entities) {
+    async createEntities(threadId, entities) {
         await this.ensureInitialized();
-        return EntityOps.createEntities(this.storage, entities);
+        return EntityOps.createEntities(this.storage, threadId, entities);
     }
-    async deleteEntities(entityNames) {
+    async deleteEntities(threadId, entityNames) {
         await this.ensureInitialized();
-        return EntityOps.deleteEntities(this.storage, entityNames);
+        return EntityOps.deleteEntities(this.storage, threadId, entityNames);
     }
     // Relation Operations
-    async createRelations(relations) {
+    async createRelations(threadId, relations) {
         await this.ensureInitialized();
-        return RelationOps.createRelations(this.storage, relations);
+        return RelationOps.createRelations(this.storage, threadId, relations);
     }
-    async deleteRelations(relations) {
+    async deleteRelations(threadId, relations) {
         await this.ensureInitialized();
-        return RelationOps.deleteRelations(this.storage, relations);
+        return RelationOps.deleteRelations(this.storage, threadId, relations);
     }
     // Observation Operations
-    async addObservations(observations) {
+    async addObservations(threadId, observations) {
         await this.ensureInitialized();
-        return ObservationOps.addObservations(this.storage, observations);
+        return ObservationOps.addObservations(this.storage, threadId, observations);
     }
-    async deleteObservations(deletions) {
+    async deleteObservations(threadId, deletions) {
         await this.ensureInitialized();
-        return ObservationOps.deleteObservations(this.storage, deletions);
+        return ObservationOps.deleteObservations(this.storage, threadId, deletions);
     }
     async updateObservation(params) {
         await this.ensureInitialized();
@@ -131,18 +131,18 @@ export class KnowledgeGraphManager {
         return AnalyticsService.getAnalytics(this.storage, threadId);
     }
     // Memory Maintenance
-    async pruneMemory(options) {
+    async pruneMemory(threadId, options) {
         await this.ensureInitialized();
-        return MemoryPruner.pruneMemory(this.storage, options);
+        return MemoryPruner.pruneMemory(this.storage, threadId, options);
     }
-    async bulkUpdate(updates) {
+    async bulkUpdate(threadId, updates) {
         await this.ensureInitialized();
-        return BulkUpdater.bulkUpdate(this.storage, updates);
+        return BulkUpdater.bulkUpdate(this.storage, threadId, updates);
     }
     // Collaboration Features
-    async flagForReview(entityName, reason, reviewer) {
+    async flagForReview(threadId, entityName, reason, reviewer) {
         await this.ensureInitialized();
-        return FlagManager.flagForReview(this.storage, entityName, reason, reviewer);
+        return FlagManager.flagForReview(this.storage, threadId, entityName, reason, reviewer);
     }
     async getFlaggedEntities(threadId) {
         await this.ensureInitialized();

package/dist/lib/maintenance/bulk-updater.js

@@ -4,13 +4,14 @@
 import { randomUUID } from 'crypto';
 /**
  * Perform bulk updates on multiple entities
+ * Thread isolation: Only updates entities in the specified thread
  */
-export async function bulkUpdate(storage, updates) {
+export async function bulkUpdate(storage, threadId, updates) {
     const graph = await storage.loadGraph();
     let updated = 0;
     const notFound = [];
     for (const update of updates) {
-        const entity = graph.entities.find(e => e.name === update.entityName);
+        const entity = graph.entities.find(e => e.name === update.entityName && e.agentThreadId === threadId);
         if (!entity) {
             notFound.push(update.entityName);
             continue;

package/dist/lib/maintenance/memory-pruner.js

@@ -3,13 +3,18 @@
  */
 /**
  * Prune memory based on age and importance criteria
+ * Thread isolation: Only prunes entities and relations in the specified thread
  */
-export async function pruneMemory(storage, options) {
+export async function pruneMemory(storage, threadId, options) {
     const graph = await storage.loadGraph();
-    const initialEntityCount = graph.entities.length;
-    const initialRelationCount = graph.relations.length;
-    // Filter entities to remove
-    let entitiesToKeep = graph.entities;
+    // Filter to only entities in the specified thread
+    const threadEntities = graph.entities.filter(e => e.agentThreadId === threadId);
+    const initialEntityCount = threadEntities.length;
+    // Count initial relations in the thread
+    const threadEntityNames = new Set(threadEntities.map(e => e.name));
+    const initialRelationCount = graph.relations.filter(r => r.agentThreadId === threadId && threadEntityNames.has(r.from) && threadEntityNames.has(r.to)).length;
+    // Filter entities to remove within the thread
+    let entitiesToKeep = threadEntities;
     if (options.olderThan) {
         const cutoffDate = new Date(options.olderThan);
         entitiesToKeep = entitiesToKeep.filter(e => new Date(e.timestamp) >= cutoffDate);
@@ -18,13 +23,13 @@ export async function pruneMemory(storage, options) {
         entitiesToKeep = entitiesToKeep.filter(e => e.importance >= options.importanceLessThan);
     }
     // Ensure we keep minimum entities
-    // If keepMinEntities is set and we need more entities, backfill from the original graph
+    // If keepMinEntities is set and we need more entities, backfill from the original thread entities
     // sorted by importance and recency
     if (options.keepMinEntities && entitiesToKeep.length < options.keepMinEntities) {
         const minToKeep = options.keepMinEntities;
         const alreadyKeptNames = new Set(entitiesToKeep.map(e => e.name));
-        // Candidates are entities from the original graph that are not already kept
-        const candidates = graph.entities
+        // Candidates are entities from the thread that are not already kept
+        const candidates = threadEntities
             .filter(e => !alreadyKeptNames.has(e.name))
             .sort((a, b) => {
             if (a.importance !== b.importance)
@@ -36,13 +41,17 @@ export async function pruneMemory(storage, options) {
         entitiesToKeep = [...entitiesToKeep, ...backfill];
     }
     const keptEntityNames = new Set(entitiesToKeep.map(e => e.name));
-    // Remove relations that reference removed entities
-    const relationsToKeep = graph.relations.filter(r => keptEntityNames.has(r.from) && keptEntityNames.has(r.to));
-    graph.entities = entitiesToKeep;
-    graph.relations = relationsToKeep;
+    const removedEntityNames = new Set(threadEntityNames);
+    keptEntityNames.forEach(name => removedEntityNames.delete(name));
+    // Update the main graph: remove entities from this thread that should be pruned
+    graph.entities = graph.entities.filter(e => e.agentThreadId !== threadId || keptEntityNames.has(e.name));
+    // Remove relations from this thread that reference removed entities
+    graph.relations = graph.relations.filter(r => !(r.agentThreadId === threadId && (removedEntityNames.has(r.from) || removedEntityNames.has(r.to))));
     await storage.saveGraph(graph);
+    // Count remaining relations in the thread after pruning
+    const finalRelationCount = graph.relations.filter(r => r.agentThreadId === threadId && keptEntityNames.has(r.from) && keptEntityNames.has(r.to)).length;
     return {
         removedEntities: initialEntityCount - entitiesToKeep.length,
-        removedRelations: initialRelationCount - relationsToKeep.length
+        removedRelations: initialRelationCount - finalRelationCount
     };
 }

package/dist/lib/operations/entity-operations.js

@@ -5,10 +5,12 @@
  * Create new entities in the knowledge graph
  * Entity names are globally unique across all threads in the collaborative knowledge graph
  * This prevents duplicate entities while allowing multiple threads to contribute to the same entity
+ * @param threadId - Thread ID passed for context (entities already have agentThreadId set)
  */
-export async function createEntities(storage, entities) {
+export async function createEntities(storage, threadId, entities) {
     const graph = await storage.loadGraph();
     const existingNames = new Set(graph.entities.map(e => e.name));
+    // Filter out entities that already exist, entities are expected to have agentThreadId already set
     const newEntities = entities.filter(e => !existingNames.has(e.name));
     graph.entities.push(...newEntities);
     await storage.saveGraph(graph);
@@ -17,11 +19,18 @@ export async function createEntities(storage, entities) {
 /**
  * Delete entities from the knowledge graph
  * Also removes all relations referencing the deleted entities
+ * Thread isolation: Only deletes entities that belong to the specified thread
  */
-export async function deleteEntities(storage, entityNames) {
+export async function deleteEntities(storage, threadId, entityNames) {
     const graph = await storage.loadGraph();
     const namesToDelete = new Set(entityNames);
-    graph.entities = graph.entities.filter(e => !namesToDelete.has(e.name));
-    graph.relations = graph.relations.filter(r => !namesToDelete.has(r.from) && !namesToDelete.has(r.to));
+    // Determine which entities will actually be deleted for this thread
+    const deletedEntityNames = new Set(graph.entities
+        .filter(e => namesToDelete.has(e.name) && e.agentThreadId === threadId)
+        .map(e => e.name));
+    // Delete entities that were identified for deletion
+    graph.entities = graph.entities.filter(e => !deletedEntityNames.has(e.name));
+    // Only delete relations that belong to the specified thread and reference actually deleted entities
+    graph.relations = graph.relations.filter(r => !(r.agentThreadId === threadId && (deletedEntityNames.has(r.from) || deletedEntityNames.has(r.to))));
     await storage.saveGraph(graph);
 }

package/dist/lib/operations/observation-operations.js

@@ -7,13 +7,15 @@ import { validateObservationNotSuperseded, createObservationVersion } from '../u
 /**
  * Add observations to entities
  * Checks for duplicate content and creates version chains when content is updated
+ * Thread parameter is used for validation to ensure only entities in the thread are modified
  */
-export async function addObservations(storage, observations) {
+export async function addObservations(storage, threadId, observations) {
     const graph = await storage.loadGraph();
     const results = observations.map(o => {
-        const entity = graph.entities.find(e => e.name === o.entityName);
+        // Find entity - thread validation happens here to ensure we only modify entities from this thread
+        const entity = graph.entities.find(e => e.name === o.entityName && e.agentThreadId === threadId);
         if (!entity) {
-            throw new Error(`Entity with name ${o.entityName} not found`);
+            throw new Error(`Entity with name ${o.entityName} not found in thread ${threadId}`);
         }
         // Check for existing observations with same content to create version chain
         const newObservations = [];
@@ -56,11 +58,13 @@ export async function addObservations(storage, observations) {
 /**
  * Delete observations from entities
  * Supports deletion by content (backward compatibility) or by ID
+ * Thread parameter is used for validation to ensure only entities in the thread are modified
  */
-export async function deleteObservations(storage, deletions) {
+export async function deleteObservations(storage, threadId, deletions) {
     const graph = await storage.loadGraph();
     deletions.forEach(d => {
-        const entity = graph.entities.find(e => e.name === d.entityName);
+        // Find entity - thread validation happens here to ensure we only modify entities from this thread
+        const entity = graph.entities.find(e => e.name === d.entityName && e.agentThreadId === threadId);
         if (entity) {
             // Delete observations by content (for backward compatibility) or by ID
             entity.observations = entity.observations.filter(o => !d.observations.includes(o.content) && !d.observations.includes(o.id));

package/dist/lib/operations/relation-operations.js

@@ -6,8 +6,9 @@ import { createRelationKey } from '../utils/relation-key.js';
  * Create new relations in the knowledge graph
  * Relations are globally unique by (from, to, relationType) across all threads
  * This enables multiple threads to collaboratively build the knowledge graph
+ * @param threadId - Thread ID passed for context (relations already have agentThreadId set)
  */
-export async function createRelations(storage, relations) {
+export async function createRelations(storage, threadId, relations) {
     const graph = await storage.loadGraph();
     // Validate that referenced entities exist
     const entityNames = new Set(graph.entities.map(e => e.name));
@@ -33,13 +34,14 @@ export async function createRelations(storage, relations) {
 }
 /**
  * Delete relations from the knowledge graph
- * Deletions affect all threads in the collaborative knowledge graph
+ * Thread isolation: Only deletes relations that belong to the specified thread
  */
-export async function deleteRelations(storage, relations) {
+export async function deleteRelations(storage, threadId, relations) {
     const graph = await storage.loadGraph();
-    // Delete relations globally across all threads by matching (from, to, relationType)
+    // Delete relations only from the specified thread by matching (from, to, relationType, threadId)
     graph.relations = graph.relations.filter(r => !relations.some(delRelation => r.from === delRelation.from &&
         r.to === delRelation.to &&
-        r.relationType === delRelation.relationType));
+        r.relationType === delRelation.relationType &&
+        r.agentThreadId === threadId));
     await storage.saveGraph(graph);
 }

package/dist/lib/save-memory-handler.js

@@ -86,7 +86,7 @@ export async function handleSaveMemory(input, createEntitiesFn, createRelationsF
             };
         });
         // Create all entities first
-        const createdEntities = await createEntitiesFn(entities);
+        const createdEntities = await createEntitiesFn(input.threadId, entities);
         // Build relations array from all entities
         const relations = [];
         for (const entity of input.entities) {
@@ -113,7 +113,7 @@ export async function handleSaveMemory(input, createEntitiesFn, createRelationsF
             }
         }
         // Create all relations
-        const createdRelations = await createRelationsFn(relations);
+        const createdRelations = await createRelationsFn(input.threadId, relations);
         // Calculate quality score
         const qualityScore = calculateQualityScore(input.entities);
         // Extract entity names for reference in subsequent calls

package/dist/lib/schemas.js

@@ -199,3 +199,99 @@ export const GetContextInputSchema = z.object({
     entityNames: z.array(z.string()).min(1).describe("Array of entity names to get context for"),
     depth: z.number().int().min(1).optional().default(1).describe("Context depth (default: 1)")
 });
+// Schema for create_entities tool
+export const CreateEntitiesInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    entities: z.array(EntitySchema).describe("Array of entities to create")
+}).superRefine((data, ctx) => {
+    const { threadId, entities } = data;
+    entities.forEach((entity, index) => {
+        if (entity.agentThreadId !== threadId) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Entity agentThreadId must match the top-level threadId",
+                path: ["entities", index, "agentThreadId"]
+            });
+        }
+    });
+});
+// Schema for create_relations tool
+export const CreateRelationsInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    relations: z.array(RelationSchema).describe("Array of relations to create")
+}).superRefine((data, ctx) => {
+    const { threadId, relations } = data;
+    relations.forEach((relation, index) => {
+        if (relation.agentThreadId !== threadId) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "Relation agentThreadId must match the top-level threadId",
+                path: ["relations", index, "agentThreadId"]
+            });
+        }
+    });
+});
+// Schema for add_observations tool
+export const AddObservationsInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    observations: z.array(z.object({
+        entityName: z.string().describe("The name of the entity to add the observations to"),
+        contents: z.array(z.string()).describe("An array of observation contents to add"),
+        agentThreadId: z.string().describe("The agent thread ID adding these observations"),
+        timestamp: z.string().describe("ISO 8601 timestamp of when the observations are added"),
+        confidence: z.number().min(0).max(1).describe("Confidence coefficient from 0 to 1"),
+        importance: z.number().min(0).max(1).describe("Importance for memory integrity if lost: 0 (not important) to 1 (critical)")
+    })).describe("Array of observations to add")
+}).superRefine((data, ctx) => {
+    data.observations.forEach((observation, index) => {
+        if (observation.agentThreadId !== data.threadId) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "agentThreadId must match the top-level threadId",
+                path: ["observations", index, "agentThreadId"],
+            });
+        }
+    });
+});
+// Schema for delete_entities tool
+export const DeleteEntitiesInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    entityNames: z.array(z.string()).describe("An array of entity names to delete")
+});
+// Schema for delete_observations tool
+export const DeleteObservationsInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    deletions: z.array(z.object({
+        entityName: z.string().describe("The name of the entity containing the observations"),
+        observations: z.array(z.string()).describe("An array of observations to delete")
+    })).describe("Array of deletions to perform")
+});
+// Schema for delete_relations tool
+export const DeleteRelationsInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    relations: z.array(RelationSchema).describe("An array of relations to delete")
+});
+// Schema for prune_memory tool
+export const PruneMemoryInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    olderThan: z.string().optional().describe("ISO 8601 timestamp - remove entities older than this"),
+    importanceLessThan: z.number().min(0).max(1).optional().describe("Remove entities with importance less than this value"),
+    keepMinEntities: z.number().optional().describe("Minimum number of entities to keep regardless of filters")
+});
+// Schema for bulk_update tool
+export const BulkUpdateInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    updates: z.array(z.object({
+        entityName: z.string(),
+        confidence: z.number().min(0).max(1).optional(),
+        importance: z.number().min(0).max(1).optional(),
+        addObservations: z.array(z.string()).optional()
+    })).describe("Array of updates to perform")
+});
+// Schema for flag_for_review tool
+export const FlagForReviewInputSchema = z.object({
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project"),
+    entityName: z.string().describe("Name of entity to flag"),
+    reason: z.string().describe("Reason for flagging"),
+    reviewer: z.string().optional().describe("Optional reviewer name")
+});

package/package.json

@@ -1,14 +1,28 @@
 {
   "name": "server-memory-enhanced",
-  "version": "3.0.0",
-  "description": "Enhanced MCP server for memory with agent threading, timestamps, and confidence scoring",
+  "version": "3.1.0",
+  "description": "Persistent memory for long conversations - MCP server for knowledge graph with atomic facts, cross-chat memory sharing, and multi-agent delegation",
   "license": "MIT",
   "mcpName": "io.github.modelcontextprotocol/server-memory-enhanced",
   "author": "Andriy Shevchenko",
   "repository": {
     "type": "git",
-    "url": "https://github.com/andriyshevchenko/servers.git"
+    "url": "https://github.com/andriyshevchenko/atomic-memory-mcp.git"
   },
+  "homepage": "https://github.com/andriyshevchenko/atomic-memory-mcp",
+  "bugs": "https://github.com/andriyshevchenko/atomic-memory-mcp/issues",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "knowledge-graph",
+    "ai",
+    "claude",
+    "copilot",
+    "context",
+    "persistence",
+    "multi-agent"
+  ],
   "type": "module",
   "bin": {
     "mcp-server-memory-enhanced": "dist/index.js"

package/README.md

@@ -1,399 +0,0 @@
-# Memory-Enhanced MCP Server
-
-An enhanced version of the Memory MCP server that provides persistent knowledge graph storage with agent threading, timestamps, and confidence scoring.
-
-## Features
-
-- **Agent Thread Isolation**: Each agent thread writes to a separate file for better organization and parallel processing
-- **Timestamp Tracking**: Every entity and relation has an ISO 8601 timestamp indicating when it was created
-- **Confidence Scoring**: Each piece of knowledge has a confidence coefficient (0.0 to 1.0) representing certainty
-- **Persistent Storage**: Knowledge graphs are stored in JSONL format, one file per agent thread
-- **Graph Operations**: Full CRUD support for entities, relations, and observations
-
-## Enhanced Data Model
-
-### Entities
-Each entity now includes:
-- `name`: Entity identifier
-- `entityType`: Type of entity (free-form, any domain-specific type allowed)
-- `observations`: Array of **versioned Observation objects** (not strings) - **BREAKING CHANGE**
-  - Each observation has: `id`, `content`, `timestamp`, `version`, `supersedes`, `superseded_by`
-  - Supports full version history tracking
-- `agentThreadId`: Unique identifier for the agent thread
-- `timestamp`: ISO 8601 timestamp of creation
-- `confidence`: Confidence score (0.0 to 1.0)
-- `importance`: Importance for memory integrity if lost (0.0 = not important, 1.0 = critical)
-
-### Relations
-Each relation now includes:
-- `from`: Source entity name
-- `to`: Target entity name
-- `relationType`: Type of relationship
-- `agentThreadId`: Unique identifier for the agent thread
-- `timestamp`: ISO 8601 timestamp of creation
-- `confidence`: Confidence score (0.0 to 1.0)
-- `importance`: Importance for memory integrity if lost (0.0 = not important, 1.0 = critical)
-
-## Storage Architecture
-
-The server implements a **collaborative knowledge graph** where multiple agent threads contribute to a shared graph:
-
-### Design Principles
-- **Shared Entities**: Entity names are globally unique across all threads. If entity "Alice" exists, all threads reference the same entity.
-- **Shared Relations**: Relations are unique by (from, to, relationType) across all threads.
-- **Metadata Tracking**: Each entity and relation tracks which agent thread created it via `agentThreadId`, along with `timestamp` and `confidence`.
-- **Distributed Storage**: Data is physically stored in separate JSONL files per thread for organization and performance.
-- **Aggregated Reads**: Read operations combine data from all thread files to provide a complete view of the knowledge graph.
-
-### File Organization
-The server stores data in separate JSONL files per agent thread:
-- Default location: `./memory-data/thread-{agentThreadId}.jsonl`
-- Custom location: Set `MEMORY_DIR_PATH` environment variable
-- Each file contains entities and relations for one agent thread
-- Read operations aggregate data across all thread files
-
-## Available Tools
-
-### ⭐ Recommended Tool (New)
-1. **save_memory**: **[RECOMMENDED]** Unified tool for creating entities and relations atomically with server-side validation
-   - Enforces observation limits (max 300 chars, 3 sentences per observation, ignoring periods in version numbers)
-   - Requires at least 1 relation per entity (prevents orphaned nodes)
-   - Free-form entity types with soft normalization
-   - Atomic transactions (all-or-nothing)
-   - Bidirectional relation tracking
-   - Quality score calculation
-   - Clear, actionable error messages
-
-### Core Operations
-> ⚠️ **Note**: `create_entities` and `create_relations` are **deprecated**. New code should use `save_memory` for better reliability and validation.
-
-1. **create_entities**: Create new entities with metadata (including importance) - **[DEPRECATED - Use save_memory]**
-2. **create_relations**: Create relationships between entities with metadata (including importance) - **[DEPRECATED - Use save_memory]**
-3. **add_observations**: Add observations to existing entities with metadata (including importance)
-4. **update_observation**: **[NEW]** Update an existing observation by creating a new version with updated content, maintaining version history
-5. **delete_entities**: Remove entities and cascading relations
-6. **delete_observations**: Remove specific observations
-7. **delete_relations**: Delete relationships
-8. **read_graph**: Read the entire knowledge graph
-9. **search_nodes**: Search entities by name, type, or observation content
-10. **open_nodes**: Retrieve specific entities by name
-11. **query_nodes**: Advanced querying with range-based filtering by timestamp, confidence, and importance
-12. **list_entities**: List entities with optional filtering by type and name pattern for quick discovery
-13. **validate_memory**: Validate entities without saving (dry-run) - check for errors before attempting save_memory
-
-### Memory Management & Insights
-14. **get_analytics**: **[NEW]** Get simple, LLM-friendly analytics about your knowledge graph
-    - Recent changes (last 10 entities)
-    - Top important entities (by importance score)
-    - Most connected entities (by relation count)
-    - Orphaned entities (quality check)
-15. **get_observation_history**: **[NEW]** Retrieve version history for observations
-    - Track how observations evolve over time
-    - View complete version chains
-    - Supports rollback by viewing previous versions
-16. **get_memory_stats**: Get comprehensive statistics (entity counts, thread activity, avg confidence/importance, recent activity)
-17. **get_recent_changes**: Retrieve entities and relations created/modified since a specific timestamp
-18. **prune_memory**: Remove old or low-importance entities to manage memory size
-19. **bulk_update**: Efficiently update multiple entities at once (confidence, importance, observations)
-20. **list_conversations**: List all available agent threads (conversations) with metadata including entity counts, relation counts, and activity timestamps
-
-### Relationship Intelligence
-21. **find_relation_path**: Find the shortest path of relationships between two entities (useful for "how are they connected?")
-22. **get_context**: Retrieve entities and relations related to specified entities up to a certain depth
-
-### Quality & Review
-23. **detect_conflicts**: Detect potentially conflicting observations using pattern matching and negation detection
-24. **flag_for_review**: Mark entities for human review with a specific reason (Human-in-the-Loop)
-25. **get_flagged_entities**: Retrieve all entities flagged for review
-
-## Usage
-
-### Installation
-
-```bash
-npm install server-memory-enhanced
-```
-
-### Running the Server
-
-```bash
-npx mcp-server-memory-enhanced
-```
-
-### Configuration
-
-#### File Storage (Default)
-
-Set the `MEMORY_DIR_PATH` environment variable to customize the storage location:
-
-```bash
-MEMORY_DIR_PATH=/path/to/memory/directory npx mcp-server-memory-enhanced
-```
-
-#### Neo4j Storage (Optional)
-
-The server supports Neo4j as an alternative storage backend. If Neo4j environment variables are set, the server will attempt to connect to Neo4j. If the connection fails or variables are not set, it will automatically fall back to file-based JSONL storage.
-
-**Environment Variables:**
-
-```bash
-# Neo4j connection settings
-export NEO4J_URI=neo4j://localhost:7687
-export NEO4J_USERNAME=neo4j
-export NEO4J_PASSWORD=your_password
-export NEO4J_DATABASE=neo4j  # Optional, defaults to 'neo4j'
-
-# Run the server
-npx mcp-server-memory-enhanced
-```
-
-**Using Docker Compose:**
-
-A `docker-compose.yml` file is provided for local development with Neo4j:
-
-```bash
-# Start Neo4j and the MCP server
-docker-compose up
-
-# The Neo4j browser will be available at http://localhost:7474
-# Username: neo4j, Password: testpassword
-```
-
-**Using with Claude Desktop:**
-
-Configure the server in your Claude Desktop configuration with Neo4j:
-
-```json
-{
-  "mcpServers": {
-    "memory-enhanced": {
-      "command": "npx",
-      "args": ["-y", "mcp-server-memory-enhanced"],
-      "env": {
-        "NEO4J_URI": "neo4j://localhost:7687",
-        "NEO4J_USERNAME": "neo4j",
-        "NEO4J_PASSWORD": "your_password"
-      }
-    }
-  }
-}
-```
-
-**Benefits of Neo4j Storage:**
-
-- **Graph-native queries**: Faster relationship traversals and path finding
-- **Scalability**: Better performance with large knowledge graphs
-- **Advanced queries**: Native support for graph algorithms
-- **Visualization**: Use Neo4j Browser to visualize your knowledge graph
-- **Automatic fallback**: If Neo4j is not available, automatically uses file storage
-
-## User Guide
-
-### ✨ Using save_memory (Recommended)
-
-The `save_memory` tool is the recommended way to create entities and relations. It provides atomic transactions and server-side validation to ensure high-quality knowledge graphs.
-
-#### Key Principles
-
-1. **Atomic Observations**: Each observation should be a single, atomic fact
-   - ✅ Good: `"Works at Google"`, `"Lives in San Francisco"`
-   - ❌ Bad: `"Works at Google and lives in San Francisco and has a PhD in Computer Science"`
-   - **Max length**: 300 characters per observation
-   - **Max sentences**: 3 sentences per observation (technical content with version numbers supported)
-
-2. **Mandatory Relations**: Every entity must connect to at least one other entity
-   - ✅ Good: `{ targetEntity: "Google", relationType: "works at" }`
-   - ❌ Bad: Empty relations array `[]`
-   - This prevents orphaned nodes and ensures a well-connected knowledge graph
-
-3. **Free Entity Types**: Use any entity type that makes sense for your domain
-   - ✅ Good: `"Person"`, `"Company"`, `"Document"`, `"Recipe"`, `"Patient"`, `"API"`
-   - Soft normalization: `"person"` → `"Person"` (warning, not error)
-   - Space warning: `"API Key"` → suggests `"APIKey"`
-
-4. **Error Messages**: The tool provides clear, actionable error messages
-   - Too long: `"Observation too long (350 chars). Max 300. Suggestion: Split into multiple observations."`
-   - No relations: `"Entity 'X' must have at least 1 relation. Suggestion: Add relations to show connections."`
-   - Too many sentences: `"Too many sentences (4). Max 3. Suggestion: Split this into 4 separate observations."`
-
-### Example Usage
-
-```typescript
-// ✅ RECOMMENDED: Use save_memory for atomic entity and relation creation
-await save_memory({
-  entities: [
-    {
-      name: "Alice",
-      entityType: "Person",
-      observations: ["Works at Google", "Lives in SF"],  // Atomic facts, under 300 chars
-      relations: [{ targetEntity: "Bob", relationType: "knows" }]  // At least 1 relation required
-    },
-    {
-      name: "Bob",
-      entityType: "Person",
-      observations: ["Works at Microsoft"],
-      relations: [{ targetEntity: "Alice", relationType: "knows" }]
-    }
-  ],
-  threadId: "conversation-001"
-});
-
-// Get analytics about your knowledge graph
-await get_analytics({
-  threadId: "conversation-001"
-});
-// Returns: {
-//   recent_changes: [...],      // Last 10 entities
-//   top_important: [...],       // Top 10 by importance
-//   most_connected: [...],      // Top 10 by relation count
-//   orphaned_entities: [...]    // Quality check
-// }
-
-// Get observation version history
-await get_observation_history({
-  entityName: "Python Scripts",
-  observationId: "obs_abc123"
-});
-// Returns: { history: [{ id, content, version, timestamp, supersedes, superseded_by }, ...] }
-
-// Update an existing observation (creates a new version)
-await update_observation({
-  entityName: "Alice",
-  observationId: "obs_abc123",
-  newContent: "Works at Google (Senior Engineer)",
-  agentThreadId: "conversation-001",
-  timestamp: "2024-01-20T12:00:00Z",
-  confidence: 0.95  // Optional: update confidence
-});
-// Returns: { success: true, updatedObservation: { id, content, version: 2, supersedes, ... }, message: "..." }
-
-// Query nodes with range-based filtering
-await queryNodes({
-  timestampStart: "2024-01-20T09:00:00Z",
-  timestampEnd: "2024-01-20T11:00:00Z",
-  confidenceMin: 0.8,
-  importanceMin: 0.7  // Only get important items
-});
-
-// Get memory statistics
-await getMemoryStats();
-// Returns: { entityCount, relationCount, threadCount, entityTypes, avgConfidence, avgImportance, recentActivity }
-
-// List all conversations (agent threads)
-await listConversations();
-// Returns: { conversations: [{ agentThreadId, entityCount, relationCount, firstCreated, lastUpdated }, ...] }
-
-// Get recent changes since last interaction
-await getRecentChanges({ since: "2024-01-20T10:00:00Z" });
-
-// Find how two entities are connected
-await findRelationPath({ from: "Alice", to: "Charlie", maxDepth: 5 });
-
-// Get context around specific entities
-await getContext({ entityNames: ["Alice", "Bob"], depth: 2 });
-
-// Detect conflicting observations
-await detectConflicts();
-
-// Flag entity for human review
-await flagForReview({ entityName: "Alice", reason: "Uncertain data", reviewer: "John" });
-
-// Bulk update multiple entities
-await bulkUpdate({
-  updates: [
-    { entityName: "Alice", importance: 0.95 },
-    { entityName: "Bob", confidence: 0.85, addObservations: ["updated info"] }
-  ]
-});
-
-// Prune old/unimportant data
-await pruneMemory({ olderThan: "2024-01-01T00:00:00Z", importanceLessThan: 0.3, keepMinEntities: 100 });
-```
-
-### 🔄 Migration Guide
-
-For users of the old `create_entities` and `create_relations` tools:
-
-#### What Changed
-- **Old approach**: Two separate tools that could be used independently
-  - `create_entities` → creates entities
-  - `create_relations` → creates relations (optional, often skipped by LLMs)
-- **New approach**: Single `save_memory` tool with atomic transactions
-  - Creates entities and relations together
-  - Enforces mandatory relations (at least 1 per entity)
-  - Validates observation length and atomicity
-
-#### Migrating Your Code
-```typescript
-// ❌ OLD WAY (deprecated but still works)
-await create_entities({
-  entities: [{ name: "Alice", entityType: "person", observations: ["works at Google and lives in SF"] }]
-});
-await create_relations({  // Often forgotten!
-  relations: [{ from: "Alice", to: "Bob", relationType: "knows" }]
-});
-
-// ✅ NEW WAY (recommended)
-await save_memory({
-  entities: [
-    {
-      name: "Alice",
-      entityType: "Person",
-      observations: ["Works at Google", "Lives in SF"],  // Split into atomic facts
-      relations: [{ targetEntity: "Bob", relationType: "knows" }]  // Required!
-    }
-  ],
-  threadId: "conversation-001"
-});
-```
-
-#### Migration Strategy
-1. **Old tools remain available**: `create_entities` and `create_relations` are deprecated but not removed
-2. **No forced migration**: Update your code gradually at your own pace
-3. **New code should use `save_memory`**: Benefits from validation and atomic transactions
-4. **Observation versioning**: New installations use versioned observations (breaking change for data model)
-
-## Development
-
-### Build
-
-```bash
-npm run build
-```
-
-### Test
-
-```bash
-npm run test
-```
-
-### Watch Mode
-
-```bash
-npm run watch
-```
-
-## License
-
-MIT
-
-## 🤝 Contributing
-
-Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-## 🔒 Security
-
-See [SECURITY.MD](SECURITY.md) for reporting security vulnerabilities.
-
-## 📜 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 💬 Community
-
-- [GitHub Discussions](https://github.com/modelcontextprotocol/servers/discussions)
-- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
-
----
-
-Part of the [Model Context Protocol](https://modelcontextprotocol.io) project.