Engram

すべての思考には痕跡が残る。

AIエージェントに「忘れる」ことができる脳を搭載しよう。

Engramは、完全にローカルで動作するMCPメモリサービスです。単なる「保存と取得」ではありません。人間の記憶の忘却、強化、連想のメカニズムをシミュレートし、エージェントがセッションを超えて本当に重要なことを記憶し、不要になった詳細を自然に忘れるようにします。

クラウド依存はゼロ。データは常にあなたのマシン上にあります。

解決する課題

課題 1：セッション間の状態の断絶

AIエージェントとの対話は、毎回が白紙の状態です。昨日伝えた好み、先週決定したアーキテクチャ、先月ハマった落とし穴など、次の対話ではすべてリセットされます。コンテキストウィンドウのクリアは、脳のフォーマットを意味します。

課題 2：ファイルのエントロピー増大

CLAUDE.md や .cursorrules にコンテキストを詰め込むのは解決策に見えますが、実際には新たな問題を生みます。ファイルは肥大化し、古い情報と新しい情報が混在し、手動メンテナンスのコストが増え続けます。あなたは記憶を管理しているのではなく、読みづらくなっていくドキュメントを保守しているのです。

課題 3：エンジニアリング状態の喪失

エージェントが何をしたか、どこで詰まっているか、次に何をすべきか。こうした構造化されたエンジニアリング状態を保存する場所がありません。新しいセッションのたびに10分かけて「再調整」し、同じ作業を繰り返すことになります。

Engramの解決策： 「すべてを保存する」のではなく、人間の記憶の忘却・強化・連想メカニズムをシミュレートします：

• 重要な好みや決定事項は、減衰が極めて遅く、ほぼ永久に保持されます。

• 一時的なデバッグコンテキストは、11日で自然に消滅します。

• 繰り返し思い出される知識は、使うほど強固になります。

• 矛盾する情報は自動的に上書きされ、混乱を防ぎます。

• v0.2 新機能：構造化されたセッションハンドオフ（session handoff）。次のセッションをゼロからではなく、中断地点から再開できます。

• v0.4 新機能：エンジニアリング状態ハブ — 構造化された失敗の要因分析（track_failure）と進捗追跡（track_progress）により、エージェントは情報だけでなくエンジニアリングの状態も記憶します。

Related MCP server: Ori Mnemos

コアメカニズム

1. エビングハウスの忘却曲線

すべての記憶には「強度（strength）」があり、時間とともに指数関数的に減衰します：

effective_λ = base_λ × (1 - importance × 0.8)
strength = importance × e^(-λ × days) × (1 + recall_count × 0.2)

3つの要素が記憶の寿命を決定します：

4つの記憶カテゴリ：

設計意図：成功した戦略は最も長く記憶し（strategy ~38日）、失敗の教訓は最も短く記憶します（failure ~11日）。環境は変化するため、昨日の落とし穴は明日には埋まっている可能性があるからです。

2. インテリジェントな重複排除と矛盾解消

新しい記憶を保存する際、システムは単純な追加ではなく、既存の記憶との意味的な比較を行います：

相似度 ≥ 0.85 → REINFORCE  只增加回忆次数，不重复存储
相似度 0.65~0.84 → 检测矛盾
  ├── 语义矛盾 → REPLACE   用新内容覆盖旧内容
  └── 语义兼容 → MERGE     合并为一条更完整的记忆
相似度 < 0.65 → NEW        存为新记忆

矛盾検出は極性分析によって実現されます。肯定的な単語（prefer/love/adopt）と否定的な単語（avoid/hate/reject）、および否定語（not/don't/never）を抽出し、2つの記憶が相反する立場を表明しているかを判断します。

例：既存の「ユーザーはTypeScriptを好む」に対し、「ユーザーはTypeScriptを捨ててGoを採用することにした」を保存する場合、システムは矛盾と認識し、古い記憶を新しい記憶で自動的に置き換えます。

3. ハイブリッド検索（ベクトル + BM25 + グラフ）

記憶の取得には3つの手法を組み合わせたハイブリッドスコアリングを使用します：

最终得分 = 0.4 × BM25关键词得分 + 0.6 × (语义相似度 × 衰减强度) + 图谱加成

なぜベクトル検索だけではないのか？

3つの融合効果：「データベースのパフォーマンス」で検索すると、直接パフォーマンスに言及した記憶だけでなく、グラフを通じて関連するインデックス戦略やキャッシュの決定なども見つけ出せます。

4. 意味グラフ

すべての記憶は保存時に、既存の記憶と意味的な関連付けを自動的に行います：

• すべての既存記憶とのコサイン類似度を計算

• 類似度 ≥ 0.40 の場合に双方向のエッジを作成（重み = 類似度 × 0.5）

• 各記憶は最大5つの最も類似した隣接ノードと接続

グラフの2つの重要な役割：

