Skip to content

Commit d5df9ad

Browse files
benfrank241benfrank241
authored
blog: Cline persistent memory (lifecycle hooks, no MCP) (#2085)
* blog: add Cline persistent memory integration post Walkthrough of the new Hindsight + Cline integration that wires up persistent memory via Cline's lifecycle hooks (no MCP). Covers the four hooks, install + config, per-project and team memory patterns, and tradeoffs. Cover is a placeholder (Codex art) for now — swap before merging. * blog(cline): replace em-dashes with contextual punctuation Targeted sweep replacing 21 em-dashes with the appropriate punctuation (commas / semicolons / periods / colons) given each surrounding clause. The table-cell placeholder on the "Model tool-calling needed" row becomes "n/a" so the column still reads as "not applicable for the default." Code blocks, URLs, file paths, and the ASCII flow diagram (which uses U+2500 box-drawing characters, not em-dashes) are untouched. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * blog(cline): explain why Cloud matters for the Cline workflow Expand the Cloud-section intro to cover the Cline-specific wins: multi-machine VS Code sync, no LLM key in the hook environment, and no local hindsight-api to keep running while doing dev work. * blog(cline): swap placeholder cover for Hindsight x Cline card
1 parent d7ff44b commit d5df9ad

2 files changed

Lines changed: 231 additions & 0 deletions

File tree

‎hindsight-docs/blog/2026-06-09-cline-persistent-memory.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
title: "Cline Persistent Memory: Lifecycle Hooks Instead of MCP"
3+
authors: [benfrank241]
4+
slug: "2026/06/09/cline-persistent-memory"
5+
date: 2026-06-09T12:00
6+
tags: [cline, memory, persistent-memory, hindsight, coding-agents, tutorial]
7+
description: "Add persistent memory to Cline with Hindsight using lifecycle hooks. No MCP server, no model tool-calling required. Hooks deterministically recall context before each task and retain what happened after."
8+
image: /img/blog/cline-persistent-memory.png
9+
hide_table_of_contents: true
10+
---
11+
12+
![Cline Persistent Memory with Hindsight](/img/blog/cline-persistent-memory.png)
13+
14+
[Cline](https://github.com/cline/cline) is one of the most-used AI coding agents in VS Code. It reads files, runs commands, writes code, and iterates on a task until it's done. What it doesn't do is remember anything once a task ends. The next task opens cold, with no recollection of decisions you made, conventions you've established, or fragile areas of the codebase you've found the hard way.
15+
16+
This post is a walkthrough of the new Hindsight + Cline integration. It uses **Cline's lifecycle hooks** to add automatic recall before each task and automatic retain when a task ends, with no MCP server in the loop, and the model doesn't have to decide to call a memory tool. Memory just happens.
17+
18+
## TL;DR
19+
20+
<!-- truncate -->
21+
22+
- Cline has no persistent memory built in. Tasks restart from zero each time.
23+
- The Hindsight integration installs four lifecycle hook scripts (`TaskStart`, `UserPromptSubmit`, `TaskComplete`, `TaskCancel`) plus a small Python lib. One installer command, no `pip install` for runtime use.
24+
- **Recall is deterministic.** Because it runs on hooks, memory is injected automatically. There's no MCP tool the model can forget to use.
25+
- Recalled memories appear inside Cline as a `<hindsight_memories>` block, scoped to the current task description and your in-progress prompt.
26+
- Hindsight Cloud means no local daemon. Memory is stored server-side and follows you across machines. [Sign up free.](https://ui.hindsight.vectorize.io/signup)
27+
- **Platform note:** Cline hooks run on **macOS and Linux** only, with no Windows support.
28+
29+
## The Problem: Cline Has No Memory Between Tasks
30+
31+
Cline is fast and capable inside a single task. It can read your whole project, edit dozens of files, run tests, and converge on a solution. But when the task ends, everything it learned is gone. The next task starts with the model's training data plus whatever files Cline reads, with nothing you taught it before.
32+
33+
For one-off tasks that's fine. For an agent you use every day on the same codebase, it's a problem. You re-explain the same conventions, re-warn it about the same pitfalls, and re-state the same architectural decisions every time. The agent never gets to know your codebase the way a teammate would.
34+
35+
Hindsight closes that gap by giving Cline a persistent memory bank, and the lifecycle-hook integration wires it in without any in-task tool calls.
36+
37+
## How Hindsight Adds Memory to Cline
38+
39+
Cline supports [lifecycle hooks](https://docs.cline.bot/customization/hooks): small executable scripts it runs at key moments. The Hindsight integration installs four of them and routes each event to a Hindsight API call:
40+
41+
| Cline hook | What Hindsight does |
42+
| --- | --- |
43+
| `TaskStart` | Recall context for the new task description; inject it. |
44+
| `UserPromptSubmit` | Recall memories for your message; record the prompt for retain later. |
45+
| `TaskComplete` | Retain the task's accumulated transcript and final summary. |
46+
| `TaskCancel` | Retain the partial transcript of a cancelled task. |
47+
48+
Because it runs on hooks, memory is **deterministic**. There's no MCP tool the model can forget to call and no extra latency from a tool-use round-trip. The recall and retain logic runs at well-defined points in Cline's task lifecycle.
49+
50+
```
51+
Task starts ─ TaskStart ─────────► recall(task description) → inject memories
52+
You send a message ─ UserPromptSubmit ─► recall(prompt) → inject memories
53+
(and append the prompt to the task transcript)
54+
Task completes ─ TaskComplete ──► retain(accumulated transcript + summary)
55+
Task cancelled ─ TaskCancel ────► retain(partial transcript)
56+
```
57+
58+
One Cline-specific detail worth knowing: **Cline doesn't hand hooks a transcript.** Each hook gets the task ID and the current event payload, not the running conversation. The integration accumulates each task's prompts in `~/.hindsight/cline/state/` as it goes, and the end-of-task hook reads that back to retain the full transcript at once. The model never sees this bookkeeping; it just sees memories show up in context when relevant.
59+
60+
## Installing
61+
62+
The installer is a small Python script that copies the four hook files (plus their shared lib and a `settings.json`) into Cline's hooks directory.
63+
64+
From your project directory:
65+
66+
```bash
67+
python /path/to/hindsight-integrations/cline/install.py \
68+
--api-url https://api.hindsight.vectorize.io \
69+
--api-token YOUR_KEY
70+
```
71+
72+
That installs to `.clinerules/hooks/`; commit it to share with your team. To install globally (apply to every project), add `--global`:
73+
74+
```bash
75+
python install.py --global \
76+
--api-url https://api.hindsight.vectorize.io \
77+
--api-token YOUR_KEY
78+
```
79+
80+
This drops hooks into `~/Documents/Cline/Rules/Hooks/` instead.
81+
82+
**Final step, enable hooks in Cline:** Settings → Features → Hooks (toggle on).
83+
84+
Cline hooks run on **macOS and Linux only**. They use Python 3 (any modern system Python works, with no `pip install` needed at runtime).
85+
86+
## Hindsight Cloud (Recommended)
87+
88+
The fastest path is Hindsight Cloud: no daemon to keep alive, memory syncs across machines, and the extraction work happens server-side. That matters more for Cline than for a server-side agent. Cline lives in VS Code, which most developers use across a laptop, a desktop, and sometimes a remote dev box; Cloud means the same memory bank shows up everywhere without copying files around. Because extraction runs server-side, you also don't have to thread an LLM API key into the hook environment (the retain hook would otherwise need one to call the extraction model), and there's no `hindsight-api` process you have to remember to start before opening VS Code. The installer's `--api-url` and `--api-token` flags configure it in one step. Your connection settings land in `~/.hindsight/cline.json`, which is stable across reinstalls:
89+
90+
```json
91+
{
92+
"hindsightApiUrl": "https://api.hindsight.vectorize.io",
93+
"hindsightApiToken": "hsk_your_token"
94+
}
95+
```
96+
97+
Create an account and grab an API key at [hindsight.vectorize.io](https://ui.hindsight.vectorize.io/signup).
98+
99+
Self-hosting works exactly the same way: start the API locally and point the installer at it:
100+
101+
```bash
102+
pip install hindsight-all
103+
export HINDSIGHT_API_LLM_API_KEY=your-openai-key
104+
hindsight-api # http://localhost:8888
105+
```
106+
107+
Then re-run the installer with `--api-url http://localhost:8888`.
108+
109+
## What Gets Recalled
110+
111+
`TaskStart` and `UserPromptSubmit` both run a Hindsight recall and return a `<hindsight_memories>` block as context that Cline injects before the model sees your prompt:
112+
113+
```
114+
<hindsight_memories>
115+
Relevant memories from past conversations. Only use memories that are directly useful to continue this task; ignore the rest:
116+
Current time - 2026-06-09 13:42
117+
118+
- Project uses asyncpg, not SQLAlchemy; switched after Redis cache stampede in March [world]
119+
- Tests live under tests/integration/ and run via `make test-int`, not pytest directly [world]
120+
- The `auth_v2` module is being deprecated; new code should target `identity/` [experience]
121+
</hindsight_memories>
122+
```
123+
124+
Cline sees this block; it doesn't appear in your editor output. The result: Cline starts every task with relevant past context already in scope, without you having to provide it.
125+
126+
You can tune how much context to pull with `recallBudget` (`"low"` / `"mid"` / `"high"`) and `recallMaxTokens`.
127+
128+
### Before and after
129+
130+
Without persistent memory, a new task in Cline starts cold. You type "fix the broken auth tests" and Cline reads the test file, makes reasonable guesses about which auth module is in scope, and may try patterns you already rejected.
131+
132+
With Hindsight, the same task opens with recalled context: that `auth_v2` is deprecated, that the test runner is `make test-int`, that the recent fix-stack landed in `identity/`. Cline picks the right module and the right test command on the first turn instead of the third.
133+
134+
## Per-Project Memory
135+
136+
By default all Cline tasks share a single bank (`cline`). To give each project its own isolated bank, switch to dynamic bank IDs in `~/.hindsight/cline.json`:
137+
138+
```json
139+
{
140+
"dynamicBankId": true,
141+
"dynamicBankGranularity": ["agent", "project"]
142+
}
143+
```
144+
145+
Bank IDs are derived from the workspace path (`agent::project`), so a task in `~/projects/api` writes to a different bank than one in `~/projects/frontend`. Switching folders automatically switches memory context.
146+
147+
Valid granularity fields are `agent`, `project`, `session`, and `user`. Adding `user` (sourced from the `HINDSIGHT_USER_ID` env var) is useful if multiple people share a machine but should not share recall.
148+
149+
## Team Shared Memory
150+
151+
Individual persistent memory is useful. Shared memory across a team is transformative.
152+
153+
When everyone on a team points their Cline config at the same Hindsight bank, context accumulated by one developer becomes available to all. A bug discovered on Monday surfaces in recall on Tuesday, regardless of who's asking. Architecture decisions made in one task inform the next, without requiring anyone to update a shared doc.
154+
155+
To configure team shared memory, set a fixed `bankId` in each developer's config and point them at the same Hindsight Cloud endpoint:
156+
157+
```json
158+
{
159+
"hindsightApiUrl": "https://api.hindsight.vectorize.io",
160+
"hindsightApiToken": "hsk_your_token",
161+
"bankId": "my-team-project"
162+
}
163+
```
164+
165+
See [Shared Memory for AI Coding Agents](https://hindsight.vectorize.io/blog/2026/03/31/team-shared-memory-ai-coding-agents) for a full team setup guide.
166+
167+
## Key Configuration Options
168+
169+
Settings live in `~/.hindsight/cline.json` (personal overrides) or the installed `settings.json` (defaults). Every setting can also be set via `HINDSIGHT_*` environment variables.
170+
171+
| Setting | Default | What it does |
172+
|---------|---------|--------------|
173+
| `bankId` | `cline` | Memory bank for this integration. |
174+
| `autoRecall` | `true` | Inject memories before tasks/prompts. |
175+
| `autoRetain` | `true` | Retain the task transcript when it ends. |
176+
| `recallBudget` | `mid` | Recall depth: `low` (fast) / `mid` / `high` (thorough). |
177+
| `recallTypes` | `["world","experience"]` | Memory categories to recall. |
178+
| `retainMission` | generic | Steers fact extraction; tell it what to focus on. |
179+
| `dynamicBankId` | `false` | Per-project bank isolation. |
180+
| `debug` | `false` | Log activity to stderr. |
181+
182+
A focused `retainMission` makes the extracted memories meaningfully better:
183+
184+
```json
185+
{
186+
"retainMission": "Extract technical decisions, code patterns, debugging solutions, user preferences, project context, and architectural choices. Ignore routine greetings and transient operational details."
187+
}
188+
```
189+
190+
## Pitfalls
191+
192+
**Hooks not firing.** The installer copies the files in, but the toggle is still off by default. Go to Settings → Features → Hooks in Cline and turn it on. A quick way to verify hooks run: enable `debug: true` and watch stderr for `[Hindsight]` lines.
193+
194+
**No memories recalled in the first task.** Recall only returns results after something has been retained. Complete one real task first; the second one starts seeing recalled context.
195+
196+
**Nothing happening on Windows.** Cline's hook runner is macOS/Linux only; there is currently no Windows path. (If you're on Windows and want persistent memory for a coding agent, the [Hermes + Hindsight](https://hindsight.vectorize.io/blog/2026/06/01/hermes-hindsight-windows-setup) setup is a good alternative.)
197+
198+
**Smoke-testing a hook without Cline.** You can pipe a synthetic event into a hook script directly to make sure it works end-to-end:
199+
200+
```bash
201+
echo '{"hookName":"UserPromptSubmit","prompt":"how do we authenticate?","taskId":"t1","workspaceRoots":["/tmp/x"]}' \
202+
| .clinerules/hooks/UserPromptSubmit
203+
# → {"cancel": false, "contextModification": "<hindsight_memories>…", "errorMessage": ""}
204+
```
205+
206+
## Tradeoffs
207+
208+
**Recall adds latency.** Every prompt triggers a Hindsight query before Cline sees it. With Hindsight Cloud and a fast connection that's typically under 300ms, imperceptible in interactive use. Drop `recallBudget` to `"low"`, or set `autoRecall: false`, if you need to skip it.
209+
210+
**Retain runs at task end, not mid-task.** Memories from the task you're in become available *after* it completes. If you cancel a task you'd otherwise want to recall from, the `TaskCancel` hook still retains the partial transcript, but you have to actually cancel to trigger it.
211+
212+
**Extraction quality depends on conversation quality.** Hindsight extracts facts from what's in the transcript. If a task is all file edits and no narration, there's little for the extractor to work with. A few sentences explaining what you decided and why go a long way.
213+
214+
## Recap
215+
216+
| | Cline default | With Hindsight |
217+
|---|---|---|
218+
| Memory across tasks | None | Automatic |
219+
| Memory setup | Manual `.clinerules` / docs | Extracted from task transcripts |
220+
| Recall mechanism | Files Cline reads each task | Semantic search, injected per task/prompt |
221+
| Per-project isolation | No | Optional via `dynamicBankId` |
222+
| Team shared memory | No | Shared bank via Hindsight Cloud |
223+
| Model tool-calling needed | n/a | No (lifecycle hooks) |
224+
225+
## Next Steps
226+
227+
- **Hindsight Cloud:** [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io/signup)
228+
- **Integration docs:** [Cline + Hindsight](/sdks/integrations/cline)
229+
- **Source:** [vectorize-io/hindsight/hindsight-integrations/cline](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/cline)
230+
- **Team memory:** [Shared Memory for AI Coding Agents](https://hindsight.vectorize.io/blog/2026/03/31/team-shared-memory-ai-coding-agents)
231+
- **Windows alternative:** [Hermes Agent with Hindsight](https://hindsight.vectorize.io/blog/2026/06/01/hermes-hindsight-windows-setup)

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

312 KB
Loading

0 commit comments

Comments
 (0)