Reference

MCP tool reference

How memex speaks MCP, and what each of its tools does, takes and returns.

memex speaks MCP over plain HTTPS at https://memex.tools/mcp: one JSON-RPC request per call, no streaming. A connection authenticates with the bearer token memex minted for it, either through the assistant’s sign-in flow or a token you created on the Other tab of Settings › Assistants. An invalid or revoked token gets “Invalid or revoked token”.

Every note id on the wire is the note’s number in your knowledge base, the same one in its address. Proposal and journal ids are numbered within your knowledge base the same way.

Every tool has a title, which clients show in their list of memex’s tools. Each call answers with structured JSON. A refused call (a missing argument, an anchor that no longer matches, an allowance reached, a role the token does not hold) comes back as a tool error with a sentence saying why. Lists page with offset and limit and report a total. Long note bodies page with max_chars and body_next_offset.

The tools, in the order memex lists them:

search

Find notes by meaning and keyword, or browse. With a query, results are ranked as How search works describes, and the same operators apply (OR, NOT or -word, parentheses, "quoted phrases"), matching words as written with no fall-back to meaning, which the reply says in exact_match. Without one, it lists notes filtered by tags (all must match) and status (verified or pending), ordered by order (relevance, or updated or created, ascending or descending).

Up to twenty-five per page. Each result carries the id, title, description, status, source URL, tags and last update, and sometimes which section matched. Tag names that match nothing are reported back as unknown_tags. If meaning-search could not run, the reply says so in semantic_search_unavailable, and an empty result then means only that no note contains those words. Open to every role.

get

Read one note by id: the full body, tags, wiki-links and backlinks, status, description, who added and last edited it, and the true length of the body. If you flagged the note, curation_flag carries your comment, and the assistant is told to weigh it above its own reading. If the note is tagged live-state, live_state_notice carries the standing correction instruction; if it is tagged user-profile, profile_notice carries the reading instruction instead, or, for a profile still pending, the instruction not to follow it.

For a long note the assistant can ask for a slice with max_chars and continue from body_next_offset; memex tells assistants not to give up on a note for being large. Open to every role.

inbox

What is waiting for you: counts of pending notes and held proposals, and the oldest of each kind up to limit, with proposed bodies only if max_chars is asked for. Read-only, for every role: an assistant can tell you what is waiting, and can avoid filing what a peer already filed, but nothing here approves anything.

propose

The one write tool, in two shapes.

Without note_id it files a new note: title and body_md required, plus summary, tags and optionally a source_url. Assistants are told to write the description themselves, about two or three sentences, to call list_tags first and reuse your vocabulary, and to list what they consulted under a Sources heading at the end of the body. memex never describes or tags what an assistant writes: a note it saves without them waits in needs_enrichment. The note lands pending (agent) or verified (curator).

With note_id it files an edit, sending only what should change: a new title, a full replacement body_md, or a patch (up to fifty ordered find-and-replace operations, each find copied exactly from the note and occurring exactly once; an empty replace deletes), plus summary, tags (the full new list) and a change_title of six or seven words with a comment reporting what the change does, one short sentence per change. A summary alone is a complete edit.

For an agent the edit is held; for a curator a patch or a field change applies immediately, a whole body_md is held, and hold: true holds it on purpose. A held patch is checked again against the note as it stands when you approve it, so an anchor that has since changed is refused rather than misapplied.

A comment with nothing else is a report: the note is unchanged, and the comment waits in your inbox as a staleness report. A second propose on a note the same connection already has in review revises that draft. The reply says which of these happened, and may add free hints: near-duplicates it noticed, notes the text names but does not link (with ready patches), and vocabulary tags the text uses, none of which was applied. If other notes cite this one, the reply says so and asks the assistant to check them.

propose_delete

Ask for a note to be retired, with a reason you can decide from. Held for every role. If other notes link to it, the reply asks where those links should point instead.

propose_merge

Ask for a duplicate to be folded into a keeper: note_id is absorbed, into_note_id survives and inherits its tags and backlinks, and merged_body_md optionally replaces the keeper’s body. Held for every role. Both notes stay until you approve.

needs_enrichment

The backlog of notes with no description or no tags, oldest first, leaving out any note whose description is already waiting in your inbox. The intended loop is get a note and propose its description, one call per note. Open to every role; an assistant works it when you ask, never unasked.

list_skills and get_skill

The instruction sets memex serves to this connection: the shipped skills and your own served skill notes, each with a slug, title and description; then the full text of one by slug. The list is this connection’s own, not everyone’s, narrowed by the skill’s enabled state, its tool and resource surface flag, and the connections it has been granted to. Assistants are told to check the list before a task that a skill might cover, and to follow what they load.

Every tool result also carries skills_version, a short hash of that list; when it differs from the one this connection last saw, the result carries skills_changed too, the served list in one line, so a change made on the Skills page is learned on the connection’s very next call. See How assistants receive skills and instructions.

list_tags

Your vocabulary with a count per tag, the names you removed (with what they were merged into, so an assistant never proposes a retired word), and the three system tags marked with what each does.

health

Confirms the connection, gives this memex’s address, names the connection and its role, and reports how much work is waiting (inbox counts and the enrichment backlog), so a scheduled run can stop when there is nothing to do.

curation_candidates

The curation queue: which notes need attention and why, ranked as How curation works describes, with counts per reason. reason narrows to one defect, stale_days to notes unread for that long, cooldown_days (seven by default) holds back recently curated notes, and include_pending adds pending notes as advisory. Notes another connection is currently working are withheld for up to half an hour. Open to every role. An empty result means there is nothing to do.

blast_radius

Notes whose linked neighbours changed recently, with what changed, so a pass can find notes left stale by an edit you, an agent or an import made; curators’ own edits do not count. Open to every role.

last_curated

With no arguments, a preflight: when the last pass ran, what changed since, the size of the queue, and whether a pass is due. With note_ids, the last time each was curated. Open to every role; curators also see who and what.

log

Curator only. Append to the journal: a run summary (with the start time, the ids examined, and the counts the assistant claims, which memex checks against what it logged), an observation, or a tooling gap. A run summary that lists the notes it examined also releases the notes the queue was holding for that connection; otherwise they are released within half an hour.

log_recent

Curator only. Read the journal newest first: by default the curation record (what curators did, and your verdicts, flags and tag changes); for one note, everything done to it by anyone; or one kind of entry, or only the verdicts you marked as precedent. Assistants are told that your comments on their held items outrank their own judgment, and that a precedent applies to comparable cases from then on.

resolve_curation_flag

Curator only. Close your flag on a note by saying what was done about it. Disagreeing is a valid resolution. Refused while a delete or merge of that note is waiting for you, because your verdict on that proposal answers the flag.

duplicate_candidates

Curator only. Pairs of notes closest in meaning, with a distance, for a pass to open both and decide. unsettled counts notes still being compared; their pairs arrive on a later call.

Connector filters

Some assistants reach memex through a connector path that blocks text which looks like shell commands, answering with an HTML block page instead of JSON. Every write tool accepts body_encoding: "base64" as a retry: the assistant re-sends the same call with the free-text fields base64-encoded, including the find and replace of each patch operation, and memex decodes them so the note keeps its literal commands.