Skip to main content
Glama
MCP Roo Memory

MCP Roo Memory

by mcasdfgf

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

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"
      }
    }
  }
}

Related MCP server: M.I.M.I.R - Multi-agent Intelligent Memory & Insight Repository

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

Available Tools

17 tools
desktop_focusA

Focus on a specific node — expand its subgraph with all relations and child nodes. Use when you need to explore context around a specific task, fact, or decision. Also logs this focus to navigation history for Hot/Cold tier calculations.

workspace_id is OPTIONAL.

Inputs: node_id (required), workspace_id.

desktop_historyA

Get navigation history for a workspace session. Use to understand what was recently worked on or to restore context.

workspace_id is OPTIONAL.

Inputs: workspace_id, limit.

desktop_openA

Open a workspace session and return its Desktop Viewport (Hot/Cold/Archive tiers). Use at the START of every task to initialize or resume a session. Returns: session root, hot nodes (current focus + direct relations), cold nodes (other active nodes, titles only), archive info (old nodes, search only). Hot=3-10 nodes always in context, Cold=10-100 by focus/search, Archive=100+ by vector_search only.

Without workspace_id, opens YOUR PROJECT's workspace (from CORTEX_WORKSPACE_ID / --workspace). To see another project's viewport, pass its workspace_id explicitly.

Inputs: workspace_id.

graph_add_nodeA

Add a node to the knowledge graph. Supports 13 types (entity, fact, decision, thought, chunk, question, hypothesis, action, error, note, pattern, goal, constraint — all vectorized; session, task, subtask, fileref — graph only). Text in data.text or data.title is automatically indexed into Qdrant vector search for vectorizable types. For fileref nodes, pass path in data.path.

workspace_id is OPTIONAL.

Inputs: type (required), data (required), parent_id, workspace_id.

graph_add_relationB

Create a relation between two nodes. Supports 22 relation types: Hierarchical (contains, decomposes_to, belongs_to), Semantic (derives_from, supports, contradicts, related_to, questions, answers), Index (indexes Entity->Fileref, extracted_from Fact/Chunk->Fileref, references, implements, relates_to_file), Chronological (sequel_to, supersedes, leads_to, resolves, triggers), Dependency (depends_on, blocks, constrained_by).

Inputs: from_id (required), to_id (required), type (required), weight.

graph_decomposeA

Decompose a task node into subtasks. Creates subtask nodes and adds decomposes_to relations. Use for planning and breaking down complex tasks into manageable pieces.

Inputs: task_id (required), subtasks (required).

graph_delete_nodeA

Delete a node and its vector from Qdrant. With cascade=true, also deletes all child nodes (subtree). Use with caution — prefer graph_supersede (stale) for history preservation.

Inputs: node_id (required), cascade.

graph_get_nodeA

Get a node with its relations and child nodes. Use to inspect a node's full context: what it contains, what it relates to, what references it.

Inputs: node_id (required), depth.

graph_supersedeA

Supersede an old node with a new one (Strategy B: Supersedes). Marks old node as stale, creates a new node with supersedes relation. Use when a decision or fact fundamentally changes — preserves history of why previous decision was made. The old node remains searchable but is marked stale and deprioritized in results.

Inputs: old_id (required), new_data (required).

graph_traverseA

Traverse the graph starting from a node, following relations. Optionally filter by relation type. Uses recursive CTE up to specified depth. Use to discover how nodes are connected in the graph.

Inputs: start_id (required), relation, depth.

graph_update_nodeA

Update a node's data in-place (Strategy A: Update). If data.text changes, the Qdrant vector is automatically re-indexed. Use for small corrections and improvements. For major decision changes, use graph_supersede instead.

Inputs: node_id (required), data (required).

graph_walkA

Walk along a reasoning chain following sequel_to, derives_from, and leads_to relations. Use to reconstruct the chain of thought: how one thought led to another, what decisions were derived from what facts. Returns nodes in chronological order.

Inputs: start_id (required), steps.

session_timelineA

Show a flat timeline of the session: nodes created + navigation events. All merged and sorted by created_at ASC. Use to answer 'what happened in this session over time?'.

workspace_id is OPTIONAL.

Inputs: workspace_id, from_time, to_time, limit.

temporal_walkA

Walk the graph along the time axis. Returns nodes ordered by created_at ASC within optional time range. Use to reconstruct the chronological sequence of decisions and events.

workspace_id is OPTIONAL.

Inputs: workspace_id, from_time, to_time, relation_type, +1 more.

vector_storeA

Store text with automatic vectorization into Qdrant. Use for quick ad-hoc storage of facts without creating a full graph node. For structured knowledge, prefer graph_add_node which creates both a graph node and a vector.

workspace_id in metadata is OPTIONAL.

Inputs: text (required), metadata (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 17 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose. Desktop tools manage sessions and viewports, graph tools handle node and relation CRUD plus traversal, and vector tools handle semantic search and storage. Even similar-sounding tools like graph_search and vector_search are well-differentiated by their mechanics.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern, predominantly verb_noun (e.g., graph_add_node, vector_search). The naming is predictable and makes the tool's action and target clear.

    Tool Count4/5

    17 tools is slightly above the ideal 3-15 range, but the set is well-scoped for a memory server covering graph operations, search, session management, and temporal navigation. Each tool serves a distinct need without being excessive.

    Completeness4/5

    The tool surface covers CRUD for nodes, relations, search, session initialization, and temporal queries. Minor gaps exist (e.g., no direct relation deletion tool), but core workflows are fully supported with workarounds available.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI assistants with persistent graph database memory using Neo4j, enabling task management, relationship understanding, semantic search with embeddings, file indexing, and multi-agent coordination through the Model Context Protocol.
      290
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A local, persistent, semantically-aware knowledge graph for AI coding agents like Claude Code, providing efficient session memory with minimal token cost and zero runtime network calls.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides persistent memory for AI coding agents through the Model Context Protocol, enabling them to store and retrieve project knowledge across sessions.
      27 npm
      MIT