# 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+](https://img.shields.io/badge/python-3.11+-blue)
![MIT](https://img.shields.io/badge/license-MIT-green)
![Status](https://img.shields.io/badge/status-beta-yellow)
![Docker](https://img.shields.io/badge/docker-ready-2496ED)

> **⚠️ 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`](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

```bash
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):

```json
{
  "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:

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

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

```json
{
  "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:

```bash
# 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:

```json
{
  "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:

```bash
# 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`](.roo/custom_instructions.md) | Cortex bootstrap — mandatory sequence, core principles |
| [`mcp.json`](.roo/mcp.json) | Reference MCP server config (edit `--workspace` for your project) |
| [`rules/`](.roo/rules) | Boot, save, templates, triggers — memory lifecycle |
| [`rules-architect/`](.roo/rules-architect) | Memory rules for Architect mode |
| [`rules-ask/`](.roo/rules-ask) | Memory rules for Ask mode |
| [`rules-code/`](.roo/rules-code) | Memory rules for Code mode |
| [`rules-coding-teacher/`](.roo/rules-coding-teacher) | Memory rules for Coding Teacher mode |
| [`rules-debug/`](.roo/rules-debug) | Memory rules for Debug mode |
| [`rules-documentation-writer/`](.roo/rules-documentation-writer) | Memory rules for Documentation Writer mode |
| [`rules-orchestrator/`](.roo/rules-orchestrator) | Memory rules for Orchestrator mode |
| [`rules-project-research/`](.roo/rules-project-research) | Memory rules for Project Research mode |

For deep understanding of the memory model, see [`CONCEPT.md`](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`](CONCEPT.md#8-mcp-protocol) |

---

## 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`](CONCEPT.md) | Full philosophy, data model, node taxonomy (17 types), relation taxonomy (22 types), SQL schema |
| [`ADR-001`](plans/ADR-001-fractal-memory.md) | Fractal memory architecture decision |
| [`ADR-002`](plans/ADR-002-sqlite-graph.md) | SQLite + JSON for graph instead of Neo4j/Cayley |
| [`ADR-003`](plans/ADR-003-qdrant-vectors.md) | Qdrant for vectors (existing) |
| [`ADR-004`](plans/ADR-004-fastembed.md) | fastembed for embeddings (paraphrase-multilingual-MiniLM-L12-v2) |
| [`ADR-005`](plans/ADR-005-desktop-viewport.md) | Desktop Viewport — context window strategy |
| [`ADR-006`](plans/ADR-006-mutation-strategy.md) | Knowledge evolution: update / supersede / stale |
| [`ADR-007`](plans/ADR-007-regression-pattern.md) | Regression search: meaning → context → files |
| [`ADR-008`](plans/ADR-008-temporal-layer.md) | Temporal layer — time as first-class citizen |
| [`CHANGELOG.md`](CHANGELOG.md) | Project release history |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development guidelines |

---

## Development

```bash
# 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`](CONTRIBUTING.md) for guidelines.

---

## License

MIT © 2026