Skip to content

Tool reference ​

Every tool Muninn serves, with its parameters. The descriptions here are the same ones clients receive in tools/list; mem_man serves them from the server too.

Muninn serves one project per server, so project may be omitted. The project is named by MUNINN_PROJECT (default main); MUNINN_PROJECT_ID adds a second accepted name. A tool given another project returns an error.

With MUNINN_READ_ONLY=1 the write tools (mem_write, mem_edit, mem_move, mem_delete) are not listed, and calling one returns tool not found.

Every tool declares the four MCP tool annotations, so a client can tell the read tools from the write tools and ask before a destructive call. None reaches beyond the notes folder (openWorldHint: false).

ToolsreadOnlyHintdestructiveHintidempotentHint
mem_search, mem_read, mem_list, mem_find, mem_context, mem_project, mem_schema, mem_mantruefalsetrue
mem_write, mem_edit, mem_deletefalsetruefalse
mem_movefalsefalsefalse
ToolWritesSummary
mem_searchSearch the knowledge base, ranked by relevance.
mem_readRead a note or file by path, permalink, memory:// URL or exact title.
mem_writeyesCreate or replace a note.
mem_edityesChange part of an existing note.
mem_moveyesMove or rename a note (identifier) or a directory (path) within the project.
mem_deleteyesDelete a note (identifier) or a directory (path).
mem_listList one folder of the project: its subfolders, then its files with title, date and permalink.
mem_findFind files in the project, recursively.
mem_contextFollow the knowledge graph from a note: the note, its observations, and the notes its relations reach (both directions), up to depth hops (1-5).
mem_projectProjects.
mem_schemaNote schemas (Picoschema).
mem_manRead this server's manual.

Results and errors ​

Tools answer in readable text by default. With output_format: "json" they answer with one JSON document instead, which suits programs and long result lists.

A call that cannot be done (an unknown note or project, a checksum that no longer matches, a note that already exists) comes back as a tool result marked isError, with the reason as text, so the model can read it and try again. A request that is wrong in itself is a protocol error (invalid_params): a missing required parameter, a value of the wrong type, or a path that leaves the notes folder (.., a hidden segment, a symlink).

Search the knowledge base, ranked by relevance. query supports quoted phrases, AND/OR/NOT and tag:name. mode picks hybrid (meaning and words fused; the default when embeddings are configured), text, semantic, title or permalink (globs with *). Narrow with filters (frontmatter), note_types, items (note, observation, relation), categories and since. lines returns each hit's matching lines with context, like grep. path limits the search to a folder; identifier searches one note. Read full notes with mem_read.

ParameterTypeDefaultDescription
querystringWhat to search for. Omit to search by filters alone.
identifierstringSearch only this note; returns its matching lines.
all_projectsbooleanfalseSearch every project.
categorieslist of stringObservation categories to match exactly, e.g. ['decision'].
compactbooleanfalseOmit excerpts; keep identifiers and scores.
filtersobjectFrontmatter filters as {field: condition}: a value for equality, null for absent-or-null, a list for contains-all, or an operator object with $gt, $gte, $lt, $lte, $in, $between, $contains or $exists. Nested fields use dot notation.
itemslist of stringWhat to return: note, observation, relation, or a mix. Default: note.
linesintegerReturn each hit's matching lines with this many lines of context (0-10), instead of an excerpt.
max_matchesinteger10Matching lines shown per note with lines.
min_similaritynumberOverride the semantic similarity floor (0-1).
modestringSearch mode: hybrid (default when semantic search is available), text, semantic, title or permalink.
note_typeslist of stringFrontmatter type values, e.g. ['person', 'meeting'].
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
pageinteger1Page number, from 1.
page_sizeinteger10Results per page (1-100).
pathstringSearch only this folder and its subfolders.
projectstringProject name. Optional: this server holds one project, used when this is omitted.
projectslist of stringSearch these projects together.
sincestringHow far back to look: '7d', '24h', '2 days ago', 'last week', or a date.
time_kindstringNot supported here: temporal qualifiers are not indexed.
valid_atstringNot supported here.
valid_overlapsstringNot supported here.

mem_read ​

Read a note or file by path, permalink, memory:// URL or exact title. Slice a long note with section (a heading), start_line/end_line or max_tokens; line numbers count the whole file, frontmatter included. include_content=false returns only the metadata and the checksum that mem_write, mem_edit, mem_move and mem_delete take as expected_checksum. Images come back as images. A missing note is an error: find notes with mem_search.

