frugal-memory

frugal-memory

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.

Why

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; 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).

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 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:

{

"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.

Teaching the agent how to use it

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 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 --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.

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 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 (--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 --archive

• Same 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).

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 memor