# recall

**Give your AI assistant a memory it keeps between conversations.**

Normally, when you close a chat with an AI assistant, it forgets everything. Next time, you start from scratch. `recall` fixes that. It's a small add-on that gives your assistant a notebook it can write to and read back later, so the things you tell it once, it remembers for good.

It's built to be simple enough for people who are brand new to this. Using it day to day takes no coding at all. The one-time setup is a few copy-paste commands, walked through below.

---

## What it's good for

- **Stop repeating yourself.** Tell your assistant your preferences, your projects, or facts about your work once. It remembers them next time.
- **Keep notes your assistant can actually use.** Decisions, reminders, how-you-like-things-done. Your assistant can look them up on its own when they're relevant.
- **Your memory, your files.** Memories are saved as plain text files on your own computer that you can open and read anytime. They stay local by default (see the short privacy note below for the full picture).

Here's the kind of thing it makes possible:

> **You:** Remember that I prefer short, plain-language answers and that my business is called Birchwood Bakery.
>
> **Assistant:** Saved. *(writes a memory)*
>
> *...a week later, in a brand-new conversation...*
>
> **You:** Draft a welcome note for a new client.
>
> **Assistant:** *(quietly looks up what it knows about you, then writes a short, plain-language note signed Birchwood Bakery)*

---

## What you need first

Two free tools, installed once:

1. **Node.js** (this is what runs `recall`). Go to **https://nodejs.org**, download the version marked **"LTS"**, open it, and click through the installer.
2. **Git** (this is used to download `recall` in the next step). Most Macs already have it. To check, type `git --version` in Terminal; if it prints a version number, you're set. If not, it will offer to install it, or you can get it from **https://git-scm.com**.

> Prefer not to touch Git at all? Once `recall` is on GitHub, you can click the green **Code** button on its page, choose **Download ZIP**, unzip it into your home folder, and skip the `git clone` line in the next step.

You only ever do this once.

---

## Install it (the simple way)

Copy and paste these lines one at a time into your **Terminal** (on Mac: press `Cmd+Space`, type "Terminal", press Enter):

```bash
# 1. Download recall into a folder in your home directory
git clone https://github.com/andrewhomeyer/recall-mcp.git ~/recall-mcp

# 2. Go into that folder
cd ~/recall-mcp

# 3. Set it up and build it (one command)
npm install && npm run build
```

When the last command finishes, `recall` is ready. You won't need to do this again.

---

## Connect it to your AI assistant

`recall` works with any app that supports **MCP** (Model Context Protocol, the open standard for plugging tools into AI assistants). The setup is the same everywhere: you point the app at `node ~/recall-mcp/dist/index.js`. By default every app you connect shares the *same* memory, so what you tell one, the others know too.

### Claude Desktop

