collective-memory-mcp 0.6.4 → 0.7.0

package/README.md

@@ -1,23 +1,35 @@
 # Collective Memory MCP Server
 
-A persistent, graph-based memory system with **vector search** 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.
+> A persistent, graph-based memory system with vector search that enables AI agents to document their work and learn from each other's experiences.
+
+[![npm version](https://badge.fury.io/js/collective-memory-mcp.svg)](https://www.npmjs.org/package/collective-memory-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
 
 ## Overview
 
-The Collective Memory System is designed for multi-agent environments where agents need to:
+Collective Memory transforms ephemeral agent interactions into a searchable knowledge base. It enables AI agents working across multiple projects to:
+
+- **Document** their completed work for future reference
+- **Discover** how similar tasks were solved using vector search
+- **Learn** from structural patterns and approaches of other agents
+- **Organize** knowledge by project for multi-codebase workflows
 
-- Document their completed work for future reference
-- Discover how similar tasks were solved previously using **vector search**
-- Learn from the structural patterns and approaches of other agents
-- Coordinate across parallel executions without duplicating effort
+---
 
-## Key Features
+## Features
 
-- **Vector Search** - TF-IDF based search finds conceptually similar content even when keywords differ
-- **Knowledge Graph** - Entities and relations capture complex relationships
-- **Ranked Results** - Similarity scores help identify the most relevant past work
-- **Zero Configuration** - Works out of the box, no external dependencies or API keys needed
-- **Pure JavaScript** - No native dependencies, works completely offline
+| Feature | Description |
+|---------|-------------|
+| **Vector Search** | TF-IDF based search finds conceptually similar content even when keywords differ |
+| **Knowledge Graph** | Entities and relations capture complex relationships |
+| **Ranked Results** | Similarity scores help identify the most relevant past work |
+| **Multi-Project** | Organize and search knowledge across multiple codebases |
+| **Zero Configuration** | Works out of the box, no external dependencies or API keys needed |
+| **Pure JavaScript** | No native dependencies, works completely offline |
+
+---
 
 ## Installation
 
@@ -25,9 +37,16 @@ The Collective Memory System is designed for multi-agent environments where agen
 npx collective-memory-mcp
 ```
 
-## Claude Desktop Configuration
+---
+
+## 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):
+### Claude Desktop
+
+Add to your Claude Desktop MCP configuration:
+
+**macOS/Linux:** `~/.config/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
@@ -35,110 +54,193 @@ Add to your Claude Desktop MCP configuration (`~/.config/Claude/claude_desktop_c
     "collective-memory": {
       "command": "npx",
       "args": ["-y", "collective-memory-mcp"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
     }
   }
 }
 ```
 
-The `-y` flag suppresses the npx prompt and auto-installs the latest version.
+> **Note:** The `sequential-thinking` MCP server is required for the full workflow. The `-y` flag suppresses the npx prompt and auto-installs the latest version.
 
-## System Prompt (Required)
+---
 
-This MCP server does NOT automatically inject its prompts into new chats. You MUST manually add this to your Claude/AI system prompt:
+## System Prompt
+
+Add this to your AI system prompt:
 
 ```
 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 (vector search - understands meaning, not just keywords)
-- find_similar_procedures (finds similar tasks with full implementation details)
+## SEQUENTIAL THINKING (ALWAYS)
+- Call `mcp_sequential-thinking_sequentialthinking` as your FIRST action in EVERY response
+- Use it to analyze the request, plan your approach, and organize your thoughts
+- Continue calling it until `nextThoughtNeeded: false`
+- This applies to ALL responses: questions, tasks, explanations, debugging, etc.
+- NO EXCEPTIONS - even simple questions benefit from structured thinking
 
-The search uses TF-IDF vector embeddings, so it finds relevant content even when different
-terminology is used. Results are ranked by similarity score.
+## MANDATORY WORKFLOW (Every Chat)
 
-AFTER completing any task (like any, it doesn't matter even if you answer a question), document it using:
-- record_task_completion
+### Phase 1: INIT (First response of every chat)
+1. Call `sequentialthinking` to analyze the user's request
+2. Call `getting_started` tool to load tool knowledge
+3. Acknowledge initialization complete (brief confirmation)
+
+### Phase 2: SEARCH (Before any task)
+- Call `sequentialthinking` to formulate search strategy
+- Call `search_collective_memory` OR `find_similar_procedures` with relevant query
+- Review past solutions before implementing
+
+### Phase 3: WORK
+- Call `sequentialthinking` before each major step
+- Apply learnings from Phase 2
+
+### Phase 4: DOCUMENT (After completing ANY task, including Q&A)
+- Call `sequentialthinking` to summarize what was accomplished
+- Call `record_task_completion` with:
+  - Specific observations (file paths, versions, metrics, error messages)
+  - NO vague statements like "works well" or "fixed bugs"
+
+## ENFORCEMENT
+- Sequential thinking is NON-NEGOTIABLE on EVERY response
+- Phase 1 is NON-NEGOTIABLE on first response of chat
+- Phase 4 applies to ALL completions, no exceptions
+- If you skip any phase, acknowledge the violation and correct immediately
+
+## Available Tools
+
+BEFORE starting work, search for similar past tasks using:
+- `search_collective_memory` - Vector search (understands meaning, not just keywords)
+- `find_similar_procedures` - Find similar tasks with full implementation details
+
+AFTER completing any task (including answering questions), 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".
 
-When to use getPrompt():
-- Use listPrompts() at the start of a new chat to see all available prompt templates
-- Call getPrompt(name) when you need a specific predefined prompt (e.g., "getting-started")
-- Fetch prompts proactively - don't wait for the user to request them
-- This is especially important in new chats where context hasn't been established yet
+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
+## How It Works
 
-This system uses **TF-IDF (Term Frequency-Inverse Document Frequency)** vector search:
+### Vector Search
+
+Uses **TF-IDF (Term Frequency-Inverse Document Frequency)** for semantic-like search:
 
 - Tokenizes text into meaningful terms
 - Calculates term importance based on frequency
 - Uses cosine similarity to rank results
 - Works entirely offline with no external dependencies
 
-No configuration needed - it just works!
+```
+Query: "login" → Finds: "authentication", "JWT", "OAuth", "user session"
+Query: "slow API" → Finds: "performance", "optimization", "caching", "database index"
+```
+
+### Multi-Project Support
+
+Organize knowledge by project when working on multiple codebases:
+
+```javascript
+// Record a task with project context
+await record_task_completion({
+  project: "my-app",
+  task_name: "Task_Add_JWT_Auth",
+  observations: ["Added JWT middleware at /src/auth/jwt.js"]
+})
+
+// Search within a specific project
+await search_collective_memory({
+  project: "my-app",
+  query: "authentication"
+})
+```
+
+---
 
 ## Entity Types
 
 | Type | Description |
 |------|-------------|
-| `agent` | Represents an autonomous AI agent |
+| `agent` | 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 |
+| `project` | Groups tasks by project/repository |
+
+---
 
 ## Relation Types
 
-| Type | From -> To | Description |
+| 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 |
+| `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/Project | Groups tasks in session or project |
+| `similar_to` | Task → Task | Similar problem solutions |
+| `uses` | Task → Artifact | Task consumed artifact |
+| `implements` | Artifact → Structure | Artifact implements structure |
+
+---
 
 ## API Tools
 
+### Core Workflow
+
+| Tool | Purpose |
+|------|---------|
+| `record_task_completion` | **PRIMARY** - Document completed work with full context |
+| `search_collective_memory` | Vector search with ranked results |
+| `find_similar_procedures` | Find similar tasks with full implementation details |
+
 ### 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
+| Tool | Purpose |
+|------|---------|
+| `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
+| Tool | Purpose |
+|------|---------|
+| `create_relations` | Create directed relations between entities |
+| `delete_relations` | Remove specific relations |
 
-### Query & Search
+### Query & Guidance
 
-- **read_graph** - Read entire knowledge graph
-- **search_collective_memory** - Vector search with ranked results
-- **open_nodes** - Retrieve specific nodes by name
+| Tool | Purpose |
+|------|---------|
+| `read_graph` | Read entire knowledge graph |
+| `open_nodes` | Retrieve specific nodes by name |
+| `getting_started` | Introduction to the system |
+| `task_documentation_guide` | How to document completed tasks |
+| `search_workflow_guide` | How to search and learn from past work |
+| `observation_best_practices` | How to write effective observations |
 
-### Agent Workflow
+---
 
-- **record_task_completion** - Primary tool for documenting completed work
-- **find_similar_procedures** - Find similar tasks with full implementation details
-
-## Example Usage
+## Examples
 
 ### Recording a Task Completion
 
 ```javascript
-await session.callTool("record_task_completion", {
+await record_task_completion({
   agent_name: "Agent_Backend_Developer",
-  task_name: "Task_Implement_Pagination",
+  task_name: "Task_Implement_Pagination_20241224",
+  project: "my-backend-api",
   task_type: "implementation",
   description: "Added cursor-based pagination to all list endpoints",
   observations: [
@@ -146,21 +248,19 @@ await session.callTool("record_task_completion", {
     "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"
+  created_artifacts: [{
+    name: "Artifact_Pagination_Middleware",
+    observations: ["Located at /src/middleware/pagination.js"]
+  }]
 });
 ```
 
-### Finding Similar Procedures (Vector Search)
+### Finding Similar Procedures
 
 ```javascript
-const result = await session.callTool("find_similar_procedures", {
-  query: "authentication implementation"
+const result = await find_similar_procedures({
+  query: "authentication implementation",
+  project: "my-backend-api"  // Optional: filter by project
 });
 
 // Returns ranked results with similarity scores:
@@ -173,37 +273,26 @@ const result = await session.callTool("find_similar_procedures", {
 // }
 ```
 
-### Searching the Collective Memory
-
-```javascript
-const result = await session.callTool("search_collective_memory", {
-  query: "database optimization"
-});
-
-// Returns matching entities with similarity scores
-```
+---
 
 ## Database
 
-The server uses JSON file storage for persistence. Data is stored at:
+Data is stored locally at:
 
 ```
-~/.collective-memory/memory.json      # Knowledge graph data
+~/.collective-memory/memory.json
 ```
 
-## Vector Search Benefits
+No database setup required. Everything is stored as JSON.
 
-| Traditional Keyword Search | TF-IDF Vector Search |
-|---------------------------|---------------------|
-| Exact word matching required | Finds related terms automatically |
-| No relevance ranking | Results ranked by similarity score (0-1) |
-| "login" misses "authentication" | "login" finds "authentication", "JWT", "OAuth" |
-| High false-positive rate | More precise, relevant results |
+---
 
 ## Requirements
 
 - Node.js 18+
 
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "collective-memory-mcp",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "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/models.js

@@ -5,7 +5,7 @@
 /**
  * Valid entity types
  */
-export const ENTITY_TYPES = ["agent", "task", "structure", "artifact", "session"];
+export const ENTITY_TYPES = ["agent", "task", "structure", "artifact", "session", "project"];
 
 /**
  * Valid relation types