collective-memory-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,29 +1,32 @@
-# Collective Memory MCP - npx Wrapper
+# Collective Memory MCP Server
 
-This package provides an `npx` wrapper for the Collective Memory MCP Server, making it easy to run without manually installing Python dependencies.
+A persistent, graph-based memory system that enables AI agents to document their work and learn from each other's experiences. This system transforms ephemeral agent interactions into a searchable knowledge base of structural patterns, solutions, and methodologies.
 
-## Usage
+## Overview
+
+The Collective Memory System is designed for multi-agent environments where agents need to:
+
+- Document their completed work for future reference
+- Discover how similar tasks were solved previously
+- Learn from the structural patterns and approaches of other agents
+- Coordinate across parallel executions without duplicating effort
+
+## Installation
 
 ```bash
 npx collective-memory-mcp
 ```
 
-On first run, the wrapper will automatically:
-1. Detect Python on your system
-2. Install the `collective-memory-mcp` Python package via pip
-3. Start the MCP server
-
 ## Claude Desktop Configuration
 
+Add to your Claude Desktop MCP configuration (`~/.config/Claude/claude_desktop_config.json` on macOS/Linux or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
 ```json
 {
   "mcpServers": {
     "collective-memory": {
       "command": "npx",
-      "args": ["-y", "collective-memory-mcp"],
-      "env": {
-        "COLLECTIVE_MEMORY_DB_PATH": "/path/to/memory.db"
-      }
+      "args": ["-y", "collective-memory-mcp"]
     }
   }
 }
@@ -31,21 +34,100 @@ On first run, the wrapper will automatically:
 
 The `-y` flag suppresses the npx prompt and auto-installs the latest version.
 
-## Requirements
+## Entity Types
 
-- Node.js 16+
-- Python 3.10+
+| Type | Description |
+|------|-------------|
+| `agent` | Represents an autonomous AI agent |
+| `task` | A unit of work completed by an agent |
+| `structure` | Architectural decisions or code patterns |
+| `artifact` | Concrete outputs like files or configurations |
+| `session` | A continuous work context grouping related tasks |
 
-## Manual Python Installation
+## Relation Types
 
-If automatic installation fails, install manually:
+| Type | From -> To | Description |
+|------|------------|-------------|
+| `executed_by` | Task -> Agent | Links task to executing agent |
+| `created` | Task -> Artifact | Task produced an artifact |
+| `modified` | Task -> Structure | Task changed existing structure |
+| `documented` | Task -> Structure | Task defined a structure |
+| `depends_on` | Task -> Task | Task dependency |
+| `part_of` | Task -> Session | Groups tasks in session |
+| `similar_to` | Task -> Task | Similar problem solutions |
+| `uses` | Task -> Artifact | Task consumed artifact |
+| `implements` | Artifact -> Structure | Artifact implements structure |
 
-```bash
-pip install collective-memory-mcp
+## API Tools
+
+### Entity Management
+
+- **create_entities** - Create multiple new entities
+- **delete_entities** - Remove entities with cascade delete
+- **add_observations** - Add observations to existing entities
+- **delete_observations** - Remove specific observations
+
+### Relation Management
+
+- **create_relations** - Create directed relations between entities
+- **delete_relations** - Remove specific relations
+
+### Query & Search
+
+- **read_graph** - Read entire knowledge graph
+- **search_collective_memory** - Natural language search
+- **open_nodes** - Retrieve specific nodes by name
+
+### Agent Workflow
+
+- **record_task_completion** - Primary tool for documenting completed work
+- **find_similar_procedures** - Find similar tasks with full implementation details
+
+## Example Usage
+
+### Recording a Task Completion
+
+```javascript
+await session.callTool("record_task_completion", {
+  agent_name: "Agent_Backend_Developer",
+  task_name: "Task_Implement_Pagination",
+  task_type: "implementation",
+  description: "Added cursor-based pagination to all list endpoints",
+  observations: [
+    "Used keyset pagination pattern for better performance",
+    "Cursor encodes last_seen_id and last_seen_timestamp",
+    "Default page size: 50 items, max: 200"
+  ],
+  created_artifacts: [
+    {
+      name: "Artifact_Pagination_Middleware",
+      observations: ["Located at /src/middleware/pagination.js"]
+    }
+  ],
+  session_id: "Session_API_Performance_Optimization"
+});
 ```
 
-Then run directly with Python:
+### Finding Similar Procedures
 
-```bash
-python -m collective_memory
+```javascript
+const result = await session.callTool("find_similar_procedures", {
+  query: "authentication implementation"
+});
 ```
+
+## Database
+
+The server uses SQLite for persistence (via `better-sqlite3`). The database is stored at:
+
+```
+~/.collective-memory/memory.db
+```
+
+## Requirements
+
+- Node.js 18+
+
+## License
+
+MIT

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "collective-memory-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A persistent, graph-based memory system for AI agents (MCP Server)",
   "type": "module",
+  "main": "src/server.js",
   "bin": {
-    "collective-memory-mcp": "./index.js"
-  },
-  "npx": {
-    "true": true
+    "collective-memory-mcp": "./src/server.js"
   },
   "scripts": {
-    "postinstall": "python -m pip install collective-memory-mcp || pip3 install collective-memory-mcp || pip install collective-memory-mcp"
+    "start": "node src/server.js",
+    "test": "node src/test.js"
   },
   "keywords": [
     "mcp",
@@ -20,7 +19,8 @@
     "knowledge-graph",
     "collective",
     "anthropic",
-    "claude"
+    "claude",
+    "model-context-protocol"
   ],
   "license": "MIT",
   "repository": {
@@ -29,11 +29,14 @@
   },
   "homepage": "https://github.com/YOUR_USERNAME/collective-memory-mcp#readme",
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   },
   "os": [
     "darwin",
     "linux",
     "win32"
-  ]
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.6.0"
+  }
 }

package/src/models.js

@@ -0,0 +1,89 @@
+/**
+ * Core data models for the Collective Memory System.
+ */
+
+/**
+ * Valid entity types
+ */
+export const ENTITY_TYPES = ["agent", "task", "structure", "artifact", "session"];
+
+/**
+ * Valid relation types
+ */
+export const RELATION_TYPES = [
+  "executed_by",  // Task -> Agent
+  "created",      // Task -> Artifact
+  "modified",     // Task -> Structure
+  "documented",   // Task -> Structure
+  "depends_on",   // Task -> Task
+  "part_of",      // Task -> Session
+  "similar_to",   // Task -> Task
+  "uses",         // Task -> Artifact
+  "implements",   // Artifact -> Structure
+];
+
+/**
+ * Entity class representing a node in the knowledge graph
+ */
+export class Entity {
+  constructor(data = {}) {
+    this.name = data.name || "";
+    this.entityType = data.entityType || data.entity_type || "";
+    this.observations = data.observations || [];
+    this.createdAt = data.createdAt || data.created_at || new Date().toISOString();
+    this.metadata = data.metadata || {};
+  }
+
+  /**
+   * Convert entity to plain object
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      entityType: this.entityType,
+      observations: this.observations,
+      createdAt: this.createdAt,
+      metadata: this.metadata,
+    };
+  }
+
+  /**
+   * Create entity from plain object
+   */
+  static fromJSON(data) {
+    return new Entity(data);
+  }
+}
+
+/**
+ * Relation class representing a directed edge between entities
+ */
+export class Relation {
+  constructor(data = {}) {
+    this.from = data.from || data.from_entity || "";
+    this.to = data.to || data.to_entity || "";
+    this.relationType = data.relationType || data.relation_type || "";
+    this.createdAt = data.createdAt || data.created_at || new Date().toISOString();
+    this.metadata = data.metadata || {};
+  }
+
+  /**
+   * Convert relation to plain object
+   */
+  toJSON() {
+    return {
+      from: this.from,
+      to: this.to,
+      relationType: this.relationType,
+      createdAt: this.createdAt,
+      metadata: this.metadata,
+    };
+  }
+
+  /**
+   * Create relation from plain object
+   */
+  static fromJSON(data) {
+    return new Relation(data);
+  }
+}