MCP Roo Memory

MCP Roo Memory

Persistent, graph-based memory for Roo Code via the Model Context Protocol (MCP).

LLMs have a short memory. Every new conversation starts from scratch — context windows overflow, past decisions fade, and reasoning chains disappear.

MCP Roo Memory gives your AI agent a structured, persistent brain:

• Graph memory — knowledge is not a flat dump, but a fractal graph of tasks, entities, facts, and decisions
• Semantic search — find what matters by meaning, not keywords (50+ languages)
• Context window control — hot/cold/archive tiers so you don't drown in tokens
• Knowledge evolution — decisions can be superseded, facts can be updated, stale data gets archived
• Temporal awareness — time as first-class citizen: chronological walks, session timelines, temporal vector filters

⚠️ Disclaimer

This is an experimental project — a search for form and architecture. It works, it has tests, but treat it as a Proof of Concept (PoC). The software is provided "AS IS", without any warranty of any kind. Use it at your own risk. See LICENSE for details.

---

Quick Start

🐳 Docker (recommended)

Zero system dependencies — just Docker. Everything runs in containers; no Python, no venv, no pip.

1. Start the stack

git clone https://github.com/mcasdfgf/mcp-roo-memory.git
cd mcp-roo-memory
docker compose up -d

This starts two containers:

2. Global MCP configuration

Add Cortex as a global MCP server for all your projects. The server is always running in Docker, so any project can connect.

Edit ~/.config/VSCodium/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json (or the equivalent path for VS Code):

{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": ["exec", "-i", "cortex-mcp", "python3", "-m", "src.cortex"]
    }
  }
}

VSCode users: replace VSCodium with Code in the path above.

3. Project-level configuration (for workspace isolation)

If you want memory isolated per project, copy the reference .roo/ directory into your project:

cp -r ./mcp-roo-memory/.roo ./your-project/

Then edit .roo/mcp.json in your project and add --workspace your-project-name:

{
  "mcpServers": {
    "cortex": {
      "command": "docker",
      "args": [
        "exec", "-i", "cortex-mcp", "python3",
        "-m", "src.cortex", "--workspace", "your-project-name"
      ],
      "alwaysAllow": ["desktop_open", "graph_add_node", "vector_search", "graph_get_node",
                       "graph_add_relation", "graph_search", "desktop_focus",
                       "desktop_history", "graph_traverse", "graph_walk",
                       "graph_decompose", "graph_update_node", "graph_supersede",
                       "graph_delete_node", "vector_store",
                       "temporal_walk", "session_timeline"]
    }
  }
}

Replace your-project-name with a unique identifier — mcp-roo-memory, researcher, ai-pulse, etc.

How isolation works:

• desktop_open() and graph_add_node() — always write to your project's workspace
• vector_search() without workspace_id — searches across all projects (cross-project recall)
• vector_search(workspace_id="project") — narrows search to one project

4. Done

Restart Roo Code. Your agent now has persistent memory — zero system pollution.

---

🏠 Native pip (advanced)

If you prefer running without Docker — or you're developing Cortex itself:

# Requirements: Python 3.11+
git clone https://github.com/mcasdfgf/mcp-roo-memory.git
cd mcp-roo-memory
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Qdrant is still needed:
docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

MCP config:

{
  "mcpServers": {
    "cortex": {
      "command": "python",
      "args": ["-m", "src.cortex"],
      "env": {
        "CORTEX_DB_PATH": "/path/to/cortex.db",
        "CORTEX_QDRANT_HOST": "localhost",
        "CORTEX_QDRANT_PORT": "6333"
      }
    }
  }
}

---

Problems This Solves

---

Architecture

┌──────────────────────────────────────────────┐
│              MCP Client (Roo Code)            │
└──────────────────────┬───────────────────────┘
                        │ stdio (MCP protocol)
┌──────────────────────▼───────────────────────┐
│               CortexServer                     │
│         17 tools · 4 resources                 │
├──────────┬──────────┬──────────┬─────────────┤
│ Graph    │ Vector   │ Desktop  │ Database    │
│ CRUD,    │ Qdrant + │ Hot/     │ SQLite      │
│ traverse,│ fastembed│ Cold/    │ graph +     │
│ walk     │ semantic │ Archive  │ history     │
└──────────┴──────────┴──────────┴─────────────┘

Three layers of intelligence:

1. Graph (SQLite) — who relates to who, what decomposes into what
2. Vector (Qdrant) — what does this mean, what's semantically similar
3. Desktop (viewport) — what fits in the context window right now

---

Using as Primary Roo Memory

Make Cortex your agent's default memory system by copying the .roo/ directory into your project:

# Copy reference config from this repo
cp -r ./mcp-roo-memory/.roo ./your-project/

The .roo/ directory contains ready-to-use reference configs:

For deep understanding of the memory model, see CONCEPT.md.

---

Tools Overview

---

Configuration

All via CORTEX_* environment variables:

---

Project Structure

.
├── docker-compose.yml    ← Two services: cortex + qdrant
├── Dockerfile            ← Multi-stage, python:3.11-slim
├── .dockerignore
├── src/cortex/
│   ├── __init__.py    — Cortex factory (component assembly)
│   ├── __main__.py    — MCP server entry point (stdio)
│   ├── config.py      — Configuration (pydantic-settings)
│   ├── db.py          — DatabaseManager (SQLite)
│   ├── desktop.py     — DesktopManager (viewport + timeline)
│   ├── graph.py       — GraphManager (CRUD, navigation, mutation, temporal)
│   ├── models.py      — Pydantic models (Node, Relation, Viewport)
│   ├── server.py      — MCP server (17 tools, 4 resources)
│   └── vector.py      — VectorManager (Qdrant, embeddings, temporal filters)
└── tests/

---

Deep Dive

---

Development

# Native install (inside venv)
pip install -e .
pip install pytest pytest-asyncio

# Run all tests (188+ tests)
pytest tests/ -v

# With coverage
pytest tests/ --cov=src.cortex -v

Tests cover every component: models (17), config (19), database (26), graph (19), desktop (14), vector (19), server (19), integration (3) — 136+ total.

See CONTRIBUTING.md for guidelines.

---

License

MIT © 2026