Getting Started

Retrace is a local-first AI work journal. It runs on your machine with SQLite — no account needed. When you want multi-device sync or a dashboard, you can switch to the cloud.

Quick Start (Local — Recommended)

Run the MCP server locally in 10 seconds. No account, no config, no data leaving your machine.

1. Add to your MCP client

VS Code (Copilot): Add to .vscode/mcp.json in any project:

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

Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor: Go to Settings → MCP and add the same config.

2. Start using it

Your agent now has access to all journal tools. Try asking:

• “Log that I fixed the Redis TTL bug — root cause was a 24h TTL when data changes hourly.”
• “What did I work on yesterday?”
• “Recall anything about caching problems.”

Data is stored at ~/.retrace/journal.db. You own it completely.

→ Full local setup guide — all MCP clients, custom paths, global install

Cloud Mode

Connect directly to the hosted MCP endpoint for multi-device sync, a web dashboard, and encrypted backup. No local binary needed.

1. Create an account

Visit retrace-zeta.vercel.app/register and sign in with GitHub, Google, or email/password.

2. Add to your MCP config

{
  "mcpServers": {
    "retrace": {
      "url": "https://retrace-zeta.vercel.app/mcp"
    }
  }
}

OAuth handles authentication automatically — your MCP client will open a browser window on first use.

→ Cloud upgrade guide — migrating from local, running both

Add Agent Instructions

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

# 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
- When a decision is made — include WHY
- When a bug is found — include root cause
- When a colleague is mentioned

## What to include
- content: Write for recall 3 months from now
- people: Anyone involved
- refs: Ticket IDs, PR numbers
- component: The system/module being worked on
- project: Consistent project name

## When to search
- User asks about past work → use recall or query_journal
- Before making architectural decisions