Hindsight Memory Plugin for Cursor

Biomimetic long-term memory for Cursor using Hindsight. Automatically recalls relevant context at session start and retains conversation transcripts for future use.

Quick Start

Option A — Hindsight Cloud (fastest)

No local server needed. Sign up for Hindsight Cloud and create an API key under Settings > API Keys.

cd /path/to/your-project
pip install hindsight-cursor
hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_HINDSIGHT_API_TOKEN

If Cursor is already open, fully quit and reopen it after installing. Plugins load at startup.

Option B — Local Hindsight server

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

Then install the plugin:

cd /path/to/your-project
pip install hindsight-cursor
hindsight-cursor init --api-url http://localhost:8888

You can also use uvx hindsight-cursor init instead of pip install + hindsight-cursor init if you prefer not to install the package permanently.

What init does

• Copies plugin files into .cursor-plugin/hindsight-memory/
• Writes/merges project .cursor/hooks.json so Cursor registers sessionStart / stop / sessionEnd (workspace-relative commands — plugin-dir hooks alone are not loaded by the IDE). 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 recall/retain/reflect 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.

After installing, fully quit and reopen Cursor. The plugin activates automatically.

Features

• Session recall — at the start of each session, queries Hindsight for relevant project memories and injects them as context via additionalContext
• Auto-retain — after every task, extracts and retains conversation content to Hindsight for long-term storage
• On-demand MCP tools — use recall, retain, and reflect tools from the Hindsight MCP server for explicit memory operations during a session
• On-demand recall skill — use the hindsight-recall skill for explicit 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 two complementary mechanisms:

1. Plugin Hooks (automatic)

The sessionStart hook fires when the agent processes the first prompt of each new chat. It performs a broad project-level recall and surfaces the result two ways — see "How session memory reaches the agent" below for why both.

The stop hook fires when the agent completes a task. It reads the conversation transcript and retains it to Hindsight for future recall.

retain.py is also registered on sessionEnd, which fires once when the conversation ends and acts as a final flush.

Without it, 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 two events overlap at the end of a conversation. The plugin records how many transcript messages it has already retained per session, so a run with nothing new is a no-op — the overlap cannot double-store.

How session memory reaches the agent

Cursor's native injection channel for session-start hooks is the additionalContext JSON field — the hook returns memory text on stdout and Cursor places it in the agent's system prompt. That channel has been broken in Cursor 3.x (acknowledged by Cursor staff in forum thread 158452; reconfirmed still-open against Cursor 3.6.31). When additionalContext is the only delivery path, recalled memories never reach the model — the agent answers as if Hindsight isn't installed.

This plugin works around the bug by also writing the recalled memories to <workspace>/.cursor/rules/hindsight-session.mdc with alwaysApply: true in the frontmatter. Workspace rules files are reliably injected by Cursor's rules engine, so the agent sees the memories on the very first prompt of each new chat.

What this means in practice:

• Every new agent's first prompt has memories. Cursor blocks prompt submission until the sessionStart hook returns — verified empirically. The only delay is the recall latency itself (typically <1s).
• The rules file is regenerated at the top of every sessionStart. Stale memories from a previous session never linger.
• The rules file is auto-.gitignore'd in git workspaces. It's safe to delete by hand; it'll be regenerated.
• additionalContext is still emitted to stdout for forward-compat. If Cursor restores the native channel, the same plugin keeps working without code changes.

You can disable the rules-file write entirely (useRulesFileFallback: false) — then the plugin relies on additionalContext, which means no memory delivery until Cursor fixes the upstream bug. Useful only if you'd rather see the bug bite than have the plugin touch your workspace.

2. MCP Server (on-demand)

The init command also configures Cursor's native MCP support (.cursor/mcp.json) to connect directly to Hindsight's MCP endpoint. This gives the agent access to explicit tools:

• recall — search for specific memories by query
• retain — store specific content to memory
• reflect — reason over accumulated memories with a question

The agent can use these tools mid-session when it needs memory beyond what was injected at session start.

Library Modules

Connection Modes

1. External API (recommended for production)

Connect to a running Hindsight server (cloud or self-hosted).

{
  "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.

{
  "hindsightApiUrl": "",
  "apiPort": 9077
}

3. Existing Local Server

If you already have hindsight-embed running, leave hindsightApiUrl empty and set apiPort to match your server's port.

Configuration

All settings live in ~/.hindsight/cursor.json. Every setting can also be overridden via environment variables. The plugin ships with sensible defaults.

Loading order (later entries win):

1. Built-in defaults (hardcoded in the plugin)
2. Plugin settings.json (ships with the plugin)
3. User config (~/.hindsight/cursor.json)
4. Environment variables

Connection & Daemon

Memory Bank

Session Recall

Auto-Retain

LLM (Daemon Mode)

Debug

Development

# Run tests
pip install pytest
python -m pytest tests/ -v

Links

• Hindsight Documentation
• Cursor Documentation
• GitHub Repository

License

MIT