ParameterTypeDefaultDescription
identifierstringrequiredThe note or file: a path ('notes/plan.md'), permalink, memory:// URL, exact title, or '<project>/path'.
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
end_lineintegerLast line to return, inclusive.
include_contentbooleantrueFalse returns only title, paths, checksum and updated_at.
include_frontmatterbooleantrueInclude the YAML frontmatter in a whole-note read.
max_tokensintegerApproximate token budget; longer content is cut at a section or paragraph boundary.
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
sectionstringA heading to read: "Decisions", "Auth/Decisions", or "Decisions[1]" for the second one.
start_lineintegerFirst line to return, counting the whole file (frontmatter included) from 1.

mem_write ​

Create or replace a note. Give a file path as identifier ('notes/plan.md'), or title plus directory. The title comes from the content's frontmatter, then title, then the file name. An existing note is an error unless overwrite=true; pass expected_checksum (from mem_read) to replace only the revision you read. To change part of a note use mem_edit. Content may hold frontmatter, observations ('- [category] fact #tag') and relations ('- relation_type [[Other Note]]'). The result lists observations already saved that say nearly what this write added: update one of those rather than keep both.

ParameterTypeDefaultDescription
contentstringrequiredThe note's Markdown, saved as given; it may start with frontmatter.
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
identifierstringFile path for the note, e.g. 'notes/plan.md'; '.md' is added when missing. Use instead of title + directory.
directorystringFolder for a note addressed by title; '/' is the root.
expected_checksumstringReplace the note only while it is still this revision (the checksum from mem_read). Implies overwrite.
metadataobjectExtra frontmatter fields, merged into the note's frontmatter.
note_typestringFrontmatter type:. A type: in the content wins.
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
overwritebooleanReplace a note that already exists.
tagsanyTags, as a list or 'a,b,c'.
titlestringNote title. With directory, it also names the file.

mem_edit ​

Change part of an existing note. command: append or prepend content; find_replace find_text with content (exact text that must occur expected_replacements times, default 1); replace_section, insert_before_section or insert_after_section for a section heading ('Decisions', 'Auth/Decisions', 'Decisions[1]'); set_metadata to merge metadata into the frontmatter without touching the body. metadata also merges with any other command. Pass expected_checksum (from mem_read) to edit only the revision you read. Like mem_write, the result lists observations already saved that say nearly what the edit added. Create notes with mem_write.

ParameterTypeDefaultDescription
identifierstringrequiredThe note: a path, permalink, memory:// URL or exact title.
commandappend | prepend | find_replace | replace_section | insert_before_section | insert_after_section | set_metadatarequiredThe edit: append, prepend, find_replace, replace_section, insert_before_section, insert_after_section or set_metadata.
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
contentstringThe text to add or the replacement. Not used by set_metadata.
expected_checksumstringEdit only while the note is still this revision (from mem_read).
expected_replacementsinteger1For find_replace: how many times find_text must occur.
find_textstringFor find_replace: the exact, case-sensitive text to replace.
metadataobjectFrontmatter fields to set; other fields are kept.
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
replace_subsectionsbooleantrueFor replace_section: true replaces the subsections too; false stops at the first subsection heading.
sectionstringThe heading for section commands: "Decisions", "Auth/Decisions", or "Decisions[1]".

mem_move ​

Move or rename a note (identifier) or a directory (path) within the project. destination is the new project-relative path; ending it with '/' moves into that folder under the current name. Pass expected_checksum (from mem_read) to move a note only if it is still the revision you read. Links by title keep resolving; the permalink in the frontmatter does not change.

ParameterTypeDefaultDescription
destinationstringrequiredNew path, e.g. 'archive/plan.md'. A trailing '/' moves into that folder under the current name.
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
identifierstringThe note to move.
expected_checksumstringMove the note only while it is still this revision (from mem_read).
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
pathstringThe directory to move, with everything in it.

mem_delete ​

Delete a note (identifier) or a directory (path). A directory delete removes every file under it and needs recursive=true. Pass expected_checksum (from mem_read) to delete a note only if it is still the revision you read. A note that does not exist is an error. This cannot be undone.

