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: for the usual one markdown file
per fact, found with and read whole. That baseline is the naive case
on purpose: it is what happens when the file is opened with , which
loads it whole. The careful path, 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
().
Both compare against markdown notes, not against other memory servers.
The gap grows as the memory does, because every answer here is capped and
is not. All figures come from one installation, and the docs say
where one did not hold up.
Memory for AI assistants in one SQLite file: full-text search, no vectors, no embeddings.
API-Schlüssel
MEMORY_LANG, MEMORY_DB
Zuletzt geprüft
2026-11-16
Sterne
—
Tools
—
Uptime
—
2,359 tokens
per answered question, against 11,319
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.
Features
Capped, calculable answers — a search returns eight preview lines
of about 1.2 KB in total instead of 4.2 KB of full text; zeige 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 — themen() 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 marke=. 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.
German by default, English on request — tool names, messages and
kinds are German; MEMORY_LANG=en switches all of it. The search also
matches inflected forms and compound parts ("Rangliste" finds
"Ranglisten"). Measured, that rarely changes the answer: the plain
any-term stage of the search already finds what the stems would add
(details).
Requirements
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
Setup
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-memory
With uv it also works without installing
first; uvx fetches the package on the first start:
claude mcp add memory -s user -- uvx frugal-memory
The 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.py
Here 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:
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.
Teaching the agent how to use it
The tools alone don't tell an agent the working rules: search before
reading files, recall → zeige, 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 (German, or English with MEMORY_LANG=en),
which Claude Code adds to every session that has the server. Guest mode
(--gast) 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 clone
Claude 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.
Reading another machine's memory
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 --gast
--gast (guest) means three things:
Read-only. The file is opened with mode=ro, and only recall,
zeige and themen are offered. The writing tools are gone, and so are
verdichten and pruefe: 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.zeige("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.
-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.
Two Opt-in Extensions
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=en 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.
Literature archive (--archiv)
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 --archiv
Same eight tools, other kinds: befund (finding), methode (method),
ueberblick (survey), werkzeug (code, dataset), luecke (searched,
nowhere measured), spur (unchecked lead) and verworfen (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 archiv#12 (archive#12 in English 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 --gast, so all of them can write).
Lab notebook (--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 --messbuch
reihen() / series() 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 reihen(kennung="vision/lr-*", tabelle=True).
reihe_anlegen / new_seriesbefore 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 beobachtung (observation).
rezept / recipe records the command, code version, seed and
machine; messwerte / measurements one value per row;
ergebnis / 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 (nachtrag=, begonnen= 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.
The Eight Tools
remember(text, tags, art, ersetzt)
store an entry; reports similar existing ones and what it would supersede
recall(query, limit, art, marke, …)
ranked full-text search, preview by default; under marke= it names a better match outside the project
zeige(ids, voll)
full text of specific entries, about 6000 characters per call; what doesn't fit is listed with the call that fetches it
themen(marke, limit, seite, alle)
browse: which projects exist, or one project's title lines, newest first, a page at a time
vergessen(ids, grund, rueckgaengig)
mark as outdated — never deletes; rueckgaengig=True brings entries back
einordnen(ids, art)
assign the knowledge kind of existing entries
verdichten(marke, art, …)
find groups of entries that say much the same thing
pruefe(ids)
opt-in: have a language model judge contradiction vs. newer state
Full reference with parameters and behavior: docs/TOOLS.md.
With MEMORY_LANG=en the same tools come with English names and parameters,
see A Note on Language.
Some Numbers
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 themen and zeige. On 110 project questions the
cap cost not one answer.
the eight underlying measurement reports (mostly German)
A Note on Language
German is the default: tool names, status messages and the kind vocabulary
(schnittstelle, fallstrick, entscheidung, messwert, arbeitsweise,
verlauf, gemischt) are German, and the search stems German and splits
German compounds.
English mode: start the server with MEMORY_LANG=en. Then
the tools are remember(text, tags, kind, supersedes),
recall(query, limit, kind, tag, full, include_superseded), show(ids, full),
topics(tag, limit, page, all), forget(ids, reason, undo), classify(ids, kind),
consolidate(tag, kind, threshold, groups) and check(ids),
the kinds are interface, pitfall, decision, measurement,
workflow, history, unsorted,
every message is English,
the search uses a small English suffix stemmer ("configured" finds
"configuring") instead of the German one, and does not split compounds.
The database itself does not change: kinds are always stored under their
German names and translated at the border, and German kind names are
accepted in both modes. What does change is the stem index, so the file
records the language it was built in 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 (from a checkout:
MEMORY_LANG=en python3 nachziehen.py).
The two extensions follow the same switch: in English mode the archive's
kinds are finding, method, survey, resource, gap, lead and
rejected, and the notebook's tools are series, new_series,
edit_series, recipe, measurements and result, with English
statuses and verdicts. Their files store the German names, as the memory does.
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 is new and has
not been measured on real questions the way the German search has.
stemmer and compound splitter (German; small English stemmer for MEMORY_LANG=en)
werkzeuge_en.py
the English tool surface for MEMORY_LANG=en
messbuch.py
the lab notebook (--messbuch)
messbuch_en.py
its English tools and messages
texte_en.py
English messages, keyed by the German text
nachziehen.py
recomputes the derived columns, the word and tag directories and the chain marks (frugal-memory-nachziehen after pip install)
faktencheck.py
opt-in second opinion via any OpenAI-compatible model (off unless configured)
pruefstand_fc.py
measures the fact check against gold labels from the dataset
pruefpaare_gebaut.json
the hand-built and hand-found contradiction pairs
import_memos.py
import a folder of markdown notes (frugal-memory-import after pip install; see docs/IMPORT.md)
test_memory.py
regression net, one case per pitfall (no pytest)
test_archiv.py, test_messbuch.py
the tests of the two extensions
skills/frugal-memory/SKILL.md
working rules for the agent, as a Claude Code skill (in the package too)
skill_installieren.py
copies the skill to ~/.claude/skills/ (frugal-memory-skill after pip install)
requirements.txt
just mcp>=2.2.0
pyproject.toml
package definition for PyPI (frugal-memory)
server.json
entry in the official MCP registry
memory.db
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.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich Frugal Memory?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt Frugal Memory einen API-Schlüssel?
Der Herausgeber nennt diese Umgebungsvariablen: MEMORY_LANG, MEMORY_DB.
Welchen Transport verwendet Frugal Memory?
Frugal Memory läuft lokal über stdio.
Wann wurde Frugal Memory zuletzt geprüft?
Zuletzt geprüft: 2026-11-16. Memory for AI assistants in one SQLite file: full-text search, no vectors, no embeddings.