Engram - AI エージェント向け永続メモリシステム

Engram は セッション間の永続メモリを提供します。以前の会話からバグフィックス、アーキテクチャの決定、パターン、発見を覚えています。

⚠️ 重要: 起動メカニズム

クロンジョブのような自動実行ではありません → エージェントの能動的な判断が必要です。

✅ エージェントが Engram を呼び出すタイミング:

タイミング	ツール	理由
セッション開始時	mem_context	前回の作業を復元
重要な作業後	mem_save	発見内容を保存
ユーザーが「覚えている」と言う	mem_search	メモリ内を検索
類似作業開始時	mem_search	以前実施したか確認
セッション終了時	mem_session_summary	コンテキストを保存
コンテキスト圧縮後	mem_context	状態を復元

❌ エージェントが Engram を呼び出してはいけないタイミング:

• ユーザーの各メッセージ（ノイズ）
• ハートビート（トークンが無駄）
• バックグラウンド cron（目的に合致しない）
• 些細なツール呼び出し（保存する価値がない）

🤖 エージェントの判断:

エージェントがコンテキストを評価して判断します：

• 重要な作業でしたか？ → 保存
• 重要なことを学びましたか？ → 保存
• 重要な設定変更ですか？ → 保存
• 些細なことでしたか？ → 保存しない

保存を求めるのを待たないでください → 能動的に判断してください。

---

⚙️ 前提条件

このスキルには 2 つのバイナリのインストールが必要です：

ツール	用途	リポジトリ
MCPorter	MCP クライアント - ツール実行用	steipete/mcporter
Engram	永続メモリバックエンド	Gentleman-Programming/engram

MCPorter をインストール

macOS / Linux (Homebrew):

brew tap steipete/tap
brew install steipete/tap/mcporter

全プラットフォーム (npm):

# テスト用（インストール不要）
npx mcporter --version

# グローバルインストール
npm install -g mcporter

Windows (バイナリ):

1. GitHub Releases から mcporter-<version>.exe をダウンロード
2. mcporter.exe にリネーム
3. システムの PATH に追加

確認:

mcporter --version

Engram をインストール

macOS / Linux (Homebrew):

brew install gentleman-programming/tap/engram

全プラットフォーム (バイナリ):

1. GitHub Releases からダウンロード
2. Windows: engram.exe にリネームして PATH に追加
3. macOS/Linux: chmod +x engram && sudo mv engram /usr/local/bin/

確認:

engram version

---

セットアップ (MCPorter と Engram を接続)

両方のバイナリをインストールしたら、Engram を MCP サーバーとして登録します：

# Engram MCP サーバーを登録
mcporter config add engram --stdio "engram mcp"

# 接続確認（13 個のツールが表示される）
mcporter list engram

期待される結果:

engram - AI エージェント向け永続メモリシステム
  13 tools · HTTP/stdio

コアコンセプト

• エージェント選別メモリ: あなたが何を覚えるべきかを決定し、自動キャプチャではない
• 段階的な開示: 検索 → タイムライン → フル観察（トークン効率的）
• セッションライフサイクル: 開始時にコンテキスト、作業中に保存、終了時にサマリー

---

🌐 OpenClaw エコシステムとの統合

完全なメモリエコシステム

┌──────────────────────────────────────┐
│   MEMORY.md (静的/永続)              │
│  - ユーザー情報（変更なし）          │
│  - セキュリティルール（永続）        │
│  - ガイドライン（永続）              │
└──────────────────────────────────────┘
         ↓ 補足関係
┌──────────────────────────────────────┐
│  memory/YYYY-MM-DD.md (日次/生)     │
│  - その日のノート                    │
│  - 作業プロジェクト                  │
│  - 直近コンテキスト                  │
│  - 自動アーカイブされる              │
└──────────────────────────────────────┘
         ↓ 補足関係
