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:

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:

Graph (SQLite) — who relates to who, what decomposes into what
Vector (Qdrant) — what does this mean, what's semantically similar
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

…

Roo Memory

Installation

Configuration

How to use

README

MCP Roo Memory

Quick Start

🐳 Docker (recommended)

1. Start the stack

2. Global MCP configuration

3. Project-level configuration (for workspace isolation)

4. Done

🏠 Native pip (advanced)

Problems This Solves

Architecture

Using as Primary Roo Memory

Tools Overview

Configuration

Project Structure

Deep Dive

Development

You might also like