frugal-memory

frugal-memory

AI アシスタントのための永続メモリです。SQLite ファイルだけで動作し、Markdown のメモを読む場合と比べて、コストは約 5 分の 1 です。

ベクトルストアも、埋め込みも、外部サービスも、API キーも不要です。Python、FTS5 を備えた SQLite、stdio を使用し、依存関係は公式の mcp SDK だけです。オプションのファクトチェックを明示的に有効にしない限り、データがマシンの外に出ることはありません。

89 回の作業セッションで実際に寄せられた 275 件の質問で計測した結果、回答済みの質問 1 件あたりのトークン数は 2,359 トークンでした。事実ごとに Markdown ファイルを 1 つ作り、grep で見つけてファイル全体を読む通常の方法では 11,319 トークンです。このベースラインは、あえて単純なケースにしています。ファイルを Read で開くと、全体が読み込まれるためです。コンテキストを前後 3 行付ける慎重な方法である grep -C は、安くなるどころか、より高コストでした。現実的な検索順序では中央値の文字数が 28 倍（実行後に追加した方法で、事前に固定したルールでは 65 倍）になりました。1,756 個のファイルを広く検索すると、該当する行が何百件も返ってくるためです （詳細）。どちらも Markdown のメモとの比較であり、ほかのメモリサーバーとの比較ではありません。ここでは回答のサイズに上限がありますが、grep にはないため、メモリが増えるほど差は広がります。すべての数値は 1 つの環境で得られたものであり、ドキュメントでは、うまくいかなかったケースも説明しています。

理由

アシスタントのメモリは通常、2 つの問題のどちらかを抱えています。検索するにはファイル全体を読む必要がある Markdown ファイルの山か、何かが一致したことは答えても、なぜ一致したのかは決して答えないベクトルデータベースです。

これは、短いエントリを対象とするランキング付き全文検索インデックスです。単なるメモの山をメモリに変える 2 つの機能を追加しています。エントリは、どこに属するか（プロジェクト）と、どのような種類の知識か（落とし穴、決定、測定値など）という 2 つの軸で分類されます。また、何かを書き込むと、既存のどのエントリと重複しているかをツールが知らせるため、矛盾がひそかに積み重なるのではなく、表面化します。

機能

• 上限があり、回答量を見積もれます — 検索では、全文の 4.2 KB ではなく、合計約 1.2 KB のプレビュー行を 8 行返します。その後、zeige で選んだ項目を取得します。すべてを指定しない限り、1 回の呼び出しにつき約 6,000 文字です。質問する前に最悪の場合の量がわかります。
• 自身の失敗から学習します — 検索の後に項目を取得すると、その組み合わせを記憶します。同じことをもう一度尋ねると、前回回答に使われた項目が最初に表示されます。完全に同じ文言の繰り返しだけが対象で、該当した場合はヘッダーに表示されます。
• 2 つの分類軸 — 自由記述のプロジェクトタグと、種類が限定され、適用が強制されるナレッジ種別です。クロニクル項目は既定では検索対象から除外されますが、ヘッダーには除外された件数が常に表示されます。
• 重複と矛盾のヒント — remember は類似する既存項目と、変更された番号を報告するため、蓄積するのではなく、既存項目を置き換えられます。
• 削除されることはありません — 置き換えられた項目は既定の表示から外れますが、理由と置き換えた項目が記された状態で検索できます。間違いだった場合は、スイッチ 1 つで再表示できます。
• 検索だけでなく、閲覧もできます — themen() はプロジェクトと、各プロジェクトの最新のタイトル行を一覧表示します。検索する言葉を忘れたときに便利です。他の機能と同様に上限があり、1 ページ分を表示し、残りの取得方法も示します。
• 利用時はプロジェクトに限定し、検索時は限定しません — 通常は marke= を指定して、1 つのプロジェクト内で質問します。このフィルターは厳密に適用されるため、最適な一致項目がプロジェクト外にある場合、recall は該当項目を明示します。別の項目のもっともらしい一覧だけを返すことはありません。
• 同じエンジン上で利用できる、オプトイン方式の拡張機能が 2 つあります — すべてのプロジェクトで共有する文献アーカイブと、測定系列用の実験ノートです。それぞれ独自のファイルとサーバーエントリーを持ちます。追加しなくても何も変わりません（以下を参照）。
• オプトイン方式のセカンドオピニオン — 必要に応じて、OpenAI 互換モデルに 2 つの項目が矛盾しているのか、単に一方が他方に置き換わったのかを確認できます。
• 既定はドイツ語、リクエストに応じて英語 — ツール名、メッセージ、種別はドイツ語です。MEMORY_LANG=en ですべて英語に切り替わります。検索では活用形や複合語の一部にも一致します（「Rangliste」で「Ranglisten」が見つかります）。実測では、回答が変わることはほとんどありません。検索の単純な「いずれかの語」段階ですでに、語幹によって追加される結果が見つかるためです（詳細）。

