A local, SQLite-backed persistent memory for AI assistants that stores, searches, and curates short knowledge entries—no embeddings or external service required.
Store facts with remember, filing each entry on two axes: a free-text project tag and a kind (interface, pitfall, decision, measurement, workflow, history); it reports similar existing entries and flag-worthy new tags.
Supersede instead of accumulate by passing supersedes ids, which hide older entries without deleting them.
Search with recall using ranked full-text (FTS5) matching that handles inflected forms, with filters for kind and tag, optional full text, and optional inclusion of superseded entries.
Fetch full entries with show by id, capped at ~6,000 characters per call so the cost is predictable.
Browse with topics to list all projects or one project's newest title lines page by page—useful when you don't know the search terms.
Tidy up with consolidate, which finds groups of near-duplicate entries for you to merge manually.
Get a second opinion from check, an opt-in call to any OpenAI-compatible model that judges whether two entries contradict or merely progress.
Retire entries with forget, marking them obsolete with a reason (reversible via undo), and reclassify existing entries with classify.
Learn from use—repeated searches re-rank entries that answered before—and run read-only as a guest (--guest) over SSH, with ids prefixed by the memory's name.
Enables an optional fact-checking tool that uses an OpenAI-compatible model to judge whether memory entries contradict each other, supersede one another, or are independent.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@frugal-memory remember that the release process requires a sign-off from QA"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A persistent memory for AI assistants that is just a SQLite file — and costs about a fifth of what reading markdown notes does.
No vector store, no embeddings, no external service, no API key. Python,
SQLite with FTS5, stdio — the only dependency is the official mcp SDK.
Nothing leaves your machine unless you explicitly turn on the optional
fact check.
Measured over 275 real questions from 89 working sessions: 2,359 tokens
per answered question, against 11,319 for the usual one markdown file
per fact, found with grep and read whole. That baseline is the naive case
on purpose: it is what happens when the file is opened with Read, which
loads it whole. The careful path, grep -C with three lines of context,
turned out more expensive, not cheaper: 28 times the characters in the
median with a realistic search order (added after the run; 65 times under
the rule fixed before it), because a broad search over 1,756 files returns
hundreds of matching lines
(details).
Both compare against markdown notes, not against other memory servers.
The gap grows as the memory does, because every answer here is capped and
grep is not. All figures come from one installation, and the docs say
where one did not hold up.
An assistant's memory usually fails in one of two ways: it is a pile of markdown files that has to be read whole to be searched, or it is a vector database that answers that something matched but never why.
This one is a ranked full-text index over short entries, with two things bolted on that turn a note pile into a memory: entries are filed on two axes — where it belongs (project) and what kind of knowledge it is (pitfall, decision, measurement, …) — and when you write something down, the tool tells you which existing entries it overlaps with, so contradictions surface instead of quietly piling up.
Related MCP server: MCPMem
Capped, calculable answers — a search returns eight preview lines
of about 1.2 KB in total instead of 4.2 KB of full text; show then
fetches the entries you pick, about 6,000 characters per call unless
you ask for everything. The worst case is known before you ask.
It learns from its own failures — when a search is followed by fetching an entry, that pair is remembered. Ask the same thing again and the entry that answered last time comes first. Word-for-word repeats only, and the header says when it fired.
Two filing axes — a free-text project tag and a closed, enforced vocabulary of knowledge kinds. Chronicle entries are hidden from search by default, but the header always says how many were held back.
Duplicate and contradiction hints — remember reports similar
existing entries and which numbers changed, so you can supersede
instead of accumulate.
Nothing is ever deleted — superseded entries drop out of the default view and stay findable, with a note on why and by what. One switch brings them back if that was a mistake.
Browsing, not just searching — topics() lists projects and a
project's newest title lines for when you have forgotten the words to
search for. Capped like everything else: one page, and a line saying how
to get the rest.
Project-bound in use, not in search — the usual question is asked
inside one project, with tag=. That filter is hard, so when the best
match lies outside the project, recall names it instead of leaving you
with a plausible-looking list of the wrong entries.
Two opt-in extensions on the same engine — a literature archive that all projects share, and a lab notebook for measurement series. Each is its own file and its own server entry; leave them out and nothing changes (below).
Opt-in second opinion — optionally ask any OpenAI-compatible model whether two entries contradict each other or just supersede one another.
English by default, German as a second language — the search
matches inflected forms ("configured" finds "configuring").
MEMORY_LANG=de switches tool names, messages and kinds to German, and
the search to German stems and compound parts ("Rangliste" finds
"Ranglisten", "Katalysator" finds "Fusionskatalysator"). The figures
from real use below come from German notes
(A Note on Language). Measured, the stems rarely
change the answer: the plain any-term stage of the search already finds
what they would add
(details).
Python 3.11+
The mcp SDK (requirements.txt, that's the whole list)
SQLite with FTS5 — included in standard CPython builds
Tested on Linux, macOS and Windows with Python 3.11 and 3.14: the full test suites plus the installed package, on every push. Day-to-day use so far is on Linux only — reports from macOS and Windows are very welcome as issues.
Optional, for the fact check only: any OpenAI-compatible endpoint
From PyPI, as a command in its own environment:
pipx install frugal-memory # or: uv tool install frugal-memory
claude mcp add memory -s user -- frugal-memoryWith uv it also works without installing
first; uvx fetches the package on the first start:
claude mcp add memory -s user -- uvx frugal-memoryThe database is created on first use at
~/.local/share/frugal-memory/memory.db ($XDG_DATA_HOME if set).
frugal-memory-nachziehen is the upkeep script described in
DESIGN.md.
Coming from a folder of markdown notes, frugal-memory-import <folder>
moves them in, paragraph by paragraph
(IMPORT.md).
frugal-memory-skill installs the working rules for Claude Code (see below).
With uvx, all of them run as uvx --from frugal-memory frugal-memory-import ….
Or from a checkout of this repository:
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
claude mcp add memory -s user -- \
/path/to/frugal-memory/.venv/bin/python \
/path/to/frugal-memory/memory_server.pyHere the database is created as memory.db next to the script. Either way,
MEMORY_DB=/some/path.db puts it somewhere else.
-s user makes the server available in all projects; the entry ends up in
~/.claude.json. Restart Claude Code afterward — MCP servers are only
loaded at startup. The tools are then called mcp__memory__recall and
mcp__memory__remember.
For Claude Desktop, use ~/.config/Claude/claude_desktop_config.json
instead:
{
"mcpServers": {
"memory": {
"command": "/path/to/frugal-memory/.venv/bin/python",
"args": ["/path/to/frugal-memory/memory_server.py"]
}
}
}One rule matters more than any setting: one fact per call, not one
document. recall returns whole entries — store a 180 KB file as a
single entry and you get it back as a single hit, having gained nothing.
The tools alone don't tell an agent the working rules: search before
reading files, recall → show, exactly one kind per entry, supersede
instead of accumulate, retry in the other language. Two layers carry them:
The short form comes with the server. On connecting it sends about
600 characters of instructions (English, or German with MEMORY_LANG=de),
which Claude Code adds to every session that has the server. Guest mode
(--guest) sends none, since it cannot store anything.
The full rules are a skill. It ships with the repo and the PyPI package; one command installs it:
uvx --from frugal-memory frugal-memory-skill # or frugal-memory-skill after pip install
cp -r skills/frugal-memory ~/.claude/skills/ # or from a cloneClaude Code loads the skill's full text only when the memory comes up;
until then only its one-line description sits in context. An existing
SKILL.md that differs is left alone unless you add --force.
A third layer is up to you: a few lines in CLAUDE.md, for what neither
layer can say — mainly that the server, not Claude Code's own memory
files, is where knowledge goes. An optional block to copy is in
docs/CLAUDE-MD.md.
Each machine keeps its own memory, and each numbers its entries from 1. A session on machine A can read the memory of machine B over SSH — the server runs on B, next to its file; the database itself never crosses the network:
claude mcp add memory-b -s project -- \
ssh b /path/to/frugal-memory/.venv/bin/python \
/path/to/frugal-memory/memory_server.py --guest--guest (German: --gast) means three things:
Read-only. The file is opened with mode=ro, and only recall,
show and topics are offered. The writing tools are gone, and so are
consolidate and check: upkeep belongs to the owner, who can act on it. A guest's searches do
not feed the owner's search feedback either, and a guest never migrates
the schema.
Every id carries the memory's name: b#72, not #72. The name is the
host name in lower case; MEMORY_NAME overrides it.
A named id is checked, in both modes. show("b#72") asked of any
memory other than b is refused instead of quietly returning that
memory's own #72. Bare ids (72, #72) mean the memory being asked.
The guest speaks the language of the memory it reads, unless
MEMORY_LANG says otherwise. -s project keeps the three extra tool
definitions out of sessions that do not need them. The tools are then called mcp__memory-b__recall and so on.
The same server starts in two more modes. Each has its own file, its own
tools and its own entry in Claude Code; the memory itself is never opened
in them. Both follow MEMORY_LANG like the memory does. They grew out
of daily use with several projects at once and have not been measured
the way the memory has — they are offered because they made that work
noticeably easier, not because a number says so.
--archive)Papers, datasets and prior work, shared by all projects. The memory holds what you found out; the archive holds what others published, and its value lies in the find another project already made.
claude mcp add archive -s user -- uvx frugal-memory --archiveSame eight tools, other kinds: finding, method, survey,
resource (code, dataset), gap (searched, nowhere measured), lead
(unchecked) and rejected (checked and rejected — e.g. a citation a
language model made up). Leads and rejected entries are hidden from
search, like the chronicle in the memory.
The same source is recognized by its id, not its wording. When
remember sees an arXiv number, DOI or link that is already in the
archive, it says so — two projects rarely describe a paper in the same
words. It also asks for the source and the evidence level (full text,
abstract, unconfirmed) when they are missing.
Every id carries the name archive#12 (archiv#12 in German mode),
so it is never mistaken for a memory id.
File: archive.db next to the memory's, or ARCHIVE_DB. Several
machines can share one archive by starting it over SSH on the machine
that holds the file (without --guest, so all of them can write).
--messbuch)Measurement series as a structure instead of loose entries: question, criterion, recipe, numbers, verdict, and what supersedes what. Spread over a dozen memory entries, a series loses exactly the things that matter — which one is still running without an evaluation, and whether the criterion stood before the result.
claude mcp add messbuch -s user -- uvx frugal-memory --messbuchseries() lists open series with what needs a look: no entry for N
days — is the process still running?, measurements without result,
no criterion. A table across all series of one topic is
series(key="vision/lr-*", table=True).
new_series before the first run. The criterion gets a timestamp;
after the first measurement it can only change with a reason, and the
change stays visible. Without a criterion the only possible verdict is
observation.
recipe records the command, code version, seed and machine;
measurements one value per row; result the verdict against the
criterion and what follows from it. Nothing is deleted; wrong values
are superseded.
Turn it on before your first series. Entering old series after the
fact works (backfill=, started= keep their real dates), but
collecting them from scattered notes costs far more tokens than
writing each one down when it happens.
File: messbuch.db, or MESSBUCH_DB. Memory ids written into the
notebook must carry the memory's name (laptop#452): the notebook may
be shared by machines whose memories all count from 1.
| store an entry; reports similar existing ones and what it would supersede |
| ranked full-text search, preview by default; under |
| full text of specific entries, about 6000 characters per call; what doesn't fit is listed with the call that fetches it |
| browse: which projects exist, or one project's title lines, newest first, a page at a time |
| mark as outdated — never deletes; |
| assign the knowledge kind of existing entries |
| find groups of entries that say much the same thing |
| opt-in: have a language model judge contradiction vs. newer state |
Full reference with parameters and behavior: docs/TOOLS.md.
With MEMORY_LANG=de the same tools come with German names and parameters,
see A Note on Language.
Measured on one real dataset that grew from ~900 to ~1,900 entries along the way — evidence from one installation, not a benchmark:
4.8× cheaper than reading markdown files, in real tokens, over 275 real questions (2,359 vs. 11,319 per question). The gap grows with the dataset and with file size, because reading a file is all-or-nothing: one question against a 188 KB project file costs 94,152 tokens.
89.8 % Recall@10 against the public LoCoMo dataset with a session as the unit, untuned (2026-10-19; the first run in September gave 82.3 %, and 45.1 % with a single dialogue turn as the unit).
73 % smaller returns from the preview, with a calculable worst case.
−23 % expected characters per question from the feedback loop, at 84 % vs. 73 % first-round hit rate, measured over 164 questions from 30 real sessions in a time-ordered replay — a pair only ever helps later questions, never itself. 19 questions gained, none lost.
53 % → 64 % hit rate on 47 real reformulation chains from a one-line ranking fix — found by measuring where real search sessions had failed, not by guessing. On today's dataset the same fix also costs 3 of the 117 questions that already worked, so the net is +2 of 164.
93 % of the dataset belongs to a project (1,777 of 1,907 entries),
and that is how the tool is used. Search itself does not care: general
knowledge is found as well as project knowledge (92 % vs. 96 %, a tie
under the 10 % rule). What the project filter buys is precision for
short questions — 97 % vs. 85 % found at about three words. What it
costs is everything outside the project: 40 questions about general
knowledge, asked under 22 project tags, found 0 of 880. recall now
names the better match outside the tag in 82 % of those cases, and in
70 % that line already is the entry sought; on real project questions
it fires in 7–16 %.
−83 % for a project's title index, −34 % for fetching eight full
texts, from capping topics and show. On 110 project questions the
cap cost not one answer.
Where a measurement did not survive a larger sample, it says so:
docs/MEASUREMENTS.md, with the raw reports in
messung/. The ranking figure above was corrected twice —
see The Ranking Fix, Corrected Twice.
all eight tools in detail | |
the two axes, the morphology, the database schema, and what was left out on purpose | |
what was measured, and the known limitations | |
the opt-in fact check: setup, what it can and cannot do | |
importing an existing folder of notes, and the damage that did | |
an optional block to copy into your | |
the eight underlying measurement reports (mostly German) |
English is the default since 0.3.0: tool names, messages and the kind vocabulary are English, and the search uses a small English suffix stemmer.
German mode: start the server with MEMORY_LANG=de. If your notes are
in German, this is the better choice, and it is the mode all figures from
real use in this README were measured in. (LoCoMo, a set of English
conversations, gave 89.8 % in English mode and 89.7 % in German mode.) Then
the tools are remember(text, tags, art, ersetzt),
recall(query, limit, art, marke, voll, mit_veraltet), zeige(ids, voll),
themen(marke, limit, seite, alle), vergessen(ids, grund, rueckgaengig),
einordnen(ids, art), verdichten(marke, art, schwelle, gruppen) and
pruefe(ids),
the kinds are schnittstelle, fallstrick, entscheidung, messwert,
arbeitsweise, verlauf, gemischt,
every message is German,
the search stems German and splits German compounds.
Existing memories keep their language. Without MEMORY_LANG, the server
speaks the language the file was built in — a new file starts in English,
and a memory from before 0.3.0 stays German. So updating changes nothing
unless you set the variable. The stem index is what ties a file to its
language: the file records it, and the server refuses to open it with the
other one. To switch an existing memory, back it up and run
MEMORY_LANG=en frugal-memory-nachziehen once (or MEMORY_LANG=de …; from a
checkout: python3 nachziehen.py). Kinds are stored under their German
names in both modes and translated at the border; English kind names are
accepted in German mode too.
The two extensions follow the same switch: in German mode the archive's
kinds are befund, methode, ueberblick, werkzeug, luecke, spur
and verworfen, and the notebook's tools are reihen, reihe_anlegen,
reihe_aendern, rezept, messwerte and ergebnis. The archive follows
its own file like the memory does; the notebook stores the same data in
both languages, so it follows MEMORY_LANG alone and is English without it.
Not covered by the switch: the fact-check prompt stays German (it is calibrated word for word, and adding one sentence once halved its accuracy; only its verdicts are shown in English), and so do the import script and the measurement reports. The English stemmer has not been measured on real questions the way the German search has.
| MCP server, eight tools, search cascade, schema, migrations |
| stemmers: a small English one (default) and a German one with compound splitting ( |
| the English tool surface (the default) |
| the lab notebook ( |
| its English tools and messages |
| English messages, keyed by the German text |
| recomputes the derived columns and the word and tag directories ( |
| opt-in second opinion via any OpenAI-compatible model (off unless configured) |
| measures the fact check against gold labels from the dataset |
| the hand-built and hand-found contradiction pairs |
| import a folder of markdown notes ( |
| regression net, one case per pitfall (no pytest) |
| the tests of the two extensions |
| working rules for the agent, as a Claude Code skill (in the package too) |
| copies the skill to |
| just |
| package definition for PyPI ( |
| entry in the official MCP registry |
| the database — created on first use, never committed |
messung/ keeps the eight measurement reports. The scripts that
produced them and their raw data are not included: they only run against
the author's own dataset, and the raw data is a verbatim transcript of
real working sessions.
Bug reports, questions and experiences from your own setup are welcome as a GitHub issue - including "it did not work for me", which is the report this project can least get any other way.
MIT — see LICENSE.
Has a small language model judge how the named entries relate.
Use it on a group from consolidate, or on two entries that seem to disagree, to ask whether a CONTRADICTION is behind it, PROGRESS (a newer state), or nothing (INDEPENDENT). Not authoritative: measured 67 % correct on 70 German pairs, so the result says where to look, not what is true.
Returns one line per pair. Each pair is asked in both directions; only what comes back the same both times is reported, otherwise "disputed". At most 5 pairs per call, roughly 10 seconds each.
Opt-in: needs MEMORY_FC_URL and MEMORY_FC_MODEL (any OpenAI-compatible endpoint; MEMORY_FC_KEY if it wants a key). Without them this tool does nothing and says so. When set up, up to 200 characters of each note are sent there.
Args: ids: Two or more entry ids, e.g. "249,255".
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly: it discloses the bidirectional querying scheme and 'disputed' fallback, a 5-pair / ~10-second-per-pair cost budget, required environment variables, the no-op behavior when unset, and a privacy-relevant detail that up to 200 characters of each note are sent to an external endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and usage are front-loaded before the caveats, and each block (accuracy, return semantics, cost limits, opt-in setup, args) is distinct and earns its place. The environment-variable paragraph is somewhat long relative to the single-parameter surface, but it is operationally necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still clarifies the shape of results ('one line per pair', 'disputed' labeling), so nothing about return interpretation is ambiguous. Combined with cost limits, accuracy caveat, and opt-in setup, an agent has everything needed to decide whether and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema only declares 'ids' as an untyped string, but the description compensates by specifying cardinality ('Two or more entry ids') and the exact format with an example ('249,255'). The only remaining gap is that the delimiter is shown rather than stated for other separators.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Has a small language model judge how the named entries relate') and enumerates the three relation verdicts it returns (CONTRADICTION, PROGRESS, INDEPENDENT). It also distinguishes itself from the sibling 'consolidate' by describing the input as a group produced by that tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use: 'Use it on a group from consolidate, or on two entries that seem to disagree.' It also states an explicit when-not/limitation ('Not authoritative: measured 67 % correct ... the result says where to look, not what is true') and the opt-in prerequisite conditions under which the tool does nothing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets the kind of knowledge for existing entries.
Use it in passing on entries recall shows as "unsorted"; the backlog need not be sorted in one sitting. Writes only the kind - text, tags, ids and superseded status stay as they are - and is undone by classifying again.
Returns the ids changed, names unknown ids, and how many live entries are still unsorted.
Args: ids: One or more entry ids, e.g. "376,481"; a range "376-380" means every id in between. kind: Exactly one of: interface, pitfall, decision, measurement, workflow, history. "unsorted" undoes the classification.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| kind | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present the description carries the full burden, and it does: it declares the write is narrow ('Writes only the kind - text, tags, ids and superseded status stay as they are'), states reversibility ('undone by classifying again'), and previews the return payload including unknown-id reporting and remaining backlog count.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then usage, then side effects and return shape, then args. Each sentence contributes something an agent cannot get from the schema - notably the range syntax and the undo semantics - with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be spelled out, yet the description still summarizes the response usefully. Input format quirks, reversibility, and mutation scope are all covered, leaving no operational gap for an agent calling this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does: 'ids' accepts comma-separated values and '376-380' range syntax, and 'kind' must be exactly one of the six listed values, with 'unsorted' documented as the undo operation rather than just another enum member.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: setting the 'kind' of knowledge for existing entries. The word 'existing' implicitly distinguishes it from the sibling 'remember' (which adds entries) and it references 'recall' as the source of candidates, but it never explicitly names the sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete trigger: run it on entries 'recall shows as "unsorted"', and notes the backlog can be worked incrementally. It is clear when to reach for it, though it offers no explicit 'do not use this for X' exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds groups of entries that say largely the same thing.
Use it for tidying up. Read-only, changes nothing: merging is a judgment call - replace a group by one new entry via remember(..., supersedes="..."). Compares shared word stems weighted by rarity, not meaning; identical copies are always found. A few seconds for thousands of entries.
Returns how many entries and pairs were compared, then the groups, largest first, each with its best similarity and its entries (id, kind, date, title) - or that nothing reached the threshold.
Args: tag: Only consider entries from this project (empty = all). Sub-tags are included, as in recall. kind: Only consider entries of this kind/these kinds, comma-separated. Default "all"; "history" alone is the most rewarding case. threshold: Share of the weighted stems two entries must have in common, 0 to 1. Default 0.5; 0.8 shows only near-copies. groups: Maximum number of groups reported (default 5).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| kind | No | all | |
| groups | No | ||
| threshold | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it declares read-only semantics ('changes nothing'), explains the matching algorithm and its limit ('shared word stems weighted by rarity, not meaning; identical copies are always found'), and gives a performance envelope ('a few seconds for thousands of entries'). These are exactly the non-obvious traits an agent needs to interpret weak or empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a one-line purpose, then behavior, then return shape, then args - a clean structure where each section has a job. The return-value paragraph is somewhat dense and partly redundant given an output schema exists, which is the only thing keeping this from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what the tool does, that it is safe and non-mutating, how matching works and where it fails, the performance profile, and every parameter's semantics. With an output schema present, the brief return summary is more than sufficient; nothing an agent needs to invoke or interpret this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and it does for all four parameters: tag (project scoping, sub-tags included 'as in recall'), kind (comma-separated, default "all", with a recommended value), threshold (0-1 scale, default 0.5, with the 0.8 near-copy interpretation), and groups (max groups, default 5). Each adds semantics the bare JSON schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Finds groups of entries that say largely the same thing') and immediately frames the scope as duplicate detection. It also separates itself from siblings by naming remember(..., supersedes="...") as the tool that actually performs merging, so an agent can tell consolidate apart from remember/recall without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use it for tidying up' sets the intent, and 'merging is a judgment call - replace a group by one new entry via remember(..., supersedes="...")' explicitly routes the follow-up action to the correct sibling with the exact parameter. It further narrows the best case ('"history" alone is the most rewarding case'), giving concrete when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hides entries that are wrong or obsolete and have no replacement.
If a newer entry replaces them, use remember(..., supersedes=...) instead. Nothing is deleted: show and recall(..., include_superseded=True) still find them, undo=True brings them back.
Returns the ids changed and names unknown ones.
Args: ids: One or more entry ids, e.g. "12,34". reason: Why - shown later next to the superseded entry. undo: True brings superseded entries back.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| undo | No | ||
| reason | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so: it discloses soft-delete semantics ('Nothing is deleted'), the observability consequence (show/recall still find them), reversibility (undo=True brings them back), and the return payload (ids changed, unknown names reported). These are exactly the mutation risks an agent must know before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the one-line purpose, then the alternative route, then the non-destructive guarantee. Every sentence earns its place; the only near-redundancy is the return-value line, which is cheap and reassuring given the destructive-sounding verb 'forget'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A mutation tool with zero annotation coverage and zero schema coverage needs the description to explain both side effects and parameter formats, and it does. An output schema already exists, so the extra return-value sentence is surplus but harmless rather than a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the Args section is doing essential work: 'ids' is documented as one-or-more values with a concrete format example ("12,34"), 'reason' is explained as text displayed next to the entry later, and 'undo' is given meaning rather than just a type. Minor looseness: 'undo' is described in terms of 'superseded entries' even for the no-replacement case, but the intent is recoverable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (hides) and resource (wrong/obsolete entries with no replacement) and draws the boundary against the supersedes path on 'remember'. An agent can distinguish this from remember, recall, and show without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing: 'If a newer entry replaces them, use remember(..., supersedes=...) instead' names the sibling and the condition that selects it. It also documents the recovery path (undo=True) and that show/recall with include_superseded=True still surface the entries, so the agent knows when this is not a hard delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches memory by words, best matches first.
Use it first, before searching files or the web for something noted before. It matches words, not meaning: inflected forms count ("configured" -> "configuring"), synonyms don't - if nothing fits, retry in the other language your notes may use. No search terms? Browse with topics.
Returns a preview per hit (id, kind, date, title line). Read the ones you need with show("376,481"), or set full=True for a narrow question.
Args: query: Search term(s), FTS5 syntax allowed (e.g. "sqlite AND fts5", "proj*"). limit: Maximum number of hits (default 8). kind: Restrict to kinds of knowledge, e.g. "pitfall,decision". Possible: interface, pitfall, decision, measurement, workflow, history, unsorted, all. Default: everything except history - otherwise the chronicle drowns out every search for a detail. tag: Restrict to a project, e.g. "spaceship". Several tags separated by comma or space are OR-combined. Sub-tags are included: "lighthouse" also matches "lighthouse-project", but "mcp-memory-server" does not match "mcp-memory". topics() lists which tags exist. full: Full text instead of preview (default: no), capped like show. include_superseded: Also show superseded entries (default: no).
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| full | No | ||
| kind | No | ||
| limit | No | ||
| query | Yes | ||
| include_superseded | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it explains word-based matching, inflection handling, lack of synonym matching, default exclusion of history, preview return shape, and superseded-entry behavior. These are material behavioral traits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and search semantics, then supplies argument details needed because schema coverage is zero. The structure is dense but each sentence contributes relevant selection or invocation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters, no annotations, and an output schema, the description covers both behavior and argument semantics thoroughly. The output schema can carry return details, but the included preview explanation further helps an agent understand what recall returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: query syntax, limit default, kind values and default exclusion, tag OR-combination and sub-tag matching, full behavior, and include_superseded are all explained. This adds substantial meaning beyond bare parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: searching memory by words, with best matches first. It distinguishes itself from file/web search and explicitly routes browsing to topics and reading hits to show, so sibling selection is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance (use first, before files or web), when to switch (no search terms → topics, read hits → show), and how to handle failed matches (retry in the other language). Alternatives are named, not implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stores one fact permanently in memory.
Use it for knowledge a later session needs: a decision with its reason, a pitfall, a measured number, an interface. Not for secrets, guesses or short-lived details. Search with recall first; if an entry covers the fact, supersede that one.
Returns the new id, existing entries that resemble it (candidates to supersede) and a note when the tag is new - often a misspelling.
Args: text: The fact. A text that belongs to two kinds is two entries. tags: The project, i.e. WHERE the knowledge belongs (spaces or commas between several). kind: WHICH KIND of knowledge: interface (signature, file name, command, data format), pitfall (the obvious approach is wrong because ...), decision (with rationale), measurement (a number plus its criterion), workflow (how to work with this user), history (chronicle, hidden from recall's default view). Empty = unsorted. supersedes: Ids this entry replaces, e.g. "12,34". Hidden, not deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | ||
| tags | No | ||
| text | Yes | ||
| supersedes | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden well: it discloses that storage is permanent, that superseded entries are 'Hidden, not deleted' rather than destroyed, and what the call returns (new id, resembling candidates, new-tag warning). It omits error behavior and how entries are ultimately removed, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then usage, return values, and args in a predictable order. The kind enumeration is dense but every clause is informative; only the parenthetical asides and line-wrapped kind definitions push slightly past necessary length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still names the three return elements the agent must act on (new id, supersede candidates, new-tag warning). Combined with full parameter coverage and retention semantics, nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate and does: it defines text (with the 'belongs to two kinds is two entries' rule), tags (project/WHERE, space or comma separated), kind (every enum value explained with concrete examples, plus what empty means), and supersedes (format '12,34'). This adds substantial meaning beyond the bare enum list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource with scope qualifiers: 'Stores one fact permanently in memory.' The 'one fact' constraint and 'permanently' distinguish it from siblings like forget, consolidate and recall without needing to open any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('knowledge a later session needs: a decision with its reason, a pitfall, a measured number, an interface'), explicit when-not ('Not for secrets, guesses or short-lived details'), and an alternative workflow ('Search with recall first; if an entry covers the fact, supersede that one').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the named entries in full text.
Use it after recall or topics, once you know which entries you need - it takes ids, not search terms. Superseded entries are included: whoever asks for the id means that one.
Returns about 6000 characters per call, in the order asked. Whatever doesn't fit comes back as a title line plus the call that fetches it; unknown ids are named as such.
Args: ids: One or more entry ids, e.g. "376,481". Most wanted first. full: Everything asked for at once, without the cap (default: no).
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| full | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to lean on, the description carries the burden well: it discloses the ~6000 character per-call cap, the truncation fallback (title line plus the call that fetches the remainder), preserved request ordering, inclusion of superseded entries, and unknown-id reporting. It never explicitly states the operation is read-only / side-effect free, which is the one behavioral fact left implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then usage, then behavioral contract, then args — a sensible order. Nearly every sentence carries information, though the parenthetical justification "whoever asks for the id means that one" and the approximate "about 6000 characters" are slightly loose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two params, zero schema coverage, no annotations, and an output schema that already covers return shape, the description supplies everything needed: workflow placement, id format, ordering, size cap, truncation recovery path, and error-like behavior for unknown ids.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it explains that ids are entry ids with a concrete format example ("376,481") and precedence ordering ("most wanted first"), and that full removes the cap with a stated default. Both parameters gain meaning beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Returns the named entries in full text") and immediately distinguishes itself from the recall/topics siblings by noting it "takes ids, not search terms." An agent can tell exactly which tool fetches by id versus which searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly positions the tool in a workflow: "Use it after recall or topics, once you know which entries you need." It names the upstream alternatives and the condition (already having ids) that selects this tool over them, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browses memory: the board of all tags, or the title index of one project.
Use it when search terms are missing - a project picked up after months, or "what happened here lately". To find a specific fact, recall is faster.
Returns the tag board (entries per tag and kind) or, with a tag, that project's title lines, newest first, one page at a time. Follow up with show("...") or recall(query, tag="...").
Args: tag: Project, e.g. "spaceship". Empty = tag board. limit: Rows per page (default 40 for the board, 30 for the title index). page: Page of the title index (default 1 = the newest). all: Whole title index at once, grouped by kind.
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | ||
| tag | No | ||
| page | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, and it does disclose the return shape (tag board with entries per tag and kind, or title lines), ordering (newest first), and paging behavior (one page at a time). It never explicitly states it is a read-only, side-effect-free operation, though "browses" strongly implies it; that is the only real gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and primary alternative are front-loaded in the first two sentences, then return behavior, then per-argument notes. No sentence is redundant; the quoted triggers ("what happened here lately") buy concrete recall cues cheaply.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need only be sketched, and the description does more than that plus documents every parameter at 0% schema coverage. The remaining gap is the all-vs-page/limit interaction and no explicit statement of read-only safety, which matters given zero annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it defines all four parameters including non-obvious semantics: limit has different defaults (40 board / 30 index) rather than the schema's 0, page 1 means newest, and empty tag means the board. It does not say whether all=true overrides page/limit, leaving one interaction ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Browses memory: the board of all tags, or the title index of one project" names a specific verb and two concrete resources/results. It explicitly contrasts itself with recall ("To find a specific fact, recall is faster"), so an agent can distinguish it from siblings without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the triggering condition precisely ("when search terms are missing - a project picked up after months") and names the alternative for the opposite case (recall for a specific fact). It also prescribes follow-up tool calls (show("...") or recall(query, tag="...")), which is explicit when/when-not/next-step guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0checkclassifyconsolidateeinordnenforgetprueferecall8 fields changedInput schema / properties / artRemoved value: -{
- "default": "",
- "type": "string"
-}Input schema / properties / fullAdded value: +{
+ "default": false,
+ "type": "boolean"
+}Input schema / properties / include_supersededAdded value: +{
+ "default": false,
+ "type": "boolean"
+}Input schema / properties / kindAdded value: +{
+ "default": "",
+ "type": "string"
+}Input schema / properties / markeRemoved value: -{
- "default": "",
- "type": "string"
-}Input schema / properties / mit_veraltetRemoved value: -{
- "default": false,
- "type": "boolean"
-}Input schema / properties / tagAdded value: +{
+ "default": "",
+ "type": "string"
+}Input schema / properties / vollRemoved value: -{
- "default": false,
- "type": "boolean"
-}remember4 fields changedInput schema / properties / artRemoved value: -{
- "default": "",
- "type": "string"
-}Input schema / properties / ersetztRemoved value: -{
- "default": "",
- "type": "string"
-}Input schema / properties / kindAdded value: +{
+ "default": "",
+ "enum": [
+ "interface",
+ "pitfall",
+ "decision",
+ "measurement",
+ "workflow",
+ "history"
+ ],
+ "type": "string"
+}Input schema / properties / supersedesAdded value: +{
+ "default": "",
+ "type": "string"
+}showthementopicsverdichtenvergessenzeigev0.2.3vergessen1 field changedInput schema / properties / rueckgaengigAdded value: +{
+ "default": false,
+ "type": "boolean"
+}v0.1.0einordnenprueferecallrememberthemenverdichtenvergessenzeigeScored across 8 tools
Each tool has a distinct role: remember writes, recall searches by words, show fetches by id, topics browses when no terms exist, classify/forget mutate metadata, and consolidate/check form a two-step duplicate-analysis workflow. The only mild adjacency is recall vs topics vs show, but the descriptions explicitly state when to use which.
Seven of eight names are single lowercase verbs (remember, recall, show, classify, forget, consolidate, check), giving a predictable pattern. 'topics' is a noun, a minor deviation, though its browsing purpose makes the name natural.
Eight tools is well within the sweet spot and each maps to a real operation (write, search, fetch, browse, classify, supersede, dedupe, judge). No tool feels redundant or like padding.
The lifecycle is well covered: create (remember), read (recall/show/topics), update-kind (classify), retire (forget/supersede), and maintenance (consolidate/check). The only gap is no direct text-editing operation — replacement is done via remember(supersedes=...), which is a workaround rather than a dead end.
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent memory for AI agents. Search, store, and recall across sessions.
Persistent memory for AI assistants: store, search, and connect knowledge across conversations.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
