Engram を理解する
コマンドガイドを読む前に、こちらをお読みください。Engram が有用である理由は、コマンドの多さではなく、誰がメモリを所有しているかにあります。
一言で表すモデル
Engram は、AI エージェントが永続的なメモリを使用できるようにしつつ、何が永続化されるかを人間が決定するファイルプロトコルです。
Engram とは何か
Engram は、以下を管理するための知識メモリセンターです：
- プロジェクトのルール
- チームの決定事項
- 再利用可能なワークフロー
- 永続的な事実
- プロジェクトをまたいで適用したい個人の設定
メモリはプレーンな Markdown です。インデックス、グラフ、ハッシュ、およびアダプターファイルは、その Markdown をより簡単かつ安全に使用できるようにするために存在します。
Engram ではないもの
Engram は以下のものではありません：
- エージェントのための隠された脳
- ベンダーが所有する閉じたメモリシステム
- プロジェクトドキュメントの代替物
- 権威を装ったベクトルデータベース
- すべてを永久に保存する自動レコーダー
エージェントはメモリを提案できますが、人間がメモリの承認、拒否、編集、アーカイブ、および所有を行います。
コアとなる約束
Engram は、AI メモリを以下のようにすることを目指しています：
- レビュー可能：一般的なエディタで直接読むことができます
- ポータブル：Git で同期し、異なるエージェント間で再利用できます
- 修正可能：誤ったメモリは、将来の作業に悪影響を及ぼさないようにアーカイブ（理由付き）できます
- デフォルトでプライベート：除外ルールと承認ゲートにより、誤った情報のキャプチャを防ぎます
- 意図的にシンプル：不可視のプラットフォームの状態よりも、Markdown ファイルのほうが信頼しやすいです
各レイヤー
| レイヤー | 意味 |
|---|---|
| Markdown | 永続的な信頼できる唯一の情報源（source of truth） |
| JSON インデックス | 高速ルックアップレイヤー |
| JSON グラフ | トピックおよび関係性のルーティングレイヤー |
| ハッシュ | 整合性チェック |
| 承認（Approval） | 書き込み前の信頼の境界 |
| 除外ルール | プライバシーコントロール |
| Git | 履歴管理、ポータビリティ、レビュー、復元 |
| エージェントアダプター | Codex、Claude、Cursor、Gemini、その他のエージェント用の利便性レイヤー |
生成される JSON はエージェントがメモリを素早く見つけるのを助けますが、それは権威ではありません。生成されたファイルと Markdown の内容が矛盾する場合、Markdown が優先されます。
メモリのライフサイクル
- セッション、ファイル、または人間のメモに有用な知識が含まれている。
- エージェントが簡潔なメモリ候補を提案する。
- 人間がすべてを承認、一部を選択、メモを追加、または拒否する。
- Engram が承認された Markdown メモリを書き込む。
- Engram がハッシュ、インデックス、グラフ、および変更履歴（changelog）を更新する。
- 将来のエージェントが、現在のタスクに関連するメモリのみを読み込む。
- メモリが誤りになった場合、Engram は理由とともにそれをアーカイブする。
このライフサイクルにより、メモリを不可視にすることなく有効に保ちます。
人間、エージェント、Engram、Git
| アクター | 役割 |
|---|---|
| 人間 | 何を永続メモリにするかを選択する |
| エージェント | パターンを検知し、メモリ候補を提案する |
| Engram | スキーマ、安全性、ルーティング、承認、およびメンテナンスを適用する |
| Git | マシン間でメモリを搬送し、レビュー履歴を提供する |
エージェントは支援をしますが、所有者ではありません。
良いメモリ
良い Engram メモリとは：
- 来週になっても価値がある程度に安定していること
- 後でルーティングできる程度に具体的であること
- エージェントのコンテキストに収まる程度に短いこと
- 意図したスコープで共有しても安全であること
- ルール（rule）、スキル（skill）、または知識項目（knowledge）として記述されていること
悪いメモリとは、一時的なチャットのノイズ、機密情報、認証情報、その場限りの推測、または誰も承認していない事実などです。
スコープ
ワークスペースメモリの保存先：
<project>/.agents/.engram/
グローバルメモリはオプションであり、ユーザーが設定した場所に保存されます。
ワークスペースメモリが優先されます。グローバルメモリは、再利用可能な設定、個人の習慣、またはチーム全体のデフォルト値のためのフォールバックです。
なぜ内蔵のエージェントメモリだけではダメなのか
内蔵メモリは便利ですが、検査、比較（diff）、エクスポート、共有、あるいは修正が困難な場合があります。また、特定のアプリやアカウントに依存しがちです。
Engram は永続的なレイヤーを可視化します。内蔵メモリも役立ちますが、知識が重要である場合には、人間が所有する Engram が信頼できる情報源であるべきです。
知っておくべき限界
デフォルトの Engram 検索は、決定論的なレキシカル検索です。engram search --semantic は決定論的なローカル類似度チェックを追加しますが、外部の埋め込み（embeddings）を利用した意味検索ではありません。グラフのベクトルは、セマンティックな埋め込みではなく、ローカルでハッシュ化された単語ベクトルです。矛盾の検出はアドバイザリー（推奨情報）にすぎません。暗号化設定は存在しますが、暗号化ストレージはまだ実装されていません。
これらの制限は、あえて明確に示すようにしています。Engram は、現在何が実現可能で、何が将来の課題であるかをユーザーに明確に伝えるべきだと考えています。