要件

• Python 3.11 以降
• mcp SDK（requirements.txt に記載されているもののみ）
• FTS5 対応の SQLite — 標準的な CPython ビルドに含まれています
• Python 3.11 および 3.14 を使用し、Linux、macOS、Windows でテスト済みです。プッシュのたびに、全テストスイートとインストール済みパッケージをテストしています。これまでの日常的な使用環境は Linux のみです。macOS と Windows からの報告も issue として歓迎します。
• オプション（ファクトチェックのみ）：OpenAI 互換の任意のエンドポイント

セットアップ

PyPI から、専用の環境にコマンドとしてインストールします。

pipx install frugal-memory        # or: uv tool install frugal-memory

claude mcp add memory -s user -- frugal-memory

uv を使えば、事前にインストールしなくても動作します。uvx は初回起動時にパッケージを取得します。

claude mcp add memory -s user -- uvx frugal-memory

データベースは初回使用時に ~/.local/share/frugal-memory/memory.db に作成されます（$XDG_DATA_HOME が設定されている場合はその場所）。frugal-memory-nachziehen は、DESIGN.md で説明されているメンテナンススクリプトです。Markdown メモのフォルダーから移行する場合は、frugal-memory-import <folder> を使うと、段落ごとに取り込めます（IMPORT.md）。frugal-memory-skill は Claude Code 用の作業ルールをインストールします（後述）。uvx を使う場合は、いずれも uvx --from frugal-memory frugal-memory-import … のように実行します。

または、このリポジトリのチェックアウトから実行します。

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

この場合、データベースはスクリプトと同じ場所に memory.db として作成されます。どちらの場合も、MEMORY_DB=/some/path.db を指定すると、別の場所に保存できます。

-s user を指定すると、すべてのプロジェクトでサーバーを利用できるようになり、設定は ~/.claude.json に追加されます。その後、Claude Code を再起動してください。MCP サーバーは起動時にのみ読み込まれます。ツールは mcp__memory__recall および mcp__memory__remember という名前で呼び出せるようになります。

Claude Desktop の場合は、代わりに ~/.config/Claude/claude_desktop_config.json を使用します。

{
  "mcpServers": {
    "memory": {
      "command": "/path/to/frugal-memory/.venv/bin/python",
      "args": ["/path/to/frugal-memory/memory_server.py"]
    }
  }
}

どの設定よりも重要なルールが一つあります。1 回の呼び出しにつき 1 つの事実を保存し、文書全体を保存しないでください。 recall はエントリー全体を返します。180 KB のファイルを 1 つのエントリーとして保存すると、1 件の検索結果としてそのまま返されるだけで、何も得られません。

エージェントに使い方を教える

ツールだけでは、ファイルを読む前に検索する、recall → zeige の順に使う、各エントリーの種類を 1 つだけにする、蓄積するのではなく古い内容を置き換える、もう一方の言語でもう一度試す、といった作業ルールはエージェントに伝わりません。このルールを伝える仕組みは 2 つあります。

• 短い説明はサーバーに組み込まれています。 接続時に約 600 文字の指示が送られます（ドイツ語、または MEMORY_LANG=en の場合は英語）。Claude Code は、サーバーを利用するすべてのセッションにこの指示を追加します。ゲストモード（--gast）では、何も保存できないため、指示は送られません。
• 完全なルールはスキルとして提供されます。 リポジトリと PyPI パッケージに含まれており、次のコマンドでインストールできます。

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 はメモリが使われるときにのみ、スキルの全文を読み込みます。それまでは、1 行の説明だけがコンテキストに含まれます。既存の SKILL.md の内容が異なる場合、--force を指定しない限り、そのファイルは変更されません。

3 つ目の仕組みは任意で、CLAUDE.md に数行を追加できます。これは、どちらの仕組みでも伝えられないこと、主に知識の保存先は Claude Code 独自のメモリファイルではなくサーバーであることを伝えるためのものです。コピーして使える任意のブロックが docs/CLAUDE-MD.md にあります。

別のマシンのメモリを読む

各マシンは独自のメモリを保持し、エントリーにはそれぞれ 1 から番号が付けられます。マシン A のセッションから SSH 経由でマシン B のメモリを読むことができます。サーバーは B 上で、そのファイルの隣で動作します。データベース自体がネットワークを越えることはありません。

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（ゲスト）は、次の 3 つのことを意味します。

