server-memory-enhanced 2.3.0 → 2.3.2

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/analysis/analytics-service.js

@@ -0,0 +1,111 @@
+/**
+ * Analytics service for thread-specific metrics
+ */
+/**
+ * Calculate recent changes for a thread
+ */
+function calculateRecentChanges(threadEntities) {
+    return threadEntities
+        .map(e => ({
+        entityName: e.name,
+        entityType: e.entityType,
+        lastModified: e.timestamp,
+        changeType: 'created' // Simplified: all are 'created' for now
+    }))
+        .sort((a, b) => b.lastModified.localeCompare(a.lastModified))
+        .slice(0, 10);
+}
+/**
+ * Calculate top important entities for a thread
+ */
+function calculateTopImportant(threadEntities) {
+    return threadEntities
+        .map(e => ({
+        entityName: e.name,
+        entityType: e.entityType,
+        importance: e.importance,
+        observationCount: e.observations.length
+    }))
+        .sort((a, b) => b.importance - a.importance)
+        .slice(0, 10);
+}
+/**
+ * Calculate most connected entities for a thread
+ */
+function calculateMostConnected(threadEntities, entityRelationCounts) {
+    return Array.from(entityRelationCounts.entries())
+        .map(([entityName, connectedSet]) => {
+        const entity = threadEntities.find(e => e.name === entityName);
+        return {
+            entityName,
+            entityType: entity.entityType,
+            relationCount: connectedSet.size,
+            connectedTo: Array.from(connectedSet)
+        };
+    })
+        .sort((a, b) => b.relationCount - a.relationCount)
+        .slice(0, 10);
+}
+/**
+ * Calculate orphaned entities for a thread
+ */
+function calculateOrphanedEntities(threadEntities, threadRelations, entityRelationCounts) {
+    const orphaned_entities = [];
+    const allEntityNames = new Set(threadEntities.map(e => e.name));
+    for (const entity of threadEntities) {
+        const relationCount = entityRelationCounts.get(entity.name)?.size || 0;
+        if (relationCount === 0) {
+            orphaned_entities.push({
+                entityName: entity.name,
+                entityType: entity.entityType,
+                reason: 'no_relations'
+            });
+        }
+        else {
+            // Check for broken relations (pointing to non-existent entities)
+            const entityRelations = threadRelations.filter(r => r.from === entity.name || r.to === entity.name);
+            const hasBrokenRelation = entityRelations.some(r => !allEntityNames.has(r.from) || !allEntityNames.has(r.to));
+            if (hasBrokenRelation) {
+                orphaned_entities.push({
+                    entityName: entity.name,
+                    entityType: entity.entityType,
+                    reason: 'broken_relation'
+                });
+            }
+        }
+    }
+    return orphaned_entities;
+}
+/**
+ * Get analytics for a specific thread (limited to 4 core metrics)
+ */
+export async function getAnalytics(storage, threadId) {
+    const graph = await storage.loadGraph();
+    // Filter to thread-specific data
+    const threadEntities = graph.entities.filter(e => e.agentThreadId === threadId);
+    const threadRelations = graph.relations.filter(r => r.agentThreadId === threadId);
+    // Calculate all metrics
+    const recent_changes = calculateRecentChanges(threadEntities);
+    const top_important = calculateTopImportant(threadEntities);
+    // Build the relation counts map once for both most_connected and orphaned_entities
+    const entityRelationCounts = new Map();
+    for (const entity of threadEntities) {
+        entityRelationCounts.set(entity.name, new Set());
+    }
+    for (const relation of threadRelations) {
+        if (entityRelationCounts.has(relation.from)) {
+            entityRelationCounts.get(relation.from).add(relation.to);
+        }
+        if (entityRelationCounts.has(relation.to)) {
+            entityRelationCounts.get(relation.to).add(relation.from);
+        }
+    }
+    const most_connected = calculateMostConnected(threadEntities, entityRelationCounts);
+    const orphaned_entities = calculateOrphanedEntities(threadEntities, threadRelations, entityRelationCounts);
+    return {
+        recent_changes,
+        top_important,
+        most_connected,
+        orphaned_entities
+    };
+}

package/dist/lib/analysis/conflict-detector.js

