How do I use MCP Roo Memory?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Roo Memory save that the user prefers dark mode for the UI" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Roo Memory

by mcasdfgf

Overview Schema Related Servers Score Discussions

Python

Local

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

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

Related MCP server: memora

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), config (19), database (26), graph (19), desktop (14), vector (19), server (19), integration (3) — 136+ total.

See CONTRIBUTING.md for guidelines.

License

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Tools

View all tools

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mcasdfgf/mcp-roo-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server