• 読み取り専用です。 ファイルは mode=ro で開かれ、利用できるのは recall、zeige、themen のみです。書き込みツールはなく、verdichten と pruefe も利用できません。メンテナンスは、実行権限のある所有者が行います。ゲストの検索は所有者の検索フィードバックにも反映されず、ゲストがスキーマを移行することもありません。
• すべての ID にメモリ名が付きます。 #72 ではなく b#72 です。名前はホスト名を小文字にしたもので、MEMORY_NAME で上書きできます。
• どちらのモードでも、名前付き ID は検証されます。 b 以外のメモリに対して zeige("b#72") を要求した場合、そのメモリ自身の #72 をひそかに返すのではなく、拒否されます。名前のない ID（72、#72）は、要求先のメモリを指します。

-s project を指定すると、不要なセッションに 3 つの追加ツール定義が含まれないようにできます。ツールは mcp__memory-b__recall などの名前で呼び出せるようになります。

2つのオプトイン拡張機能

同じサーバーを、さらに2つのモードで起動できます。それぞれ専用のファイル、ツール、Claude Code でのエントリーがあり、メモリ自体は開きません。どちらも、メモリと同じく MEMORY_LANG=en に従います。複数のプロジェクトを同時に進める日々の利用から生まれたもので、メモリのような測定はまだ行っていません。数値で効果が示されたからではなく、作業が目に見えて楽になったため、提供しています。

文献アーカイブ（--archiv）

すべてのプロジェクトで共有する論文、データセット、先行研究です。メモリにはあなたが見つけたことを保存し、アーカイブには他の人が発表したことを保存します。その価値は、別のプロジェクトですでに行われた発見を見つけられる点にあります。

claude mcp add archive -s user -- uvx frugal-memory --archiv

• 同じ8つのツールを、異なる種類のデータに使います。befund（知見）、methode（手法）、ueberblick（サーベイ）、werkzeug（コード、データセット）、luecke（調査済みだが、どこにも測定結果がないもの）、spur（未確認の手がかり）、verworfen（確認して却下したもの。例：言語モデルが捏造した引用）です。spur と verworfen のエントリーは、メモリの記録と同じく、検索結果には表示されません。
• 同じソースは、文言ではなくIDで識別します。 remember が、アーカイブにすでにある arXiv 番号、DOI、リンクを検出すると、そのことを知らせます。2つのプロジェクトが同じ論文を同じ言葉で説明することは、ほとんどないためです。ソースやエビデンスレベル（全文、要約、未確認）が未入力の場合は、入力を求めます。
• すべてのIDには archiv#12（英語モードでは archive#12）という名前が付くため、メモリIDと取り違えることはありません。
• ファイル：メモリと同じ場所にある archive.db、または ARCHIVE_DB。ファイルを置いたマシンで SSH 経由で起動すれば、複数のマシンから1つのアーカイブを共有できます（--gast は付けず、すべてのマシンから書き込めるようにします）。

実験ノート（--messbuch）

ばらばらのエントリーではなく、構造化された測定系列です。質問、基準、手順、数値、判定、何が何に取って代わるのかを記録します。測定系列をメモリのエントリー十数件に分散させると、大切なことがまさに失われます。評価せずにまだ進行中なのはどれか、そして基準が結果より前に定められていたかどうか、といったことです。

claude mcp add messbuch -s user -- uvx frugal-memory --messbuch

• reihen() / series() は、確認が必要な点とともに、進行中の系列を一覧表示します。 N 日間エントリーがありません — プロセスはまだ実行中ですか？、測定値はあるが結果がありません、基準がありません。1つのトピックに関する全系列を横断する表は、reihen(kennung="vision/lr-*", tabelle=True) で表示できます。
• 最初の実行前に reihe_anlegen / new_series を実行します。基準にはタイムスタンプが記録され、最初の測定後は理由を添えなければ変更できず、変更の履歴も残ります。基準がない場合に可能な判定は beobachtung（観察）のみです。
• rezept / recipe にはコマンド、コードのバージョン、シード、マシンを記録し、messwerte / measurements には1行につき1つの値を記録します。ergebnis / result には基準に照らした判定と、そこから導かれることを記録します。何も削除せず、誤った値は新しい値で置き換えます。
• 最初の系列を始める前に有効にしてください。 過去の系列を後から入力することもできます（nachtrag=、begonnen= に実際の日付を指定します）が、散在するメモから情報を集めるには、発生した時点で記録するよりはるかに多くのトークンが必要です。
• ファイル：messbuch.db、または MESSBUCH_DB。ノートブックに記録するメモリIDには、メモリの名前を付ける必要があります（laptop#452）。ノートブックは、メモリのIDがそれぞれ1から始まる複数のマシンで共有されることがあるためです。

