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`](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