Exocortex 🧠

"Extend your mind." - Your External Brain

日本語版はこちら (Japanese)

---

Exocortex is a local MCP (Model Context Protocol) server that acts as a developer's "second brain."

It persists development insights, technical decisions, and troubleshooting records, allowing AI assistants (like Cursor) to retrieve contextually relevant memories when needed.

Why Exocortex?

🌐 Cross-Project Knowledge Sharing

Unlike tools that store data per-repository (e.g., .serena/ in each project), Exocortex uses a single, centralized knowledge store.

Traditional approach (per-repository):
project-A/.serena/    ← isolated knowledge
project-B/.serena/    ← isolated knowledge
project-C/.serena/    ← isolated knowledge

Exocortex approach (centralized):
~/.exocortex/data/    ← shared knowledge across ALL projects
    ├── Insights from project-A
    ├── Insights from project-B
    └── Insights from project-C
        ↓
    Cross-project learning!

Benefits:

• 🔄 Knowledge Transfer: Lessons learned in one project are immediately available in others
• 🏷️ Tag-based Discovery: Find related memories across projects via shared tags
• 📈 Cumulative Learning: Your external brain grows smarter over time, not per project
• 🔍 Pattern Recognition: Discover common problems and solutions across your entire development history

Features

• 🔒 Fully Local: All data and AI processing stays on your machine. Privacy guaranteed.
• 🔍 Semantic Search: Find memories by meaning, not just keywords.
• 🕸️ Knowledge Graph: Maintains relationships between projects, tags, and memories with explicit links.
• 🔗 Memory Links: Connect related memories to build a traversable knowledge network.
• ⚡ Lightweight & Fast: Uses embedded KùzuDB and lightweight fastembed models.
• 🧠 Memory Dynamics: Smart recall based on recency and frequency—frequently accessed memories surface higher.
• 🔥 Frustration Indexing: Prioritize "painful memories"—debugging nightmares get boosted in search results.
• 🖥️ Web Dashboard: Beautiful cyberpunk-style UI for browsing memories, monitoring health, and visualizing the knowledge graph.

📚 Usage Guide

→ See the full usage guide

• Tool reference with use cases
• Practical workflows
• Prompting tips
• Tips & Tricks

Installation

# Clone the repository
git clone https://github.com/fuwasegu/exocortex.git
cd exocortex

# Install dependencies with uv
uv sync

Usage

Starting the Server

uv run exocortex

Cursor Configuration

Add the following to your ~/.cursor/mcp.json:

Option 1: Direct from GitHub (Recommended)

Auto-updates when uvx cache expires. No manual git pull needed.

{
  "mcpServers": {
    "exocortex": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fuwasegu/exocortex", "exocortex"]
    }
  }
}

Option 2: Local Installation

For development or customization.

{
  "mcpServers": {
    "exocortex": {
      "command": "uv",
      "args": ["--directory", "/path/to/exocortex", "run", "exocortex"]
    }
  }
}

Note: Your data is stored in ~/.exocortex/ and is preserved regardless of which option you choose.

Option 3: Proxy Mode (Multiple Cursor Instances - Recommended)

Use this method if you want to use Exocortex from multiple Cursor windows simultaneously.

KùzuDB doesn't support concurrent writes from multiple processes. With the stdio approach where each Cursor instance spawns its own server process, lock conflicts occur. Proxy mode automatically starts a single SSE server in the background, and each Cursor instance connects via proxy.

{
  "mcpServers": {
    "exocortex": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/fuwasegu/exocortex",
        "exocortex",
        "--mode", "proxy",
        "--ensure-server"
      ]
    }
  }
}

How it works:

1. First Cursor starts Exocortex → SSE server automatically starts in background
2. Subsequent Cursors connect to the existing SSE server
3. All Cursors share the same server → No lock conflicts!

Note: No manual server startup required. The --ensure-server option automatically starts the server if it's not running.

Option 4: Manual Server Management (Advanced)

If you prefer to manage the server manually:

Step 1: Start the server

# Start the server in a terminal (can also run in background)
uv run --directory /path/to/exocortex exocortex --transport sse --port 8765

Step 2: Configure Cursor

{
  "mcpServers": {
    "exocortex": {
      "url": "http://127.0.0.1:8765/mcp/sse"
    }
  }
}

Bonus: With this setup, you can also access the web dashboard at http://127.0.0.1:8765/

Tip: To auto-start the server on system boot, use launchd on macOS or systemd on Linux.