8つのツール

remember(text, tags, art, ersetzt)	エントリーを保存します。類似する既存のエントリーと、置き換える場合の内容を報告します
recall(query, limit, art, marke, …)	ランク付けされた全文検索を行います。デフォルトではプレビューを表示し、marke=を指定すると、プロジェクト外にあるより適切な一致候補を示します
zeige(ids, voll)	指定したエントリーの全文を表示します。1回の呼び出しで約6000文字まで表示し、収まらない内容は、それを取得する呼び出しとともに一覧表示します
themen(marke, limit, seite, alle)	プロジェクトの一覧、または1つのプロジェクトのタイトル行を新しい順にページ単位で閲覧します
vergessen(ids, grund, rueckgaengig)	古くなったものとしてマークします。削除はしません。rueckgaengig=Trueでエントリーを復元します
einordnen(ids, art)	既存のエントリーにナレッジの種類を割り当てます
verdichten(marke, art, …)	ほぼ同じ内容を述べているエントリーのグループを探します
pruefe(ids)	オプトイン：言語モデルに、矛盾しているか、より新しい状態かを判定させます

パラメーターと動作の詳細なリファレンス：docs/TOOLS.md。 MEMORY_LANG=enを指定すると、同じツールを英語の名前とパラメーターで利用できます。 言語についてを参照してください。

数字で見る実績

実際の1つのデータセットで計測しました。データセットはその間に約900件から約1,900件へと増加しています。これは1つのインストール環境での結果であり、ベンチマークではありません。

• Markdownファイルを読むより4.8倍低コストです。実際のトークン数で、実際の質問275件を計測しました（質問1件あたり2,359対11,319）。データセットとファイルが大きくなるほど差は広がります。ファイルを読む場合、全部を読むか、何も読まないかのどちらかだからです。188 KBのプロジェクトファイルを対象にした質問1件では、94,152トークンかかります。
• 公開されているLoCoMoデータセットに対して、セッションを単位とした Recall@10は89.8％ です。チューニングはしていません（2026-10-19。9月の初回計測では、対話ターン1件を単位とした場合、82.3％、45.1％でした）。
• プレビューにより、返される内容を 73％削減できます。計算可能な最悪ケースもあります。
• フィードバックループにより、質問あたりの予想文字数を 23％削減しました。1回目のヒット率は73％から84％に向上しました。これは、実際の30セッションからの質問164件を、時間順に再生して計測したものです。ペアが役立つのは、あくまで後の質問に対してであり、自分自身に対しては役立ちません。19件の質問で改善し、悪化した質問はありませんでした。
• 1行のランキング修正により、実際の言い換えの連鎖47件で、ヒット率が 53％から64％へ向上しました。推測ではなく、実際の検索セッションが失敗した箇所を計測して見つけた修正です。現在のデータセットでは、同じ修正によって、すでに成功していた117件の質問のうち3件で失敗するようになりました。そのため、164件全体での純増は2件です。
• データセットの93％はプロジェクトに属しています（1,907件中1,777件）。ツールもそのように使われています。検索自体はプロジェクト知識と一般知識を区別しません。どちらも同程度に見つかります（92％対96％。10％ルールでは同等です）。プロジェクトフィルターの利点は、短い質問に対する精度です。約3語の質問で、85％に対して97％が見つかりました。一方で、プロジェクト外のすべてを見落とすという代償があります。22個のプロジェクトタグを付けて尋ねた一般知識に関する質問40件では、880件中 0件 しか見つかりませんでした。現在、recallはこのようなケースの82％で、タグの外にあるより適切な一致候補を示します。そのうち70％では、その行に示されたエントリーがすでに探しているものです。実際のプロジェクトに関する質問では、この機能が働く割合は7～16％です。
• themenとzeigeに上限を設定したことで、プロジェクトのタイトルインデックスは83％、全文を8件取得する場合は34％削減されました。プロジェクトに関する質問110件では、この上限によって回答が失われることはありませんでした。

より大きなサンプルでは再現しなかった計測結果については、その旨を記載しています：docs/MEASUREMENTS.md。元のレポートはmessung/にあります。上記のランキングの数値は2度修正されています。 ランキング修正、2度の訂正を参照してください。

ドキュメント

