Memory for your programs

Programs on your computer can use MindDuck as their memory. You connect a program, choose the projects it works in and give it a key. From then on the program can read what those projects hold, search them, save documents there and add working notes. The next session of the program starts from what the last one learned, and you read all of it in MindDuck, on any device.

The program does not run inside MindDuck and MindDuck does not run it. It talks to MindDuck on this computer only; nothing is sent over the network.

Writing needs you to be signed in under Settings → Account with active access to MindDuck. See Account.

Turn it on

1. Open Settings → Agents and scroll to Memory for your programs.
2. Turn on Accept connections on this computer. The card shows the address programs connect to, http://127.0.0.1:47821 by default.
3. Press Connect a program. Choose the program, give it a name, tick the projects it works in and press Create key.
4. Copy the key and give it to the program. MindDuck shows the key once and keeps only a fingerprint of it. If the key is lost, make a new one.

MindDuck answers programs while it is running, with its window open or closed. See Background in Assistant. While the workspace is locked, programs are told so and get nothing from it.

If Not running appears with a note that the port is used by another program, type another number in Port and press Use this port. Programs you already connected need the new address.

Connect Claude Code

After Create key, MindDuck shows how to connect the program. The same steps open later with How to connect on the card of the program, with a place for the key instead of the key.

In a terminal, in the folder of your project:

claude mcp add --transport http mindduck http://127.0.0.1:47821/mcp --header "Authorization: Bearer mdk_..."

Claude Code keeps the connection for that folder only. Without a terminal, for example in the Claude desktop app, save the second block MindDuck shows as .mcp.json in the folder of the project. That file holds the key: keep it out of version control.

Start a new session and ask Claude Code to read the project context. It gets the memory tools: memory_context, memory_search, memory_read, memory_documents, memory_note, memory_save, memory_update, memory_projects, memory_index_status. Claude Code asks before it uses a tool for the first time; allow the ones you want it to use without asking.

If the key opens several projects, choose one under Project for this connection before you copy the command. The program then works in that project without naming it every time.

Connect Codex

Add the block MindDuck shows to ~/.codex/config.toml and start Codex again:

[mcp_servers.mindduck]
url = "http://127.0.0.1:47821/mcp"
http_headers = { "Authorization" = "Bearer mdk_..." }

To connect one project only, put the block into .codex/config.toml of a trusted project.

Connect Claude Desktop

Claude Desktop starts its MCP servers itself, as commands. MindDuck shows an entry for its configuration file; it starts MindDuck's own program as a bridge to the memory.

1. In Claude Desktop open Settings → Developer → Edit Config.
2. Add the mindduck entry MindDuck shows under Add to claude_desktop_config.json to the mcpServers section of the file.
3. Start Claude Desktop again.

MindDuck must be running for the tools to answer. If it is not, Claude is told so and can go on without memory; the next call works once MindDuck is running again.

The project context at the start of every session

Claude Code and Codex can run a command when a session starts and give its output to the model. With the two optional steps MindDuck shows, a session in your project folder starts with the project context already in front of the agent: your Agent brief, the latest working notes, the facts you confirmed and the list of documents and recent conversations.

1. In the folder of the project, run the Save the key for the folder command. The key is kept in .mindduck in your home folder.
2. Add the hook MindDuck shows to .claude/settings.local.json in that folder for Claude Code, or to ~/.codex/hooks.json for Codex. In Codex, review and trust the hook with /hooks.

The hook never holds a session up. When MindDuck is not running or the workspace is locked, the session starts without the context.

A new project folder

With May create new projects ticked for the program, a folder you start working in gets its project in MindDuck with one command, run in that folder:

"C:\Program Files\MindDuck\mindduck-desktop.exe" memory connect

The command uses the key you saved before, starts a project named after the folder and ties the folder to it. To choose the name, add --project "Name". If the key already opens a project with that name, the folder is tied to it and nothing new is made. Run again in the same folder, the command changes nothing.

To have the memory tools and the context in every folder without setting each one up, connect once for all folders: in Claude Code add --scope user to the claude mcp add command and put the hook into ~/.claude/settings.json. A session in a folder where you have not run connect starts without the context.

Without the tick, connect only saves the key, and a project name the key does not open is refused.

Connect another program

A program that connects to MCP servers by address needs the address http://127.0.0.1:47821/mcp and the header Authorization: Bearer with the key. MindDuck shows this as JSON for programs that take it in that form, and the bridge as a command for programs that start their MCP servers themselves. A program without MCP can use the HTTP API described below.

The browser extension

The MindDuck extension for Chrome and Firefox saves what you read on the web to a project and sends a passage to MindDuck when you want to ask the assistant about it.

1. Install the MindDuck extension in your browser.
2. In MindDuck press Connect a program, choose Browser extension, tick the projects it may save to and press Create key.
3. Open the options of the extension, paste the address and the key and press Connect.

The key belongs to the extension that used it first. Another extension or a web page cannot use it. To move to another browser, press New key on the card and paste the new key there.

Press the MindDuck button in the browser toolbar, choose the project and one of the actions:

• Save selection saves the selected text as a document, as a quote with the address of the page and the date.
• Save page saves the text of the page as a document.
• Discuss in MindDuck brings MindDuck to the front with a new chat of the project open and the selection, or the page when nothing is selected, in the message box. Add your question and send it. Nothing is saved until you do.
• Discuss a picture of the page does the same with a picture of what the browser shows.

The first three are also in the menu that opens with a right click on a page.