MCP Tools

Basic Tools

| Tool | Description | |------|-------------| | exo_ping | Health check to verify server is running | | exo_store_memory | Store a new memory | | exo_recall_memories | Recall relevant memories via semantic search | | exo_list_memories | List stored memories with pagination | | exo_get_memory | Get a specific memory by ID | | exo_delete_memory | Delete a memory | | exo_get_stats | Get statistics about stored memories |

Advanced Tools

| Tool | Description | |------|-------------| | exo_link_memories | Create a link between two memories | | exo_unlink_memories | Remove a link between memories | | exo_update_memory | Update content, tags, or type of a memory | | exo_explore_related | Discover related memories via graph traversal | | exo_get_memory_links | Get all outgoing links from a memory | | exo_trace_lineage | 🕰️ Trace the evolution/lineage of a memory (temporal reasoning) | | exo_curiosity_scan | 🤔 Scan for contradictions, outdated info, and knowledge gaps | | exo_analyze_knowledge | Analyze knowledge base health and get improvement suggestions | | exo_sleep | Trigger background consolidation (deduplication, orphan rescue, auto-linking) | | exo_consolidate | Extract abstract patterns from memory clusters |

🤖 Knowledge Autonomy

Exocortex automatically improves your knowledge graph! When you store a memory, the system:

1. Suggests Links: Finds similar existing memories and suggests connections
2. Detects Duplicates: Warns if the new memory is too similar to an existing one
3. Identifies Patterns: Recognizes when a success might resolve a past failure

// Example exo_store_memory response with suggestions
{
  "success": true,
  "memory_id": "...",
  "suggested_links": [
    {
      "target_id": "existing-memory-id",
      "similarity": 0.78,
      "suggested_relation": "extends",
      "reason": "High semantic similarity; may be an application of this insight"
    }
  ],
  "insights": [
    {
      "type": "potential_duplicate",
      "message": "This memory is very similar (94%) to an existing one.",
      "suggested_action": "Use exo_update_memory instead"
    }
  ]
}

🧠 Automatic Memory Consolidation

Like human sleep consolidates memories, Exocortex prompts the AI to organize after storing.

When exo_store_memory succeeds, the response includes next_actions that guide the AI to:

1. Link high-similarity memories (similarity ≥ 0.7)
2. Handle duplicates and contradictions
3. Run periodic health checks (every 10 memories)

// Example response with next_actions
{
  "success": true,
  "memory_id": "abc123",
  "summary": "...",
  "consolidation_required": true,
  "consolidation_message": "🧠 Memory stored. 2 consolidation action(s) required.",
  "next_actions": [
    {
      "action": "link_memories",
      "priority": "high",
      "description": "Link to 2 related memories",
      "details": [
        {
          "call": "exo_link_memories",
          "args": {
            "source_id": "abc123",
            "target_id": "def456",
            "relation_type": "extends",
            "reason": "High semantic similarity"
          }
        }
      ]
    },
    {
      "action": "analyze_health",
      "priority": "low",
      "description": "Run knowledge base health check",
      "details": { "call": "exo_analyze_knowledge" }
    }
  ]
}

Expected Flow:

User: "Remember this insight"
    ↓
AI: exo_store_memory() → receives next_actions
    ↓
AI: exo_link_memories() for each high-priority action
    ↓
AI: "Stored and linked to 2 related memories."

⚠️ Important Limitation: Execution of next_actions is at the AI agent's discretion. While the server strongly instructs consolidation via SERVER_INSTRUCTIONS and consolidation_required: true, execution is NOT 100% guaranteed. This is an inherent limitation of the MCP protocol—servers can only suggest, not force actions. In practice, most modern AI assistants follow these instructions, but they may be skipped during complex conversations or when competing with other tasks.

Relation Types for exo_link_memories

| Type | Description | |------|-------------| | related | Generally related memories | | supersedes | This memory updates/replaces the target | | contradicts | This memory contradicts the target | | extends | This memory extends/elaborates the target | | depends_on | This memory depends on the target | | evolved_from | This memory evolved from the target (temporal reasoning) | | rejected_because | This memory was rejected due to the target | | caused_by | This memory was caused by the target |

Temporal Reasoning with exo_trace_lineage

Trace the lineage of decisions and knowledge over time. Understand WHY something became the way it is.

| Parameter | Description | Example | |-----------|-------------|---------| | memory_id | Starting memory ID | "abc123" | | direction | "backward" (find ancest