server-memory-enhanced 2.2.1 → 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,8 +6,9 @@ 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 } 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';
 import { Neo4jStorageAdapter } from './lib/neo4j-storage-adapter.js';
 import { NEO4J_ENV_VARS, STORAGE_LOG_MESSAGES, NEO4J_ERROR_MESSAGES } from './lib/storage-config.js';
@@ -110,27 +111,57 @@ const server = new McpServer({
 // Register NEW save_memory tool (Section 1 of spec - Unified Tool)
 server.registerTool("save_memory", {
     title: "Save Memory",
-    description: "Save entities and their relations to memory graph atomically. RULES: 1) Each observation max 150 chars (atomic facts only). 2) Each entity MUST have at least 1 relation. This is the recommended way to create entities and relations.",
+    description: "Save entities and their relations to memory graph atomically. RULES: 1) Each observation max 300 chars (atomic facts, technical content supported). 2) Each entity MUST have at least 1 relation. This is the recommended way to create entities and relations.",
     inputSchema: SaveMemoryInputSchema,
     outputSchema: SaveMemoryOutputSchema
 }, async (input) => {
-    const result = await handleSaveMemory(input, (entities) => knowledgeGraphManager.createEntities(entities), (relations) => knowledgeGraphManager.createRelations(relations));
+    const result = await handleSaveMemory(input, (entities) => knowledgeGraphManager.createEntities(entities), (relations) => knowledgeGraphManager.createRelations(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` +
+            `Quality score: ${(result.quality_score * 100).toFixed(1)}%\n`;
+        if (result.created.entity_names && result.created.entity_names.length > 0) {
+            successText += `\nCreated entities: ${result.created.entity_names.join(', ')}\n`;
+        }
+        if (result.warnings.length > 0) {
+            successText += `\nWarnings:\n${result.warnings.join('\n')}`;
+        }
         return {
             content: [{
                     type: "text",
-                    text: `✓ Successfully saved ${result.created.entities} entities and ${result.created.relations} relations.\n` +
-                        `Quality score: ${(result.quality_score * 100).toFixed(1)}%\n` +
-                        (result.warnings.length > 0 ? `\nWarnings:\n${result.warnings.join('\n')}` : '')
+                    text: successText
                 }],
             structuredContent: result
         };
     }
     else {
+        // Format validation errors for display
+        let errorText = '✗ Validation failed:\n\n';
+        if (result.validation_errors) {
+            if (Array.isArray(result.validation_errors) && result.validation_errors.length > 0) {
+                // Check if structured errors
+                if (typeof result.validation_errors[0] === 'object') {
+                    const structuredErrors = result.validation_errors;
+                    errorText += structuredErrors.map(err => {
+                        let msg = `Entity #${err.entity_index} "${err.entity_name}" (${err.entity_type}):\n`;
+                        err.errors.forEach((e) => msg += `  - ${e}\n`);
+                        if (err.observations && err.observations.length > 0) {
+                            msg += `  Observations: ${err.observations.join(', ')}\n`;
+                        }
+                        return msg;
+                    }).join('\n');
+                }
+                else {
+                    // Fallback to string errors
+                    errorText += result.validation_errors.join('\n');
+                }
+            }
+        }
+        errorText += '\nFix all validation errors and retry. All entities must be valid to maintain memory integrity.';
         return {
             content: [{
                     type: "text",
-                    text: `✗ Validation failed:\n${result.validation_errors?.join('\n')}`
+                    text: errorText
                 }],
             structuredContent: result,
             isError: true
@@ -236,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",
@@ -329,6 +386,139 @@ server.registerTool("query_nodes", {
         structuredContent: { ...graph }
     };
 });
+// Register list_entities tool for simple entity lookup
+server.registerTool("list_entities", {
+    title: "List Entities",
+    description: "List entities with optional filtering by entity type and name pattern. Returns a simple list of entity names and types for quick discovery.",
+    inputSchema: ListEntitiesInputSchema,
+    outputSchema: ListEntitiesOutputSchema
+}, async (input) => {
+    const { threadId, entityType, namePattern } = input;
+    const entities = await knowledgeGraphManager.listEntities(threadId, entityType, namePattern);
+    return {
+        content: [{
+                type: "text",
+                text: `Found ${entities.length} entities:\n` +
+                    entities.map(e => `  - ${e.name} (${e.entityType})`).join('\n')
+            }],
+        structuredContent: { entities }
+    };
+});
+// Register validate_memory tool for pre-validation (dry-run)
+server.registerTool("validate_memory", {
+    title: "Validate Memory",
+    description: "Validate entities without saving (dry-run). Check for errors before attempting save_memory. Returns detailed validation results per entity.",
+    inputSchema: ValidateMemoryInputSchema,
+    outputSchema: ValidateMemoryOutputSchema
+}, async (input) => {
+    const { entities, threadId } = input;
+    // Get existing entity names for cross-thread reference validation
+    let existingEntityNames;
+    try {
+        existingEntityNames = await knowledgeGraphManager.getEntityNamesInThread(threadId);
+    }
+    catch (error) {
+        // If we can't get existing entities, proceed without cross-thread validation
+    }
+    // Preserve original entityType values before validation normalizes them
+    // This is needed to match warnings to the correct entities
+    const originalEntityTypes = entities.map((e) => e.entityType);
+    // Run validation (same logic as save_memory but without saving)
+    const validationResult = validateSaveMemoryRequest(entities, existingEntityNames);
+    // Transform validation result into per-entity format
+    const results = new Map();
+    // Initialize all entities as valid
+    entities.forEach((entity, index) => {
+        results.set(index, {
+            index: index,
+            name: entity.name,
+            type: originalEntityTypes[index], // Use original type, not normalized
+            valid: true,
+            errors: [],
+            warnings: []
+        });
+    });
+    // Add errors to corresponding entities
+    validationResult.errors.forEach((err) => {
+        const result = results.get(err.entityIndex);
+        if (result) {
+            result.valid = false;
+            const errorMsg = err.suggestion
+                ? `${err.error} Suggestion: ${err.suggestion}`
+                : err.error;
+            result.errors.push(errorMsg);
+        }
+    });
+    // Add warnings to corresponding entities
+    validationResult.warnings.forEach((warning) => {
+        // Parse entity type from warning if possible, otherwise add to first entity
+        const entityMatch = warning.match(/EntityType '([^']+)'/);
+        if (entityMatch) {
+            const warningEntityType = entityMatch[1];
+            let attached = false;
+            // Find entity whose ORIGINAL entityType matches the type in the warning
+            // (warnings contain the original type before normalization)
+            originalEntityTypes.forEach((origType, index) => {
+                if (origType === warningEntityType) {
+                    const result = results.get(index);
+                    if (result) {
+                        result.warnings.push(warning);
+                        attached = true;
+                    }
+                }
+            });
+            // If no matching entity type found, attach to first entity as fallback
+            if (!attached) {
+                const firstResult = results.get(0);
+                if (firstResult) {
+                    firstResult.warnings.push(warning);
+                }
+            }
+        }
+        else {
+            // No entity type information in warning; attach to first entity
+            const firstResult = results.get(0);
+            if (firstResult) {
+                firstResult.warnings.push(warning);
+            }
+        }
+    });
+    const resultArray = Array.from(results.values());
+    const allValid = resultArray.every(r => r.valid);
+    // Format response text
+    let responseText = allValid
+        ? `✓ All ${entities.length} entities are valid and ready to save.\n`
+        : `✗ Validation failed for ${resultArray.filter(r => !r.valid).length} of ${entities.length} entities:\n\n`;
+    if (!allValid) {
+        resultArray.filter(r => !r.valid).forEach(r => {
+            responseText += `Entity #${r.index} "${r.name}" (${r.type}):\n`;
+            r.errors.forEach(e => responseText += `  - ${e}\n`);
+            if (r.warnings.length > 0) {
+                r.warnings.forEach(w => responseText += `  ⚠ ${w}\n`);
+            }
+            responseText += '\n';
+        });
+    }
+    // Add warnings for valid entities if any
+    const validWithWarnings = resultArray.filter(r => r.valid && r.warnings.length > 0);
+    if (validWithWarnings.length > 0) {
+        responseText += 'Warnings:\n';
+        validWithWarnings.forEach(r => {
+            responseText += `Entity #${r.index} "${r.name}" (${r.type}):\n`;
+            r.warnings.forEach(w => responseText += `  ⚠ ${w}\n`);
+        });
+    }
+    return {
+        content: [{
+                type: "text",
+                text: responseText
+            }],
+        structuredContent: {
+            all_valid: allValid,
+            results: resultArray
+        }
+    };
+});
 // Register get_memory_stats tool
 server.registerTool("get_memory_stats", {
     title: "Get Memory Statistics",

package/dist/lib/constants.js

@@ -5,8 +5,9 @@
 /**
  * Maximum length for observations in characters
  * Per spec Section 2: Hard Limits on Observation Length
+ * Increased to 300 to accommodate technical content (URLs, connection strings, etc.)
  */
-export const MAX_OBSERVATION_LENGTH = 150;
+export const MAX_OBSERVATION_LENGTH = 300;
 /**
  * Maximum number of sentences allowed per observation
  * Per spec Section 2: Hard Limits on Observation Length

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)
@@ -203,6 +351,69 @@ export class KnowledgeGraphManager {
             relations: filteredRelations,
         };
     }
+    /**
+     * Get names of all entities that can be referenced in relations.
+     * @returns Set of entity names that exist in the graph.
+     *
+     * Note: Returns ALL entities globally because entity names are globally unique across
+     * all threads in the collaborative knowledge graph (by design - see createEntities).
+     * This enables any thread to reference any existing entity, supporting incremental
+     * building and cross-thread collaboration. Thread-specific filtering is not needed
+     * since entity names cannot conflict across threads.
+     */
+    async getAllEntityNames() {
+        const graph = await this.storage.loadGraph();
+        const entityNames = new Set();
+        // Return all entities in the graph that can be referenced
+        // This allows incremental building: entities from previous save_memory calls
+        // can be referenced in new calls, enabling cross-save entity relations
+        for (const entity of graph.entities) {
+            entityNames.add(entity.name);
+        }
+        return entityNames;
+    }
+    /**
+     * @deprecated Use {@link getAllEntityNames} instead.
+     *
+     * This method is kept for backward compatibility. It accepts a threadId parameter
+     * for API consistency but does not use it for filtering; it returns the same
+     * global set of entity names as {@link getAllEntityNames}.
+     *
+     * @param threadId The thread ID (accepted but not used)
+     * @returns Set of entity names that exist in the graph
+     */
+    async getEntityNamesInThread(threadId) {
+        return this.getAllEntityNames();
+    }
+    /**
+     * List entities with optional filtering by type and name pattern
+     * @param threadId Optional thread ID to filter by. If not provided, returns entities from all threads.
+     * @param entityType Optional entity type filter (exact match)
+     * @param namePattern Optional name pattern filter (case-insensitive substring match)
+     * @returns Array of entities with name and entityType
+     */
+    async listEntities(threadId, entityType, namePattern) {
+        const graph = await this.storage.loadGraph();
+        let filteredEntities = graph.entities;
+        // Filter by thread ID if specified (otherwise returns all threads)
+        if (threadId) {
+            filteredEntities = filteredEntities.filter(e => e.agentThreadId === threadId);
+        }
+        // Filter by entity type if specified
+        if (entityType) {
+            filteredEntities = filteredEntities.filter(e => e.entityType === entityType);
+        }
+        // Filter by name pattern if specified (case-insensitive)
+        if (namePattern) {
+            const pattern = namePattern.toLowerCase();
+            filteredEntities = filteredEntities.filter(e => e.name.toLowerCase().includes(pattern));
+        }
+        // Return simplified list with just name and entityType
+        return filteredEntities.map(e => ({
+            name: e.name,
+            entityType: e.entityType
+        }));
+    }
     // Enhancement 1: Memory Statistics & Insights
     async getMemoryStats() {
         const graph = await this.storage.loadGraph();
@@ -265,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: [] }
@@ -276,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) {
@@ -335,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/save-memory-handler.js

@@ -9,18 +9,57 @@ import { randomUUID } from 'crypto';
  * Saves entities and their relations to the knowledge graph atomically
  * Either all entities + relations succeed, or none are saved (rollback)
  */
-export async function handleSaveMemory(input, createEntitiesFn, createRelationsFn) {
+export async function handleSaveMemory(input, createEntitiesFn, createRelationsFn, getExistingEntityNamesFn) {
     const timestamp = new Date().toISOString();
-    // Validate the entire request
-    const validationResult = validateSaveMemoryRequest(input.entities);
+    // Get existing entity names for cross-thread reference validation
+    let existingEntityNames;
+    if (getExistingEntityNamesFn) {
+        try {
+            existingEntityNames = await getExistingEntityNamesFn(input.threadId);
+        }
+        catch (error) {
+            // If we can't get existing entities, proceed without cross-thread validation
+            console.warn(`Failed to get existing entities for thread ${input.threadId}:`, error);
+        }
+    }
+    // Validate the entire request (with cross-thread entity reference support)
+    const validationResult = validateSaveMemoryRequest(input.entities, existingEntityNames);
     if (!validationResult.valid) {
-        // Return validation errors
+        // Group errors by entity for better structure
+        const errorsByEntity = new Map();
+        for (const err of validationResult.errors) {
+            if (!errorsByEntity.has(err.entityIndex)) {
+                errorsByEntity.set(err.entityIndex, {
+                    entity_name: err.entity,
+                    entity_type: err.entityType,
+                    errors: [],
+                    observations: []
+                });
+            }
+            const entityErrors = errorsByEntity.get(err.entityIndex);
+            const errorMsg = err.suggestion
+                ? `${err.error} Suggestion: ${err.suggestion}`
+                : err.error;
+            entityErrors.errors.push(errorMsg);
+            if (err.observationPreview) {
+                entityErrors.observations.push(err.observationPreview);
+            }
+        }
+        // Convert to structured format
+        const structuredErrors = Array.from(errorsByEntity.entries()).map(([index, data]) => ({
+            entity_index: index,
+            entity_name: data.entity_name,
+            entity_type: data.entity_type,
+            errors: data.errors,
+            observations: data.observations.length > 0 ? data.observations : undefined
+        }));
+        // Return validation errors with detailed structure
         return {
             success: false,
             created: { entities: 0, relations: 0 },
             warnings: [],
             quality_score: 0,
-            validation_errors: validationResult.errors.map(err => `${err.entity}: ${err.error}${err.suggestion ? ` Suggestion: ${err.suggestion}` : ''}`)
+            validation_errors: structuredErrors
         };
     }
     try {
@@ -77,11 +116,14 @@ export async function handleSaveMemory(input, createEntitiesFn, createRelationsF
         const createdRelations = await createRelationsFn(relations);
         // Calculate quality score
         const qualityScore = calculateQualityScore(input.entities);
+        // Extract entity names for reference in subsequent calls
+        const entityNames = createdEntities.map(e => e.name);
         return {
             success: true,
             created: {
                 entities: createdEntities.length,
-                relations: createdRelations.length
+                relations: createdRelations.length,
+                entity_names: entityNames
             },
             warnings: validationResult.warnings,
             quality_score: qualityScore

package/dist/lib/schemas.js

@@ -42,7 +42,7 @@ export const SaveMemoryRelationSchema = z.object({
 export const SaveMemoryEntitySchema = z.object({
     name: z.string().min(1).max(100).describe("Unique identifier for the entity"),
     entityType: z.string().min(1).max(50).describe("Type of entity (e.g., Person, Document, File, or custom types like Patient, API). Convention: start with capital letter."),
-    observations: z.array(z.string().min(5).max(150).describe("Atomic fact, max 150 chars")).min(1).describe("Array of atomic facts. Each must be ONE fact, max 150 chars."),
+    observations: z.array(z.string().min(5).max(300).describe("Atomic fact, max 300 chars (increased to accommodate technical content)")).min(1).describe("Array of atomic facts. Each must be ONE fact, max 300 chars."),
     relations: z.array(SaveMemoryRelationSchema)
         .min(1)
         .describe("REQUIRED: Every entity must have at least 1 relation"),
@@ -57,7 +57,8 @@ export const SaveMemoryOutputSchema = z.object({
     success: z.boolean(),
     created: z.object({
         entities: z.number(),
-        relations: z.number()
+        relations: z.number(),
+        entity_names: z.array(z.string()).optional().describe("Names of created entities (for reference in subsequent calls)")
     }),
     warnings: z.array(z.string()),
     quality_score: z.number().min(0).max(1),
@@ -100,3 +101,46 @@ export const GetObservationHistoryInputSchema = z.object({
 export const GetObservationHistoryOutputSchema = z.object({
     history: z.array(ObservationSchema).describe("Full version chain of the observation, chronologically ordered")
 });
+// Schema for list_entities tool (Simple Entity Lookup)
+export const ListEntitiesInputSchema = z.object({
+    threadId: z.string().optional().describe("Filter by thread ID (optional - returns entities from all threads if not specified)"),
+    entityType: z.string().optional().describe("Filter by entity type (e.g., 'Person', 'Service', 'Document')"),
+    namePattern: z.string().optional().describe("Filter by name pattern (case-insensitive substring match)")
+});
+export const ListEntitiesOutputSchema = z.object({
+    entities: z.array(z.object({
+        name: z.string(),
+        entityType: z.string()
+    })).describe("List of entities matching the filters")
+});
+// Schema for validate_memory tool (Pre-Validation)
+export const ValidateMemoryInputSchema = z.object({
+    entities: z.array(SaveMemoryEntitySchema).min(1).describe("Array of entities to validate"),
+    threadId: z.string().min(1).describe("Thread ID for this conversation/project")
+});
+export const ValidateMemoryOutputSchema = z.object({
+    all_valid: z.boolean().describe("True if all entities pass validation"),
+    results: z.array(z.object({
+        index: z.number().describe("Entity index in the input array"),
+        name: z.string().describe("Entity name"),
+        type: z.string().describe("Entity type"),
+        valid: z.boolean().describe("True if this entity passes validation"),
+        errors: z.array(z.string()).describe("List of validation errors"),
+        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/dist/lib/validation.js

@@ -3,24 +3,39 @@
  */
 import { MAX_OBSERVATION_LENGTH, MIN_OBSERVATION_LENGTH, MAX_SENTENCES, SENTENCE_TERMINATORS, TARGET_AVG_RELATIONS, RELATION_SCORE_WEIGHT, OBSERVATION_SCORE_WEIGHT } from './constants.js';
 /**
- * Counts actual sentences in text, ignoring periods in version numbers and decimals
+ * Counts actual sentences in text, ignoring periods in technical content
  * @param text The text to analyze
  * @returns Number of actual sentences
  */
 function countSentences(text) {
-    // Remove version numbers (e.g., 1.2.0, v5.4.3, V2.1.0) and decimal numbers before counting
-    // This prevents false positives where technical data is incorrectly counted as sentences
-    // Using explicit case handling [vV] for version prefix
-    const cleaned = text
-        .replace(/\b[vV]?\d+\.\d+(\.\d+)*\b/g, 'VERSION'); // handles version numbers and decimals
-    // Split on actual sentence terminators
+    // Patterns to ignore - technical content that contains periods but aren't sentence boundaries
+    // NOTE: Order matters! More specific patterns (multi-letter abbreviations) must come before more general patterns
+    const patternsToIgnore = [
+        /https?:\/\/[^\s]+/g, // URLs (http:// or https://) - allows periods in paths
+        /\b\d+\.\d+\.\d+\.\d+\b/g, // IP addresses (e.g., 192.168.1.1)
+        /\b[A-Za-z]:[\\\/](?:[^\s<>:"|?*]+(?:\s+[^\s<>:"|?*]+)*)/g, // Windows/Unix paths (handles spaces, e.g., C:\Program Files\...)
+        /\b[vV]?\d+\.\d+(\.\d+)*\b/g, // Version numbers (e.g., v1.2.0, 5.4.3)
+        /\b(?:[A-Z]\.){2,}/g, // Multi-letter abbreviations (e.g., U.S., U.K., U.S.A., P.D.F., I.B.M., etc.) - must come before single-letter pattern
+        /\b[A-Z][a-z]{0,3}\./g, // Common single-letter abbreviations (e.g., Dr., Mr., Mrs., Ms., Jr., Sr., etc.)
+        /\b[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?){2,}\b/g, // Hostnames/domains with at least 2 dots (e.g., sub.domain.com) - must come after all abbreviation patterns
+    ];
+    // Replace technical patterns with placeholders to prevent false sentence detection
+    let cleaned = text;
+    for (const pattern of patternsToIgnore) {
+        cleaned = cleaned.replace(pattern, 'PLACEHOLDER');
+    }
+    // Split on actual sentence terminators and count non-empty sentences
     const sentences = cleaned.split(SENTENCE_TERMINATORS).filter(s => s.trim().length > 0);
     return sentences.length;
 }
+/**
+ * Maximum length for observation preview in error messages
+ */
+const OBSERVATION_PREVIEW_LENGTH = 50;
 /**
  * Validates a single observation according to spec requirements:
  * - Min 5 characters
- * - Max 150 characters
+ * - Max 300 characters (increased to accommodate technical content)
  * - Max 3 sentences (ignoring periods in version numbers and decimals)
  */
 export function validateObservation(obs) {
@@ -35,7 +50,7 @@ export function validateObservation(obs) {
         return {
             valid: false,
             error: `Observation too long (${obs.length} chars). Max ${MAX_OBSERVATION_LENGTH}.`,
-            suggestion: `Split into multiple observations.`
+            suggestion: `Split into atomic facts.`
         };
     }
     const sentenceCount = countSentences(obs);
@@ -62,15 +77,20 @@ export function validateEntityRelations(entity) {
     return { valid: true };
 }
 /**
- * Validates that relation targets exist in the same request
+ * Validates that relation targets exist in the same request or in existing entities
+ * @param entity The entity whose relations to validate
+ * @param allEntityNames Set of entity names in the current request
+ * @param existingEntityNames Optional set of entity names that already exist in storage (for cross-thread references)
  */
-export function validateRelationTargets(entity, allEntityNames) {
+export function validateRelationTargets(entity, allEntityNames, existingEntityNames) {
     for (const relation of entity.relations) {
-        if (!allEntityNames.has(relation.targetEntity)) {
+        const targetInCurrentBatch = allEntityNames.has(relation.targetEntity);
+        const targetInExisting = existingEntityNames?.has(relation.targetEntity) ?? false;
+        if (!targetInCurrentBatch && !targetInExisting) {
             return {
                 valid: false,
-                error: `Target entity '${relation.targetEntity}' not found in request`,
-                suggestion: `targetEntity must reference another entity in the same save_memory call`
+                error: `Target entity '${relation.targetEntity}' not found in request or existing entities`,
+                suggestion: `targetEntity must reference another entity in the same save_memory call or an existing entity`
             };
         }
     }
@@ -99,15 +119,23 @@ export function normalizeEntityType(entityType) {
     }
     return { normalized, warnings };
 }
-export function validateSaveMemoryRequest(entities) {
+/**
+ * Validates all aspects of a save_memory request
+ * @param entities The entities to validate
+ * @param existingEntityNames Optional set of entity names that already exist in storage (for cross-thread references)
+ */
+export function validateSaveMemoryRequest(entities, existingEntityNames) {
     const errors = [];
     const warnings = [];
     // Collect all entity names for relation validation
     const entityNames = new Set(entities.map(e => e.name));
-    for (const entity of entities) {
+    for (let entityIndex = 0; entityIndex < entities.length; entityIndex++) {
+        const entity = entities[entityIndex];
         // Validate entity type and collect warnings
+        // Note: entityType is normalized in-place for consistency with existing behavior
+        // The normalized value is used throughout the rest of validation and saving
         const { normalized, warnings: typeWarnings } = normalizeEntityType(entity.entityType);
-        entity.entityType = normalized; // Apply normalization
+        entity.entityType = normalized; // Apply normalization (intentional mutation for consistency)
         warnings.push(...typeWarnings);
         // Validate observations (note: observations are still strings in SaveMemoryEntity input)
         for (let i = 0; i < entity.observations.length; i++) {
@@ -115,8 +143,12 @@ export function validateSaveMemoryRequest(entities) {
             if (!obsResult.valid) {
                 errors.push({
                     entity: entity.name,
+                    entityIndex: entityIndex,
+                    entityType: entity.entityType,
                     error: `Observation ${i + 1}: ${obsResult.error}`,
-                    suggestion: obsResult.suggestion
+                    suggestion: obsResult.suggestion,
+                    observationPreview: entity.observations[i].substring(0, OBSERVATION_PREVIEW_LENGTH) +
+                        (entity.observations[i].length > OBSERVATION_PREVIEW_LENGTH ? '...' : '')
                 });
             }
         }
@@ -125,15 +157,19 @@ export function validateSaveMemoryRequest(entities) {
         if (!relResult.valid) {
             errors.push({
                 entity: entity.name,
+                entityIndex: entityIndex,
+                entityType: entity.entityType,
                 error: relResult.error || 'Invalid relations',
                 suggestion: relResult.suggestion
             });
         }
-        // Validate relation targets
-        const targetResult = validateRelationTargets(entity, entityNames);
+        // Validate relation targets (now supports cross-thread references)
+        const targetResult = validateRelationTargets(entity, entityNames, existingEntityNames);
         if (!targetResult.valid) {
             errors.push({
                 entity: entity.name,
+                entityIndex: entityIndex,
+                entityType: entity.entityType,
                 error: targetResult.error || 'Invalid relation target',
                 suggestion: targetResult.suggestion
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "server-memory-enhanced",
-  "version": "2.2.1",
+  "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",