Collective Memory MCP Server v2.0

A smart, three-tier memory system for AI agents with context-efficient search and auto-classification.

What's New in v2.0

| Feature | Before (v1) | After (v2) | |---------|-------------|------------| | System prompts | ~300 lines, 1500 tokens | ~20 lines, 150 tokens | | Search results | Always full detail | Brief by default (~50 tokens) | | Documentation | Everything stored | Auto-classified (critical/important/normal/skip) | | Working context | Pollutes permanent memory | Session-scoped working notes | | Search triggering | Mandatory | Smart (only when relevant) | | Context efficiency | High overhead | 10x reduction |

Quick Start

npx collective-memory-mcp

Claude Desktop Configuration

macOS/Linux: ~/.config/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "collective-memory": {
      "command": "npx",
      "args": ["-y", "collective-memory-mcp"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

IMPORTANT: The sequential-thinking MCP server is REQUIRED for best performance. This memory system is designed to work with sequential thinking for optimal decision-making.

Three-Tier Memory Architecture

┌─────────────────────────────────────────────────────────────────┐
│  TIER 1: WORKING MEMORY (Session)                               │
│  • Session-scoped, not persisted                                │
│  • Use for: temporary context, user preferences, notes         │
│  • Tool: working_notes                                          │
└─────────────────────────────────────────────────────────────────┘
                              ↓ (periodic sync)
┌─────────────────────────────────────────────────────────────────┐
│  TIER 2: PROJECT MEMORY (Per-Project)                           │
│  • Condensed ~20 line summary per project                       │
│  • Auto-generated from tasks                                    │
│  • Tool: project_summary                                        │
└─────────────────────────────────────────────────────────────────┘
                              ↓ (cross-pollination)
┌─────────────────────────────────────────────────────────────────┐
│  TIER 3: COLLECTIVE MEMORY (Cross-Project)                      │
│  • Only critical/important tasks stored                         │
│  • Searched with vector search                                  │
│  • Tool: smart_search                                           │
└─────────────────────────────────────────────────────────────────┘

Key Tools

Core Workflow

| Tool | Purpose | Token Usage | |------|---------|-------------| | smart_search | Vector search with format control | ~50 (brief) to ~1000 (full) | | working_notes | Session-scoped scratchpad | Minimal | | project_summary | Condensed project knowledge | ~200 | | record_task | Document with auto-classification | Varies by level | | should_trigger_search | Smart search recommendation | ~20 |

Search Tools

| Tool | Description | |------|-------------| | smart_search | RECOMMENDED - Format-controlled search (brief/standard/full) | | should_trigger_search | Check if search is needed before spending tokens | | project_summary | Get ~20 line project overview |

Documentation Tools

| Tool | Description | |------|-------------| | record_task | Record with auto-classification (critical/important/normal/skip) | | working_notes | Session notes (not persisted) |

Legacy Tools (Compatibility)

| Tool | Status | |------|--------| | create_entities | Available | | create_relations | Available | | search_collective_memory | Use smart_search instead | | find_similar_procedures | Use smart_search instead |

Smart Workflow

Old (Mandatory Everything)

1. ALWAYS search before any task
2. ALWAYS document after any task
3. Results: Context fills before work starts

New (Smart & Efficient)

1. Check if search needed: should_trigger_search(query)
2. If recommended: smart_search with format:'brief'
3. If relevant result found: smart_search with format:'full'
4. Use working_notes for temporary context
5. Use record_task with level:'auto' - system classifies importance

Example: Simple Question

User: "How do I create a variable?"

Agent:
1. should_trigger_search("How do I create a variable?")
   → { trigger: false, reason: "simple_question" }

2. Provide direct answer (no search, ~200 tokens saved)

3. record_task(..., task_type: "explanation")
   → Auto-classified as "skip" - goes to working notes only

Example: Complex Bug

User: "I'm getting ECONNREFUSED when connecting to Redis"

Agent:
1. should_trigger_search("Redis ECONNREFUSED error")
   → { trigger: true, reason: "debugging" }

2. smart_search({ query: "Redis ECONNREFUSED", format: "brief" })
   → Returns 3 matching tasks with scores

3. Found match with score 0.94 - get details
   smart_search({ query: "Redis connection", format: "full", task: "..." })

4. Implement fix based on past solution

5. record_task(..., task_type: "debugging", ...)
   → Auto-classified as "critical" - stored permanently

Required System Prompt

For best performance, add this to your AI agent's system prompt:

You have access to a Collective Memory MCP Server with three-tier memory and smart triggering.

## MANDATORY: Sequential Thinking
- Call `sequentialthinking` as your FIRST action in EVERY response
- Use it to analyze requests, plan approach, and organize thoughts
- Continue until `nextThoughtNeeded: false`
- This applies to ALL responses: questions, tasks, debugging, etc.

## CORE WORKFLOW

### Phase 1: INIT (First response of chat)
1. Call `sequentialthinking` to understand user's request
2. Call `quick_start` tool to learn about the memory system
3. Acknowledge initialization complete

### Phase 2: SEARCH (Before complex tasks)
1. Call `sequentialthinking` to formulate search strategy
2. Call `should_trigger_search` to check if search is needed
3. If trigger:true, call `smart_search` with format:'brief'
4. Only use format:'full' when you find a relevant match
5. Skip search for simple questions

### Phase 3: WORK
1. Call `sequentialthinking` before major steps
2. Use `working_notes` for temporary session context
3. Use `project_summary` for quick project overview

### Phase 4: DOCUMENT (After completing tasks)
1. Call `sequentialthinking` to summarize what was done
2. Call `record_task` with level:'auto' (system classifies importance)
3. Q&A and explanations auto-classify as 'skip' (working notes only)

## KEY POINTS
- Search is NOT mandatory - use `should_trigger_search` first
- Use format:'brief' by default, format:'full' only for relevant matches
- `working_notes` for session context, `record_task` for permanent storage
- System auto-classifies: critical, important, normal, skip

Documentation Levels

| Level | Trigger | Storage | Detail | |-------|---------|---------|--------| | Critical | Bugs, security, deployment failures | Permanent | Full observations + metrics | | Important | Features, architecture, performance | Long-term | Summary + key insights | | Normal | Routine tasks | Standard | Task name + 1-line | | Skip | Q&A, explanations | Working notes only | Not stored permanently |

Auto-Classification Examples

"Fixed production memory leak"        → critical
"Added JWT authentication"            → important
"Updated lodash dependency"           → normal
"Explained how JWT works"            → skip (working notes)
"Answered question about variables"  → skip (working notes)

Search Format Control

Brief Format (Default)

{
  "results": [
    {
      "name": "Task_Add_JWT_Auth_20241229",
      "score": 0.92,
      "summary": "Added JWT middleware with 1-hour expiry",
      "project": "my-app"
    }
  ],
  "count": 1,
  "format": "brief",
  "suggestion": "Use format:'full' for complete details"
}

Token usage: ~50

Full Format

{
  "results": [
    {
      "name": "Task_Add_JWT_Auth_20241229",
      "score": 0.92,
      "observations": [
        "Added JWT middleware at /src/auth/jwt.js",
        "Token expiry: 3600 seconds",
        "Using HS256 algorithm",
        "Secret from JWT_SECRET env var"
      ],
      "createdAt": "2024-12-29T10:30:00Z",
      "metadata": { "level": "important", "project": "my-app" }
    }
  ]
}

Token usage: ~500-1000

Configuration

Optional Configuration

The system works out of the box with smart defaults. Configuration is optional:

{
  "memory": {
    "auto_search": true,
    "search_threshold": "medium",
    "auto_classify": true,
    "document_qa": false,
    "default_format": "brief",
    "default_max_results": 3
  }
}

Data Storage

~/.collective-memory/
├── memory.json           # Main knowledge base
└── summaries/            # Project summaries
    ├── my-app.json
    └── backend-api.json

API Reference

smart_search

smart_search({
  query: string,           // Required
  format?: "brief" | "standard" | "full",  // Default: "brief"
  max_results?: number,    // Default: 3
  project?: string         // Optional filter
})

working_notes

working_notes({
  action: "add" | "get" | "get_formatted" | "search" | "clear",
  note?: string,           // For "add"
  category?: "context" | "preference" | "warning" | "temporary" | "debug",
  query?: string           // For "search"
})

project_summary

project_summary({
  project: string,         // Required
  section?: "all" | "tech_stack" | "decisions" | "patterns" | "issues" | "recent"
})

record_task

record_task({
  agent_name: string,      // Required
  task_name: string,       // Required
  project?: string,
  task_type?: string,
  description?: string,
  observations?: string[],
  level?: "auto" | "critical" | "important" | "normal" | "skip",  // Default: "auto"
  working_note_only?: boolean  // Skip permanent storage
})

should_trigger_search

should_trigger_search({
  query: string,           // Required
  project?: string
})
// Returns: { trigger: boolean, reason: string, confidence: string }

Examples

Example 1: Debugging with Smart Search

// 1. Check if search is needed
const decision = should_trigger_search({
  query: "Redis connection timeout error",
  project: "my-app"
});
// → { trigger: true, reason: "debugging", confidence: "high" }

// 2. Brief search first
const brief = smart_search({
  query: "Redis timeout error",
  format: "brief",
  max_results: 3
});

// 3. Found relevant match, get details
const full = smart_search({
  query: "Redis timeout",
  format: "full"
});

Example 2: Session Notes

// Add user preference
working_notes({
  action: "add",
  note: "User prefers functional components over class components",
  category: "preference"
});

// Add temporary note
working_notes({
  action: "add",
  note: "Tried Redis caching but it increased latency",
  category: "warning"
});

// Get all notes later
const notes = working_notes({ action: "get_formatted" });

Example 3: Project Overview

// Get full project summary
const summary = project_summary({
  project: "my-app",
  section: "all"
});
// Returns ~20 line summary with tech stack, decisions, patterns, issues

// Get only known issues
const issues = project_summary({
  project: "my-app",
  section: "issues"
});

Example 4: Record Task

// Critical bug fix - will be stored with full details
record_task({
  agent_name: "Agent_Debugger",
  task_name: "Task_Fix_Memory_Leak_20241229",
  project: "my-app",
  task_type: "debugging",
  description: "Fixed memory leak causing OOM crashes",
  observations: [
    "Root cause: Redis connections not closed in error handler",
    "Impact: OOM every ~2 hours during peak traffic",
    "Fix: Added try-finally in /src/cache.js:47",
    "Verified: Memory stable for 24hrs post-deploy"
  ],
  level: "auto"  // Will auto-classify as "critical"
});

// Simple Q&A - goes to working notes only
record_task({
  agent_name: "Agent_Helper",
  task_name: "Task_Explained_JWT_20241229",
  task_type: "explanation",
  description: "Explained JWT token structure",
  level: "auto"  // Will auto-classify as "skip"
});

Entity Types

| Type | Description | |------|-------------| | agent | An AI agent | | task | A unit of work (auto-classified by level) | | structure | Architectural pattern or decision | | artifact | Concrete output (file, code, config) | | session | Groups related tasks | | project | Groups tasks by project |

Relation Types

| Type | From → To | Description | |------|------------|-------------| | executed_by | Task → Agent | Links task to agent | | created | Task → Artifact | Task produced artifact | | modified | Task → Structure | Task changed structure | | documented | Task → Structure | Task defined structure | | depends_on | Task → Task | Task dependency | | part_of | Task → Session/Project | Groups tasks | | similar_to | Task → Task | Similar solutions | | uses | Task → Artifact | Task consumed artifact | | implements | Artifact → Structure | Artifact implements structure |

Requirements

• Node.js 18+
• No external dependencies (pure JavaScript)

License

MIT

Migration from v1

v2.0 is backward compatible with v1 data. Existing tools continue to work, but new tools are recommended:

| Old Tool | New Tool | Why | |----------|----------|-----| | search_collective_memory | smart_search | Format control, less tokens | | find_similar_procedures | smart_search + format:'full' | Unified interface | | record_task_completion | record_task | Auto-classification | | - | working_notes | Session context without pollution | | - | project_summary | Quick project overview | | - | should_trigger_search | Smart decisions |

No migration needed - your existing data works as-is. New features are opt-in.