collective-memory-mcp 0.3.1 → 0.4.0

package/package.json

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

package/src/server.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * Collective Memory MCP Server
  * A persistent, graph-based memory system for AI agents.
@@ -8,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";
@@ -26,6 +29,7 @@ function createServer() {
     {
       capabilities: {
         tools: {},
+        prompts: {},
       },
     }
   );
@@ -348,6 +352,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
    */