Engram について
Engramは、開発者や研究者、ノートを扱う人向けのローカル長期記憶MCPサーバーです。LLMやAPIキーを使わず原文を保存・検索し、意味・全文・時間を組み合わせた検索と記憶の変更履歴に対応します。
主な機能
- 01ノートや会話の原文をローカル保存
- 02意味・全文・時間による検索
- 03履歴を残した記憶の修正
- 04Claude Codeの自動想起と保存
- 05記憶管理用の31ツール
- 06任意のシークレット情報マスキング
活用シーン
- 01会話をまたいでプロジェクトの決定と理由を検索
- 02ノート、文書、コードを横断検索
- 03個人エージェントにローカル記憶を追加
- 04古い記録を更新し、過去の根拠を追跡
MCP 対応
EngramはMCP対応アプリに接続し、記憶の想起、検索、保存、修正を行う31のツールを提供します。同じツールはローカルWeb APIからも利用できます。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
Engram
チャットが終わると、AI はすべてを忘れてしまいます。Engram が記憶を助けます。 無料でプライベート。お使いのコンピューター上で動作し、書いた言葉をすべてそのまま保持します。
課題
月曜日、Claude と1時間かけてログインシステムのメモリリークの原因を調べ、ライブラリを切り替えることにしました。金曜日に新しいチャットを開いて、*「なぜ Passport をやめたんだっけ?」*と尋ねます。
何も分かりません。会話は消え、そこに至った理由も失われています。
AI に伝えたことは、どんなことでも同じです。妹の誕生日、すでに修正したバグ、設定がその値になっている理由。チャットを新しくするたびに、すべてがゼロから始まります。
**Engram はチャットが終わっても残る記憶です。**メモ、ファイル、会話を保存し、後から質問すると、表現がまったく違っていても、適切なものを見つけます。
動作を確認する
普通のメモを2つ入力します:
notes/decisions.md We switched from Passport to Lucia on March 3 because
Passport sessions kept leaking memory under load.
notes/personal.md My sister Maya's birthday is June 14. She loves anything
with sunflowers.
engram mine notes --wing life
数日後、自分の言葉で尋ねてみます。以下の質問は、どれもメモと同じ文を含みません:
$ engram search "why did we change the auth library"
1 life/notes We switched from Passport to Lucia on March 3 because
Passport sessions kept leaking memory under load.
$ engram search "gift idea for Maya"
1 life/notes My sister Maya's birthday is June 14. She loves anything
with sunflowers.
Claude に接続すれば、これを自動で行います。Claude は必要なときに Engram で情報を調べ、Engram は Claude Code のセッションを自動で保存します。
2分で試す
Python 3.9 以降が必要です(3.11〜3.14 を推奨します)。python3 --version で確認してください。
1. インストールする
pip install engram-chateau
PyPI でのパッケージ名は
engram-chateauですが、入力するコマンドはengramだけです。(無関係な別のパッケージが、すでにengramという名前を使用しています。)
2. 記憶させる情報を入力する
engram mine ~/Documents/notes --wing notes # any folder of notes, docs or code
初回実行時に、Engram が意味を理解するための小さな言語モデル(約80 MB)がダウンロードされます。その後はすべてオフラインで動作します。
3. 質問する
engram search "what did I decide about the database"
試すのに必要なのはこれだけです。
AI アプリに接続する
Engram は、AI アプリがツールを接続する標準的な方法である MCP に対応した、あらゆるアプリで動作します。コマンド1つで追加できます:
engram connect cursor # or: claude-desktop, windsurf, vscode, gemini, codex, zed, lm-studio
engram connect all # every supported app on this computer
engram connect # list them, with ✓ next to the ones you have
そのアプリの設定に Engram を追加します(ほかの設定は保持され、.bak バックアップも作成されます)。また、アプリの再起動方法も表示します。いつでも再実行できます。2回目以降は設定を変更しません。
| アプリ | 書き込まれる設定 |
|---|---|
| Claude Desktop | claude_desktop_config.json |
| Cursor | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| VS Code(Copilot エージェントモード) | ユーザーの mcp.json |
| Gemini CLI | ~/.gemini/settings.json |
| Codex CLI | ~/.codex/config.toml |
| Zed、LM Studio | 貼り付け用の設定を表示 |
各アプリで、31個の engram_* ツールを利用できます。思い出す、検索する、記憶する、古くなった記憶を訂正する、結論を根拠に結び付ける、記憶にその内容が記されている理由を説明する、トピックの履歴を確認する、人や事実のナレッジグラフを参照するなど、さまざまな操作が可能です。接続時に Engram は、それらの使い方も AI に伝えます。過去の作業に基づく回答の前に記憶を確認すること、決定事項を保存すること、矛盾させるのではなく訂正することを案内します。(そのガイダンスをモデルに渡すかどうかはアプリによって異なりますが、現在はほとんどのアプリが渡します。)「このリポジトリではタブを使うことを覚えておいて」、「認証について何を決めたんだっけ?」、*「PostgreSQL に移行したので、更新して」*のように尋ねてみてください。
Claude Code では、最も多くの機能を利用できます。頼まなくても機能する記憶です。
engram connect claude-code # prints the one-line `claude mcp add` command
engram install-hooks --apply # then restart Claude Code
install-hooks は、Claude Code の3つのフックを ~/.claude/settings.json に追加します(既存の設定は保持され、バックアップも作成されます):
- 自動想起。 Claude にメッセージを送るたびに、Engram がまずメモリを検索します。明らかに関連する内容が見つかった場合、Claude は回答する前に最大 3 件のメモを含む短いノートを受け取ります。現在のバージョンが最初に示され、以前のバージョンから何が置き換わったか、その理由も記載され、古い情報には古い情報であることが表示されます。新しいチャットで 「なぜ Passport をやめたの?」 と尋ねても、Claude はすでに把握しています。関連する情報がなければ何も追加されず、同じセッション内でメモリが繰り返し表示されることもありません。起動後は約 1 秒で動作します(パソコンの起動後、最初のメッセージでは読み込みに数秒かかることがあります)。
- プロジェクトを認識。 メモリは作業中のプロジェクト(git リポジトリまたはフォルダー名)ごとに保存され、想起時にはそのプロジェクトのメモが最初に表示されます。他のプロジェクトのメモは、非常に強く一致する場合にのみ表示されます。
- 自動保存。 Claude が編集したファイルはすべて保存されます。
- コンパクト化の前に保存。 Claude Code が会話をコンパクト化する前に、会話が保存されます。
engram recall "your message" を実行すると、自動想起によって Claude に渡される内容を確認できます。engram install-hooks を --apply を付けずに実行すると、設定を適用せずに確認できます。または、--no-recall を追加すると自動想起をスキップできます。
その他の MCP アプリ: コマンド engram-mcp(または python -m engram.mcp_server)を指定します。Engram は公式の MCP レジストリにも io.github.TushaeBXN/engram として登録されています。
MCP に対応していないアプリ(Open WebUI、n8n、独自のスクリプト)からは、小規模なローカル Web API を通じて Engram を利用できます。
engram serve # http://127.0.0.1:7742, the same tools and rules as MCP
アプリの接続先を http://127.0.0.1:7742/openapi.json に設定してください。すべてのツールの説明が記載されています。または、直接呼び出すこともできます。
curl -s localhost:7742/v1/tools/engram_recall -H 'Content-Type: application/json' \
-d '{"message": "why did we drop Passport?"}'
メモリはプライベートなため、デフォルトでは厳格な設定になっています。localhost のみで待ち受け、Web ページまたはプロキシ経由からのリクエストと思われるものは拒否します。別のマシンからアクセスするには、engram serve --host 0.0.0.0 を使用してください。この場合は必ずトークンが必要です(初回使用時に ~/.engram/server/token に作成され、表示されることはありません)。トークンは Authorization: Bearer <token> として送信します。engram serve --token は localhost でもトークンを必須とします。CORS ヘッダーは一切送信されないため、Web ページからアクセスすることはできません。
あらゆるコーディングエージェントに使い方を教える。 skills/engram/SKILL.md は、いつ想起、保存、修正を行うか、結論をどう説明するかを定めた、そのまま使えるエージェントスキルです。npx skills add TushaeBXN/engram でインストールするか、ファイルをコピーしてください。
uv、pipx、またはガイド付きセットアップを使いますか?
uv tool install engram-chateau # or: pipx install engram-chateau
engram init ~/myproject # guided setup: your AI's identity, a default wing, then saves the project
どちらもシステムの Python に触れることなく、engram と engram-mcp を PATH に追加します。
対象ユーザー
🧑💻 Claude Code を使う開発者。 Engram は Claude が扱うファイルと、その背後にある会話をひっそりと保存します。数か月後に 「なぜリトライ上限は 7 なの?」 と尋ねれば、推測ではなく実際の議論が見つかります。
🤖 AI コンパニオンやエージェントを構築する人。 ボットに独自のメモリを持たせましょう。ユーザーについて学んだこと、日記、人物や事実のナレッジグラフ(「Kai は 6 月から Orion で働いている」)などです。すべてオフラインで、数行の Python だけで動作します。Engram は、まさにこのようなパーソナルコンパニオンアプリのメモリとして誕生しました。
📚 作家、研究者、メモを取る人。 メモのフォルダー、Obsidian の保管庫、Notion や Linear のエクスポートを指定すれば、「価格帯について思いついたあのアイデア」 のように、意味に基づいて全体を検索できます。
Engramが異なる点
- 🔒 自分のものです。 すべてのデータは、お使いのコンピューター上の1つのフォルダー(
~/.engram/)に保存されます。アカウントも、クラウドも、APIキーも、追跡もありません。 - 📝 あなたの言葉をそのまま残します。 ほとんどのAIメモリーツールは、LLMに会話を書き換えさせて短い「事実」にまとめ、元の内容を破棄します。Engramは元のテキストを保存し、あとから見つけ出します。要約で失われるものはありません。
- 🧠 意図を理解します。 「認証ライブラリーの変更」について尋ねると、「PassportからLuciaに切り替えた」という記録を見つけます。また、正確な名前や番号(
INV-20931)にも一致し、「2週間前」、「6月に」、*「5月8日に」*といった時間も理解します。 - 💸 無料で使えます。 保存にも検索にもLLMは不要なので、メッセージごとの費用も、利用制限もありません。
- 🎯 高精度です。 AIメモリーの標準的な2つのテストで、公開済みのLLM不使用の最高成績を上回っています(以下の数値をご覧ください)。
- 📖 すべて読むことができます。 約10,000行のシンプルなPythonで書かれており、MITライセンスです。データがどう扱われているか正確に知りたい場合は、確認できます。
- 🔄 古くなった情報を把握します。 決定が変更されると、新しいメモリーに古いメモリーを置き換える印が付きます。検索では現在の回答が最初に表示され、古い情報は変更時期と理由とともに履歴としてその下に残ります。
- 🔑 秘密情報を非表示にできます。
redact_secretsを有効にすると、ディスクに書き込まれる前にAPIキー、トークン、パスワードが空欄に置き換えられます。
仕組み
Engramは、大きな家を整理するようにメモリーを分類します。人物やプロジェクトごとに棟、トピックごとに部屋、メモリーの種類ごとに廊下を設け、その中の引き出しに元のテキストを格納します。
Wing – a person or project ("myapp", "life")
└── Room – a topic ("auth-migration")
└── Hall – the kind of memory (facts, events, discoveries, preferences, advice)
└── Drawer – your original text, word for word
これらを自分で管理する必要はありません。Engramが保存時に自動で整理します。検索時には、複数の手がかりを組み合わせて判断します。
| 手がかり | 動作 |
|---|---|
| 意味 | 表現が異なっていても、同じ意味のテキストを見つけます |
| 正確な単語 | 全文インデックスにより、意味検索では見つからない名前、番号、珍しい単語も見つけます |
| 時間 | *「2週間前に何を買った?」や「6月に何があった?」*といった質問では、その時期のメモリーを優先します |
| さりげない発言 | 何気なく話したこと(*「最近よく眠れていない」*など)にも気付き、あとからの質問で見つけられるようにします |
| 新しさ | 新しいメモリーをやや優先します。ピン留めされたメモリーは古くなりません |
| 再ランキング (任意) | 小さなローカルモデルが上位20件を読み直し、最適なものを先頭に並べます |
セッションの開始時に、EngramはAIに短い「起動」メモを渡すこともできます(誰であるかと重要な事実。まずピン留めされたものを示し、次に新しいものを示します。デフォルトで約120トークンです)。これにより、毎回まったく何も知らない状態から始めずに済みます。
変更があったとき
3月に、アプリがすべてのデータをSQLiteに保存すると記録します。4月にPostgreSQLへ移行します。多くのメモリーツールでは、矛盾する2つのメモが残り、質問によりよく一致したほうが返されます。
Engramでは、あなた(またはClaude、あるいはエージェント)が、変更を一度記録するだけです。
engram correct file-05aa607a "We migrated the app from SQLite to PostgreSQL on April 9" --reason "SQLite locked under concurrent writes"
以降、検索では現在の回答が最初に表示され、古い情報は明確なラベル付きでそのすぐ下に残ります。
$ engram search "which database does the app use"
1 c6e0b7b4 [current, replaces file-05aa607a] We migrated the app from SQLite to PostgreSQL on April 9…
2 file-05aa607a [outdated → c6e0b7b4] Decision: the app stores everything in SQLite because…
engram history file-05aa607aを実行すると、記録の全容を確認できます。何が書かれ、何に置き換えられ、いつ、なぜ変更されたのかがわかります。情報がひそかに削除されることはありません。古い根拠も引き続き検索でき、誤った訂正はengram supersede <id> --undoで取り消せます。
Engramが、あるメモが別のメモと矛盾すると独自に判断することはありません。何が真実かを決めるのは、使う人の役目です。Claudeがメモリーを保存するとき、Engramは更新対象となる可能性のある既存のメモリーを示し、Claudeが判断します。
なぜそう言えるのでしょうか?
メモリには、何を根拠にしているのか、どこから得たのかを記録できるため、結論が証拠から切り離されることはありません。
engram source 903294e5 primary --ref "U.S. Const. art. I, § 2" # where a memory came from
engram link c9422f65 based_on 903294e5 --reason "constitutional text"
engram link c9422f65 derived_from 2da14213 # also: contradicts, supersedes
情報源は、user(あなたが述べたもの)、primary(原文書、法律、判決、データセット)、secondary(報道や分析)、tool(検索やプログラムの結果)、inference(AI 自身の結論)です。推論は推論としてラベル付けされたままになります。
engram why <id> は、メモリの情報源と日付、それが記録なのか推論なのか、その根拠となる証拠、その証拠が後から訂正または異議を唱えられたかどうか、以前のバージョンとその根拠、さらに --query を指定した場合は、検索でそれが上位にランク付けされた理由を説明します。
$ engram why c9422f65
c9422f65-… amy/views 2026-10-20
My view: population apportionment is the baseline; the 2025 map changes the state's representation.
Source: AI inference. Type: an inference.
Evidence
based_on 903294e5 2026-10-20 primary source, U.S. Const. art. I, § 2
Article I, Section 2: Representatives shall be apportioned among the several States…
derived_from 2da14213 2026-10-20 secondary source OUTDATED → 914e0cb2
Report: the legislature adopted a new map in 2025.
Needs review
• evidence 2da14213 was corrected (current version: 914e0cb2); check whether this still holds
engram check は、メモリ全体を対象に、訂正または異議を唱えられた証拠に基づく結論、証拠のない推論、未解決の対立、削除済みメモリへのリンクなどを一覧表示します。何も変更しません。見解を修正した場合も、以前の見解には当時の証拠が保持されるため、以前の見解が何に基づいていたのか、そして新しい見解を何が裏付けているのかをいつでも確認できます。
バックアップ。 engram export backup.json.gz は、すべてのメモリ、訂正、ナレッジグラフの事実、日記を1つのファイルにまとめます。engram import backup.json.gz は、まずファイル全体を確認してから、別のコンピューターに復元します。問題があれば、何も変更されません。形式については、docs/backup-format.md に記載されています。
どれほど優れているのでしょうか?
研究者は、2つの公開ベンチマークを使ってAIのメモリをテストします。それぞれのベンチマークでは、システムに長いチャット履歴を与え、その中のどこかに答えが埋もれている質問をします。スコアは、システムが正しい会話をどれだけの頻度で見つけられるかを示します。
| ベンチマーク(デフォルト設定、LLMなし) | Engram |
|---|---|
| LongMemEval:500問、正しい会話が上位5件以内 | 98.8% |
| LoCoMo:1,986問、回答に関連するセッションが上位10件以内 | 92.1% |
簡単に言うと、数か月分のチャット履歴についてEngramに500問尋ねると、そのうち494問で正しい会話が上位5件に入ります。ノートパソコンで動作する小型モデルを使い、LLMもAPIも使わずに実現しています。これらのテストで測定するのは、正しい会話を見つける能力です。訂正、根拠リンク、想起メモによってAIの正確さが向上するかどうかは測定していません。それについてはbenchmarks/trust_eval.pyで確認でき、結果を以下に示しています。
メモリの信頼性は保たれるのでしょうか? これらのテストでは、訂正、モデルに渡すメモ、クラッシュは対象外のため、benchmarks/trust_eval.pyで確認します。現行バージョンを使い、単独で実行した(作成者が記述した、意図的に小規模な)シナリオでの結果は次のとおりです。
| 結果 | |
|---|---|
| 事実が変わった後、現在のバージョンが最初に表示される | 20問中20問(訂正履歴なしでは20問中4問) |
| 自動想起メモのサイズと、すべてのメモリを貼り付けた場合の比較 | 92トークン対5,134 |
| 自動想起メモに回答が含まれる | 20問中17問(単純な上位5件検索では20問中19問) |
| 関連情報が何も保存されていないとき、自動想起がその旨を伝える | 20回中0回 |
| 40回の強制クラッシュ後に、半端な状態で残ったメモリファイル | 0件(1.10.1で修正する前は10件) |
| 6つのライターが並行して動作した際に失われた訂正またはリンク | 240件中0件 |
自動想起は、一部の回答を控えて、短いメモを優先します。完全な表、このテストで示されないこと、実際にテストを実行する方法もそちらに記載しています。ここに示した結果から、AIのエンドツーエンドの正確さが向上するとは言えません。その点はまだテストされていません。
細かい注意点
- 小型のローカル埋め込みモデル(all-MiniLM-L6-v2)を使用します。Engramは、あなたの返信だけでなくアシスタントの返信もインデックス化します。
- これらの数値はホールドアウトデータによるものではありません。 Engramのブーストは汎用ルールとして固定されており、質問ごとに調整していません。ただし、LongMemEvalとLoCoMoのスコアをバージョンごとに確認して、どのルールを採用するか選んだため(各段階はBENCHMARKS.mdに記載)、スコアの一部はこれら2つのテストに適合しています。
- ブーストを一切使わない、生の意味検索だけでは、LongMemEvalでR@5が96.8%です。 ブーストによって約2ポイント上がります。
- LongMemEvalでは、1問あたり0.2ポイントです。そのため、小さな差でも1~2問分に相当します。
- LLMリランカー(APIキーが必要です)を使えば、スコアをさらに上げられます。設計上、Engramにはその機能はありません。
- すべてこのリポジトリから再現できます。質問の種類ごとの詳細な結果、以前のバージョン、正確なコマンドはbenchmarks/BENCHMARKS.mdに記載されています。
Engramを使うべきでしょうか?
優れたメモリツールはいくつかあります。率直な選び方をご紹介します。
| 望むもの… | 使うもの |
|---|---|
| Claude CodeまたはClaude Desktop向けの、プライベートで無料、すぐに使えるメモリ | Engram |
| オフラインで使えて、呼び出しごとの費用がかからない、独自のAIアプリ、コンパニオン、エージェント向けのメモリライブラリ | Engram |
| データを扱うコードのすべての行を読んで、信頼したい | Engram |
| ダッシュボードとAPIを備えた、クラウド上のマルチユーザー製品向けメモリ | Mem0、Zep、Supermemoryなどのホステッドサービス(通常はアカウント、APIキー、LLMが必要です) |
| 少数の常時適用するルール(「タブを使う」、*「私の名前は…」*など)だけ | Claudeの組み込みメモリまたはCLAUDE.mdファイル |
独自のアプリで使用する
from engram.agents import AgentDiary
from engram.backends import get_backend
from engram.chateau import Chateau
from engram.knowledge_graph import KnowledgeGraph
from engram.searcher import Searcher
memory = Chateau() # your memory folder (~/.engram/chateau)
searcher = Searcher(get_backend("chromadb"), memory)
for hit in searcher.search("what music does Maya like", n=5):
print(hit["text"], hit["final_score"])
AgentDiary("my-assistant").write("Helped plan the week") # an agent's diary
KnowledgeGraph().add(subject="Maya", predicate="likes", obj="jazz") # facts about people and things
これらの呼び出しは tests/test_public_api.py で固定されているため、これらを使って構築したアプリはリリースをまたいでも動作し続けます。完全なデフォルト検索(完全一致語インデックスを含む)を利用するには、engram.backends.backend_from_config(engram.config.load_config()) でバックエンドを構築してください。
日常的なコマンド
# Save things
engram mine ~/project --wing myapp # a folder of files
engram mine ~/Downloads/claude-export --mode convos --wing myapp # a Claude, ChatGPT or Slack export
engram watch ~/project --wing myapp # keep saving as files change
# Find things
engram search "auth decisions" --wing myapp
engram answer "What did we decide about the database?" # a written answer (needs Ollama)
engram replay --room auth-migration # a topic's history, in order
# Fix and keep things
engram correct <id> "the new, correct version" # replace an outdated memory (old one kept as history)
engram history <id> # what replaced what, when and why
engram why <id> # where it came from, what it rests on, what changed
engram forget <id> # delete a memory for good (shows what changes; add --yes)
engram export backup.json.gz # back up everything to one file
engram import backup.json.gz # restore it (checked first; safe to repeat)
# Look after it
engram status # what's in your memory
engram wake-up # the short start-of-session note
engram audit --fix # health check and safe fixes
ID は engram search の検索結果にある最初の列の短いコードです。
コマンドの完全なリファレンス
セットアップ
engram init <dir> # guided setup
engram serve [--host H] [--port P] [--token] # local web API for apps without MCP (OpenAPI at /openapi.json)
engram reindex [--wing W] # rebuild the search index (after changing the embedding model)
engram connect <app> # add Engram to Cursor, VS Code, Gemini CLI, Codex… (no app: list)
engram install-hooks --apply # Claude Code hooks: auto-recall, auto-save, save before compacting
engram recall "a message" # preview what auto-recall would give Claude
engram setup-reranker # download the reranker model (90 MB) and turn it on
engram setup-reranker --disable # turn the reranker off
保存
engram mine <dir> # project files
engram mine <dir> --mode convos # conversation exports (Claude, ChatGPT, Slack, Claude Code)
engram mine <dir> --wing myapp --room auth # choose the wing and room
engram mine <dir> --since 2026-01-01 # skip older files
engram mine <dir> --plugin obsidian # also: notion, linear
engram watch <dir> --wing myapp # auto-save on change
engram split <dir> [--dry-run] # split concatenated transcripts
engram remember-type "Prefer SQLite for local dev" preference --wing myapp
engram remember-type --list # the 13 memory types
検索
engram search "query" [--wing W] [--room R] [--results 20]
engram search "query" --no-decay # ignore recency
engram search "query" --no-hybrid # meaning only
engram search "query" --rerank / --no-rerank # force the reranker on or off for one search
engram answer "question" [--wing W] [--model llama3.2] [--chunks 8]
コンテキスト、履歴、グラフ
engram wake-up [--wing W] [--rebuild]
engram replay --room R [--wing W] [--type decision] [--since 2026-06-01] [--min-confidence 0.8]
engram kg query "Kai" [--all]
engram kg add "Kai" works_on "Orion" --from 2025-06-01
engram kg invalidate "Kai" works_on "Orion" --ended 2026-03-01
engram kg timeline "auth-migration"
engram graph [--wing W] [--output file.png] # needs: pip install "engram-chateau[viz]"
修正
engram correct <id> "new text" [--reason "why"] # save a correction that replaces <id>
engram supersede <old-id> <new-id> [--reason R] # mark an existing memory as replacing another
engram supersede <old-id> --undo # make <old-id> current again
engram history <id> # status and full replacement history
engram correct <id> "text" --source primary --ref "cite" --based-on <evidence-id>
削除
engram forget <id> # show what deleting it would change
engram forget <id> --yes # delete it, its search entries and every link to it
忘却は、保存してはいけなかった情報に使います。置き換えられていた記憶は再び現在のものになり、それを根拠としていた記憶はその証拠を失います(何も根拠が残っていないものは engram check に一覧表示されます)。また、以前にエクスポートしたデータには引き続き含まれます。履歴を失わずに記憶を変更するには、代わりに engram correct を使ってください。
根拠と説明
engram link <id> based_on <evidence-id> [--reason R] # <evidence-id> supports <id>
engram link <id> derived_from <other-id> # <id> was inferred from <other-id>
engram link <id> contradicts <other-id> # conflict, undecided
engram link <id> supersedes <old-id> # <id> replaces <old-id>
engram link <id> based_on <evidence-id> --undo # remove a link
engram source <id> user|primary|secondary|tool|inference [--ref "citation or URL"]
engram why <id> [--query "the question"] [--json] # explain a memory
engram check [--json] # what needs review; changes nothing
バックアップ
engram export <file>[.gz] # back up everything to one file
engram import <file> [--dry-run] [--overwrite] # restore; the whole file is checked first
メンテナンス
engram status
engram audit [--fix]
engram conflicts # resolve contradicting knowledge-graph facts
engram compress [--wing W] [--room R] # rebuild short summaries (ES)
engram provenance <drawer-id> [--history]
engram provenance --summary
engram ui # local notes app at http://127.0.0.1:7741
設定
すべて初期状態のままで動作します。設定を調整する場合は、~/.engram/config.json にあります。すべてのキーは省略可能で、デフォルト値はベンチマーク済みの設定です。
| 設定 | デフォルト | 説明 |
|---|---|---|
redact_secrets | false | 保存前に API キー、トークン、パスワードを伏せ字([REDACTED:…])にします |
reranker | false | ローカルのリランカーです。engram setup-reranker で有効にします。無効の間は追加でダウンロードされません |
recall | true | Claude Code で自動的に記憶を呼び出します(engram install-hooks が必要です)。false にすると無効になります |
recall_max / recall_min_relevance | 3 / 0.30 | 1 メッセージにつき呼び出す記憶の最大数と、必要な一致度です(0~1) |
recall_preference_min_relevance | 0.20 | 保存された好みに対する同じ一致度のしきい値です。選択を求める依頼では、その好みと同じ言葉が繰り返されることはまれなため、低めに設定されています |
recall_exclude_wings | ["library"] | 自動的な記憶の呼び出しに表示されないウィングです |
recall_other_min_relevance | 0.55 | 別のプロジェクトの記憶を表示するために必要な一致度です |
projects | {} | フォルダー名を希望どおりにできない場合に、フォルダーをウィングに割り当てます。例:{"~/code/app": "billing"} |
keyword_search | true | 意味による検索と併せて完全一致語インデックスを検索します(SQLite、ダウンロード不要)。初回実行時に既存の記憶から作成されます |
embedding_api_url / embedding_api_model | 未設定 | 内蔵の英語モデルの代わりに、自分で実行している埋め込みサーバー(LM Studio、Ollama、llama.cpp、vLLM など、/v1/embeddings に対応するもの)を使います。たとえば、他の言語を使う場合に便利です。設定後に engram reindex を一度実行してください。記憶のテキストが送信されるため、embedding_api_allow_remote が true でない限り、サーバーはこのコンピューターまたはネットワーク上にある必要があります |
vector_backend | chromadb | 検索エンジンです。chromadb、faiss、または sqlitevec(コンパイル済みのコンポーネント不要)を指定します |
hybrid_weight | 0.3 | 完全一致する語を共有する結果への加重値です。0 にすると無効になります |
temporal_weight | 0.4 | 質問で指定された時点に近い記憶への加重値です。0 にすると無効になります |
preference_summaries | true | 会話の中でさりげなく言及された好みや懸念の短い要約をインデックス化します |
l1_budget_tokens | 120 | 起動メモの重要な事実部分のサイズです |
rerank_top | 20 | リランカーが並べ替える上位結果の数です |
decay_factor / decay_max_days | 0.005 / 90 | 新しい記憶をどの程度優先するか、また優先期間を何日間にするかを指定します |
chateau_path | ~/.engram/chateau | 記憶の保存場所です |
ENGRAM_VECTOR_BACKEND=sqlitevec engram … を実行すると、その実行中のみバックエンドが切り替わります。埋め込みサーバーはデフォルトの chromadb バックエンドで動作します。サーバーとモデルごとに個別のインデックスが使われるため、切り替えて戻す際に再インデックスは不要で、記憶が変更されることもありません。~/.engram/identity.txt には、各起動メモの冒頭に記載される短い自己紹介が保存されています。
トラブルシューティング
- インストール後に
engram: command not foundと表示される。 pip のインストール先が PATH に含まれていません。python3 -m pip install --user engram-chateauを使用するか、PATH を自動で設定するuv tool install engram-chateau/pipx install engram-chateauでインストールしてください。 pip: command not foundと表示される。pip3またはpython3 -m pipをお試しください。uv仮想環境内では、uv pip install …を使用してください。- 新しいコンピューターに移行する。 古いコンピューターで
engram export backup.json.gzを実行し、新しいコンピューターに Engram をインストールしてから、engram import backup.json.gzを実行してください。インポート中に検索インデックスが再構築されます。 - Claude に engram のツールが表示されない。 サーバーを追加した後、Claude Code または Claude Desktop を再起動してください。アプリが
engram-mcpを見つけられない場合は、which engram-mcpで確認したフルパスを指定してください。 - 「ChromaDB failed to load」と表示される。 ChromaDB のコンパイル済みコンポーネントが Python と一致していません。
pip install --force-reinstall --no-cache-dir chromadbをお試しいただくか、コンパイル済みコンポーネントが不要な"vector_backend": "sqlitevec"を設定してください。その後、各バックエンドが個別のインデックスを保持するため、もう一度engram mineを実行してください。 - Python 3.15 以降を使用している。 ChromaDB はまだインストールできないため、Engram は
sqlitevecにフォールバックします。これは意味ではなく単語を照合します。意味ベースの検索には、Python 3.11 から 3.14 を使用してください。 - GitHub から更新した後に「No such command」と表示される。
git pull origin mainを実行し、続けて Engram フォルダー内でpip install -e .(またはuv pip install -e .)を実行してください。 - 検索結果の Relevance 列に
<0.001と表示される。 ランカーは質問に本当に答える結果を見つけられませんでした。質問をより具体的にしてみてください。
内部の仕組み:略記、メモリレイヤー、Web UI、コードマップ
Engram Shorthand (ES)
デコーダーなしであらゆる LLM が読み取れる、簡潔なテキスト形式です。Engram がモデルに読み込む短いコンテキストにのみ使用され、各引き出しには常に元のテキストが保持されます。ES は不要な語を省き、文章で約 1.6 倍、コードで約 1.1 倍の節約になります。
from engram.shorthand import compress
compress("The authentication module is a critical component that has a dependency on the database.")
# → "auth module=★★ component +dep on db."
メモリレイヤー
| レイヤー | 内容 | サイズ | 読み込み |
|---|---|---|---|
| L0 | アイデンティティ:AI が何者か | 約 50 トークン | 常時 |
| L1 | 重要な事実、略記 | 最大 120 トークン(l1_budget_tokens) | 常時 |
| L2 | 現在のトピックに関するメモリ | 必要に応じて | トピックが話題に上がったとき |
| L3 | 全文検索 | 必要に応じて | 要求されたとき |
Web UI
engram ui を実行すると、http://127.0.0.1:7741 でローカルのノートアプリが開きます。リンクされたノートのグラフ、タグ、ピン留めしたノート、日記、Markdown 編集機能を備えています。現時点ではノートをブラウザー内に保存し、~/.engram/ 内のメモリはまだ表示しません。そちらには engram search または MCP ツールを使用してください。
| ファイル | 説明 |
|---|---|
engram/chateau.py | ディスク上のウィング、部屋、ホール、引き出し |
engram/searcher.py | 検索:意味、キーワード、時間、最新性、再ランキング |
engram/keyword_index.py | 意味検索と統合される完全一致語インデックス(SQLite FTS5) |
engram/indexing.py | 長いテキストをインデックス用のチャンクに分割 |
engram/temporal.py | 「2週間前」「6月に」「5月8日に」などを理解 |
engram/preferences.py | メッセージ内の好みや懸念点を検出 |
engram/redact.py | 任意のシークレットのマスキング |
engram/reranker.py | 任意のローカル再ランキング(ONNX) |
engram/miner.py, engram/convo_miner.py | ファイルと会話の保存 |
engram/lineage.py | 訂正:どの記憶が最新か、どの記憶が置き換えられたか、その理由 |
engram/relations.py | エビデンスのリンク、情報源、engram why、engram check |
engram/server.py | engram serve:ローカル Web API とリクエストの検証 |
engram/validate.py | 各ツールのスキーマに照らしてツール引数を検証(MCP と Web) |
engram/embedding.py | 組み込みモデルの代わりに使う任意の埋め込みサーバー |
engram/backup.py | engram export / engram import |
engram/recall.py | Claude Code 用の自動呼び出しフック |
engram/mcp_server.py | MCP サーバー(31 個のツール)。engram-mcp として実行 |
engram/connect.py | engram connect:AI アプリの設定に Engram を追加 |
engram/layers.py, engram/shorthand.py | 起動時のメモと ES の略記 |
engram/knowledge_graph.py, engram/agents.py | ナレッジグラフとエージェントの日記 |
engram/backends/ | ChromaDB(デフォルト)、FAISS、sqlite-vec |
engram/plugins/ | Obsidian、Notion、Linear のインポーター |
engram/hooks/ | Claude Code の保存フックと圧縮前フック |
benchmarks/ | LongMemEval と LoCoMo の実行ツール |
要件
- Python 3.9 以降。 意味ベースの検索には 3.11~3.14 を推奨します。
- 自動インストール: ChromaDB、typer、rich、watchdog、questionary、pyyaml、requests。
- 任意の追加機能:
engram-chateau[faiss]、[sqlitevec]、[viz](グラフ画像)、または[all]。 - 任意:
engram answer用の Ollama。
インターネットの使用: 初回のみ行われる 2 件のダウンロードを除き、使用しません。埋め込みモデル(約 80 MB)は、初めて保存または検索するときにダウンロードされます。任意の再ランキングモデル(90 MB)は、engram setup-reranker を実行した場合にのみダウンロードされます。記憶がマシンの外に出ることはありません。
コントリビューション
バグ報告、アイデア、プルリクエストを歓迎します。
git clone https://github.com/TushaeBXN/engram && cd engram
pip install -e ".[dev]"
pytest
リリース(メンテナー向け)
Engram は、PyPI trusted publishing(保存済みトークンなし。所有者 TushaeBXN、リポジトリ engram、ワークフロー publish.yml、環境 pypi)を使用し、.github/workflows/publish.yml から engram-chateau として PyPI に公開されます。
pyproject.tomlのversionとengram/__init__.pyの__version__を更新し、CHANGELOG.mdに項目を追加します。mainにマージします。- マージ後に、タグのドットをそのまま保持した
v<version>(例:v1.51ではなくv1.5.1)を付けた新しい GitHub リリースを作成し、mainを対象にします。ワークフローでタグとバージョンの一致を確認し、テストを実行して、ビルドとアップロードを行います。
クレジットとライセンス
Engram のデザイン(ウィング、部屋、ホール、引き出し、時間的ナレッジグラフ)は、ほかのオープンソースの記憶システムから着想を得ています。いくつかの検索機能(完全一致語インデックスと日付の理解)は、Hindsight を参考にしています。
MIT © 2026 Tushae Thomas
Engram が大切なことを覚えておく助けになったなら、⭐を付けていただけると、ほかの人にも見つけてもらいやすくなります。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。