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):

# 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):

{
  "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:

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:

{
  "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 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:

---
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 for the full model.

Develop and test

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.