|
| 1 | +--- |
| 2 | +title: "Give Zed's AI Assistant a Persistent Memory" |
| 3 | +authors: [benfrank241] |
| 4 | +slug: "2026/07/07/zed-persistent-memory" |
| 5 | +date: 2026-07-07T12:00 |
| 6 | +tags: [hindsight, zed, integration, memory, persistent-memory, mcp, tutorial] |
| 7 | +description: "The Zed editor's AI assistant is sharp inside a task and a stranger between them. hindsight-zed gives it long-term memory that recalls and retains across sessions." |
| 8 | +image: /img/blog/zed-persistent-memory.png |
| 9 | +hide_table_of_contents: true |
| 10 | +--- |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +[Zed](https://zed.dev) is a fast, Rust-built editor with a genuinely good AI assistant in its Agent Panel. But like most coding agents, it is brilliant inside a single task and a stranger between them. Close the panel, start a new conversation tomorrow, and it has forgotten that this repo uses pnpm, that you settled on a repository pattern last week, and that you like your tests colocated. |
| 15 | + |
| 16 | +`hindsight-zed` fixes that. One command wires Zed's Agent Panel to a shared [Hindsight](https://github.com/vectorize-io/hindsight) memory so the agent can recall relevant decisions before it answers and retain durable facts as it works, across every session. |
| 17 | + |
| 18 | +<!-- truncate --> |
| 19 | + |
| 20 | +## TL;DR |
| 21 | + |
| 22 | +- `hindsight-zed init` registers the Hindsight **MCP server** in Zed and adds a rule telling the agent to use it. |
| 23 | +- The agent gets three tools: `recall`, `retain`, and `reflect`. |
| 24 | +- Recall runs at **query time** against your actual message, so it pulls context relevant to what you just asked, with no lag. |
| 25 | +- Works with [Hindsight Cloud](https://hindsight.vectorize.io) or a self-hosted server. It is [agent memory](https://vectorize.io/what-is-agent-memory) that outlives the conversation. |
| 26 | + |
| 27 | +## The problem: a great assistant with no yesterday |
| 28 | + |
| 29 | +A coding assistant that forgets everything between sessions makes you the memory. You re-explain the stack, restate the conventions, and re-litigate decisions you already made, every time you open a fresh conversation. The model is capable; it just has no continuity. |
| 30 | + |
| 31 | +Persistent memory closes that gap. The point of memory is that the things you have already told your agent, and the things it has already figured out, are still there next time. That is what turns a per-session tool into an assistant that actually knows your project. |
| 32 | + |
| 33 | +## How Zed's memory works |
| 34 | + |
| 35 | +Zed does not expose a pre-prompt hook, so there is nowhere to automatically inject context before a turn. What Zed does give you is two building blocks, and the integration uses both. |
| 36 | + |
| 37 | +**MCP context servers.** Zed runs [Model Context Protocol](https://modelcontextprotocol.io) servers listed under `context_servers` in its `settings.json` and exposes their tools in the Agent Panel. `hindsight-zed` registers the Hindsight MCP server there, which hands the agent `recall`, `retain`, and `reflect` tools. |
| 38 | + |
| 39 | +**A global instructions file.** Zed includes `~/.config/zed/AGENTS.md` in every agent conversation. The integration writes a short rule into that file, inside a fenced `<!-- HINDSIGHT:BEGIN -->` to `<!-- HINDSIGHT:END -->` block so it never touches your own rules. The rule tells the agent to call `recall` at the start of each task to load relevant decisions, preferences, and project context, and to call `retain` whenever it learns a durable fact worth keeping across sessions. |
| 40 | + |
| 41 | +The result is recall that happens at query time, against the message you actually sent. Because it runs when you ask rather than on a fixed schedule, it can pull the memories relevant to this specific request. From your seat it is automatic: you type, the agent quietly checks its memory, then answers. |
| 42 | + |
| 43 | +One transport note. Zed does not yet ship native HTTP MCP transport, so the server connects through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) stdio bridge, run via `npx`. Because that bridge runs on Node.js, and the setup CLI is a Node tool too, Node.js is the only requirement. No Python needed. |
| 44 | + |
| 45 | +## Install and quick start |
| 46 | + |
| 47 | +```bash |
| 48 | +npx hindsight-zed init --api-token YOUR_HINDSIGHT_API_KEY --bank-id my-memory |
| 49 | +``` |
| 50 | + |
| 51 | +`hindsight-zed` is a zero-dependency Node CLI, so `npx` runs it with no global install. Prefer a persistent command? Run `npm install -g hindsight-zed` first. |
| 52 | + |
| 53 | +`init` adds the `hindsight` MCP server to `~/.config/zed/settings.json` and the recall/retain rule to `~/.config/zed/AGENTS.md`. Restart Zed, open the Agent Panel, and the `hindsight` server should show a green dot. |
| 54 | + |
| 55 | +That is the whole setup. Under the hood, the settings entry looks like this: |
| 56 | + |
| 57 | +```jsonc |
| 58 | +{ |
| 59 | + "context_servers": { |
| 60 | + "hindsight": { |
| 61 | + "source": "custom", |
| 62 | + "command": "npx", |
| 63 | + "args": [ |
| 64 | + "-y", "mcp-remote", |
| 65 | + "https://api.hindsight.vectorize.io/mcp/my-memory/", |
| 66 | + "--header", "Authorization: Bearer YOUR_HINDSIGHT_API_KEY" |
| 67 | + ] |
| 68 | + } |
| 69 | + } |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +If your `settings.json` uses comments (JSONC), `init` will not rewrite it. Instead it prints the exact `context_servers` entry for you to paste. You can see that snippet any time with `hindsight-zed init --print-only`. |
| 74 | + |
| 75 | +## Commands |
| 76 | + |
| 77 | +| Command | What it does | |
| 78 | +| --- | --- | |
| 79 | +| `hindsight-zed init` | Add the MCP server and the recall/retain rule | |
| 80 | +| `hindsight-zed status` | Show whether the server and rule are configured | |
| 81 | +| `hindsight-zed uninstall` | Remove the server and the rule | |
| 82 | +| `hindsight-zed init --print-only` | Print the config to add manually | |
| 83 | + |
| 84 | +Prefix any of these with `npx ` if you did not install globally. |
| 85 | + |
| 86 | +## Cloud or self-hosted |
| 87 | + |
| 88 | +For **Hindsight Cloud**, pass an API key from your dashboard. The API URL defaults to `https://api.hindsight.vectorize.io`, so there is nothing else to set. |
| 89 | + |
| 90 | +For a **self-hosted** server, point at your own base URL with `--api-url http://localhost:8888`. An open local server needs no token. |
| 91 | + |
| 92 | +Configuration resolves from flags, environment, or `~/.hindsight/zed.json` (written by `init`): |
| 93 | + |
| 94 | +| Setting | Env var | Default | |
| 95 | +| --- | --- | --- | |
| 96 | +| API URL | `HINDSIGHT_API_URL` | `https://api.hindsight.vectorize.io` | |
| 97 | +| API token | `HINDSIGHT_API_TOKEN` | none (required for Cloud) | |
| 98 | +| Bank id | `HINDSIGHT_ZED_BANK_ID` | `zed` | |
| 99 | + |
| 100 | +The bank is one isolated store. Point Zed and your other tools at the same bank id and they share one memory, which is the idea behind [one memory for every AI tool](/blog/2026/04/07/one-memory-for-every-ai-tool). |
| 101 | + |
| 102 | +## Verify it works |
| 103 | + |
| 104 | +Give the agent a durable fact in one conversation: "This repo uses pnpm, never npm." Start a **new** conversation and ask for something related, like "add the date-fns dependency." A memory-aware agent recalls the convention and reaches for pnpm without being reminded, because the fact was retained to Hindsight and recalled against your new request. |
| 105 | + |
| 106 | +You can watch this happen from the other side too. Open your Hindsight bank and you will see the retained convention show up as a stored memory after the first conversation. |
| 107 | + |
| 108 | +## Frequently asked questions |
| 109 | + |
| 110 | +**Does the agent recall automatically?** |
| 111 | +Recall is a tool the agent calls, and the global rule tells it to call `recall` at the start of every task. So in practice it runs on its own, and because it runs at query time it uses your actual message to find relevant memory. |
| 112 | + |
| 113 | +**What do I need installed?** |
| 114 | +Just Node.js (version 18.3 or newer). `hindsight-zed` is a zero-dependency Node CLI, and Zed's MCP bridge (`mcp-remote`) also runs on Node via `npx`. No Python required. |
| 115 | + |
| 116 | +**Will it overwrite my Zed config?** |
| 117 | +No. The rule lives inside a fenced `HINDSIGHT` block in `AGENTS.md`, and `init` leaves the rest untouched. If your `settings.json` has comments, `init` prints the snippet instead of rewriting the file. |
| 118 | + |
| 119 | +**What does `reflect` do?** |
| 120 | +Alongside `recall` and `retain`, the agent can call `reflect` to consolidate and reason over what it has stored, so memory improves as it accumulates rather than becoming a flat pile of notes. |
| 121 | + |
| 122 | +## Further reading |
| 123 | + |
| 124 | +- [What is agent memory?](https://vectorize.io/what-is-agent-memory): the concepts behind recall and retention. |
| 125 | +- [Best AI agent memory systems](https://vectorize.io/articles/best-ai-agent-memory-systems): how the major memory frameworks compare. |
| 126 | +- [Cursor persistent memory](/blog/2026/06/12/cursor-persistent-memory): the same idea for the other AI-first editor. |
| 127 | +- [One memory for every AI tool](/blog/2026/04/07/one-memory-for-every-ai-tool): point Zed and your other agents at the same bank. |
0 commit comments