Skip to content

Commit 4a0a599

Browse files
benfrank241benfrank241
authored
fix(docs): add cursor-cli to integrations gallery (#2060)
The cursor-cli release (integrations/cursor-cli/v0.1.0, #1975) created a release tag but never added the integration to the docs single source of truth. check-integrations.mjs enforces that every released integration tag has an entry in src/data/integrations.json with a matching doc page, so the build-docs job has been failing on every PR (e.g. #866) — not from those PRs' changes, but from the missing cursor-cli entry on main. Add the gallery entry, the docs-integrations/cursor-cli.md page, and an icon. Both invariants now pass locally.
1 parent bfdc1c5 commit 4a0a599

3 files changed

Lines changed: 207 additions & 0 deletions

File tree

‎hindsight-docs/docs-integrations/cursor-cli.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
---
2+
sidebar_position: 7
3+
title: "Cursor CLI Persistent Memory with Hindsight | Integration Guide"
4+
description: "Add persistent memory to Cursor CLI with Hindsight. Python hook scripts automatically recall context before each prompt and retain conversations — no workflow changes required."
5+
---
6+
7+
# Cursor CLI
8+
9+
[View Changelog →](/changelog/integrations/cursor-cli)
10+
11+
Persistent memory for [Cursor CLI](https://docs.cursor.com/en/cli/overview) using [Hindsight](https://vectorize.io/hindsight). Python hook scripts automatically recall relevant context before each prompt and retain conversations after each turn — no changes to your Cursor workflow required.
12+
13+
## Quick Start
14+
15+
:::tip Recommended: Hindsight Cloud
16+
[Sign up free](https://ui.hindsight.vectorize.io/signup) for a Hindsight Cloud API key — no self-hosting, no local daemon to manage.
17+
:::
18+
19+
```bash
20+
export HINDSIGHT_API_URL=https://api.hindsight.vectorize.io
21+
export HINDSIGHT_API_TOKEN=your-api-key
22+
23+
git clone https://github.com/vectorize-io/hindsight.git
24+
cd hindsight/hindsight-integrations/cursor-cli
25+
./scripts/install.sh
26+
```
27+
28+
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. Restart Cursor CLI — memory is live.
29+
30+
To uninstall:
31+
32+
```bash
33+
./scripts/uninstall.sh
34+
```
35+
36+
## Features
37+
38+
- **Auto-recall** — before each prompt, queries Hindsight for relevant memories and injects them as additional context (visible to the model, not the transcript)
39+
- **Auto-retain** — after each response, and again on session end, stores the conversation to Hindsight for future recall
40+
- **Dynamic bank IDs** — supports per-project memory isolation based on the working directory
41+
- **Session-level upsert** — uses the session ID as the document ID so re-running the same session updates rather than duplicates stored content
42+
- **Zero dependencies** — pure Python stdlib, no pip install required
43+
44+
## Architecture
45+
46+
The plugin uses four Cursor CLI hook events:
47+
48+
| Hook | Event | Purpose |
49+
|------|-------|---------|
50+
| `session_start.py` | `sessionStart` | Warm up — verify Hindsight is reachable |
51+
| `recall.py` | `beforeSubmitPrompt` | **Auto-recall** — query memories, inject as additional context |
52+
| `retain.py` | `stop` | **Auto-retain** — extract transcript, POST to Hindsight (async) |
53+
| `session_end.py` | `sessionEnd` | **Final flush** — force a retain so the last turns aren't lost |
54+
55+
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:
56+
57+
```
58+
<hindsight_memories>
59+
Relevant memories from past conversations...
60+
Current time - 2026-03-27 09:14
61+
62+
- Project uses FastAPI with asyncpg — not SQLAlchemy [world] (2026-03-26)
63+
- Preferred testing framework: pytest with pytest-asyncio [experience] (2026-03-26)
64+
</hindsight_memories>
65+
```
66+
67+
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.
68+
69+
## Connection Modes
70+
71+
### 1. External API (recommended)
72+
73+
Connect to a running Hindsight server (cloud or self-hosted) via `~/.hindsight/cursor-cli.json`:
74+
75+
```json
76+
{
77+
"hindsightApiUrl": "https://api.hindsight.vectorize.io",
78+
"hindsightApiToken": "hsk_your_token"
79+
}
80+
```
81+
82+
### 2. Local Daemon
83+
84+
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:
85+
86+
```bash
87+
uvx hindsight-embed
88+
```
89+
90+
Then leave `hindsightApiUrl` empty in your config and the plugin connects to `http://localhost:9077`.
91+
92+
## Configuration
93+
94+
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.
95+
96+
**Loading order** (later entries win):
97+
98+
1. Built-in defaults
99+
2. Plugin `settings.json` (at `~/.cursor/hooks/cursor-cli/settings.json`)
100+
3. User config (`~/.hindsight/cursor-cli.json`)
101+
4. Environment variables
102+
103+
---
104+
105+
### Connection
106+
107+
| Setting | Env Var | Default | Description |
108+
|---------|---------|---------|-------------|
109+
| `hindsightApiUrl` | `HINDSIGHT_API_URL` | `""` | URL of the Hindsight API server. Empty = local daemon. |
110+
| `hindsightApiToken` | `HINDSIGHT_API_TOKEN` | `null` | API token for authentication. Required for Hindsight Cloud. |
111+
| `apiPort` | `HINDSIGHT_API_PORT` | `9077` | Port for the local `hindsight-embed` daemon. |
112+
113+
---
114+
115+
### Memory Bank
116+
117+
| Setting | Env Var | Default | Description |
118+
|---------|---------|---------|-------------|
119+
| `bankId` | `HINDSIGHT_BANK_ID` | `"cursor-cli"` | The bank to read from and write to. All sessions share this bank unless `dynamicBankId` is enabled. |
120+
| `bankMission` | `HINDSIGHT_BANK_MISSION` | coding assistant prompt | Describes the agent's purpose. Sent when creating or updating the bank. |
121+
| `retainMission` | — | extraction prompt | Instructions for Hindsight's fact extraction — what to extract from coding conversations. |
122+
| `dynamicBankId` | `HINDSIGHT_DYNAMIC_BANK_ID` | `false` | When `true`, derives a unique bank ID from `dynamicBankGranularity` fields — useful for per-project isolation. |
123+
| `dynamicBankGranularity` | — | `["agent", "project"]` | Which fields to combine for dynamic bank IDs. `"project"` = working directory, `"agent"` = agent name. |
124+
| `agentName` | `HINDSIGHT_AGENT_NAME` | `"cursor-cli"` | Agent name used in dynamic bank ID derivation. |
125+
126+
---
127+
128+
### Auto-Recall
129+
130+
| Setting | Env Var | Default | Description |
131+
|---------|---------|---------|-------------|
132+
| `autoRecall` | `HINDSIGHT_AUTO_RECALL` | `true` | Master switch for auto-recall. |
133+
| `recallBudget` | `HINDSIGHT_RECALL_BUDGET` | `"mid"` | Search depth: `"low"` (fast), `"mid"` (balanced), `"high"` (thorough). |
134+
| `recallMaxTokens` | `HINDSIGHT_RECALL_MAX_TOKENS` | `1024` | Max tokens in the recalled memory block. |
135+
| `recallTypes` | — | `["world", "experience"]` | Memory types to retrieve. |
136+
| `recallContextTurns` | `HINDSIGHT_RECALL_CONTEXT_TURNS` | `1` | Prior turns to include when building the recall query. `1` = latest prompt only. |
137+
138+
---
139+
140+
### Auto-Retain
141+
142+
| Setting | Env Var | Default | Description |
143+
|---------|---------|---------|-------------|
144+
| `autoRetain` | `HINDSIGHT_AUTO_RETAIN` | `true` | Master switch for auto-retain. |
145+
| `retainMode` | `HINDSIGHT_RETAIN_MODE` | `"full-session"` | `"full-session"` sends the full transcript per session (upserted by session ID). `"chunked"` sends sliding windows every N turns. |
146+
| `retainEveryNTurns` | — | `10` | Retain fires every N turns. `1` = every turn. Higher values reduce API calls. |
147+
| `retainContext` | — | `"cursor-cli"` | Label identifying the source integration. Useful when multiple integrations write to the same bank. |
148+
149+
---
150+
151+
### Debug
152+
153+
| Setting | Env Var | Default | Description |
154+
|---------|---------|---------|-------------|
155+
| `debug` | `HINDSIGHT_DEBUG` | `false` | Enable verbose logging to stderr. All log lines are prefixed with `[Hindsight]`. |
156+
157+
## Per-Project Memory
158+
159+
To give each project its own isolated memory bank, enable dynamic bank IDs:
160+
161+
```json
162+
{
163+
"dynamicBankId": true,
164+
"dynamicBankGranularity": ["agent", "project"]
165+
}
166+
```
167+
168+
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.
169+
170+
## Troubleshooting
171+
172+
**Hooks not firing**: Confirm `~/.cursor/hooks.json` exists and that `python3` is on your shell's `$PATH`. Re-run `./scripts/install.sh` to rewrite the hook entries.
173+
174+
**No memories recalled**: Recall returns results only after something has been retained. Complete one Cursor session first, then start a new one.
175+
176+
**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.
177+
178+
**Debug mode**: Add `"debug": true` to `~/.hindsight/cursor-cli.json` to see what Hindsight is doing on each turn.

‎hindsight-docs/src/data/integrations.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,16 @@
140140
"link": "/sdks/integrations/codex",
141141
"icon": "/img/icons/codex.svg"
142142
},
143+
{
144+
"id": "cursor-cli",
145+
"name": "Cursor CLI",
146+
"description": "Automatic long-term memory for Cursor CLI via Hindsight hooks. Recalls relevant context before each prompt and retains conversations after each turn.",
147+
"type": "official",
148+
"by": "hindsight",
149+
"category": "tool",
150+
"link": "/sdks/integrations/cursor-cli",
151+
"icon": "/img/icons/cursor-cli.svg"
152+
},
143153
{
144154
"id": "openclaw",
145155
"name": "OpenClaw",

‎hindsight-docs/static/img/icons/cursor-cli.svg‎

Lines changed: 19 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)