連想発見：検索時にヒットした記憶からBFS（最大深度2）を行い、エッジを辿って関連記憶を見つけます。たとえ検索語と直接的な意味的類似性がなくても、人間のように「あれからこれを連想する」ことが可能です。

連鎖保護：ある記憶自体の強度が閾値を下回っても、その隣接ノードに強力な記憶が存在する場合、その記憶は保持されます。重要な知識同士をつなぐ橋渡しである可能性があるためです。

5. 自動統合と淘汰

バックグラウンドで12時間ごとにメンテナンスタスクが実行されます：

統合（Consolidation）：

1. 類似度 ≥ 0.70 の記憶クラスターを特定

2. 最も重要度が高いものをメイン記憶として保持

3. 他の記憶の固有情報を統合

4. ベクトルとグラフ関係を再計算

5. 統合された冗長な記憶を削除

淘汰（Pruning）：

1. 各記憶の現在の強度を計算

2. 強度 < 0.05 かつ 連鎖安全チェックを通過 → 削除

3. 強度 < 0.05 だが隣接ノードが強力 → 保持（連鎖保護）

これにより、メモリライブラリは自動的にスリムに保たれます。手動でのクリーンアップは不要で、無限に肥大化することもありません。

エンジニアリング状態ハブ（v0.4）

Engramは単なる「情報を保存する」メモリプラグインではなく、エンジニアリングプロセスを理解する状態レイヤーです。

失敗の要因分析（track_failure）

エージェントがバグやテスト失敗、デプロイ問題に遭遇した際、構造化された形式で記録します：

# MCP 调用
track_failure(
    error="CSRF token missing on checkout",
    component="payment",
    severity="critical",        # → importance=0.9
    root_cause="middleware not loaded after refactor",
    fix="re-add CsrfMiddleware to pipeline",
    related_test_ids=["test_checkout_01", "test_payment_csrf"]
)

設計決定：

• severity は自動的に importance にマッピング（critical=0.9, major=0.7, minor=0.5）

• 固定で failure カテゴリを使用（最速の減衰 λ=0.35、半減期約11日）— 環境は変化するため、古い失敗記録は自然に期限切れになります

• component フィールドにより、モジュールごとの統計集計をサポートし、高リスク領域を迅速に特定

進捗追跡（track_progress）

セッションを超えて機能やタスクの状態を追跡します：

track_progress(
    feature="login-flow-refactor",
    status="in_progress",       # → importance=0.8
    completion=60,
    blockers=["waiting for API design review"],
    quality_score=0.85,
    notes="auth module done, UI pending"
)

設計決定：

• status は自動的に importance にマッピング（blocked=0.9 最高, done=0.5 最低）

• 固定で strategy カテゴリを使用（最遅の減衰 λ=0.10、半減期約38日）— 進捗状態は最も長く記憶すべきです

• 完了した機能は自然に減衰して消えるため、手動削除は不要です

エンジニアリング指標（memory_stats 強化）

memory_stats はエンジニアリングデータを自動的に集計します：

{
  "total": 42,
  "categories": {"fact": 20, "failure": 8, "strategy": 14},
  "engineering": {
    "failures": {
      "total": 8,
      "by_component": {"auth": 5, "payment": 3},
      "by_severity": {"critical": 2, "major": 6}
    },
    "features": {
      "total_tracked": 4,
      "active": {
        "login-refactor": {"status": "in_progress", "completion": 60},
        "payment-fix": {"status": "blocked", "completion": 30}
      }
    }
  }
}

技術アーキテクチャ

┌──────────────────────────────────────────────┐
│              MCP Client                      │
│      (Claude Code / Cursor / ...)            │
└──────────────────┬───────────────────────────┘
                   │ stdio (JSON-RPC)
┌──────────────────▼───────────────────────────┐
│              server.py                       │
│  8 MCP tools  ·  APScheduler (12h 维护)      │
├──────────────────────────────────────────────┤
│                                              │
│  ┌─ 写入路径 ──────┐  ┌─ 读取路径 ──────┐    │
│  │  resolve.py     │  │  retrieve.py    │    │
│  │  去重/矛盾消解   │  │  混合检索+评分   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
│  ┌─ 维护路径 ──────┐  ┌─ 统计路径 ──────┐    │
│  │  consolidator   │  │  decay.py       │    │
│  │  聚类合并+剪枝   │  │  遗忘曲线+强度   │    │
│  └─────────────────┘  └─────────────────┘    │
│                                              │
├──────────────────────────────────────────────┤
│  embedding.py          │  graph.py           │
│  768d / 1024d 向量编码  │  NetworkX 语义图谱  │
├──────────────────────────────────────────────┤
│              db.py — DuckDB                  │
│  向量存储  ·  BM25 全文索引  ·  CRUD          │
└──────────────────────────────────────────────┘

数据文件（~/.engram/）：
├── memories.duckdb     # 向量数据库（单文件，零运维）
├── graph.json          # 语义图谱（JSON 序列化）
└── model_cache/        # 嵌入模型缓存