@@ -0,0 +1,48 @@
+/**
+ * Conflict detection service
+ */
+import { hasNegation, NEGATION_WORDS } from '../utils/negation-detector.js';
+/**
+ * Detect conflicting observations within entities
+ * Identifies potential contradictions by checking for negation patterns
+ */
+export async function detectConflicts(storage) {
+    const graph = await storage.loadGraph();
+    const conflicts = [];
+    for (const entity of graph.entities) {
+        const entityConflicts = [];
+        for (let i = 0; i < entity.observations.length; i++) {
+            for (let j = i + 1; j < entity.observations.length; j++) {
+                const obs1Content = entity.observations[i].content.toLowerCase();
+                const obs2Content = entity.observations[j].content.toLowerCase();
+                // Skip if observations are in the same version chain
+                if (entity.observations[i].supersedes === entity.observations[j].id ||
+                    entity.observations[j].supersedes === entity.observations[i].id ||
+                    entity.observations[i].superseded_by === entity.observations[j].id ||
+                    entity.observations[j].superseded_by === entity.observations[i].id) {
+                    continue;
+                }
+                // Check for negation patterns
+                const obs1HasNegation = hasNegation(obs1Content);
+                const obs2HasNegation = 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);
+                    const words2Set = new Set(obs2Content.split(/\s+/).filter(w => w.length > 3));
+                    const commonWords = words1.filter(w => words2Set.has(w) && !NEGATION_WORDS.has(w));
+                    if (commonWords.length >= 2) {
+                        entityConflicts.push({
+                            obs1: entity.observations[i].content,
+                            obs2: entity.observations[j].content,
+                            reason: 'Potential contradiction with negation'
+                        });
+                    }
+                }
+            }
+        }
+        if (entityConflicts.length > 0) {
+            conflicts.push({ entityName: entity.name, conflicts: entityConflicts });
+        }
+    }
+    return conflicts;
+}

package/dist/lib/analysis/context-builder.js

@@ -0,0 +1,31 @@
+/**
+ * Context builder service
+ */
+/**
+ * Get context (entities related to specified entities up to a certain depth)
+ * Expands to include related entities up to specified depth
+ */
+export async function getContext(storage, entityNames, depth = 1) {
+    const graph = await storage.loadGraph();
+    const contextEntityNames = new Set(entityNames);
+    // Expand to include related entities up to specified depth
+    for (let d = 0; d < depth; d++) {
+        const currentEntities = Array.from(contextEntityNames);
+        for (const entityName of currentEntities) {
+            // Find all relations involving this entity
+            const relatedRelations = graph.relations.filter(r => r.from === entityName || r.to === entityName);
+            // Add related entities
+            relatedRelations.forEach(r => {
+                contextEntityNames.add(r.from);
+                contextEntityNames.add(r.to);
+            });
+        }
+    }
+    // Get all entities and relations in context
+    const contextEntities = graph.entities.filter(e => contextEntityNames.has(e.name));
+    const contextRelations = graph.relations.filter(r => contextEntityNames.has(r.from) && contextEntityNames.has(r.to));
+    return {
+        entities: contextEntities,
+        relations: contextRelations
+    };
+}

package/dist/lib/analysis/memory-stats.js

@@ -0,0 +1,63 @@
+/**
+ * Memory statistics service
+ */
+/**
+ * Get comprehensive memory statistics
+ */
+export async function getMemoryStats(storage) {
+    const graph = await storage.loadGraph();
+    // Count entity types
+    const entityTypes = {};
+    graph.entities.forEach(e => {
+        entityTypes[e.entityType] = (entityTypes[e.entityType] || 0) + 1;
+    });
+    // Calculate averages
+    const avgConfidence = graph.entities.length > 0
+        ? graph.entities.reduce((sum, e) => sum + e.confidence, 0) / graph.entities.length
+        : 0;
+    const avgImportance = graph.entities.length > 0
+        ? graph.entities.reduce((sum, e) => sum + e.importance, 0) / graph.entities.length
+        : 0;
+    // Count unique threads
+    const threads = new Set([
+        ...graph.entities.map(e => e.agentThreadId),
+        ...graph.relations.map(r => r.agentThreadId)
+    ]);
+    // Recent activity (last 7 days, grouped by day)
+    const now = new Date();
+    const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
+    const recentEntities = graph.entities.filter(e => new Date(e.timestamp) >= sevenDaysAgo);
+    // Group by day
+    const activityByDay = {};
+    recentEntities.forEach(e => {
+        const day = e.timestamp.substring(0, 10); // YYYY-MM-DD
+        activityByDay[day] = (activityByDay[day] || 0) + 1;
+    });
+    const recentActivity = Object.entries(activityByDay)
+        .map(([timestamp, entityCount]) => ({ timestamp, entityCount }))
+        .sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+    return {
+        entityCount: graph.entities.length,
+        relationCount: graph.relations.length,
+        threadCount: threads.size,
+        entityTypes,
+        avgConfidence,
+        avgImportance,
+        recentActivity
+    };
+}
+/**
+ * Get recent changes since a specific timestamp
+ */
+export async function getRecentChanges(storage, since) {
+    const graph = await storage.loadGraph();
+    const sinceDate = new Date(since);
+    // Only return entities and relations that were actually modified since the specified time
+    const recentEntities = graph.entities.filter(e => new Date(e.timestamp) >= sinceDate);
+    // Only include relations that are recent themselves
+    const recentRelations = graph.relations.filter(r => new Date(r.timestamp) >= sinceDate);
+    return {
+        entities: recentEntities,
+        relations: recentRelations
+    };
+}