/hindsight-docs

Cursor

Biomimetic long-term memory for Cursor using Hindsight. Automatically recalls relevant project context at session start and retains conversation transcripts after each task — adapted to Cursor's hook-based plugin architecture with MCP for on-demand tools.

View Changelog →

How It Works

The Hindsight plugin uses two complementary mechanisms:

Both are set up by a single hindsight-cursor init command. Use --no-mcp to skip the MCP integration if you only want hooks.

Quick Start

# 1. Install the plugin
pip install hindsight-cursor
cd /path/to/your-project

# 2a. Connect to Hindsight Cloud (fastest — no local server needed)
hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_HINDSIGHT_API_TOKEN

# 2b. Or connect to a local Hindsight server
hindsight-cursor init --api-url http://localhost:8888

# 3. Fully quit and reopen Cursor — plugins load at startup

Sign up at Hindsight Cloud to get a token, or start Hindsight locally with Docker:

export OPENAI_API_KEY=your-key
docker run --rm -it --pull always -p 8888:8888 \
  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
  -e HINDSIGHT_API_LLM_MODEL=gpt-4o-mini \
  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
  ghcr.io/vectorize-io/hindsight:latest

What init does

• Copies plugin files into .cursor-plugin/hindsight-memory/
• Writes/merges project .cursor/hooks.json so Cursor registers the hooks. Cursor only loads hooks from .cursor/hooks.json (workspace) or ~/.cursor/hooks.json (user) — files under .cursor-plugin/ are not enough on their own. Hooks you already had are preserved, and re-running init replaces only Hindsight's own entries.
• Creates ~/.hindsight/cursor.json with your connection settings (if the file does not already exist)
• Writes .cursor/mcp.json with the Hindsight MCP endpoint for on-demand tools
• Use --force to overwrite an existing installation
• Use --no-mcp to skip the MCP configuration

hindsight-cursor uninstall reverses all of it: the plugin directory, Hindsight's .cursor/hooks.json entries, the MCP server entry, the generated session rules file, and its .gitignore line.

🚨 Caution

If you add the plugin to an already-open workspace, fully quit Cursor and reopen it. Plugins are loaded at startup — a simple window reload is not enough.

Features

• Session recall — at the start of each session, queries Hindsight for relevant project memories and injects them as context via additionalContext (invisible to the chat, visible to the agent)
• Auto-retain — after every task completion, extracts and retains conversation content to Hindsight for long-term storage
• On-demand MCP tools — recall, retain, and reflect tools for explicit mid-session memory operations
• On-demand recall skill — use the hindsight-recall skill for manual memory lookups
• Daemon management — can auto-start/stop hindsight-embed locally or connect to an external Hindsight server
• Dynamic bank IDs — supports per-agent, per-project, or per-session memory isolation
• Zero runtime dependencies — plugin scripts use pure Python stdlib only

Architecture

The plugin uses Cursor's hook system:

The sessionStart hook fires once when a new Cursor session begins. It performs a broad project-level recall and injects relevant memories as hidden context.

retain.py runs on sessionEnd as well. Without that, every conversation shorter than retainEveryNTurns is lost outright: at the default of 10, a seven-turn chat fires stop seven times, the turn gate rejects all seven, and the session is never stored. sessionEnd bypasses the turn window so the tail of a session is always retained. The plugin tracks how many transcript messages it has already retained per session, so the overlap between the two events cannot double-store.

The init command also configures Cursor's MCP support (.cursor/mcp.json) to connect to Hindsight's MCP endpoint, giving the agent explicit recall, retain, and reflect tools for mid-session use.

Additionally, the plugin provides:

• Skill (hindsight-recall) — on-demand memory querying
• Rule (hindsight-memory.mdc) — always-on rule instructing the agent to leverage recalled memories and MCP tools

Connection Modes

1. External API (recommended for production)

Connect to a running Hindsight server (cloud or self-hosted). No local LLM needed — the server handles fact extraction.

{
  "hindsightApiUrl": "https://your-hindsight-server.com",
  "hindsightApiToken": "your-token"
}

2. Local Daemon (auto-managed)

The plugin automatically starts and stops hindsight-embed via uvx. Requires an LLM provider API key for local fact extraction.

Set an LLM provider:

export OPENAI_API_KEY="sk-your-key"
# or
export ANTHROPIC_API_KEY="your-key"

The model is selected automatically by the Hindsight API. To override, set HINDSIGHT_LLM_MODEL.

3. Existing Local Server

If you already have hindsight-embed running, leave hindsightApiUrl empty and set apiPort to match your server's port. The plugin will detect it automatically.

Configuration

All settings live in ~/.hindsight/cursor.json. Every setting can also be overridden via environment variables. The plugin ships with sensible defaults — you only need to configure what you want to change.

Loading order (later entries win):

1. Built-in defaults (hardcoded in the plugin)
2. Plugin settings.json (ships with the plugin, at CURSOR_PLUGIN_ROOT/settings.json)
3. User config (~/.hindsight/cursor.json — recommended for your overrides)
4. Environment variables

Connection & Daemon

LLM Provider (local daemon only)

These settings configure which LLM the local daemon uses for fact extraction. They are ignored when connecting to an external API.

Memory Bank

A bank is an isolated memory store — like a separate "brain."

Session Recall

Session recall runs once at the start of each session. It queries Hindsight for relevant project memories and injects them into the agent's context as invisible additionalContext.

Auto-Retain

Auto-retain runs after the agent completes a task. It extracts the conversation transcript and sends it to Hindsight.

Debug

Verifying Plugin Hooks

The plugin writes a status file on every hook invocation — even when no memories are found or retain is skipped. Check them to confirm hooks are firing:

# Default location when CURSOR_PLUGIN_DATA is not set:
cat ~/.hindsight/cursor-state/state/last_recall.json
cat ~/.hindsight/cursor-state/state/last_retain.json

Each file contains:

• saved_at — timestamp of the last invocation
• status — one of success, empty, skipped, or error
• bank_id — which bank was used (present on success and empty)
• mode — always plugin
• hook — sessionStart for recall
• result_count (recall) or message_count (retain) — present on success

If saved_at updates when you use Cursor, the hooks are firing. Check status to understand what happened.

Troubleshooting

Plugin not activating: Check that .cursor-plugin/plugin.json exists in the plugin directory. Enable "debug": true in ~/.hindsight/cursor.json and check stderr output.

Seeing "Ran Recall in hindsight" in the Agent Window? That is MCP, not the plugin. Plugin-based recall is silent — it injects context via additionalContext without a visible tool call. If you see explicit Hindsight tool calls, you have MCP configured in .cursor/mcp.json. Both can work together.

Recall returning no memories: Verify the Hindsight server is reachable (curl http://localhost:9077/health). Memories need at least one retain cycle.

Daemon not starting: Ensure an LLM API key is set. Review daemon logs at ~/.hindsight/profiles/cursor.log.

High latency on session start: The session recall hook has a 15-second timeout. Use recallBudget: "low" or reduce recallMaxTokens.