Feature: Built-in MCP Server for LadybugDB (eliminate external server requirement for Agent Memory Access)

Problem Statement

Currently, Auto-Claude has two separate memory systems that use different databases, causing user confusion (see #882):

The Disconnect

1. Local memory uses embedded LadybugDB at ~/.auto-claude/memories/
2. Agent Memory Access expects an external HTTP server at localhost:8000/mcp/
3. The external Graphiti MCP Server (getzep/graphiti) uses FalkorDB or Neo4j, NOT LadybugDB
4. Data is NOT synchronized between these two systems

User Impact

• Users enable "Agent Memory Access" expecting it to work like local memory
• It requires running a separate Docker container with a different database
• Agents cannot access memories stored by the local system (and vice versa)
• Documentation is confusing ("no Docker required" vs "MCP server on port 8000")

Proposed Solution

Option A: Built-in MCP Server for LadybugDB (Recommended)

Create a lightweight MCP server that:

• Runs embedded within Auto-Claude (no Docker)
• Uses the same LadybugDB database as local memory
• Starts automatically when "Agent Memory Access" is enabled
• Supports per-project group_id for multi-project isolation

┌─────────────────────────────────────────────────────────────┐
│                      AUTO-CLAUDE                             │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              UNIFIED MEMORY SYSTEM                    │   │
│  │                                                       │   │
│  │   LadybugDB: ~/.auto-claude/memories/                │   │
│  │                                                       │   │
│  │   ┌─────────────────┐   ┌─────────────────────────┐  │   │
│  │   │ Local Access    │   │ Built-in MCP Server     │  │   │
│  │   │ (Enable Memory) │   │ (Agent Memory Access)   │  │   │
│  │   │                 │   │ localhost:8000/mcp/     │  │   │
│  │   └────────┬────────┘   └────────────┬────────────┘  │   │
│  │            │                         │               │   │
│  │            └─────────┬───────────────┘               │   │
│  │                      ▼                               │   │
│  │              SAME DATABASE                           │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Implementation Approach

Since graphiti-core already supports Kuzu via KuzuDriver, and LadybugDB is a Kuzu fork, we could:

1. Create a minimal MCP server in apps/backend/mcp_server/ that:

   • Uses existing GraphitiMemory class
   • Exposes MCP tools: search_nodes, search_facts, add_episode, get_episodes, get_entity_edge
   • Runs as a subprocess or thread when enabled

2. Auto-start when enabled:

   python复制

   # In agent-process.ts or equivalent
   if (project.settings.graphitiMcpEnabled) {
       # Start built-in MCP server instead of expecting external
       await startEmbeddedMcpServer(project.settings.graphitiMcpUrl);
   }

3. Use same database path:

   python复制

   # MCP server uses same config as local memory
   db_path = GraphitiConfig.from_env().get_db_path()

Option B: Documentation + UI Clarity (Minimum)

If Option A is too complex:

1. Clearly document that "Agent Memory Access" requires external Docker setup
2. Add warning in UI when toggle is enabled without external server
3. Consider renaming toggle to "External MCP Server" to clarify

Benefits of Option A

• ✅ Zero configuration for users
• ✅ No Docker dependency
• ✅ Unified memory - agents see same data as local system
• ✅ Per-project isolation via group_id
• ✅ Consistent with "embedded LadybugDB" messaging

Technical Notes

Existing Code That Could Be Leveraged

• apps/backend/integrations/graphiti/queries_pkg/graphiti.py - GraphitiMemory class
• apps/backend/integrations/graphiti/queries_pkg/client.py - LadybugDB client with monkeypatch
• apps/backend/agents/tools_pkg/models.py - GRAPHITI_MCP_TOOLS definition

MCP Tools Expected by Auto-Claude

GRAPHITI_MCP_TOOLS = [
    "mcp__graphiti-memory__search_nodes",
    "mcp__graphiti-memory__search_facts",
    "mcp__graphiti-memory__add_episode",
    "mcp__graphiti-memory__get_episodes",
    "mcp__graphiti-memory__get_entity_edge",
]

Related Issues

• #882 - User confusion about memory setup (this FR would resolve it)
• #377 - Memory not creating with Ollama (related to external server confusion)
• #467 - Graph memory says connected but not working

Environment

• Auto-Claude version: 2.8.x+
• Affected: All platforms (Windows, macOS, Linux)