Skip to content

Commit 42e7260

Browse files
benfrank241benfrank241
authored
blog: Cursor persistent memory (editor + CLI in one post) (#2171)
* blog: add Cursor persistent memory post covering both integrations One post covers both new integrations: - hindsight-cursor (editor, first-party): plugin hooks + MCP server, with the Cursor 3.x additionalContext workaround via workspace rules-file fallback - hindsight-cursor-cli (CLI, community-built by @Korayem): four lifecycle hooks (sessionStart, beforeSubmitPrompt, stop, sessionEnd) The angle of the post is that both surfaces can share a single bankId and switch between editor and CLI mid-task without losing context. Every claim sourced from the integrations' README files: - Editor: install commands, sessionStart/stop hooks, MCP config, the Cursor 3.x bug + rules-file workaround, useRulesFileFallback flag, bankId default = "cursor" - CLI: four-hook table, install command, ~/.cursor/hooks.json shape, Cursor CLI v0.45+ requirement, bankId default = "cursor-cli", dynamicBankGranularity including gitProject Test stamps from both integrations on current main: - hindsight-cursor: 82 passed, 4 skipped - hindsight-cursor-cli: 87 passed, 0 skipped Cover is a placeholder (Codex art) for now; swap before merging. * blog(cursor): swap placeholder cover for Hindsight x Cursor card
1 parent 4835bf7 commit 42e7260

2 files changed

Lines changed: 193 additions & 0 deletions

File tree

‎hindsight-docs/blog/2026-06-12-cursor-persistent-memory.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: "Cursor Persistent Memory: One Bank for the Editor and the CLI"
3+
authors: [benfrank241]
4+
slug: "2026/06/12/cursor-persistent-memory"
5+
date: 2026-06-12T12:00
6+
tags: [cursor, cursor-cli, memory, persistent-memory, hindsight, coding-agents, tutorial]
7+
description: "Two new Hindsight integrations give Cursor persistent long-term memory: one for the Cursor editor (with a workaround for the broken sessionStart additionalContext channel in Cursor 3.x) and one for Cursor CLI. Both can share the same memory bank."
8+
image: /img/blog/cursor-persistent-memory.png
9+
hide_table_of_contents: true
10+
---
11+
12+
![Cursor Persistent Memory with Hindsight](/img/blog/cursor-persistent-memory.png)
13+
14+
[Cursor](https://cursor.com) has two surfaces a developer actually uses: the editor and the [Cursor CLI](https://cursor.com/docs/cli). Both run agents. Neither remembers anything between sessions. Today there are two new Hindsight integrations that fix that, and (this is the interesting part) they can both write to and read from the same memory bank. Switch from the editor to the CLI mid-task and the agent already knows what you decided yesterday.
15+
16+
This post is a walkthrough of both integrations: `hindsight-cursor` for the editor and `hindsight-cursor-cli` for the command-line agent. The story is mostly the same memory primitives wired into two different lifecycles, with one notable detail on the editor side: Cursor 3.x has a known bug in its session-start context-injection channel, and the editor integration ships with a clean workaround.
17+
18+
## TL;DR
19+
20+
<!-- truncate -->
21+
22+
- Two pip packages: `hindsight-cursor` (editor, first-party) and `hindsight-cursor-cli` (CLI, community-built by [@Korayem](https://github.com/Korayem)).
23+
- Both use Cursor's lifecycle hooks: recall before each chat session/prompt, retain after each task or every N turns.
24+
- **Editor integration also ships an MCP server** for explicit `recall` / `retain` / `reflect` tools during a session, on top of the automatic session-start recall.
25+
- **Editor integration works around a Cursor 3.x bug** that broke the native `additionalContext` injection channel. Memories get written to a workspace rules file that Cursor's rules engine reliably picks up.
26+
- **CLI integration has four hooks** (`sessionStart`, `beforeSubmitPrompt`, `stop`, `sessionEnd`) and requires Cursor CLI v0.45+.
27+
- Point both at the same `bankId` and switching surfaces is transparent.
28+
29+
## Why Cursor Needs Persistent Memory
30+
31+
A new Cursor session is a fresh model with no context. It can read the files in your workspace, and it has whatever you wrote in your `.cursor/rules`. What it doesn't have is anything about previous sessions: the bug you debugged on Tuesday, the architecture decision you talked through last week, the convention you've established for how this codebase names test files.
32+
33+
You can manually pin context with rules files. That works for the things you remember to write down, but not for the things you didn't realize were important until later. Persistent memory closes that gap: every session retains itself, every new session recalls relevant past content automatically.
34+
35+
Two surfaces, one memory layer.
36+
37+
## `hindsight-cursor`: The Editor Integration
38+
39+
The editor integration is a `pip` plugin that installs into your project's `.cursor-plugin/hindsight-memory/` directory. It wires up two complementary mechanisms.
40+
41+
**Plugin hooks (automatic).** `session_start.py` runs when the agent processes the first prompt of each new chat. It runs a project-level recall against your bank and surfaces the result so the agent sees it before it answers. `retain.py` runs on the `stop` event after each task and stores the transcript.
42+
43+
**MCP server (on-demand).** The installer also writes `.cursor/mcp.json` to connect Cursor to Hindsight's MCP endpoint, giving the agent three explicit tools (`recall`, `retain`, `reflect`) that it can call mid-session when it needs memory beyond what was injected at start.
44+
45+
### The Cursor 3.x Workaround
46+
47+
Cursor's native channel for delivering session-start hook output is the `additionalContext` JSON field: the hook prints memory text on stdout, Cursor places it in the agent's system prompt. In Cursor 3.x that channel is broken (the bug is [acknowledged by Cursor staff](https://forum.cursor.com/t/sessionstart-hook-additional-context-is-never-injected-into-agents-initial-system-context/158452), still open against 3.6.31 as of writing). If `additionalContext` is the only delivery path, recalled memories never reach the model.
48+
49+
The plugin works around it 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 memories on the very first prompt of every new chat.
50+
51+
A few details worth knowing:
52+
53+
- **Every new agent's first prompt has memories.** Cursor blocks prompt submission until the `sessionStart` hook returns; recall latency is typically under a second.
54+
- **The rules file is regenerated at the top of every `sessionStart`.** Stale memories from a previous session don't linger.
55+
- **The rules file is auto-`.gitignore`'d** in git workspaces (idempotent append; no-op for non-git workspaces).
56+
- **`additionalContext` is still emitted to stdout** for forward-compat. If Cursor restores the native channel, the same plugin keeps working without code changes.
57+
58+
If you'd rather not have the plugin touch your workspace rules, set `useRulesFileFallback: false` and the plugin will fall back to the (currently broken) native channel. Useful only if you'd rather see the bug bite than have the plugin write a rules file.
59+
60+
### Install
61+
62+
```bash
63+
pip install hindsight-cursor
64+
cd /path/to/your-project
65+
hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_KEY
66+
```
67+
68+
Then **fully quit and reopen Cursor**: plugins load at startup.
69+
70+
For self-hosting, drop the `--api-url` / `--api-token` flags and run Hindsight locally (`docker run ghcr.io/vectorize-io/hindsight:latest`). The plugin can also auto-manage a local `hindsight-embed` daemon via `uvx` if you'd rather not run a server yourself.
71+
72+
## `hindsight-cursor-cli`: The CLI Integration
73+
74+
The CLI integration is a separate package, community-built by [@Korayem](https://github.com/Korayem), that wires four Cursor CLI hooks to the same recall/retain primitives.
75+
76+
| Hook | Action |
77+
|---|---|
78+
| `sessionStart` | Confirms Hindsight is reachable and pre-warms the local daemon if needed |
79+
| `beforeSubmitPrompt` | Recalls relevant memories and injects them as `additional_context` |
80+
| `stop` | Retains the conversation to long-term memory every configured N turns |
81+
| `sessionEnd` | Forces a final retain so short sessions are still stored |
82+
83+
Two things this lifecycle does differently from the editor plugin:
84+
85+
- **Recall fires before every prompt, not just session start.** The CLI is a more turn-by-turn surface, and per-prompt recall means each new question gets context fitted to it rather than relying on a single broad project-level recall at the top.
86+
- **`sessionEnd` guarantees a retain.** Short CLI sessions (one or two prompts, then exit) used to drop on the floor if `stop` only fired every N turns. The `sessionEnd` hook closes that gap.
87+
88+
### Install
89+
90+
```bash
91+
pip install hindsight-cursor-cli
92+
hindsight-cursor-cli install --api-url https://api.hindsight.vectorize.io --api-token YOUR_KEY
93+
```
94+
95+
The installer copies the hook scripts to `~/.cursor/hooks/cursor-cli/`, writes `~/.cursor/hooks.json` (merged with any existing entries) with absolute paths to the scripts, and seeds `~/.hindsight/cursor-cli.json` for personal overrides. Restart Cursor CLI to load the hooks.
96+
97+
Cursor CLI v0.45+ is required for hooks support. The hook scripts use Python 3 stdlib only, with no `pip install` required at runtime.
98+
99+
## Sharing One Bank Across Both Surfaces
100+
101+
Both integrations write to a `bankId`. By default the editor uses `cursor` and the CLI uses `cursor-cli`. Point them at the same bank and they share memory:
102+
103+
```json
104+
// ~/.hindsight/cursor.json AND ~/.hindsight/cursor-cli.json
105+
{
106+
"hindsightApiUrl": "https://api.hindsight.vectorize.io",
107+
"hindsightApiToken": "hsk_your_key",
108+
"bankId": "my-cursor-memory"
109+
}
110+
```
111+
112+
Now anything you retain from a CLI session shows up in the editor's session-start recall, and vice-versa. A decision you talked through with the CLI agent on the train Tuesday morning lands in your editor's first prompt Tuesday afternoon.
113+
114+
For per-project isolation across both surfaces, switch both configs to dynamic bank IDs:
115+
116+
```json
117+
{
118+
"dynamicBankId": true,
119+
"dynamicBankGranularity": ["agent", "project"]
120+
}
121+
```
122+
123+
Both integrations derive `project` from the workspace path (basename). The CLI also supports `gitProject` if you want to share memory across worktrees of the same repo.
124+
125+
## What's the Same and What's Different
126+
127+
Most of the config surface is shared. The differences are about what each surface can do, not how Hindsight behaves.
128+
129+
| | `hindsight-cursor` (editor) | `hindsight-cursor-cli` (CLI) |
130+
|---|---|---|
131+
| Author | Hindsight team (first-party) | [@Korayem](https://github.com/Korayem) (community) |
132+
| Hooks | `sessionStart`, `stop` | `sessionStart`, `beforeSubmitPrompt`, `stop`, `sessionEnd` |
133+
| Recall trigger | Once per chat (session start) | Once per prompt |
134+
| MCP server | Yes (`recall` / `retain` / `reflect` tools) | No |
135+
| Cursor 3.x `additionalContext` workaround | Workspace rules-file fallback | n/a (uses different channel) |
136+
| Local daemon auto-management | Yes (`uvx hindsight-embed`) | Yes |
137+
| Default `bankId` | `cursor` | `cursor-cli` |
138+
| Cursor version requirement | Cursor 3.x (works around the bug) | Cursor CLI v0.45+ |
139+
| Runtime Python deps | stdlib only | stdlib only |
140+
141+
Both share: full `retainMode` semantics (`full-session` / `chunked`), `recallBudget` (`low` / `mid` / `high`), `recallMaxTokens`, `dynamicBankId` + `dynamicBankGranularity`, `HINDSIGHT_*` environment-variable overrides, and Hindsight Cloud or self-host connection.
142+
143+
## Tradeoffs
144+
145+
**Editor: the rules-file workaround puts a file in your workspace.** It's small, regenerated every session, and auto-`.gitignore`'d. Most people won't notice. If you'd rather not have the plugin write to your workspace at all, `useRulesFileFallback: false` reverts to the native channel, at the cost of no memory delivery until Cursor fixes the upstream bug.
146+
147+
**CLI: per-prompt recall costs more.** Every prompt triggers a Hindsight query before the agent runs. On Hindsight Cloud that's typically well under a second, but it's not free. Drop `recallBudget` to `"low"`, or set `autoRecall: false`, if you need to skip it.
148+
149+
**Both: retain extracts facts asynchronously.** The retain call returns when the transcript lands in the bank, not when the extractor finishes. Facts become recallable within seconds. That's fine for chat-style workflows where the next session is at least a minute away. For automated scripts that retain-then-recall in the same run, give the extractor a beat.
150+
151+
**Two banks vs. one is a real choice.** Sharing one bank is convenient but mixes editor and CLI usage patterns in the same fact set. Two banks gives each surface its own context but loses the cross-surface continuity. Most people will be happier with one shared bank; tag-based filtering (`retainTags`) can still differentiate which surface produced what if you need to.
152+
153+
## Setup
154+
155+
The fast path for both:
156+
157+
1. Sign up at [hindsight.vectorize.io](https://ui.hindsight.vectorize.io/signup) (free tier is enough).
158+
2. Grab an API key from the dashboard.
159+
3. Install whichever integration(s) you want:
160+
```bash
161+
pip install hindsight-cursor # editor
162+
pip install hindsight-cursor-cli # CLI
163+
```
164+
4. Run the installer once per integration:
165+
```bash
166+
cd /path/to/your-project
167+
hindsight-cursor init --api-url https://api.hindsight.vectorize.io --api-token YOUR_KEY
168+
hindsight-cursor-cli install --api-url https://api.hindsight.vectorize.io --api-token YOUR_KEY
169+
```
170+
5. Restart Cursor (fully quit and reopen the editor; restart the CLI session). The agent has memory from the next prompt onward.
171+
172+
If you want both surfaces to share a bank, set the same `bankId` in `~/.hindsight/cursor.json` and `~/.hindsight/cursor-cli.json`.
173+
174+
## Recap
175+
176+
| | Cursor default | With Hindsight |
177+
|---|---|---|
178+
| Memory across sessions (editor) | None | Recalled at session start, retained on `stop` |
179+
| Memory across prompts (CLI) | None | Recalled before each prompt, retained on `stop` + `sessionEnd` |
180+
| On-demand memory tools in editor | None | MCP `recall` / `retain` / `reflect` |
181+
| Per-project isolation | Manual rules | Optional via `dynamicBankId` |
182+
| Shared memory across editor + CLI | n/a | One `bankId` across both configs |
183+
| Cursor 3.x `additionalContext` bug | Hits you | Worked around via rules file |
184+
185+
## Next Steps
186+
187+
- **Hindsight Cloud:** [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io/signup)
188+
- **Editor integration docs:** [Cursor + Hindsight](/sdks/integrations/cursor)
189+
- **CLI integration docs:** [Cursor CLI + Hindsight](/sdks/integrations/cursor-cli)
190+
- **Sources:**
191+
[`hindsight-integrations/cursor`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/cursor),
192+
[`hindsight-integrations/cursor-cli`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/cursor-cli)
193+
- **Hindsight API reference:** [API quickstart](/developer/api/quickstart)

‎hindsight-docs/static/img/blog/cursor-persistent-memory.png‎

316 KB
Loading

0 commit comments

Comments
 (0)