collective-memory-mcp 0.4.0 → 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.4.0",
+  "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

@@ -230,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"],
@@ -265,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",
@@ -306,7 +322,7 @@ function createServer() {
                   },
                   required: ["name"],
                 },
-                description: "Artifacts created during the task",
+                description: "Files, code, or configs you created",
               },
               modified_structures: {
                 type: "array",
@@ -321,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"],
@@ -334,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"],