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

!Python 3.11+ !MIT !Status !Docker

⚠️ 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:

| Container | What it does | |-----------|-------------| | cortex-qdrant | Vector database (port 6333) | | cortex-mcp | Cortex server (idle, waits for MCP connections) |

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

| Problem | How Cortex solves it | |---------|---------------------| | Flat memory — facts are stored as unrelated chunks | Fractal graph — tasks decompose into subtasks, facts connect to decisions, entities index files | | Context window overflow — everything grows unbounded | Desktop Viewport — Hot (always loaded) / Cold (on focus) / Archive (search only) tiers | | No navigation — can't walk a reasoning chain | Graph traversal — follow supersedes, derives_from, leads_to relations like a path | | Stale facts linger — old decisions pollute context | Mutation strategy — Update (typo fix) / Supersede (approach changed) / Stale-cascade (rework) | | Keyword search fails — "auth implementation" doesn't find "JWT with RS256" | Semantic vector search — multilingual embeddings (50+ languages) via Qdrant + fastembed | | No time axis — can't answer "what happened in what order" | Temporal layer — chronological walks, session timelines, temporal vector filters |

---

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:

| File / Dir | Purpose | |------------|---------| | custom_instructions.md | Cortex bootstrap — mandatory sequence, core principles | | mcp.json | Reference MCP server config (edit --workspace for your project) | | rules/ | Boot, save, templates, triggers — memory lifecycle | | rules-architect/ | Memory rules for Architect mode | | rules-ask/ | Memory rules for Ask mode | | rules-code/ | Memory rules for Code mode | | rules-coding-teacher/ | Memory rules for Coding Teacher mode | | rules-debug/ | Memory rules for Debug mode | | rules-documentation-writer/ | Memory rules for Documentation Writer mode | | rules-orchestrator/ | Memory rules for Orchestrator mode | | rules-project-research/ | Memory rules for Project Research mode |

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

---

Tools Overview

| Tool | What it does | |------|-------------| | desktop_open | Open/restore a workspace session | | desktop_focus | Bring a node into hot context | | desktop_history | Get navigation history for a workspace | | graph_add_node | Store any knowledge: entity, fact, decision, task... | | graph_get_node | Retrieve a node with its relations | | graph_add_relation | Create a relation between two nodes | | graph_traverse | Walk the graph from a starting node | | graph_walk | Walk along a reasoning chain | | graph_decompose | Break a task into structured subtasks | | graph_update_node | Update a node's data in-place | | graph_supersede | Replace outdated knowledge (keeps history) | | graph_delete_node | Delete a node and its vector | | vector_search | Find things by meaning, across 50+ languages | | vector_store | Store text with automatic vectorization | | graph_search | Hybrid: semantic + graph subgraph expansion | | temporal_walk | Chronological graph traversal (time axis) | | session_timeline | Flat timeline of all events in a session | | That's all 17 tools | See full list in CONCEPT.md §8 |

---

Configuration

All via CORTEX_* environment variables:

| Variable | Default | Description | |----------|---------|-------------| | CORTEX_DB_PATH | cortex.db | SQLite database path | | CORTEX_QDRANT_HOST | localhost | Qdrant host | | CORTEX_QDRANT_PORT | 6333 | Qdrant port | | CORTEX_QDRANT_TIMEOUT | 30 | Connection timeout (s) | | CORTEX_COLLECTION_NAME | cortex_memory | Qdrant collection name | | CORTEX_EMBEDDING_MODEL | sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 | Embedding model (50+ languages) | | CORTEX_ARCHIVE_DAYS_THRESHOLD | 7 | Days before auto-archive | | CORTEX_DESKTOP_HOT_LIMIT | 5 | Max hot nodes in viewport | | CORTEX_DESKTOP_HISTORY_LIMIT | 10 | Max history entries |

---

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

| Document | What you'll find | |----------|-----------------| | CONCEPT.md | Full philosophy, data model, node taxonomy (17 types), relation taxonomy (22 types), SQL schema | | ADR-001 | Fractal memory architecture decision | | ADR-002 | SQLite + JSON for graph instead of Neo4j/Cayley | | ADR-003 | Qdrant for vectors (existing) | | ADR-004 | fastembed for embeddings (paraphrase-multilingual-MiniLM-L12-v2) | | ADR-005 | Desktop Viewport — context window strategy | | ADR-006 | Knowledge evolution: update / supersede / stale | | ADR-007 | Regression search: meaning → context → files | | ADR-008 | Temporal layer — time as first-class citizen | | CHANGELOG.md | Project release history | | CONTRIBUTING.md | Development guidelines |

---

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