docs/TOOLS.md	8 つのツールの詳細
docs/DESIGN.md	2 つの軸、形態、データベーススキーマ、および意図的に省いたもの
docs/MEASUREMENTS.md	測定内容と既知の制約
docs/FACTCHECK.md	オプトインのファクトチェック：セットアップ、できることとできないこと
docs/IMPORT.md	既存のメモフォルダーのインポートと、それによって生じた問題
docs/CLAUDE-MD.md	CLAUDE.md にコピーできる任意のブロック
messung/	基盤となる 8 件の測定レポート（ほとんどがドイツ語）

言語について

デフォルトはドイツ語です。ツール名、ステータスメッセージ、種類の語彙 （schnittstelle、fallstrick、entscheidung、messwert、arbeitsweise、 verlauf、gemischt）はドイツ語で、検索ではドイツ語の語幹処理を行い、 ドイツ語の複合語を分割します。

英語モード： MEMORY_LANG=en を指定してサーバーを起動してください。すると、

• ツールは 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)、check(ids) になります。
• 種類は interface、pitfall、decision、measurement、 workflow、history、unsorted です。
• すべてのメッセージが英語になります。
• 検索ではドイツ語の語幹処理の代わりに、簡易的な英語の接尾辞語幹処理 （「configured」で「configuring」が見つかります）を使い、複合語は分割しません。

データベース自体は変わりません。種類は常にドイツ語名で保存され、境界部分で翻訳されます。また、どちらのモードでもドイツ語の種類名を受け付けます。変わるのは語幹インデックスです。そのため、ファイルには作成時の言語が記録され、サーバーは別の言語でのオープンを拒否します。既存のメモリを切り替えるには、バックアップを取ってから MEMORY_LANG=en frugal-memory-nachziehen を一度実行してください（チェックアウトからの場合は MEMORY_LANG=en python3 nachziehen.py）。

2 つの拡張機能も同じ切り替えに従います。英語モードでは、アーカイブの種類は finding、method、survey、resource、gap、lead、rejected となり、ノートブックのツールは英語のステータスと判定を使う series、new_series、edit_series、recipe、measurements、result となります。メモリと同様に、ファイルにはドイツ語名が保存されます。

この切り替えの対象外：ファクトチェックのプロンプトはドイツ語のままです（語句を一字一句調整しており、一文加えただけで精度が半減したことがあります。判定のみ英語で表示されます）。インポートスクリプトと測定レポートもドイツ語のままです。英語の語幹処理は新しく、ドイツ語検索のように実際の質問を使った測定はまだ行われていません。

ファイル

memory_server.py	MCP サーバー、8 つのツール、検索カスケード、スキーマ、マイグレーション
morphologie.py	ステマーと複合語の分割処理（ドイツ語。MEMORY_LANG=en 用の小規模な英語ステマーも含みます）
werkzeuge_en.py	MEMORY_LANG=en 用の英語ツール群
messbuch.py	ラボノート（--messbuch）
messbuch_en.py	ラボノートの英語ツールとメッセージ
texte_en.py	ドイツ語のテキストをキーとする英語メッセージ
nachziehen.py	派生列、単語・タグのディレクトリ、チェーンマークを再計算します（pip install 後は frugal-memory-nachziehen）
faktencheck.py	任意で利用できる、OpenAI 互換モデルによるセカンドオピニオン（設定しない限り無効）
pruefstand_fc.py	データセットの正解ラベルを使ってファクトチェックの精度を測定します
pruefpaare_gebaut.json	手作業で作成・発見した矛盾ペア
import_memos.py	Markdown メモのフォルダーをインポートします（pip install 後は frugal-memory-import。docs/IMPORT.md を参照）
test_memory.py	回帰テスト一式。各落とし穴につき 1 件を用意しています（pytest は使用しません）
test_archiv.py、test_messbuch.py	2 つの拡張機能のテスト
skills/frugal-memory/SKILL.md	Claude Code スキルとしてのエージェントの作業ルール（パッケージにも含まれます）
skill_installieren.py	スキルを ~/.claude/skills/ にコピーします（pip install 後は frugal-memory-skill）
requirements.txt	mcp>=2.2.0 のみ
pyproject.toml	PyPI 用パッケージ定義（frugal-memory）
server.json	公式 MCP レジストリのエントリー
memory.db	データベース。初回使用時に作成され、コミットされることはありません

messung/ には、8 件の測定レポートが格納されています。レポートを生成したスクリプトとその生データは含まれていません。これらは作者自身のデータセットでしか実行できず、生データには実際の作業セッションの逐語的な記録が含まれているためです。

ライセンス

MIT — LICENSE を参照してください。