┌──────────────────────────────────────┐
│    Engram (技術メモリ)               │
│  - バグフィックス                    │
│  - コード決定                        │
│  - 発見パターン                      │
│  - 技術設定                          │
│  - 高速検索                          │
└──────────────────────────────────────┘
         ↓ 補足関係
┌──────────────────────────────────────┐
│  self-improving (振る舞い)           │
│  - ユーザー補正                      │
│  - 学習済み選好                      │
│  - 振る舞いパターン                  │
│  - HOT/WARM/COLD システム            │
└──────────────────────────────────────┘

各システムの使い分け

情報タイプ	保存先	理由
ユーザー永続情報	MEMORY.md	変更されない、素早い参照
日次ノート	memory/YYYY-MM-DD.md	直近コンテキスト、生情報
技術バグフィックス	Engram	高速検索、技術的
ユーザー補正	self-improving	将来の振る舞い
アーキテクチャ決定	Engram	技術的、参照可能
コミュニケーション選好	MEMORY.md + self-improving	両方
アクティブプロジェクト	memory/YYYY-MM-DD.md	直近コンテキスト
コードパターン	Engram	再利用可能

ハートビートとの関係

❌ ハートビートから Engram を呼び出さない → 不要にトークンを消費します。

✅ ハートビートの用途:

• 先制的チェック（メール、カレンダーなど）
• 定期タスク
• 通知

✅ Engram の用途:

• セッション間メモリ
• 技術コンテキスト
• 前回作業の検索

self-improving との関係

「学習」タイプで重複することがあります：

• self-improving: ユーザーの振る舞い選好
• Engram: コード技術学習

ルール: ユーザーがあなたの振る舞いを望む方法について → self-improving。技術的 → Engram。

---

各ツールの使い分け

トリガー	ツール	用途
プロジェクト作業開始	mem_context	前回セッションのコンテキストを読み込み
バグ修正後	mem_save	何を/なぜ/どこで/学んだことを文書化
アーキテクチャ決定時	mem_save	決定と理由を記録
パターン/ゴッチャ発見時	mem_save	将来参照用に保存
ユーザーが「覚えている」と言う	mem_search	関連メモリを検索
重複する作業開始時	mem_search	以前実施したか確認
セッション終了時	mem_session_summary	セッションコンテキストを保存
コンテキスト圧縮後	mem_context	セッション状態を復元

---

ツール参照（MCPorter 経由）

すべてのツールは MCPorter 経由で呼び出します：

mcporter call engram.<ツール名> [パラメータ]

デフォルトパラメータ: project を指定しない場合、Engram は現在のディレクトリから検出を試みます。検出できない場合は default を使用します。

コアツール

mem_save - 観察を保存

必須: title, content オプション: type, project, scope, topic_key

# 例 - バグフィックス
mcporter call engram.mem_save \
  title="ユーザーリストの N+1 エラー" \
  type="bugfix" \
  project="my-project" \
  content='**何**: UserList クエリに eager loading を追加
**なぜ**: 100+ ユーザーでのパフォーマンス低下
**どこ**: src/services/users.ts
**学んだこと**: ORM には Preload() 明示が必須'

# 例 - アーキテクチャ決定
mcporter call engram.mem_save \
  title="自動バックアップシステム" \
  type="config" \
  project="my-project" \
  content='**何**: 日次バックアップ cron を設定
**なぜ**: クリティカルデータ損失を防止
**どこ**: scripts/backup.sh, crontab
**学んだこと**: 自動化前に権限を確認すること'

# 例 - パターン発見
mcporter call engram.mem_save \
  title="パターン: 入力検証を境界層で" \
  type="discovery" \
  project="my-project" \
  content='**何**: HTTP レイヤーでの入力検証
