Tools reference
Every tool the twin memory MCP servers list, with its arguments, bounds, defaults and what it returns.
The hosted server lists eight read tools, and memory_add for a key that writes or a Read and save connection.
The local stdio server lists the same eight and four more, documented under
Local server only. Only memory_search can make a model call on the hosted server.
Each tool is one call to the HTTP route of the same name, with the same request schema, so a bound is the same in both places. The description a client shows for a tool is that route's own description.
A tool's result is one text content block holding the same JSON the HTTP route returns:
{
"content": [{ "type": "text", "text": "{\"query\": \"Where does Alice live?\", \"found\": 2, ...}" }],
"isError": false
}Dates are ISO days, YYYY-MM-DD, or a full ISO time that starts with one, up to 40 characters. Text arguments
are 1 to 2,000 characters. Names and paths are up to 512 characters.
No tool takes an account. Every tool reads the end user named by the connection's X-Twin-Account header, by the
choice made at sign-in for claude.ai and ChatGPT, or, on the local server, by the command's --account.
Titles and hints
tools/list sends each tool with a title and annotations, which claude.ai and ChatGPT use to decide when to ask
before a call: a read-only tool runs without asking, a write asks.
| Tool | Title | Annotations |
|---|---|---|
memory_search | Search memory | readOnlyHint: true, openWorldHint: false |
memory_grep | Find exact text | readOnlyHint: true, openWorldHint: false |
memory_read | Read a memory file | readOnlyHint: true, openWorldHint: false |
memory_ls | List memory files | readOnlyHint: true, openWorldHint: false |
memory_around | Read around a passage | readOnlyHint: true, openWorldHint: false |
memory_history | History of a value | readOnlyHint: true, openWorldHint: false |
memory_latest | Latest memories | readOnlyHint: true, openWorldHint: false |
memory_overview | What memory holds | readOnlyHint: true, openWorldHint: false |
memory_add | Save to memory | readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false |
memory_add is idempotent because sending an item with the same id again edits it rather than adding a second
one. An edit is for fixing the same statement; a change is a new item, so memory keeps both, dated. The local server's four extra tools are read-only too.
memory_search
What memory holds for a question: what is known, dated facts and whole passages, each with its address. The
default first lookup. Can make one model call. Same as /v1/memory/search.
Arguments
querystringThe question, in plain words. 1 to 2,000 characters.
beforedateOnly memory from before this day. The question is asked as of it.
afterdateOnly memory from this day on. Returns a ranked list rather than the brief.
scopestringA path prefix to search under, such as passages/memory/documents. Returns a ranked list.
memory_grep
Exact substring match, for a quoted phrase that similarity would blur. Case is ignored. Makes no model call. Same as
/v1/memory/grep.
Arguments
patternstringThe phrase to find. 1 to 2,000 characters.
scopestringA path prefix to look under.
limitintegerHow many matches to return. 1 to 50, default 50.
memory_read
One file by exact path. A missing path answers with its siblings. Makes no model call. Same as
/v1/memory/read.
Arguments
pathstringA path a result gave you, such as a hit's path.
memory_ls
The children of one directory, so a caller can see the shape before reading. Directories end in /. Makes no model call. Same
as /v1/memory/ls.
Arguments
pathstringThe directory. Default "", the top.
memory_around
The passages either side of one, in its own thread. Addressed, never ranked. Makes no model call. Same as
/v1/memory/around.
Arguments
passage_idstringA passage id from a result, such as th_8b5e5d4c8946d815/p_0001.
widthintegerHow many passages on each side. 1 to 5, default 2.
memory_latest
The most recent passages, newest first. Ordered, never ranked: the lane for "what happened last", which a
similarity search cannot answer. Makes no model call. Same as /v1/memory/latest.
Arguments
kintegerHow many passages. 1 to 50, default 10.
placestringA place to narrow to: either segment of a passage path, such as memory or documents. Default "",
everywhere. A place that holds nothing answers with the places that exist.
afterdateOnly passages from this day on.
beforedateOnly passages from before this day.
memory_history
The bi-temporal chain for one subject: what was true, and when it stopped being. Needs the conversation to have
been read in the background. Makes no model call. Same as /v1/memory/history.
Arguments
subjectstringThe subject, such as Alice Chen. A miss answers with the nearest recorded subjects.
attributestringOne attribute, such as home_city.
memory_overview
What this memory holds: its shape, its counts, and its written index. The first call a model that has never
looked should make. Makes no model call. Same as /v1/memory/overview.
Takes no arguments.
memory_add
Listed only for a read and write key or a Read and save connection, and on the local server only when it is
started with --writes. Its
description carries the save policy, because some clients (claude.ai) show the model nothing else: "Save to this
person's long-term memory (twin memory), which their other apps read too. Call this on your own, without being
asked, on every turn where they say anything new: about themselves, their work, or the people, places, projects
and things around them - preferences, facts, opinions, decisions, plans, dates, names and numbers, small details
and passing remarks. Also save what was asked, tried, decided or built together, and why. When in doubt, save.
One fact per item, as a note, in their words; several items in one call is fine. Reuse an item's id to correct
it; set expires for what stops being true. Never save secrets, passwords, keys or payment details, or your own
suggestions as facts about them." It takes the same body as /v1/memory/add. Makes no model
call. Each item is read in the background afterwards, as any added item is.
Arguments
itemsobject[]1 to 500 items, each as /v1/memory/add takes it: text, kind, id, at, author, role,
session, title, about, expires and metadata. See Items.
waitbooleanAnswer once the items are searchable, rather than a moment before. Default false.
Local server only
These four are listed by the local stdio server and not by the hosted server at
/v1/mcp. They have no route in the developer API.
Tools shaped for connector data
memory_recall, memory_lessons, memory_how_they_work and memory_next were built for agents working
over connector data, such as Slack and GitHub activity. They run over plain items too, but on a memory of
messages, documents and notes they may return little.
memory_recall
The brief for a question: records, worked-out lines and passages, as one block of text, with enough, the
model's estimate that memory holds the answer. With OPENROUTER_API_KEY set, makes one to seven model calls:
one, and up to seven with deep.
Arguments
questionstringThe question. 1 to 2,000 characters.
as_ofdateThe day the question is asked as of. Nothing said after it is used.
deepbooleanFollow the names in what was kept when memory is thin. Up to six more model calls and several seconds.
Default false.
memory_lessons
What past attempts at a task like this one taught. Makes no model call.
Arguments
taskstringThe task. 1 to 2,000 characters.
memory_how_they_work
The steps one person takes before an action, and the voice they write in. Addressed by a person, not ranked. Makes no model call.
Arguments
whostringThe person.
surfacestringWhere the answer is for, such as a channel or a repository. Default "", the surface they write on most.
memory_next
What this person usually does next, from what they have just been doing. A guess with backed_off: true is the
person's base rate, not a prediction from context. Makes no model call.
Arguments
whostringThe person. Default "", the memory's owner.
topintegerHow many guesses. 1 to 10, default 3.