server-memory-enhanced 2.3.0 → 2.3.1

package/README.md

@@ -15,8 +15,10 @@ An enhanced version of the Memory MCP server that provides persistent knowledge
 ### Entities
 Each entity now includes:
 - `name`: Entity identifier
-- `entityType`: Type of entity
-- `observations`: Array of observation strings
+- `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)
@@ -52,39 +54,64 @@ The server stores data in separate JSONL files per agent thread:
 
 ## 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
-1. **create_entities**: Create new entities with metadata (including importance)
-2. **create_relations**: Create relationships between entities with metadata (including importance)
+> ⚠️ **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. **delete_entities**: Remove entities and cascading relations
-5. **delete_observations**: Remove specific observations
-6. **delete_relations**: Delete relationships
-7. **read_graph**: Read the entire knowledge graph
-8. **search_nodes**: Search entities by name, type, or observation content
-9. **open_nodes**: Retrieve specific entities by name
-10. **query_nodes**: Advanced querying with range-based filtering by timestamp, confidence, and 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
-11. **get_memory_stats**: Get comprehensive statistics (entity counts, thread activity, avg confidence/importance, recent activity)
-12. **get_recent_changes**: Retrieve entities and relations created/modified since a specific timestamp
-13. **prune_memory**: Remove old or low-importance entities to manage memory size
-14. **bulk_update**: Efficiently update multiple entities at once (confidence, importance, observations)
+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
-15. **find_relation_path**: Find the shortest path of relationships between two entities (useful for "how are they connected?")
-16. **get_context**: Retrieve entities and relations related to specified entities up to a certain depth
+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
-17. **detect_conflicts**: Detect potentially conflicting observations using pattern matching and negation detection
-18. **flag_for_review**: Mark entities for human review with a specific reason (Human-in-the-Loop)
-19. **get_flagged_entities**: Retrieve all entities flagged for 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 @modelcontextprotocol/server-memory-enhanced
+npm install server-memory-enhanced
 ```
 
 ### Running the Server