MCPツールインターフェース

重要度の目安

ユーザーへのメリット

1. エージェントがあなたを「真に理解」する

毎回、技術スタックやコーディング習慣、プロジェクトの背景を説明する必要はありません。エージェントはあなたがJavaではなくGoを好むこと、プロジェクトがモノレポであること、先週のアーキテクチャ決定を記憶しています。

2. 知識が自然に進化する

矛盾解消により、エージェントの認識は常に最新です。ReactからVueに切り替えましたか？一度の対話で自動的に更新されます。「エージェントが知っておくべきこと」リストを手動で管理する必要はありません。

3. 運用ゼロ

• 古い記憶の手動クリーンアップ不要 — 忘却曲線が自動的に淘汰

• 重複の手動マージ不要 — 統合機能が自動処理

• データ肥大化の心配不要 — 12時間ごとの自動メンテナンス

• 外部サービス不要 — DuckDB単一ファイル、すぐに使用可能

4. 完全なプライバシー

すべてのデータは ~/.engram/ に保存され、ネットワーク接続やアップロードは行われず、クラウドサービスにも依存しません。埋め込みモデルもローカルで動作します。あなたの記憶はあなたのものです。

5. 連想的な発見

グラフ拡張により、エージェントは「検索したもの」を返すだけでなく、意味的な関連性を辿って直接一致しない知識も見つけ出します。同僚に質問したとき、単に回答するだけでなく「そういえば、これは前回のあの件と関係があるよ」と教えてくれるような体験です。

6. 使うほど賢くなる

想起強化メカニズム：繰り返し呼び出される記憶は強度が上がり、減衰が遅くなります。エージェントは、どの知識があなたにとって最も価値があるかを自動的に学習します。

クイックスタート

# 安装
pip install mcp-engram

# 初始化（下载模型、创建数据库）
engram-setup

# 按照输出提示将配置块添加到 Claude Code 配置中

Claude Code 設定

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "env": {
        "HF_ENDPOINT": "https://hf-mirror.com"
      }
    }
  }
}

CLAUDE.md 統合

プロジェクトの CLAUDE.md に以下を追加：

## Memory Rules

### Step 1 — 先回忆再行动
每次任务开始时，用请求中的关键词调用 `recall_memory`。

### Step 2 — 学到新东西就存
| 情况 | 操作 |
|------|------|
| 全新知识 | `store_memory(content, importance)` |
| 补充已有 | `update_memory(memory_id, merged_content)` |
| 推翻已有 | `update_memory(memory_id, new_content)` |

環境変数

主要閾値クイックリファレンス

LoCoMo ベンチマーク評価

LoCoMo（Snap Researchの長期対話メモリベンチマーク）に基づく検索品質評価。LoCoMoはMem0/Zep/Memobase/MemMachineなどで使用される統一評価基準です。

評価設定

• データセット：locomo10.json（2/10 conversations, 233 QA, adversarialを除く）

• 検索：recall() top-k=5

• LLM：DeepSeek-V3.2 / GLM-5.1（注：ベースライン製品はGPT-4o-miniを使用）

• 指標：Token-level F1（LoCoMo公式指標）+ Hit@5（LLM非依存の検索ヒット率）

Turn Mode — 最適設定（bge-m3 + bge-reranker-v2-m3, DeepSeek-V3.2）

2段階検索：recall top-50 → CrossEncoder rerank to top-5, importance=1.0 修正重み比

Turn Mode — 最適化パス（DeepSeek-V3.2）

4段階の最適化で累計 F1 +50.3%（0.29 → 0.44）、Hit@5 +26.2pp（51.5% → 77.7%）。

Turn Mode — LLM比較（all-mpnet-base-v2）

Observation Mode（抽象的な assertive facts）

業界ベースラインとの比較

結論：4段階の最適化 mpnet(0.29) → bge-m3(0.35) → +reranker(0.39) → +weight fix+r50(0.44)。Hit@5: 51.5% → 77.7%。Mem0(0.67) との差を 56% から 35% に縮小。

Best Config クイックリファレンス

推奨設定：bge-m3 (1024d) + bge-reranker-v2-m3 2段階検索

指標	値	説明
Overall F1	0.4383	Token-level, DeepSeek-V3.2
Overall Hit@5	77.7%	純粋な検索ヒット率, LLM非依存
Temporal Hit@5	95.2%	時系列問題で優れたパフォーマンス
最適化幅	F1 +50.3%, Hit +26.2pp	4段階累計（初期mpnet比）

重要パラメータ：recall top-50 → rerank to top-5, importance=1.0 修正重み比。 ローカルデプロイでクラウド依存ゼロ、GPT-4o-miniを使用するMem0との差を35%まで縮小。

開発

git clone https://github.com/hugfeature/engram.git
cd engram
pip install -e ".[dev]"
pytest tests/ -v

ライセンス

MIT