**なぜ**: ビジネスロジックの汚染を回避
**どこ**: src/routes/*.ts
**学んだこと**: 早期検証は cognitive load を削減'

タイプ: decision, bugfix, pattern, config, discovery, learning, architecture

コンテンツ形式（推奨）:

**何**: [簡潔な説明]
**なぜ**: [根拠/コンテキスト]
**どこ**: [影響するファイル: path/to/file.ts, other.go]
**学んだこと**: [ゴッチャ、エッジケース - オプション]

mem_search - フルテキスト検索

# 基本検索
mcporter call engram.mem_search query="middleware auth"

# プロジェクトでフィルタ
mcporter call engram.mem_search query="N+1" project="my-project"

# タイプでフィルタ
mcporter call engram.mem_search query="error" type="bugfix"

# 結果数を制限
mcporter call engram.mem_search query="JWT" limit=5

コンパクトな結果と詳細ドリルダウン用の観察 ID を返します。

mem_context - 最近のセッションコンテキストを取得

# プロジェクトの最近のコンテキストを取得
mcporter call engram.mem_context project="my-project"

# より多くの観察を取得
mcporter call engram.mem_context project="my-project" limit=30

# パーソナルスコープ
mcporter call engram.mem_context scope="personal"

セッション開始時にこれを呼び出し、前回のことを復元します。

mem_session_summary - セッション終了サマリーを保存

必須: content, project

mcporter call engram.mem_session_summary \
  project="my-project" \
  content='## 目的
JWT 認証実装とパフォーマンスバグを修正

## 指示
ユーザーは説明は日本語を希望

## 発見
- ORM には associations に対する Preload() 明示が必須
- 検証は境界レイヤーに配置
- リフレッシュトークンはセキュリティのため回転すること

## 実施内容
- ✅ リフレッシュトークン付き JWT を実装
- ✅ N+1 クエリを修正（100 倍高速化）
- ✅ 認証ミドルウェアを追加
- 🔲 統合テスト待ち
- 🔲 API ドキュメント待ち

## 関連ファイル
- src/auth/jwt.ts — トークン生成と検証
- src/middleware/auth.ts — 認証ミドルウェア
- src/services/users.ts — 最適化されたクエリ
- src/routes/*.ts — 境界層での入力検証'

必須コンテンツ形式:

## 目的
[1 文: このセッションで何を構築/作業したか]

## 指示
[発見されたユーザー選好 - オプション]

## 発見
- [技術的発見 1]
- [技術的発見 2]

## 実施内容
- ✅ [完了タスク 1 — 主要な詳細付き]
- ✅ [完了タスク 2 — 変更ファイルを記載]
- 🔲 [識別したが未実施 — 次回セッション用]

## 関連ファイル
- path/to/file.ts — [何をしたか/何が変更されたか]
- path/to/other.go — [アーキテクチャ内の役割]

セカンダリツール

mem_timeline - 時系列コンテキスト

mcporter call engram.mem_timeline observation_id=42 before=5 after=5

特定の観察の前後で何が起きたかを表示します。

mem_get_observation - 完全なコンテンツを取得

mcporter call engram.mem_get_observation id=42

特定の観察の切り詰めなしコンテンツを返します。

mem_update - 既存観察を更新

mcporter call engram.mem_update id=42 content="更新されたコンテンツ..."
mcporter call engram.mem_update id=42 title="新しいタイトル"

mem_delete - 観察を削除

mcporter call engram.mem_delete id=42
mcporter call engram.mem_delete id=42 hard_delete=true

デフォルトはソフト削除（復元可能）です。

mem_suggest_topic_key - 安定した topic key を取得

mcporter call engram.mem_suggest_topic_key type="architecture" title="Auth architecture"
# 返す: architecture/auth-architecture

進化するトピック（同じ topic_key = 既存観察を更新）に使用します。

mem_save_prompt - ユーザープロンプトを保存

mcporter call engram.mem_save_prompt content="ユーザーが OAuth 実装を要求" project="my-project"

mem_session_start / mem_session_end - セッションライフサイクル

mcporter call engram.mem_session_start id="session-123" project="my-project"
mcporter call engram.mem_session_end id="session-123" summary="認証実装を完了"

mem_stats - メモリ統計

mcporter call engram.mem_stats

---

🔄 メモリプロトコル

1. セッション開始

セッション開始時にALWAYS mem_context を呼び出して前回のコンテキストを復元します。

2. 作業中 - 能動的に保存

重要な作業完了後にメモリを保存します。保存を求めるのを待たないでください。

保存する場合:

• バグを修正 → type: "bugfix"
• アーキテクチャ決定を下した → type: "decision" または type: "architecture"
• パターンやゴッチャを発見 → type: "discovery" または type: "pattern"
• 設定を変更 → type: "config"
• 自明でないことを学んだ → type: "learning"

保存しない場合:

• 各ツール呼び出し（ノイズ）
• 些細な変更
• コードで簡単に見つかる情報

3. セッション終了 - 必須サマリー

セッション終了前にALWAYS mem_session_summary を呼び出します。
これはオプションではありません。スキップすると次回セッションは盲目的に始まります。

4. コンテキスト圧縮後

コンテキストが圧縮/リセットされた場合、IMMEDIATELY mem_context を呼び出して状態を復元します。
その後、続行する前に圧縮されたコンテンツで mem_session_summary を呼び出します。

---

📊 健全な使用メトリクス

セッションあたりの理想的な範囲

ツール	理想的な頻度	理由
mem_context	1x（セッション開始）	コンテキストを復元
mem_save	2-5x（重要な作業後）	発見を保存
mem_search	0-3x（必要時）	前回作業を確認
mem_session_summary	1x（セッション終了）	コンテキストを保存

過度使用アラート

• セッションあたり >10 mem_save → ノイズが多い
• 5 セッションで 0 mem_save → 重要なことを忘れている可能性
• 1 週間で >50 観察 → クリーンアップを検討

タイプの健全な比率

タイプ	理想的な比率	理由
bugfix	20-30%	一般的なエラー
discovery	20-30%	主要学習
decision	15-25%	重要な決定
pattern	10-20%	再利用可能パターン
config	10-15%	設定変更
architecture	5-10%	構造的決定

---

🚫 アンチパターン（すべきでないこと）

❌ すべてを保存しない

# 悪い: 些細なことを保存
mcporter call engram.mem_save title="ユーザーがこんにちはと言った" content="ユーザーがこんにちはと言った"

# 良い: 重要な作業のみ
mcporter call engram.mem_save \
  title="N+1 エラーを修正" \
  type="bugfix" \
  content='**何**: eager loading を追加...'

❌ ログシステムとして使わない

# 悪い: 各ツール呼び出しを保存
mcporter call engram.mem_save title="read ツールを呼び出した" content="ファイル X を読んだ"

# 良い: 発見を保存
mcporter call engram.mem_save \
  title="セキュリティ問題を発見" \
  type="discovery" \
  content='**何**: login の SQL injection...'

❌ MEMORY.md の情報を複製しない

# 悪い: ユーザー情報を複製
mcporter call engram.mem_save title="ユーザー情報" content="会社の CEO..."

# 良い: MEMORY.md がそれを持っているので、技術的なものだけを保存
# セッションに固有の技術コンテキストの場合のみ保存

❌ ハートビートから呼び出さない

# 悪い: 不要にトークンを消費
# ハートビート cron で:
mcporter call engram.mem_context  # ← NO

# 良い: インタラクティブセッションのみ
# ハートビートはプロアクティブチェック用で、メモリではない

❌ リダクションなしで機密情報を保存しない

# 悪い: API キーが露出
mcporter call engram.mem_save title="API Config" content="キー: sk-abc123..."

# 良い: <private> タグを使用
mcporter call engram.mem_save \
  title="API Config" \
  content='API key: <private>sk-abc123</private>'
# → API key: [REDACTED]

---

🔧 トラブルシューティング

エラー: "mcporter: command not found"

インストール確認:

# macOS / Linux
which mcporter

# Windows (PowerShell)
where.exe mcporter

解決策:

プラットフォーム	コマンド
macOS/Linux (Homebrew)	brew install steipete/tap/mcporter
全て (npm)	npm install -g mcporter
Windows (バイナリ)	GitHub Releases からダウンロード

エラー: "engram: command not found"

インストール確認:

# macOS / Linux
which engram

# Windows (PowerShell)
where.exe engram

解決策:

プラットフォーム	コマンド
macOS/Linux (Homebrew)	brew install gentleman-programming/tap/engram
全て (バイナリ)	GitHub Releases からダウンロード

バージョン確認:

engram version

エラー: "No MCP servers configured" または "server 'engram' not found"

MCPorter はインストール済みですが Engram が登録されていません。

解決策:

# Engram を MCP サーバーとして登録
mcporter config add engram --stdio "engram mcp"

# 確認
mcporter list engram

エラー: "MCPorter not configured"

登録確認:

mcporter list engram

失敗した場合、再度登録:

mcporter config add engram --stdio "engram mcp"

# 利用可能なツール確認（13 個であるべき）
mcporter list engram

エラー: "No previous session memories found"

エラーではありません → 初回使用時は正常です。

解決策: システムの使用を開始：

mcporter call engram.mem_save title="最初の観察" content="..."
mcporter call engram.mem_session_summary project="my-project" content="..."

メモリが大きい（>1000 観察）

# 統計を表示
mcporter call engram.mem_stats

# 古い観察を検索
mcporter call engram.mem_search query="..." limit=20

# 特定の観察をクリーンアップ
mcporter call engram.mem_delete id=XX hard_delete=true

# 推奨: <500 アクティブ観察を維持

検索結果が見つからない

考えられる原因:

1. クエリタイプ → スペルを確認
2. 高度に具体的 → より一般的な用語を使用
3. 存在しない → 最初に情報を保存
4. フィルタ誤り → project, type, scope を確認

# デバッグ: 広い検索
mcporter call engram.mem_search query="auth" limit=10

# デバッグ: プロジェクトすべてを表示
mcporter call engram.mem_context project="my-project" limit=50

エラー: "Content too long"

解決策: 複数行コンテンツにシングルクォートを使用：

# 悪い（改行で失敗）
mcporter call engram.mem_save title="..." content="行 1
行 2"

# 良い（シングルクォート）
mcporter call engram.mem_save title="..." content='行 1
行 2
行 3'

---

📝 例: 実際の完全なセッションフロー

シナリオ: ユーザーが認証実装をリクエスト

# ═══════════════════════════════════════════════════════
# 1. セッション開始 - 前回のコンテキストを復元
# ═══════════════════════════════════════════════════════
mcporter call engram.mem_context project="my-project"
# → 昨日はユーザーモジュールで作業したことを確認
# → セキュリティ問題が識別されたことを確認
# → JWT 実装が残っていることを確認

# ═══════════════════════════════════════════════════════
# 2. 作業 - JWT 実装後
# ═══════════════════════════════════════════════════════
mcporter call engram.mem_save \
  title="JWT を正しく実装" \
  type="config" \
  project="my-project" \
  content='**何**: API に JWT 認証を追加
**なぜ**: セッションは複数インスタンス間でスケールしない
**どこ**: src/auth/jwt.ts, src/middleware/auth.ts
**学んだこと**: リフレッシュトークンは回転すべき'

# ═══════════════════════════════════════════════════════
# 3. 作業 - N+1 バグ修正後
# ═══════════════════════════════════════════════════════
mcporter call engram.mem_save \
  title="ユーザーリストの N+1 クエリを修正" \
  type="bugfix" \
  project="my-project" \
  content='**何**: UserList に eager loading を追加
**なぜ**: 100+ ユーザーでパフォーマンス低下
**どこ**: src/services/users.ts
**学んだこと**: ORM は Preload() 明示を要求'

# ═══════════════════════════════════════════════════════
# 4. 作業 - パターン発見後
# ═══════════════