collective-memory-mcp 0.3.2 → 0.5.0

package/README.md

@@ -34,6 +34,24 @@ Add to your Claude Desktop MCP configuration (`~/.config/Claude/claude_desktop_c
 
 The `-y` flag suppresses the npx prompt and auto-installs the latest version.
 
+## System Prompt (Recommended)
+
+Add this to your Claude system prompt to ensure agents know about the Collective Memory:
+
+```
+You have access to a Collective Memory MCP Server that stores knowledge from previous tasks.
+
+BEFORE starting work, search for similar past tasks using:
+- search_collective_memory
+- find_similar_procedures
+
+AFTER completing any task, document it using:
+- record_task_completion
+
+When writing observations, be SPECIFIC and include facts like file paths, versions,
+metrics, and error messages. Avoid vague statements like "works well" or "fixed bugs".
+```
+
 ## Entity Types
 
 | Type | Description |
@@ -118,10 +136,10 @@ const result = await session.callTool("find_similar_procedures", {
 
 ## Database
 
-The server uses SQLite for persistence (via `better-sqlite3`). The database is stored at:
+The server uses JSON file storage for persistence. Data is stored at:
 
 ```
-~/.collective-memory/memory.db
+~/.collective-memory/memory.json
 ```
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "collective-memory-mcp",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "A persistent, graph-based memory system for AI agents (MCP Server)",
   "type": "module",
   "main": "src/server.js",

package/src/server.js

@@ -9,6 +9,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { getStorage } from "./storage.js";
 import { Entity, Relation, ENTITY_TYPES, RELATION_TYPES } from "./models.js";
@@ -27,6 +29,7 @@ function createServer() {
     {
       capabilities: {
         tools: {},
+        prompts: {},
       },
     }
   );
@@ -227,15 +230,16 @@ function createServer() {
         {
           name: "search_collective_memory",
           description:
-            "Search for relevant past work based on a natural language query. " +
-            "Search scope includes entity names, entity types, all observation content, and relation types. " +
-            "Returns entities with their immediate relations, ordered by relevance.",
+            "**Search all past work** - Use before starting a task to learn from previous solutions. " +
+            "Searches entity names, types, and all observation content. " +
+            "Returns matching entities with their relations. " +
+            "Use find_similar_procedures for more detailed results with artifacts.",
           inputSchema: {
             type: "object",
             properties: {
               query: {
                 type: "string",
-                description: "Natural language search query",
+                description: "What are you looking for? (e.g., 'authentication', 'CORS fix', 'database')",
               },
             },
             required: ["query"],
@@ -262,33 +266,48 @@ function createServer() {
         {
           name: "record_task_completion",
           description:
-            "[Primary tool for agents] Document a completed task with full context. " +
-            "Automatically creates the task entity, agent entity if needed, all artifact entities, " +
-            "and establishes all relevant relations (executed_by, created, modified, part_of). " +
-            "Returns the complete task node with all relations.",
+            "**PRIMARY TOOL - Use this after completing any task** Document completed work with full context. " +
+            "Automatically creates task entity, agent entity, artifacts, and relations. " +
+            "" +
+            "**GUIDELINES FOR observations:** " +
+            "- Be SPECIFIC: 'Added JWT with 1-hour expiry' not 'Added auth' " +
+            "- Include FACTS: file paths, versions, metrics, error messages " +
+            "- Be ATOMIC: One fact per observation " +
+            "- BAD: 'Works well', 'Fixed bugs', 'Good code' " +
+            "- GOOD: 'API response time reduced from 500ms to 120ms', 'Fixed CORS by adding Origin header' " +
+            "" +
+            "**Parameters:** " +
+            "- agent_name: Your identifier (e.g., 'Agent_Backend_Developer') " +
+            "- task_name: Unique descriptive name (e.g., 'Task_Add_JWT_Auth_20241224') " +
+            "- task_type: Type (implementation/debugging/refactoring/testing) " +
+            "- description: High-level summary " +
+            "- observations: Array of specific facts (see guidelines above) " +
+            "- created_artifacts: Files/code created with their observations " +
+            "- modified_structures: Architectural changes " +
+            "- session_id: Optional - groups related tasks together",
           inputSchema: {
             type: "object",
             properties: {
               agent_name: {
                 type: "string",
-                description: "Name of the agent completing the task",
+                description: "Your identifier (e.g., 'Agent_Backend_Developer')",
               },
               task_name: {
                 type: "string",
-                description: "Unique name for the task",
+                description: "Unique descriptive name (e.g., 'Task_Add_JWT_Auth_20241224')",
               },
               task_type: {
                 type: "string",
-                description: "Type of task (e.g., implementation, debugging, refactoring)",
+                description: "Type: implementation, debugging, refactoring, testing, etc.",
               },
               description: {
                 type: "string",
-                description: "High-level description of what was accomplished",
+                description: "High-level summary of what was accomplished",
               },
               observations: {
                 type: "array",
                 items: { type: "string" },
-                description: "Detailed observations about the task execution",
+                description: "Specific facts about the work. Be atomic and detailed. Include paths, versions, metrics.",
               },
               created_artifacts: {
                 type: "array",
@@ -303,7 +322,7 @@ function createServer() {
                   },
                   required: ["name"],
                 },
-                description: "Artifacts created during the task",
+                description: "Files, code, or configs you created",
               },
               modified_structures: {
                 type: "array",
@@ -318,11 +337,11 @@ function createServer() {
                   },
                   required: ["name"],
                 },
-                description: "Structures modified during the task",
+                description: "Architectural patterns or structures that changed",
               },
               session_id: {
                 type: "string",
-                description: "Optional session identifier",
+                description: "Optional session identifier to group related tasks",
               },
             },
             required: ["agent_name", "task_name"],
@@ -331,15 +350,16 @@ function createServer() {
         {
           name: "find_similar_procedures",
           description:
-            "Search for tasks that match a procedural query and return their full implementation details. " +
-            "Searches task entities and observations. Returns complete subgraphs (tasks + related artifacts + structures). " +
-            "Sorted by relevance and recency.",
+            "**Use BEFORE starting work** - Find how similar tasks were solved previously. " +
+            "Returns complete implementation details including artifacts and structures. " +
+            "Learn from past solutions before implementing new features. " +
+            "Query examples: 'authentication', 'database migration', 'API design', 'error handling'.",
           inputSchema: {
             type: "object",
             properties: {
               query: {
                 type: "string",
-                description: "Procedural search query (e.g., 'authentication implementation')",
+                description: "What are you trying to do? (e.g., 'authentication implementation', 'database migration')",
               },
             },
             required: ["query"],
@@ -349,6 +369,299 @@ function createServer() {
     };
   });
 
+  // ========== Prompts ==========
+
+  /**
+   * Available prompts that guide agents on using the collective memory system
+   */
+  const PROMPTS = [
+    {
+      name: "task-documentation-guide",
+      description: "Guide for documenting completed tasks in the collective memory",
+      arguments: [],
+    },
+    {
+      name: "search-workflow-guide",
+      description: "Guide for searching and learning from past work",
+      arguments: [],
+    },
+    {
+      name: "getting-started",
+      description: "Introduction to the Collective Memory System for agents",
+      arguments: [],
+    },
+    {
+      name: "observation-best-practices",
+      description: "Best practices for writing effective observations",
+      arguments: [],
+    },
+  ];
+
+  /**
+   * List available prompts
+   */
+  server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return { prompts: PROMPTS };
+  });
+
+  /**
+   * Get a specific prompt
+   */
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    const prompts = {
+      "task-documentation-guide": {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `# Collective Memory: Task Documentation Guide
+
+When you complete a task, document it using the \`record_task_completion\` tool.
+
+## Required Parameters:
+- \`agent_name\`: Your identifier (e.g., "Agent_Backend_Developer")
+- \`task_name\`: Unique, descriptive name (e.g., "Task_Add_JWT_Auth_20241224")
+
+## Optional but Recommended:
+- \`task_type\`: Type of work (implementation, debugging, refactoring, testing, etc.)
+- \`description\`: High-level summary of what was accomplished
+- \`observations\`: Array of specific, atomic facts about the work
+- \`created_artifacts\`: Files, code, configs created
+- \`modified_structures\`: Architectural patterns or structures changed
+- \`session_id\`: Session identifier to group related tasks
+
+## Writing Good Observations:
+
+✅ **Good observations** (specific, actionable):
+- "API uses JWT tokens with 1-hour expiry"
+- "Database schema includes composite index on (user_id, created_at)"
+- "Deployment succeeded after adding 2GB RAM to container"
+- "Error handling uses custom exception hierarchy from exceptions.py"
+
+❌ **Poor observations** (vague, subjective):
+- "API works well"
+- "Database is fast"
+- "Fixed some bugs"
+- "Good code structure"
+
+## Example:
+
+\`\`\`json
+{
+  "agent_name": "Agent_Backend_Developer",
+  "task_name": "Task_Implement_Pagination_20241224",
+  "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",
+    "Backward compatibility maintained with offset-based fallback"
+  ],
+  "created_artifacts": [
+    {
+      "name": "Artifact_Pagination_Middleware",
+      "observations": ["Located at /src/middleware/pagination.js", "Handles cursor encoding/decoding"]
+    }
+  ]
+}
+\`\`\``,
+            },
+          },
+        ],
+      },
+
+      "search-workflow-guide": {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `# Collective Memory: Search Workflow Guide
+
+Before starting a task, search the collective memory to learn from past work.
+
+## When to Search:
+1. **Before implementing** a feature - check if similar work was done
+2. **When debugging** - find how similar issues were resolved
+3. **When refactoring** - understand existing architectural patterns
+4. **When choosing libraries** - see what's been used successfully
+
+## Search Tools:
+
+### \`search_collective_memory\`
+Natural language search across all entities and observations.
+\`\`\`json
+{ "query": "authentication implementation" }
+\`\`\`
+
+### \`find_similar_procedures\`
+Returns complete implementation details including artifacts and structures.
+\`\`\`json
+{ "query": "database migration" }
+\`\`\`
+
+### \`open_nodes\`
+Retrieve specific entities by exact name.
+\`\`\`json
+{ "names": ["Task_JWT_Auth", "Artifact_Auth_Middleware"] }
+\`\`\`
+
+### \`read_graph\`
+Export the entire knowledge graph for analysis.
+
+## Search Strategy:
+1. Start with broad natural language queries
+2. Use \`find_similar_procedures\` to get full context
+3. Examine related entities (artifacts, structures)
+4. Look for patterns in observations (errors, solutions, decisions)
+
+## Example Workflow:
+\`\`\`
+1. search_collective_memory: "user authentication"
+2. find_similar_procedures: "JWT implementation"
+3. Review returned artifacts and structures
+4. Adapt patterns to current task
+5. Document new task with record_task_completion
+\`\`\``,
+            },
+          },
+        ],
+      },
+
+      "getting-started": {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `# Collective Memory System - Quick Start
+
+You are connected to the Collective Memory System, a persistent knowledge graph that helps AI agents learn from each other's work.
+
+## Key Concepts:
+
+**Entities** are nodes in the knowledge graph:
+- **agent**: An AI agent (you or other agents)
+- **task**: A unit of completed work
+- **artifact**: Concrete output (file, code, config)
+- **structure**: Architectural pattern or decision
+- **session**: Groups related tasks
+
+**Relations** connect entities:
+- executed_by, created, modified, documented, depends_on, part_of, similar_to, uses, implements
+
+## Your Workflow:
+
+1. **Before starting** → Search for similar past work
+   - Use \`search_collective_memory\` or \`find_similar_procedures\`
+
+2. **While working** → Learn from patterns
+   - Review how similar tasks were solved
+   - Examine artifacts and structures
+
+3. **After completing** → Document your work
+   - Use \`record_task_completion\` with specific observations
+
+## Available Tools:
+- \`record_task_completion\` - Document completed work (PRIMARY)
+- \`search_collective_memory\` - Natural language search
+- \`find_similar_procedures\` - Find similar tasks with full context
+- \`read_graph\` - Export entire knowledge graph
+- \`create_entities\` - Create new entities
+- \`create_relations\` - Connect entities
+- \`open_nodes\` - Retrieve specific entities
+
+## Best Practices:
+- Write specific, atomic observations
+- Include file paths, versions, metrics
+- Document both successes and failures
+- Link related artifacts and structures
+
+The system persists all data in ~/.collective-memory/memory.json`,
+            },
+          },
+        ],
+      },
+
+      "observation-best-practices": {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `# Collective Memory: Observation Best Practices
+
+Observations are the heart of the collective memory. Write them well to help future agents.
+
+## Characteristics of Good Observations:
+
+1. **Atomic** - One fact per observation
+2. **Specific** - Include concrete details (versions, paths, metrics)
+3. **Actionable** - Provide enough context to replicate or understand
+4. **Time-bound** - Include timestamps or relative time when relevant
+
+## Examples by Category:
+
+### Code Changes:
+✅ "Added JWT validation middleware at /src/auth/jwt.js"
+✅ "Refactored user service to use dependency injection pattern"
+❌ "Improved code quality"
+
+### Configuration:
+✅ "Set JWT expiry to 3600 seconds (1 hour)"
+✅ "Enabled CORS for https://example.com in production config"
+❌ "Configured settings"
+
+### Errors & Fixes:
+✅ "Fixed CORS error by adding Origin header to allowed list"
+✅ "Resolved memory leak by properly closing database connections"
+❌ "Fixed bugs"
+
+### Performance:
+✅ "Reduced API response time from 500ms to 120ms by adding Redis cache"
+✅ "Optimized database query by adding composite index on (user_id, created_at)"
+❌ "Made it faster"
+
+### Decisions:
+✅ "Chose PostgreSQL over MySQL for JSONB support"
+✅ "Used WebSockets instead of polling for real-time updates"
+❌ "Good technical choices"
+
+### Dependencies:
+✅ "Upgraded lodash from 4.17.15 to 4.17.21 for security fix"
+✅ "Added bcrypt@5.1.1 for password hashing (cost factor: 12)"
+❌ "Updated packages"
+
+## Template for Complex Tasks:
+
+For each significant task, include observations about:
+1. **What was changed** - Specific files, functions, configs
+2. **Why it was done** - Reasoning behind decisions
+3. **How it works** - Key implementation details
+4. **Edge cases handled** - Special conditions addressed
+5. **Testing done** - How it was verified
+6. **Known limitations** - Any remaining issues
+
+## Remember:
+Future agents will read your observations to learn. Write for them, not for yourself.`,
+            },
+          },
+        ],
+      },
+    };
+
+    const prompt = prompts[name];
+    if (!prompt) {
+      throw new Error(`Unknown prompt: ${name}`);
+    }
+
+    return prompt;
+  });
+
   /**
    * Handle tool calls
    */