/hindsight-docs

Roo Code

Persistent long-term memory for Roo Code via Hindsight. A one-command installer registers Hindsight's MCP server and injects custom rules that teach Roo to recall context before tasks and retain learnings after.

View Changelog →

Quick Start

💡 Hindsight Cloud (recommended)

Sign up free — get an API key instantly, no infrastructure to run.

# Install the CLI
pip install hindsight-roo-code

# Install the integration into your project (defaults to Hindsight Cloud)
hindsight-roo-code install

# Restart Roo Code — memory is active

Self-hosting alternative:

# Start Hindsight locally first
pip install hindsight-all
export HINDSIGHT_API_LLM_API_KEY=your-openai-key
hindsight-api

# Then install with the local URL
hindsight-roo-code install --api-url http://localhost:8888

How It Works

Roo Code has two primary extensibility mechanisms: MCP servers for tools and custom rules for system-prompt injection. This integration uses both.

New task starts
  └─ Rules file instructs Roo to call recall
       └─ Relevant memories injected into context automatically

Agent working…
  └─ Agent calls retain for significant decisions/discoveries

Task ends
  └─ Rules file instructs Roo to call retain with a summary
       └─ Summary stored for future sessions

The installer writes:

• .roo/mcp.json — registers Hindsight's /mcp endpoint as an MCP server, with recall and retain auto-approved
• .roo/rules/hindsight-memory.md — instructions injected into every Roo system prompt

Installation Options

Project-local install (default)

Writes to .roo/ in the current directory — memory is scoped to this project:

hindsight-roo-code install
hindsight-roo-code install --api-url https://api.hindsight.vectorize.io  # default (Hindsight Cloud)
hindsight-roo-code install --api-url http://localhost:8888                 # self-hosted
hindsight-roo-code install --project-dir /path/to/project

Global install

Writes to ~/.roo/ — applies to all projects:

hindsight-roo-code install --global

Configuration

The MCP entry written to .roo/mcp.json:

{
  "mcpServers": {
    "hindsight": {
      "type": "streamable-http",
      "url": "http://localhost:8888/mcp",
      "timeout": 30,
      "alwaysAllow": ["recall", "retain"]
    }
  }
}

To update the API URL after installation, re-run the installer or edit .roo/mcp.json directly.

MCP Tools

Hindsight exposes two tools via its /mcp endpoint:

The rules file instructs Roo to call these automatically at task start and end. Agents can also call them explicitly mid-task.

Verifying Setup

1. Start Hindsight and run the installer
2. Open Roo Code in your project
3. Check Settings → MCP Servers — hindsight should show as connected
4. Start a task — you should see recall invoked in the tool call log

Prerequisites

A running Hindsight instance:

Hindsight Cloud (recommended): Sign up — no self-hosting required.

Self-hosted:

pip install hindsight-all
export HINDSIGHT_API_LLM_API_KEY=your-api-key
hindsight-api  # starts on http://localhost:8888