ParameterTypeDefaultDescription
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
identifierstringThe note to delete.
expected_checksumstringDelete the note only while it is still this revision (from mem_read).
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
pathstringThe directory to delete, with everything in it.
recursivebooleanfalseRequired true to delete a directory.

mem_list ​

List one folder of the project: its subfolders, then its files with title, date and permalink. '/' lists the root. Filter files with glob and order them with sort. For a recursive search by name or frontmatter, use mem_find.

ParameterTypeDefaultDescription
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
globstringFile-name glob, e.g. '*.md' or 'meeting'.
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
pageinteger1Page number, from 1.
page_sizeinteger10Results per page.
pathstring"/"A directory in the project; '/' is the root.
sorttitle_asc | title_desc | updated_asc | updated_descFile order. Folders always come first.

mem_find ​

Find files in the project, recursively. With name, match file names against a glob ('meeting'). With filters, match notes by frontmatter, e.g. {"status": "active"} or {"priority": {"$in": ["high"]}}, and with fields return just those frontmatter values per note. path limits the search to a folder. For ranked text or meaning search, use mem_search.

ParameterTypeDefaultDescription
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
depthinteger10Folder levels to search (1-10).
fieldslist of stringFrontmatter fields to return per note (dot paths allowed). Needs filters.
filtersobjectFrontmatter filters, as in mem_search.
namestringFile-name glob, e.g. 'meeting'. Not with filters.
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
pageinteger1Page number, from 1.
page_sizeinteger10Results per page.
pathstring"/"A directory to search in; '/' is the root.

mem_context ​

Follow the knowledge graph from a note: the note, its observations, and the notes its relations reach (both directions), up to depth hops (1-5). identifier is a path, permalink, memory:// URL, or a pattern such as 'specs/*'. since keeps only related notes changed recently. compact returns the graph without note bodies; read chosen notes with mem_read.

ParameterTypeDefaultDescription
identifierstringrequiredWhere to start: a note path, permalink, memory:// URL, or a pattern such as 'specs/*'.
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
compactbooleanfalseOmit note bodies and observations; keep the graph shape.
depthinteger1Relation hops to follow (1-5).
max_relatedinteger10Most related results to return (0-100).
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
pageinteger1Page number, from 1.
page_sizeinteger10Primary results per page (1-50).
sincestringOnly related notes changed this recently: '7d', '24h', 'last week', or a date. Default: no limit.

mem_project ​

Projects. command: list (the project this server holds); recent (what changed lately in project: since, items, paging); create is not supported, this server holds one project.

ParameterTypeDefaultDescription
commandlist | create | recentrequiredlist shows the project; recent shows what changed lately; create is refused (one project per server).
itemslist of stringFor recent: notes, observations, relations, or a mix. Default: notes.
namestringFor create: not supported, this server holds one project.
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
pageinteger1Page number, from 1.
page_sizeinteger10Results per page.
pathstringFor create: accepted for compatibility and ignored.
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
set_defaultbooleanfalseFor create: accepted for compatibility and ignored.
sincestring"7d"For recent: how far back to look.
workspacestringAccepted for compatibility and ignored: there are no workspaces.

mem_schema ​

Note schemas (Picoschema). command: validate notes against their schema (one note_type, one note by identifier, or every type that has a schema); infer a schema from the notes of a note_type; diff a note_type's notes against its schema to find drift. A schema is a note with type: schema whose entity field names the note type it describes and whose schema field maps each field to its type; a field ending in '?' is optional.

ParameterTypeDefaultDescription
commandvalidate | infer | diffrequiredvalidate checks notes against their schema; infer suggests one from existing notes; diff compares the two.
projectstringThe project name. Optional: this server holds one project, used when this is omitted.
identifierstringFor validate: one note, instead of a whole note type.
note_typestringThe frontmatter type: to check. Required for infer and diff.
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
thresholdnumber0.25For infer: the share of notes a field must appear in to be suggested.

mem_man ​

Read this server's manual. With no arguments, the index of every page. page reads one tool's page ('mem_search' or 'mem-search(3)'). query lists the pages that mention every word given.

ParameterTypeDefaultDescription
querystringWords to find in the manual; lists the pages that mention them all.
output_formattext | json"text"text (readable, the default) or json (structured, for programs).
pagestringThe page to read: a tool name such as 'mem_search' or 'mem-search(3)'.

Released under the MIT License.