MCP Roo Memory
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
LICENSEfor 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 -dThis starts two containers:
Container | What it does |
| Vector database (port 6333) |
| 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
VSCodiumwithCodein 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()andgraph_add_node()— always write to your project's workspace
vector_search()withoutworkspace_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/qdrantMCP 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 |
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 |
Cortex bootstrap — mandatory sequence, core principles | |
Reference MCP server config (edit | |
Boot, save, templates, triggers — memory lifecycle | |
Memory rules for Architect mode | |
Memory rules for Ask mode | |
Memory rules for Code mode | |
Memory rules for Coding Teacher mode | |
Memory rules for Debug mode | |
Memory rules for Documentation Writer mode | |
Memory rules for Orchestrator mode | |
Memory rules for Project Research mode |
For deep understanding of the memory model, see CONCEPT.md.
Tools Overview
Tool | What it does |
| Open/restore a workspace session |
| Bring a node into hot context |
| Get navigation history for a workspace |
| Store any knowledge: entity, fact, decision, task... |
| Retrieve a node with its relations |
| Create a relation between two nodes |
| Walk the graph from a starting node |
| Walk along a reasoning chain |
| Break a task into structured subtasks |
| Update a node's data in-place |
| Replace outdated knowledge (keeps history) |
| Delete a node and its vector |
| Find things by meaning, across 50+ languages |
| Store text with automatic vectorization |
| Hybrid: semantic + graph subgraph expansion |
| Chronological graph traversal (time axis) |
| Flat timeline of all events in a session |
That's all 17 tools | See full list in |
Configuration
All via CORTEX_* environment variables:
Variable | Default | Description |
|
| SQLite database path |
|
| Qdrant host |
|
| Qdrant port |
|
| Connection timeout (s) |
|
| Qdrant collection name |
|
| Embedding model (50+ languages) |
|
| Days before auto-archive |
|
| Max hot nodes in viewport |
|
| 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 |
Full philosophy, data model, node taxonomy (17 types), relation taxonomy (22 types), SQL schema | |
Fractal memory architecture decision | |
SQLite + JSON for graph instead of Neo4j/Cayley | |
Qdrant for vectors (existing) | |
fastembed for embeddings (paraphrase-multilingual-MiniLM-L12-v2) | |
Desktop Viewport — context window strategy | |
Knowledge evolution: update / supersede / stale | |
Regression search: meaning → context → files | |
Temporal layer — time as first-class citizen | |
Project release history | |
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 -vTests 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 toolsdesktop_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_searchA
Hybrid search: vector search + expanded subgraphs. Does vector_search first, then expands each result's subgraph. Returns both vector results and their graph contexts. Use when you need deep context around search results — faster than calling vector_search then graph_get_node for each result manually.
CROSS-PROJECT: without workspace_id, searches ALL workspaces. Add workspace_id to narrow to one project.
Inputs: query (required), workspace_id.
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_searchA
Semantic vector search across all indexed layers (Entity + Chunk + Fact). Use to FIND RELEVANT KNOWLEDGE by meaning. Returns nodes sorted by relevance score. Then use graph_get_node or desktop_focus to expand the context. This is the PRIMARY entry point for the regression search pattern: 1. vector_search (meaning) -> 2. graph_get_node (context) -> 3. read files (specifics).
CROSS-PROJECT: without workspace_id, searches ALL workspaces. Add workspace_id to narrow to one project.
Inputs: query (required), workspace_id, top_k, time_from, +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…
This server cannot be deployed
TDQS
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Persistent working memory for AI agents: a knowledge graph with semantic search and decay.
Related MCP Servers
- AlicenseAqualityBmaintenancePersistent memory with knowledge graph visualization, semantic/hybrid search, importance scoring, and cloud sync (S3/R2) for cross-session context management.44749MIT
- AlicenseNot gradedqualityDmaintenanceProvides 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.290MIT
- AlicenseNot gradedqualityCmaintenanceA 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
- AlicenseNot gradedqualityDmaintenanceProvides persistent memory for AI coding agents through the Model Context Protocol, enabling them to store and retrieve project knowledge across sessions.27 npmMIT