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
> **⚠️ 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
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):
> **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:
Then edit .roo/mcp.json in your project and add --workspace your-project-name:
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:
MCP config:
---
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 |