@@ -95,44 +122,150 @@ 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
 ```
 
-## Example
+#### 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
-// Create entities with metadata including importance
-await createEntities({
+// ✅ RECOMMENDED: Use save_memory for atomic entity and relation creation
+await save_memory({
   entities: [
     {
       name: "Alice",
-      entityType: "person",
-      observations: ["works at Acme Corp"],
-      agentThreadId: "thread-001",
-      timestamp: "2024-01-20T10:00:00Z",
-      confidence: 0.95,
-      importance: 0.9  // Critical entity
+      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"
 });
 
-// Create relations with metadata including importance
-await createRelations({
-  relations: [
-    {
-      from: "Alice",
-      to: "Bob",
-      relationType: "knows",
-      agentThreadId: "thread-001",
-      timestamp: "2024-01-20T10:01:00Z",
-      confidence: 0.9,
-      importance: 0.75  // Important relationship
-    }
-  ]
+// 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({
@@ -146,6 +279,10 @@ await queryNodes({
 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" });
 
@@ -173,6 +310,49 @@ await bulkUpdate({
 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
@@ -196,3 +376,24 @@ 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.

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 } from './lib/schemas.js';
+import { EntitySchema, RelationSchema, SaveMemoryInputSchema, SaveMemoryOutputSchema, GetAnalyticsInputSchema, GetAnalyticsOutputSchema, GetObservationHistoryInputSchema, GetObservationHistoryOutputSchema, ListEntitiesInputSchema, ListEntitiesOutputSchema, ValidateMemoryInputSchema, ValidateMemoryOutputSchema, UpdateObservationInputSchema, UpdateObservationOutputSchema } 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';
@@ -267,6 +267,32 @@ server.registerTool("delete_observations", {
         structuredContent: { success: true, message: "Observations deleted successfully" }
     };
 });
+// Register update_observation tool
+server.registerTool("update_observation", {
+    title: "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 }) => {
+    const updatedObservation = await knowledgeGraphManager.updateObservation({
+        entityName,
+        observationId,
+        newContent,
+        agentThreadId,
+        timestamp,
+        confidence,
+        importance
+    });
+    const message = `Observation updated successfully. New version: ${updatedObservation.id} (v${updatedObservation.version})`;
+    return {
+        content: [{ type: "text", text: message }],
+        structuredContent: {
+            success: true,
+            updatedObservation,
+            message
+        }
+    };
+});
 // Register delete_relations tool
 server.registerTool("delete_relations", {
     title: "Delete Relations",

package/dist/lib/jsonl-storage-adapter.js

@@ -240,10 +240,14 @@ export class JsonlStorageAdapter {
      * Serialize thread data to JSONL lines
      */
     serializeThreadData(threadData) {
-        return [
-            ...threadData.entities.map(e => this.serializeEntity(e)),
-            ...threadData.relations.map(r => this.serializeRelation(r))
-        ];
+        const lines = [];
+        for (const e of threadData.entities) {
+            lines.push(this.serializeEntity(e));
+        }
+        for (const r of threadData.relations) {
+            lines.push(this.serializeRelation(r));
+        }
+        return lines;
     }
     /**
      * Save data for a specific thread

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

@@ -11,6 +11,38 @@ export class KnowledgeGraphManager {
         this.storage = storageAdapter || new JsonlStorageAdapter(memoryDirPath);
         // Lazy initialization - will be called on first operation
     }
+    /**
+     * Check if content contains any negation words (using word boundary matching)
+     * Handles punctuation and contractions, avoids creating intermediate Set for performance
+     */
+    hasNegation(content) {
+        // Extract words using word boundary regex, preserving contractions (include apostrophes)
+        const lowerContent = content.toLowerCase();
+        const wordMatches = lowerContent.match(/\b[\w']+\b/g);
+        if (!wordMatches) {
+            return false;
+        }
+        // Check each word against negation words without creating intermediate Set
+        for (const word of wordMatches) {
+            if (KnowledgeGraphManager.NEGATION_WORDS.has(word)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Create a composite key for relation deduplication.
+     *
+     * We explicitly normalize the components to primitive strings to ensure
+     * stable serialization and to document the assumption that `from`, `to`,
+     * and `relationType` are simple string identifiers.
+     */
+    createRelationKey(relation) {
+        const from = String(relation.from);
+        const to = String(relation.to);
+        const relationType = String(relation.relationType);
+        return JSON.stringify([from, to, relationType]);
+    }
     /**
      * Ensure storage is initialized before any operation
      * This is called automatically by all public methods
@@ -21,12 +53,80 @@ export class KnowledgeGraphManager {
         }
         await this.initializePromise;
     }
+    /**
+     * Find an entity by name in the knowledge graph.
+     * @param graph - The knowledge graph to search
+     * @param entityName - Name of the entity to find
+     * @returns The found entity
+     * @throws Error if entity not found
+     */
+    findEntity(graph, entityName) {
+        const entity = graph.entities.find(e => e.name === entityName);
+        if (!entity) {
+            throw new Error(`Entity '${entityName}' not found`);
+        }
+        return entity;
+    }
+    /**
+     * Find an observation by ID within an entity.
+     * @param entity - The entity containing the observation
+     * @param observationId - ID of the observation to find
+     * @returns The found observation
+     * @throws Error if observation not found
+     */
+    findObservation(entity, observationId) {
+        const observation = entity.observations.find(o => o.id === observationId);
+        if (!observation) {
+            throw new Error(`Observation '${observationId}' not found in entity '${entity.name}'`);
+        }
+        return observation;
+    }
+    /**
+     * Validate that an observation can be updated (not already superseded).
+     * @param observation - The observation to validate
+     * @throws Error if observation has already been superseded
+     */
+    validateObservationNotSuperseded(observation) {
+        if (observation.superseded_by) {
+            throw new Error(`Observation '${observation.id}' has already been superseded by '${observation.superseded_by}'. Update the latest version instead.`);
+        }
+    }
+    /**
+     * Resolve confidence value using inheritance chain: params > observation > entity.
+     * @param providedValue - Value provided in parameters (optional)
+     * @param observationValue - Value from observation (optional)
+     * @param entityValue - Value from entity (fallback)
+     * @returns Resolved confidence value
+     */
+    resolveInheritedValue(providedValue, observationValue, entityValue) {
+        return providedValue ?? observationValue ?? entityValue;
+    }
+    /**
+     * Create a new observation version from an existing observation.
+     * @param oldObs - The observation being updated
+     * @param entity - The entity containing the observation
+     * @param params - Update parameters
+     * @returns New observation with incremented version
+     */
+    createObservationVersion(oldObs, entity, params) {
+        return {
+            id: `obs_${randomUUID()}`,
+            content: params.newContent,
+            timestamp: params.timestamp,
+            version: oldObs.version + 1,
+            supersedes: oldObs.id,
+            agentThreadId: params.agentThreadId,
+            confidence: this.resolveInheritedValue(params.confidence, oldObs.confidence, entity.confidence),
+            importance: this.resolveInheritedValue(params.importance, oldObs.importance, entity.importance)
+        };
+    }
     async createEntities(entities) {
         await this.ensureInitialized();
         const graph = await this.storage.loadGraph();
         // 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
-        const newEntities = entities.filter(e => !graph.entities.some(existingEntity => existingEntity.name === e.name));
+        const existingNames = new Set(graph.entities.map(e => e.name));
+        const newEntities = entities.filter(e => !existingNames.has(e.name));
         graph.entities.push(...newEntities);
         await this.storage.saveGraph(graph);
         return newEntities;
@@ -44,9 +144,15 @@ export class KnowledgeGraphManager {
         });
         // Relations are globally unique by (from, to, relationType) across all threads
         // This enables multiple threads to collaboratively build the knowledge graph
-        const newRelations = validRelations.filter(r => !graph.relations.some(existingRelation => existingRelation.from === r.from &&
-            existingRelation.to === r.to &&
-            existingRelation.relationType === r.relationType));
+        const existingRelationKeys = new Set(graph.relations.map(r => this.createRelationKey(r)));
+        // Create composite keys once per valid relation to avoid duplicate serialization
+        const validRelationsWithKeys = validRelations.map(r => ({
+            relation: r,
+            key: this.createRelationKey(r)
+        }));
+        const newRelations = validRelationsWithKeys
+            .filter(item => !existingRelationKeys.has(item.key))
+            .map(item => item.relation);
         graph.relations.push(...newRelations);
         await this.storage.saveGraph(graph);
         return newRelations;
@@ -60,10 +166,16 @@ export class KnowledgeGraphManager {
             }
             // Check for existing observations with same content to create version chain
             const newObservations = [];
+            // Build a Set of existing observation contents for efficient lookup (single-pass)
+            const existingContents = entity.observations.reduce((set, obs) => {
+                if (!obs.superseded_by) {
+                    set.add(obs.content);
+                }
+                return set;
+            }, new Set());
             for (const content of o.contents) {
-                // Find if there's an existing observation with this content (latest version)
-                const existingObs = entity.observations.find(obs => obs.content === content && !obs.superseded_by);
-                if (existingObs) {
+                // Check if observation with this content already exists (latest version)
+                if (existingContents.has(content)) {
                     // Don't add duplicate - observation with this content already exists
                     // Versioning is for UPDATES to content, not for re-asserting the same content
                     continue;
@@ -92,8 +204,9 @@ export class KnowledgeGraphManager {
     }
     async deleteEntities(entityNames) {
         const graph = await this.storage.loadGraph();
-        graph.entities = graph.entities.filter(e => !entityNames.includes(e.name));
-        graph.relations = graph.relations.filter(r => !entityNames.includes(r.from) && !entityNames.includes(r.to));
+        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));
         await this.storage.saveGraph(graph);
     }
     async deleteObservations(deletions) {
@@ -107,6 +220,41 @@ export class KnowledgeGraphManager {
         });
         await this.storage.saveGraph(graph);
     }
+    /**
+     * Update an existing observation by creating a new version with updated content.
+     * This maintains the version history through the supersedes/superseded_by chain.
+     *
+     * @param params - Update parameters
+     * @param params.entityName - Name of the entity containing the observation
+     * @param params.observationId - ID of the observation to update
+     * @param params.newContent - New content for the observation
+     * @param params.agentThreadId - Agent thread ID making this update
+     * @param params.timestamp - ISO 8601 timestamp of the update
+     * @param params.confidence - Optional confidence score (0-1), inherits from old observation if not provided
+     * @param params.importance - Optional importance score (0-1), inherits from old observation if not provided
+     * @returns The newly created observation with incremented version number
+     * @throws Error if entity not found
+     * @throws Error if observation not found
+     * @throws Error if observation has already been superseded (must update latest version)
+     */
+    async updateObservation(params) {
+        await this.ensureInitialized();
+        const graph = await this.storage.loadGraph();
+        // Find and validate the entity and observation
+        const entity = this.findEntity(graph, params.entityName);
+        const oldObs = this.findObservation(entity, params.observationId);
+        this.validateObservationNotSuperseded(oldObs);
+        // Create new version with inheritance chain
+        const newObs = this.createObservationVersion(oldObs, entity, params);
+        // Link old observation to new one
+        oldObs.superseded_by = newObs.id;
+        // Add new observation to entity
+        entity.observations.push(newObs);
+        // Update entity timestamp
+        entity.timestamp = params.timestamp;
+        await this.storage.saveGraph(graph);
+        return newObs;
+    }
     async deleteRelations(relations) {
         const graph = await this.storage.loadGraph();
         // Delete relations globally across all threads by matching (from, to, relationType)
@@ -328,6 +476,19 @@ export class KnowledgeGraphManager {
         if (from === to) {
             return { found: true, path: [from], relations: [] };
         }
+        // Build indexes for efficient relation lookup
+        const relationsFrom = new Map();
+        const relationsTo = new Map();
+        for (const rel of graph.relations) {
+            if (!relationsFrom.has(rel.from)) {
+                relationsFrom.set(rel.from, []);
+            }
+            relationsFrom.get(rel.from).push(rel);
+            if (!relationsTo.has(rel.to)) {
+                relationsTo.set(rel.to, []);
+            }
+            relationsTo.get(rel.to).push(rel);
+        }
         // BFS to find shortest path
         const queue = [
             { entity: from, path: [from], relations: [] }
@@ -339,8 +500,8 @@ export class KnowledgeGraphManager {
                 continue;
             }
             // Find all relations connected to current entity (both outgoing and incoming for bidirectional search)
-            const outgoing = graph.relations.filter(r => r.from === current.entity);
-            const incoming = graph.relations.filter(r => r.to === current.entity);
+            const outgoing = relationsFrom.get(current.entity) || [];
+            const incoming = relationsTo.get(current.entity) || [];
             // Check outgoing relations
             for (const rel of outgoing) {
                 if (rel.to === to) {
@@ -398,8 +559,8 @@ export class KnowledgeGraphManager {
                         continue;
                     }
                     // Check for negation patterns
-                    const obs1HasNegation = Array.from(KnowledgeGraphManager.NEGATION_WORDS).some(word => obs1Content.includes(word));
-                    const obs2HasNegation = Array.from(KnowledgeGraphManager.NEGATION_WORDS).some(word => obs2Content.includes(word));
+                    const obs1HasNegation = this.hasNegation(obs1Content);
+                    const obs2HasNegation = this.hasNegation(obs2Content);
                     // If one has negation and they share key words, might be a conflict
                     if (obs1HasNegation !== obs2HasNegation) {
                         const words1 = obs1Content.split(/\s+/).filter(w => w.length > 3);

package/dist/lib/schemas.js

@@ -129,3 +129,18 @@ export const ValidateMemoryOutputSchema = z.object({
         warnings: z.array(z.string()).describe("List of validation warnings")
     })).describe("Validation results for each entity")
 });
+// Schema for update_observation tool
+export const UpdateObservationInputSchema = z.object({
+    entityName: z.string().min(1).describe("Name of the entity containing the observation"),
+    observationId: z.string().min(1).describe("ID of the observation to update"),
+    newContent: z.string().min(1).max(300).describe("New content for the observation (max 300 chars). Minimum 1 character to allow short but valid observations like abbreviations or single words."),
+    agentThreadId: z.string().min(1).describe("Agent thread ID making this update"),
+    timestamp: z.string().describe("ISO 8601 timestamp of the update"),
+    confidence: z.number().min(0).max(1).optional().describe("Optional confidence score (0-1), inherits from old observation if not provided"),
+    importance: z.number().min(0).max(1).optional().describe("Optional importance score (0-1), inherits from old observation if not provided")
+});
+export const UpdateObservationOutputSchema = z.object({
+    success: z.boolean(),
+    updatedObservation: ObservationSchema.describe("The new version of the observation"),
+    message: z.string()
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server-memory-enhanced",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Enhanced MCP server for memory with agent threading, timestamps, and confidence scoring",
   "license": "MIT",
   "mcpName": "io.github.modelcontextprotocol/server-memory-enhanced",