mcp-roo-memory

Purpose

mcp-roo-memory provides persistent, graph-based memory capabilities for the Roo Code coding agent. LLM memory is short-lived, starting from scratch in every conversation, with context windows overflowing, past decisions fading, and reasoning chains disappearing. This project provides AI agents with a structured, persistent "brain" through the Model Context Protocol (MCP).

Key Capabilities

• Graph memory: Knowledge is not a flat dump, but a fractal graph composed of tasks, entities, facts, and decisions.
• Semantic search: Search by meaning rather than keywords, supporting over 50 languages.
• Context window control: hot/cold/archive tiering to avoid being overwhelmed by tokens.
• Knowledge evolution: Decisions can be superseded, facts can be updated, and outdated data can be archived.
• Time awareness: Time is a first-class citizen, supporting chronological traversal, session timelines, and temporal vector filtering.

Three-layer intelligence architecture:

• Graph (SQLite): who is related to whom, what decomposes into what.
• Vectors (Qdrant): what the meaning is, what is semantically similar.
• Desktop (viewport): what the current context window can hold.

How to Use

Docker (recommended)

Zero system dependencies, only Docker is required. Everything runs in containers, with no need for Python, venv, or pip. Start two containers. Add Cortex as a global MCP server; the server always runs in Docker, and any project can connect.

Edit ~/.config/VSCodium/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json(VS Code users replace the path VSCodium with Code).

To isolate memory per project, copy the reference .roo/ directory into the project, then edit the project's .roo/mcp.jsonto add --workspace your-project-name, and replace your-project-name with a unique identifier (such as mcp-roo-memory、researcher、ai-pulse).

Isolation mechanism:

• desktop_open() and graph_add_node() always write to the project workspace.
• workspace_id without vector_search() searches across all projects (cross-project recall).
• vector_search(workspace_id="project") narrows the search to a single project.

Restart Roo Code, and the agent then has persistent memory with zero system pollution.

Native pip (advanced)

If you do not want to use Docker, or you are developing Cortex itself, you can use the native pip approach.

Using as the Main Roo Memory

Copy the .roo/ directory into the project to make Cortex the agent's default memory system. This directory contains ready-to-use reference configuration. To learn more about the memory model, see CONCEPT.md. All configuration is done through CORTEX_* environment variables.

Suitable Scenarios

Suitable for Roo Code coding agent users who need to preserve tasks, entities, facts, and decisions across sessions, especially in multi-project environments where global recall or per-workspace memory isolation is desired.

Limitations

The project describes itself as an experimental project, an exploration of form and architecture. Although tests can be run, it should be regarded as a proof of concept (PoC). The software is provided "as is", without any warranty, and you use it at your own risk; see LICENSE for details.