/hindsight-docs

Cursor CLI

⚠️ Superseded by the Coding Agents plugin

The Cursor CLI integration is superseded by the Coding Agents plugin — one package covering Claude Code, Codex, opencode, Kilo, Cursor, Copilot, Grok, Antigravity, Devin and Cline and other CLI agents, with a per-repo memory bank they all share instead of one bank per agent.

This page and the published package still work; they are no longer developed. To switch:

cd /path/to/your/repo
npx @vectorize-io/hindsight-coding-agents install cursor-cli

Memory does not move automatically — the banks are scoped differently and this agent's history cannot be imported (it is kept in an internal database). See Migrating from the per-agent plugins. View Changelog →

Persistent memory for Cursor CLI using Hindsight. Python hook scripts automatically recall relevant context before each prompt and retain conversations after each turn — no changes to your Cursor workflow required.

Quick Start

💡 Recommended: Hindsight Cloud

Sign up free for a Hindsight Cloud API key — no self-hosting, no local daemon to manage.

# Install the CLI
pip install hindsight-cursor-cli

# Install the hooks (defaults to Hindsight Cloud)
hindsight-cursor-cli install --api-url https://api.hindsight.vectorize.io --api-token your-api-key

# Restart Cursor CLI — memory is live

The installer copies the hook scripts to ~/.cursor/hooks/cursor-cli/, writes ~/.cursor/hooks.json (merged with any existing entries), and creates ~/.hindsight/cursor-cli.json for your personal config.

Self-hosting alternative — connect to a local hindsight-embed daemon by omitting the flags:

hindsight-cursor-cli install

To uninstall:

hindsight-cursor-cli uninstall

Features

• Auto-recall — before each prompt, queries Hindsight for relevant memories and injects them as additional context (visible to the model, not the transcript)
• Auto-retain — after each response, and again on session end, stores the conversation to Hindsight for future recall
• Dynamic bank IDs — supports per-project memory isolation based on the working directory
• Session-level upsert — uses the session ID as the document ID so re-running the same session updates rather than duplicates stored content
• Zero runtime dependencies — the hook scripts are pure Python stdlib; the pip install only ships the one-time installer

Architecture

The plugin uses four Cursor CLI hook events:

On beforeSubmitPrompt, the hook reads the prompt, queries Hindsight for the most relevant memories, and injects a context block. Cursor prepends this to the conversation before sending it to the model:

<hindsight_memories>
Relevant memories from past conversations...
Current time - 2026-03-27 09:14

- Project uses FastAPI with asyncpg — not SQLAlchemy [world] (2026-03-26)
- Preferred testing framework: pytest with pytest-asyncio [experience] (2026-03-26)
</hindsight_memories>

On stop (and again on sessionEnd), the hook reads the session transcript, strips previously injected memory tags (to prevent feedback loops), and POSTs the conversation to Hindsight asynchronously.

Connection Modes

1. External API (recommended)

Connect to a running Hindsight server (cloud or self-hosted) via ~/.hindsight/cursor-cli.json:

{
  "hindsightApiUrl": "https://api.hindsight.vectorize.io",
  "hindsightApiToken": "hsk_your_token"
}

2. Local Daemon

Run hindsight-embed locally. The session_start.py hook detects it on apiPort (default 9077). The daemon is not auto-started by the plugin — start it separately:

uvx hindsight-embed

Then leave hindsightApiUrl empty in your config and the plugin connects to http://localhost:9077.

Configuration

Default config ships in ~/.cursor/hooks/cursor-cli/settings.json. For personal overrides that survive updates, create ~/.hindsight/cursor-cli.json. Most settings can also be overridden via environment variable.

Loading order (later entries win):

1. Built-in defaults
2. Plugin settings.json (at ~/.cursor/hooks/cursor-cli/settings.json)
3. User config (~/.hindsight/cursor-cli.json)
4. Environment variables

Connection

Memory Bank

Auto-Recall

Auto-Retain

Debug

Per-Project Memory

To give each project its own isolated memory bank, enable dynamic bank IDs:

{
  "dynamicBankId": true,
  "dynamicBankGranularity": ["agent", "project"]
}

With this config, running Cursor in ~/projects/api and ~/projects/frontend stores and recalls memories separately. Bank IDs are derived from the working directory path.

Troubleshooting

Hooks not firing: Confirm ~/.cursor/hooks.json exists and that python3 is on your shell's $PATH. Re-run hindsight-cursor-cli install to rewrite the hook entries.

No memories recalled: Recall returns results only after something has been retained. Complete one Cursor session first, then start a new one.

Memory not being stored: retainEveryNTurns defaults to 10 — the stop hook only fires a retain every 10 turns. While testing, add "retainEveryNTurns": 1 to ~/.hindsight/cursor-cli.json. The sessionEnd hook also forces a final retain when you close the session.

Debug mode: Add "debug": true to ~/.hindsight/cursor-cli.json to see what Hindsight is doing on each turn.