Retain

Say what you want to remember. Get a structured markdown note in your workspace, and a review schedule that brings it back before you forget it.

Three kinds of note, chosen automatically from how you phrase things:

Notes are plain markdown with YAML frontmatter. Nothing is locked in a database — you can grep them, commit them, or open them in any other editor.

Install the extension

From the VS Code Marketplace: search Retain, or install the packaged .vsix:

code --install-extension retain-0.2.0.vsix

Requires VS Code 1.101+. Then open the Retain icon in the activity bar.

API keys

Run Retain: Set API key from the command palette. Keys are stored in your OS keychain via VS Code's SecretStorage, never in settings files or notes.

You need two things, and they can come from different providers:

• Transcription — Groq (default, whisper-large-v3-turbo) or OpenAI (whisper-1).
• Structuring — Anthropic (default, claude-sonnet-5) or OpenAI (gpt-4o-mini).

You don't need any key to start: set retain.structuring.provider to none and notes are filed instantly with local heuristics. If you record often, a smaller structuring model is plenty — the job is short.

Capture from your AI coding agent (MCP)

While you are deep in a project and notice something worth learning later, just tell your coding agent — "add this to my learning log" — and it files a structured note for you, without leaving the conversation. It runs through a small Model Context Protocol server. The agent is already an LLM, so it fills in the fields itself: no transcription or structuring API, no API keys, zero dependencies.

The server is published as @vedprakash20/retain-mcp, so every tool wires up with the same one line and no install, clone, or path — npx fetches it on first run. Requires Node 18+.

Notes land in ~/learning by default — the same folder this extension reads out of the box — so anything the agent captures shows up in your Library and review automatically. Override the location with the RETAIN_DIR environment variable.

VS Code (this extension) — nothing to configure

Because the extension already ships the server, VS Code (1.101+) registers it for you. Open Copilot Chat's tools/MCP list and Retain is already there, pointed at the same notes folder the extension uses. There is no path to copy and nothing that breaks on an extension update.

Every other tool — one block

Drop this into the tool's MCP config. It's identical everywhere except the wrapper.

Claude Code — one command, at user scope so it's available in every project:

claude mcp add retain --scope user -- npx -y @vedprakash20/retain-mcp

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "retain": { "command": "npx", "args": ["-y", "@vedprakash20/retain-mcp"] }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json; Cline — its MCP Servers → Configure file. Both use the exact block above.

VS Code without this extension (or another MCP client) — .vscode/mcp.json. Note the top-level key is servers, and each entry needs "type": "stdio":

{
  "servers": {
    "retain": { "type": "stdio", "command": "npx", "args": ["-y", "@vedprakash20/retain-mcp"] }
  }
}

Zed — settings.json:

{
  "context_servers": {
    "retain": { "command": "npx", "args": ["-y", "@vedprakash20/retain-mcp"] }
  }
}

To send notes somewhere other than ~/learning, add an env block — e.g. for the mcpServers shape: "env": { "RETAIN_DIR": "~/notes/learning" }. If you change it here, set retain.notesFolder to the same path so the extension reads the same store.

Prefer the local build over npx? Run Retain: Copy MCP setup command from the palette. It copies a ready-to-paste config that points node at this installed build's server and carries your current notes folder — no digging through ~/.vscode/extensions for a version-stamped path.

Tools it exposes

Using it

The Retain icon in the activity bar has two panels: Capture at the top, Library below it.

• Capture by voice — hit Start recording, talk, hit Stop. The bars move while the microphone is picking you up, which is the only reliable signal that it is actually working.
• Capture by typing or dictation — if you have text selected in an editor, that selection becomes the note. Otherwise you get an input box. Your operating system's dictation key works here (fn fn on macOS, Win+H on Windows), which is worth knowing about — see the note on microphones below.
• Start review session — walks you through everything due today, one at a time. Each note opens, you rate how well it came back, and the next date is set from there.

The raw transcript is kept at the bottom of every voice note inside a collapsed <details> block. The model cleans up your speech, so this is your record of what you actually said if it ever paraphrases something into the wrong meaning. Typed and agent-captured notes skip it — the body already is what you wrote.

A note on microphones

VS Code's extension host is Node — it has no microphone. Recording therefore happens inside a webview, which is Chromium and does have getUserMedia. This works on VS Code Desktop, but it depends on Electron passing the permission through, and it is the part most likely to break on your machine:

• On macOS, VS Code needs microphone permission in System Settings → Privacy & Security → Microphone. If you grant it while VS Code is running, reload the window.
• On Linux, PipeWire or PulseAudio needs to be reachable from the VS Code process.
• In a remote or web workspace, the audio is captured on your local machine but the API call happens wherever the extension host is running.

If the panel tells you the microphone is unavailable and you would rather not fight it, use Capture by typing or dictation with your OS dictation key. You still speak, the transcription just happens locally, and the rest of the pipeline is identical.

Where notes go

Set by retain.notesFolder, default ~/learning — one central folder, so you capture from whichever project happens to be open and the MCP server writes to the same place. Use an absolute or ~-rooted path for a fixed folder, a plain name (e.g. learning) for a folder relative to the workspace root, or leave it empty to use the extension's global storage.

~/learning/
├── topics/        mastery targets, one file each, in the review rotation
├── til/           YYYY-MM-DD-slug.md
├── discoveries/
└── audio/         only if retain.keepAudio is on

Review scheduling

SM-2, with one deviation: a topic is only marked mastered after four successful reviews and an interval past 60 days, so a good week does not retire something from the rotation prematurely. Intervals for consistently strong recall run 1 → 6 → 16 → 45 → 126 days.

All scheduling state lives in the frontmatter (ease, interval, reps, nextReview). Edit it by hand if you disagree with the algorithm.

Settings

Developing

npm install
npm run compile

Press F5 to launch an Extension Development Host with the extension loaded. Package a .vsix with npx @vscode/vsce package.

The MCP server lives in src/mcp/server.ts and is published from the mcp-server/ subpackage (npm run build:mcp compiles it). It reads and writes the exact note format the extension does, so a topic the agent captures enters the spaced-repetition rotation and is due the same day.

Dependencies

None at runtime. The frontmatter parser in src/frontmatter.ts covers the flat scalars and string lists this extension writes, which avoids a bundler and keeps the install small. If you start hand-writing nested YAML in your notes, swap it for gray-matter.