1. Open **Claude Desktop**.
2. In the menu bar, open **Settings → Developer → Edit Config**. This opens a file called `claude_desktop_config.json`.
3. Paste the `recall` block below inside it (if there's already text there, ask your assistant to help you merge it in):

```json
{
  "mcpServers": {
    "recall": {
      "command": "node",
      "args": ["REPLACE_WITH_YOUR_HOME/recall-mcp/dist/index.js"]
    }
  }
}
```

4. Replace `REPLACE_WITH_YOUR_HOME` with your home folder path. To find it, type `echo $HOME` in Terminal and paste what it prints. (For example: `/Users/yourname`.)
5. **Fully quit and reopen Claude Desktop.**

### Claude Code

One line in Terminal:

```bash
claude mcp add recall -- node ~/recall-mcp/dist/index.js
```

### Cursor

Open (or create) the file `~/.cursor/mcp.json` and paste the same `recall` block shown for Claude Desktop above. Restart Cursor.

### Cline, Windsurf, Zed, and any other MCP app

They all use the identical pattern. Wherever the app lists its "MCP servers," add one named `recall` with:

- **command:** `node`
- **argument:** the full path to your `recall-mcp/dist/index.js`

If an app supports MCP, `recall` works with it. You built it once; every app shares it.

You'll know it worked when you can ask your assistant to remember something, start a brand-new conversation, and it still knows.

---

## How to use it

You don't push buttons or learn commands. You just talk to your assistant normally:

- **To save something:** *"Remember that..."* or *"Make a note that..."*
- **To recall something:** *"What do you know about...?"* or *"Look up my notes on..."*
- **To review:** *"List everything you've remembered."*
- **To forget something:** *"Delete the note about..."*

Your assistant decides when to use its memory on its own, the same way a good assistant would glance at their notebook before answering.

## Your memory grows with you

The more you use `recall`, the more useful it gets. Whenever something is worth keeping, just tell your assistant to remember it. A simple habit that works well: once a week, take a minute to tell it the handful of new things worth holding onto. New preferences, a decision you made, a fact about a project. Over a few months it builds into a genuine picture of you and your work, and you stop having to re-explain the basics.

You can also tend it by hand. Because every memory is a plain text file, you can open the folder, fix a detail, delete something that is no longer true, or add a note yourself. There is no database and no account. It is just text. (If a hand-edited file gets garbled, `recall` simply skips that one file and keeps working.)

## Take it from one assistant to another

Your memory is a folder of files, so it travels the way any folder does. This is one of the biggest differences from built-in memory:

- **Use it in two apps at once.** By default, every app you connect points at the same folder, so a memory you save in Claude Desktop is instantly available in Cursor, Claude Code, or anything else you have set up.
- **Move to a new computer.** Copy the folder across, install `recall` on the new machine, and everything is there.
- **Switch tools entirely.** If you stop using one assistant and start using another, your memory stays with you. It was never locked inside the old one.

## Where your memories live (and how to back them up)

By default, your memories live in a hidden folder called `.recall` in your home directory. Each memory is a plain text file with a short label, a one-line summary, a category, and the note itself. You can open them in any text editor. Nothing is hidden or locked away, and you can keep them there without ever thinking about it.

If you want them **backed up automatically** or **synced across your devices**, put the folder inside a service you already use, like Dropbox, iCloud Drive, or Google Drive, and tell `recall` where it is. For example, to keep your memory in Dropbox, add one line to your setup:

```json
{
  "mcpServers": {
    "recall": {
      "command": "node",
      "args": ["REPLACE_WITH_YOUR_HOME/recall-mcp/dist/index.js"],
      "env": {
        "RECALL_MEMORY_DIR": "REPLACE_WITH_YOUR_HOME/Dropbox/recall-memory"
      }
    }
  }
}
```

Now your memory is backed up by Dropbox and follows you to every device signed into it. (Developers: point `RECALL_MEMORY_DIR` at a git repository instead, and you get a full version history of every change your assistant makes.)

### A quick note on privacy

`recall` stores your memories on your own computer by default. Two honest things to keep in mind:

- **Recalling a memory shares it with your assistant.** When your assistant looks up a memory, that text becomes part of your conversation, so it is sent to your assistant's provider just like anything else you say to it.
- **Syncing puts the files with your sync service.** If you choose to sync the folder (Dropbox, iCloud, Google Drive), those files are stored by that service.

So treat memories like notes, not a vault. **Don't store passwords, API keys, or other secrets in them.**

---

## "Doesn't my AI already have memory?"

Some AI apps do include a built-in memory. `recall` is different in three ways that tend to matter once you rely on it:

- **You own it.** Your memories are plain files on your own computer. You can read, back up, copy, move, or delete them yourself, anytime.
- **It's portable.** The same memory works across every app you connect it to. Built-in memory is usually locked to the one product it came with. Switch apps and it doesn't come with you.
- **It's durable.** Because it's just files you control, it survives app updates, account resets, and changing tools. Nothing can quietly forget or wipe it behind the scenes.

The honest trade-off: if you only ever use one AI app and never care to see or move your memories, that app's built-in memory may be all you need. `recall` is for when you want your memory to be *yours*, and to outlast any single app.

---

## Under the hood (for developers)

`recall` is an [MCP](https://modelcontextprotocol.io) server written in TypeScript on the official SDK. It runs locally over stdio as a subprocess of the client.

### Design

A **memory** is one atomic fact stored as a single Markdown file with YAML frontmatter:

```markdown
---
name: client-tone
description: How the owner likes client-facing copy written
type: feedback
---

Short, plain-language, no jargon. Signed "Birchwood Bakery". See [[brand-voice]].
```

- **Typed.** Every memory is one of `user`, `feedback`, `project`, or `reference`.
- **Recalled by relevance.** A query is scored against each memory; a hit in the `name` outweighs the `description`, which outweighs the `body` (weights 10 / 3 / 1, credited once per field). Non-matches score 0 and are dropped.
- **Linked.** `[[wikilink]]` references in a body build a lightweight graph between memories.
- **Indexed.** A human-readable `MEMORY.md` index is rebuilt on every write and delete.
- **Resilient.** A single malformed memory file is skipped (with a stderr warning) rather than breaking listing, search, or the index.

### Tools

| Tool | Purpose | Read-only |
|---|---|---|
| `recall_write` | Create a memory; refuses to overwrite unless `overwrite: true` | no |
| `recall_get` | Fetch one memory by name, with its full body | yes |
| `recall_search` | Recall memories relevant to a query, ranked | yes |
| `recall_list` | List memories (index view), paginated | yes |
| `recall_links` | Find inbound/outbound `[[links]]` for a memory | yes |
| `recall_delete` | Permanently delete a memory | no |

Read tools accept `response_format: "markdown" | "json"`.

### Security

Memory names are constrained to a kebab-case slug at the schema boundary, and the file store independently re-validates and verifies every resolved path stays inside the memory directory. Path traversal is rejected at two layers. `recall_write` will not overwrite an existing memory unless `overwrite: true` is passed, so a durable memory is never clobbered by accident. See [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) for the full model.

### Develop and test

```bash
npm install
npm run build        # compile TypeScript to dist/
npm test             # unit + integration + end-to-end stdio tests
node scripts/smoke.mjs   # drive the built server with a real MCP client
```

Configuration:

| Variable | Default | Purpose |
|---|---|---|
| `RECALL_MEMORY_DIR` | `~/.recall/memories` | Where memory files are stored |

---

## Credits

Built by Andrew Homeyer, co-developed with Claude (Anthropic's Claude Code).

## License

MIT.