Local Setup

Run Retrace entirely on your machine using SQLite. No account, no cloud, no data leaving your laptop. Your journal lives at ~/.retrace/journal.db.

Quick Start

npx retrace-mcp@latest

That's it. The server starts and creates ~/.retrace/journal.db if it doesn't exist. Add it to your MCP client config to use it automatically.

MCP Client Configuration

VS Code (GitHub Copilot)

Add to your .vscode/mcp.json (project-level) or your user settings (~/.config/Code/User/settings.json):

{
  "servers": {
    "retrace": {
      "command": "npx",
      "args": ["-y", "retrace-mcp@latest"]
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\\Claude\\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "retrace": {
      "command": "npx",
      "args": ["-y", "retrace-mcp@latest"]
    }
  }
}

Cursor

Go to Settings → MCP and add:

{
  "mcpServers": {
    "retrace": {
      "command": "npx",
      "args": ["-y", "retrace-mcp@latest"]
    }
  }
}

Zed

Edit your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "retrace": {
      "command": {
        "path": "npx",
        "args": ["-y", "retrace-mcp@latest"]
      }
    }
  }
}

Custom Database Path

By default, Retrace stores your journal at ~/.retrace/journal.db. To use a different path:

# Via environment variable
RETRACE_DB_PATH=/path/to/my-journal.db npx retrace-mcp@latest

# Or via CLI flag
npx retrace-mcp@latest --db-path /path/to/my-journal.db

You can also set RETRACE_DB_PATH in your MCP client's environment config:

{
  "mcpServers": {
    "retrace": {
      "command": "npx",
      "args": ["-y", "retrace-mcp@latest"],
      "env": {
        "RETRACE_DB_PATH": "/Users/you/Documents/retrace.db"
      }
    }
  }
}

Global Install (Optional)

If you prefer a global install over npx:

npm install -g retrace-mcp retrace-mcp --version

Then use retrace-mcp as the command in your MCP config instead of npx.

Agent Instructions

Retrace works best when your agent is instructed to log proactively. Add a .github/instructions/retrace.md file to your project:

# Retrace Work Memory

You have access to Retrace via MCP. Use it proactively:

## When to log (call log_entry)
- When a meaningful task is completed (not just file edits)
- When a decision is made and WHY (e.g. "chose X over Y because...")
- When a bug is found — include root cause and resolution
- When context-switching to a different task
- When a colleague is mentioned or involved in the work

## What to include
- content: Write for future recall 3 months from now. Include technical specifics.
- people: Anyone mentioned, involved, or who should know
- refs: Ticket IDs, PR numbers, doc links mentioned in conversation
- component: The specific service/system/module being worked on
- project: The project name (use consistent names)

## When to search (call recall or query_journal)
- When the user asks about past work or decisions
- When you notice the current task is similar to something done before

Verifying It Works

After connecting your MCP client, ask your agent:

“Log that we just set up Retrace for local journaling.”

Then ask:

“What did I work on today?”

You should see the entry you just logged returned.

Data & Backup

Your journal is a single SQLite file. Back it up like any other file:

cp ~/.retrace/journal.db ~/Dropbox/retrace-backup.db

See the Export & Import guide for more options, including migration to cloud mode.

Upgrading to Cloud

When you want multi-device sync, a web dashboard, or team features, you can switch to the cloud endpoint. See the Cloud Upgrade guide.