collective-memory-mcp 0.6.3 → 0.6.5

package/README.md

@@ -42,9 +42,9 @@ 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)
+## System Prompt (Required)
 
-Add this to your Claude system prompt to ensure agents know about the Collective Memory:
+This MCP server does NOT automatically inject its instructions into new chats. You MUST manually add this to your Claude/AI system prompt:
 
 ```
 You have access to a Collective Memory MCP Server that stores knowledge from previous tasks.
@@ -56,13 +56,18 @@ BEFORE starting work, search for similar past tasks using:
 The search uses TF-IDF vector embeddings, so it finds relevant content even when different
 terminology is used. Results are ranked by similarity score.
 
-AFTER completing any task, document it using:
+AFTER completing any task (like any, it doesn't matter even if you answer a question), 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".
+
+In new chats, call getting_started tool to learn about the system.
+Use task_documentation_guide, search_workflow_guide, and observation_best_practices for detailed guidance.
 ```
 
+**Important:** This system prompt must be manually configured in your AI client. The MCP protocol does not support automatic prompt injection on connection.
+
 ## How Vector Search Works
 
 This system uses **TF-IDF (Term Frequency-Inverse Document Frequency)** vector search:
@@ -123,6 +128,13 @@ No configuration needed - it just works!
 - **record_task_completion** - Primary tool for documenting completed work
 - **find_similar_procedures** - Find similar tasks with full implementation details
 
+### Guidance
+
+- **getting_started** - Introduction to the Collective Memory System (call in new chats)
+- **task_documentation_guide** - How to document completed tasks properly
+- **search_workflow_guide** - How to search and learn from past work
+- **observation_best_practices** - How to write effective observations
+
 ## Example Usage
 
 ### Recording a Task Completion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "collective-memory-mcp",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "A persistent, graph-based memory system for AI agents with TF-IDF vector search (MCP Server)",
   "type": "module",
   "main": "src/server.js",

package/src/server.js

@@ -366,6 +366,46 @@ async function createServer() {
             required: ["query"],
           },
         },
+        {
+          name: "getting_started",
+          description:
+            "**Call this in new chats** - Introduction to the Collective Memory System. " +
+            "Explains key concepts (entities, relations), your workflow (search, learn, document), and best practices.",
+          inputSchema: {
+            type: "object",
+            properties: {},
+          },
+        },
+        {
+          name: "task_documentation_guide",
+          description:
+            "Guide for documenting completed tasks in the collective memory. " +
+            "Shows required parameters, how to write good observations, and includes examples.",
+          inputSchema: {
+            type: "object",
+            properties: {},
+          },
+        },
+        {
+          name: "search_workflow_guide",
+          description:
+            "Guide for searching and learning from past work. " +
+            "Covers when to search, available search tools, and example workflows.",
+          inputSchema: {
+            type: "object",
+            properties: {},
+          },
+        },
+        {
+          name: "observation_best_practices",
+          description:
+            "Best practices for writing effective observations. " +
+            "Shows characteristics of good observations with examples by category.",
+          inputSchema: {
+            type: "object",
+            properties: {},
+          },
+        },
       ],
     };
   });
@@ -704,6 +744,232 @@ Future agents will read your observations to learn. Write for them, not for your
         case "find_similar_procedures":
           return { content: [{ type: "text", text: JSON.stringify(await findSimilarProcedures(args), null, 2) }] };
 
+        case "getting_started":
+          return {
+            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`,
+            }],
+          };
+
+        case "task_documentation_guide":
+          return {
+            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"]
+    }
+  ]
+}
+\`\`\``,
+            }],
+          };
+
+        case "search_workflow_guide":
+          return {
+            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
+\`\`\``,
+            }],
+          };
+
+        case "observation_best_practices":
+          return {
+            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.`,
+            }],
+          };
+
         default:
           throw new Error(`Unknown tool: ${name}`);
       }