The extension reads a page only when you press one of these, so a page behind a sign-in is saved like any other. Pictures, PDF files and video on a page are not saved. What the extension saved is listed in its activity chat in the project, with Undo; see What a program did below.

From a terminal

MindDuck's own program answers memory commands when it is started with the word memory. The path below is for Windows; on a Mac the program is /Applications/MindDuck.app/Contents/MacOS/mindduck-desktop.

"C:\Program Files\MindDuck\mindduck-desktop.exe" memory connect --key mdk_...
"C:\Program Files\MindDuck\mindduck-desktop.exe" memory context
"C:\Program Files\MindDuck\mindduck-desktop.exe" memory search release plan
"C:\Program Files\MindDuck\mindduck-desktop.exe" memory note Decided to ship on Monday.
"C:\Program Files\MindDuck\mindduck-desktop.exe" memory save --title "Release plan" --file plan.md

connect saves the key for the folder you run it in; --default saves it for every folder. memory help lists the commands. On Windows the command prints into the terminal it was started from, and the prompt may return before the output ends; pipe the output, for example | more, to wait for it.

What a connected program can do

In the projects you chose for it, and nowhere else:

• read the project's documents and conversations;
• search them;
• save a text as a new document and change a document;
• add working notes;
• keep a conversation line by line.

It never sees:

• other projects and chats without a project;
• private chats and documents you kept out of memory;
• what is in the trash.

It cannot create or change facts. Facts stay yours to confirm; a program writes what it learned into the working notes.

With May create new projects ticked, the program can start a project of its own. That project is added to its list. Your other projects stay closed.

Working notes

A note a program adds goes to the end of a document named Working notes with the month, for example Working notes 2026-10, under a line with the time and the name of the program. Nothing is rewritten: several programs and you can add to the same notes without overwriting each other. It is an ordinary document: read it, correct it, delete what is wrong.

A month with many notes continues in Working notes 2026-10 (2).

Instructions for the program

Create a document named Agent brief in the project and write there what every program working in this project should follow: how the project is built, what to check before finishing, what to leave alone. A program asks for the context of the project when it starts and gets the brief first, then the latest notes, the facts you confirmed and the list of documents and recent conversations.

You can edit the brief on your phone. The program reads the new text at the start of its next session.

What a program did

Each program has a chat of its own in every project it writes to, named after it, for example Claude Code activity. The chat lists what the program did, one line for each document it created or changed and each note it added, with a link to the document. It is an ordinary chat: it syncs, and you can read it on your phone.

Under a line there is Undo while the action can still be taken back:

• a created document goes to the trash, from where you can restore it;
• a change, or a note, is undone by making the earlier text the current one again. This is a new revision, so nothing leaves the document's history.

A change can be undone only while it is the latest one. If the document was edited afterwards, open it and use its history instead. What you undid is noted in the same chat.

Documents a program wrote are marked as written by an agent when another program, or the assistant, finds them later.

Before saving, MindDuck removes from the text whatever looks like a credential: API keys, tokens, private keys, passwords in addresses. [secret removed] is left in their place.

What programs asked for

Recent requests lists what connected programs asked MindDuck for since it was started: the time, the program, what it asked for and how it ended. The text of requests and answers is not kept there. A request with a key MindDuck does not know is listed as Unknown key, which usually means the program still has an old key.

A program that asks for too much in a short time is slowed down: 300 requests a minute and 32 MB of written text a day for each key. Such requests are listed as slowed down.

Change or remove access

On the card of a program:

• Change access - other projects, another name, the right to create projects. The key stays the same.
• New key - replaces the key. The previous one stops working at once.
• Remove - the key stops working at once. Documents and notes the program wrote stay in memory.

Turning Accept connections on this computer off stops every program at once. Keys stay valid for when you turn it back on.

The list of programs and their keys is kept on this computer and is not synced. A key made here means nothing on another computer.

For developers

Any program that can send an HTTP request can use the memory. A request carries the key as a bearer token:

curl -H "Authorization: Bearer mdk_..." http://127.0.0.1:47821/v1/projects

A source is named doc:<id>, chat:<id> or msg:<chat id>:<message id>, as search and read return it. Long sources are read in parts: pass nextOffset of one answer as offset of the next.

A change to a document names the revision it was written from. If the document was edited in the meantime, the answer is revision_conflict with the current revision: read the document again and apply the change to it.

Send an Idempotency-Key header with a write that may be retried. The same key with the same request gets the first result back and writes nothing new.

An error has a stable code: unauthorized, forbidden, not_found, invalid_request, revision_conflict, idempotency_conflict, limit_exceeded, rate_limited, unsupported, read_only, workspace_locked, busy. A source the key may not see answers not_found, like one that does not exist.

If something goes wrong

• The program cannot connect. Check that MindDuck is running, that Accept connections on this computer is on and that the program uses the address shown on the card.
• The program is told the workspace is locked. Open MindDuck and unlock the workspace.
• Claude Code shows the server as failed. MindDuck was not running, or connections were off, when the session started. Start MindDuck and begin a new session.
• The program is told it may not write. Sign in under Settings → Account; see Account.
• The program says the key is not accepted. Look at Recent requests: an Unknown key line means the program has an old key. Make a new key and give it to the program.
• A document the program saved is not found by search yet. New text is indexed in the background, usually within a minute.
• The browser extension says the key cannot be used from this browser. The key is one of another program, or another extension used it first. Connect a program of the kind Browser extension, or press New key on its card, and paste the key in the options of the extension.