ariel-memory

a-memory

AI エージェントは忘れてしまいます。a-memory が記憶させます。 ハイブリッド検索と実際のナレッジグラフを備えた、4 層構造のエージェントメモリです。すべて通常の SQLite ファイルに保存されます。クラウド不要。外部 API 不要です。

PyPI からも利用できます：pip install a-memory — オプションの追加機能：実際の多言語埋め込みには a-memory[embeddings] を使用します。

---

なぜ SQLite なのか？

他のメモリサーバーはすべて、エージェントのデータをクラウド API 経由で送信するか、別途ベクトルデータベースを必要とします。

a-memory は、すべてをお使いのマシン上の SQLite ファイルに保存します。

• インフラストラクチャ不要。 Docker、データベースサーバー、埋め込み API キーは不要です。
• ネットワーク外へのデータ流出ゼロ。 エアギャップ環境でも動作します。
• 設計上、各レイヤーは分離されています。 ユーザーの事実情報とエージェントのアイデンティティが、同じ名前空間を共有することはありません。
• 1 つのディレクトリがメモリ全体です。 cp でバックアップし、rsync で同期できます。

---

開発の背景

a-memory が解決する 3 つの問題：

① エージェントの自己進化 — AI がセッションをまたいで同じ間違いを繰り返さなくなります。専用のエージェントレイヤーに判断、エラー、修正を記憶し、1 時間ごとの統合処理によって重要な情報を長期的な事実情報へと昇格させます。

② ユーザーペルソナの継続性 — 数週間会話が途切れても、エージェントは相手が誰なのかを把握しています。好み、履歴、感情的な背景はユーザーレイヤーに保存され、エージェントのアイデンティティとは分離されます。

③ プロジェクトの継続性 — project はプロジェクトごとのコンテキストを追跡します。根拠と結果を含む判断、アーティファクトのマップ、graphify を活用したコードインデックスによって、新しいセッションでも前回の続きから作業を始められます。

---

はじめに

pip install a-memory
a-memory          # MCP server on stdio — connect from any MCP client

サーバーはこれらがなくても動作しますが、プライバシーゲート（hooks による取り込み）とグラフマイナーには、spaCy の NER モデルが 2 つ必要です。どちらも PyPI にはありません。en-core-web-sm は PyPI で 404 になり、ru-core-news-sm は無関係なプレースホルダーです。そのため、ホイール URL からしかインストールできません。また、ホイール URL は依存関係にできません。PyPI が、メタデータに直接 URL を含むディストリビューションを拒否するためです。パッケージがすでに把握している URL からモデルをインストールするには、次のコマンドを実行してください。

a-memory-ner                 # install (console script, ships in the wheel)
a-memory-ner --check         # report what is missing, install nothing

ソースのチェックアウトからは、python scripts/install_ner_models.py でも同じコマンドを実行できます。

インストールを省略しても問題ありません。ゲートはフォールバックし、失敗する代わりに degraded と報告します。

MCP クライアントの接続先を設定してください。

{
  "mcpServers": {
    "a-memory": {
      "command": "a-memory"
    }
  }
}

ダッシュボード付きの HTTP トランスポート：

a-memory --transport http --port 8000 --dashboard

または、ソースから実行します。

git clone https://github.com/Cipher208/a-memory.git
cd a-memory
uv sync
uv run ariel-memory

---

7 つのプリミティブ

エージェントが利用するツールは、意図ごとに動詞が 1 つずつの 7 つだけです。イベントブリッジ（6 つの動詞＋memory_hook）を備えており、ツール選択に迷うことはありません。

プリミティブ	意図	機能
think	記憶する	重要度、感情、関連性に基づいて、コンテンツを適切なレイヤー（L4 の事実／L3 のエピソード／wiki／グラフ）に振り分けます
dream	想起する	すべてのレイヤー（FTS5＋バイナリー埋め込み＋wiki＋グラフ）を横断してハイブリッド検索し、トークン予算に合わせたダイジェストを返します
forget	手放す	Shadow Bin にアーカイブしながら、コンテキストに応じて削除します（完全一致／あいまい一致／最近の項目）。何も書き込まないドライランと、ビンに保持された内容を元に戻す取り消し機能も備えています
evolve	成長する	エージェントの性格やルールの進化を記録します
project	継続する	プロジェクトごとの ID、意思決定ログ、アーティファクトマップ、コードインデックスを管理します
wake_up	再開する	新しいセッションで、1 回の呼び出しで記憶を呼び起こします。想起プロトコルを順にたどる代わりに、重要な情報を一度に取得できます
memory_hook	通知する	イベントブリッジです。ライフサイクルイベント（session_started、new_message、…）を 1 つ発生させ、外部ハーネスが独自のスケジュールで ariel にメモリを渡せるようにします

簡単なデモ — Python MCP クライアント：

# think — routed to the right store automatically
await session.call_tool("think", {"text": "User prefers dark mode", "layer": "user"})

# dream — finds it across every store, a week later
res = await session.call_tool("dream", {"query": "dark mode preference"})
print(res["summary"])

合計 66 個の詳細な操作があり、一貫性のあるオプトイン方式の階層に分類されています。デフォルトで公開されるのは 7 つのプリミティブです。context（想起プロトコル、/new セッションの要約、スマートなコンテキスト予算、ステアリングヒント、ツール出力の圧縮）、insight（Memory Query DSL、出典に基づく事実の責任追跡、品質ループ、振り返り、統計）、write（型付きメモリスキーマ、宣言型ルールエンジン、スクラッチパッド、反実仮想、エピソード）、さらに wiki と review（変更の段階的適用、memory_report_card、daily_brief）を追加できます。通常の稼働中エージェント向けの構成は、1 つのプリセット ARIEL_EXPOSE=agent（59 個のツール）で、primitives,context,insight,write,wiki,review と同等です。残りの 7 個は管理者向けで、ARIEL_EXPOSE=operator（66 個）または all を指定します。

階層の変更履歴。古いガイドでは brief 階層が記載されているため、ご注意ください： これは 2026-09-07 に廃止されました。現在、daily_brief は review に含まれます。ドキュメントに brief を指定するよう書かれている場合、その記述は 1.10 より前のものであり、そのトークンは単に無視されます。

⚠️ 環境変数のサニタイズに関する注意点（stdio）： MCP クライアントは stdio サーバーにサニタイズ済みの環境変数を渡します。シェルのプロファイルで ARIEL_EXPOSE を設定しても効果はありません。階層セットはMCP クライアントの設定（サーバーエントリーの env ブロック。［設定ガイド］(docs/getting-started/configuration.md)を参照）で定義してください。サーバーは起動時に解決済みのツール構成（tool exposure: N/M tools）をログに出力します。エージェントにプリミティブしか見えていないと報告された場合は、まずその行を確認し、その後クライアントセッションを再起動してください（ツールリストはセッションごとにキャッシュされます）。

---

機能

カテゴリ	内容
🧠 記憶	L1 Reflex（アトミックな永続化）→ L2 Sessions → L3 Episodic → L4 Core、重要度スコアリング、TTL ポリシー付きの型付き記憶種別、レイヤー分離；双時間的な事実履歴（is_current ビューで置き換えられた行を全体から除外、changed_since による差分ポーリング、コールドアーカイブ後も保持される生ソースへの詳細確認）、ホット／ウォーム／コールドの各階層を持つハッシュチェーン型 L0 ジャーナル；/recall プロトコル（複数軸＋開示トリガー）、セッション継続の要約（/new 復旧パック）、1 回の呼び出しで使える wake_up、セッションブリーフに表示される未解決の質問のレジストリ、ステアリングヒント、ツール出力の圧縮＋想起検証、出典に基づく事実の責任追跡、Memory Query DSL（ファセットタグ）、型付き記憶スキーマ、宣言型ルールエンジン、スマートなコンテキスト予算（重み付きトークン下限）、振り返り、反実仮想、was_useful 品質ループ、運用者向けの診断／修復＋整合性スコアを含む 66 個のツール（段階的に公開；エージェントプリセットでは 59 個、デフォルトでは 7 個のプリミティブ）
🔍 検索	FTS5＋MIB バイナリー埋め込み＋ハイブリッド RRF ランキング、複数ソースの統合（RAG＋Wiki＋Episodic＋Core＋Graph）、EDM/ITS デュアルルート再ランキング（情報利得スコアリング、№11 評価で勝者）、セマンティック重複排除ゲート（コサイン類似度、オプトイン）、RU レンマのキー正規化（pymorphy3）、反対シグナルによる悲観的評価、クエリごとの最小・最大乗数と記憶種別の重みを用いた ACT-R アクティベーション、埋め込みパスのサーキットブレーカー（ハッシュへのフォールバックによる正常な継続）、決定論的検索モード、夢のダイジェスト
🕸️ グラフ	エピステミック知識グラフ＋時間軸タイムライン、型付きノードとエッジ、BFS トラバーサル、1 ホップの GraphRAG 拡張（出典を考慮したエッジフィルター）、自己維持型マイナー 12 個（次数上限によるハブ化防止、メタデータのバックリンクを持つ wiki↔fact の出典ブリッジ、共検索、結果ゼロのギャップ）、孤立アンカーの GC、夜間のギャップレジストリ――さらに、そのレジストリを読む仕組みもあります：レジストリは各ギャップが再確認された回数（seen_count）を記録し、最も長く残るものをセッションブリーフに表示するため、誰も読まない表ではなく、エージェントが自分自身の未回答の質問を確認できます。オプトインの HDBSCAN 埋め込みクラスタリングと Louvain の一致判定
📁 プロジェクト	意思決定ログ（何を／なぜ／結果）、成果物マップ、graphify コードインデックス――セッション間で保持されます
⚡ 自動フック	プッシュモデルの記憶：エージェントごとのデーモンが会話を監視し、ariel が重要な情報を自動で保存します――重要度しきい値（EMA による適応）、段階的な変更管理（提案 → レビュー → 適用 → 差し戻し）、DREAM: マーカー、セッション開始時の注入、ギャップレポート、コンパクションを考慮した再水和（ドリフトログ＋サルベージ＋一度限りの再水和ブロック）、ru-NER プライバシーゲート（キリル文字の PERSON／ORG／LOC をマスキング）。ネイティブ統合：Hermes はプロセス内 MemoryProvider プラグインとして ariel を実行し、MiMoCode はフォークフックプラグインを介して、CowAgent はコードレベルのフックを介して統合します。配線ガイド →
🎯 スキル	スキル＝記憶：エージェントが読む Markdown ページ（第一級の skill wiki タイプ）、段階的開示（関連ファクトの補完を伴う wiki_list → wiki_search → wiki_read）、4KB のリント上限、DREAM: skill: エピソードからの昇格、エージェント間の共有 SSOT 同期、使用状況に基づく強化――スキルガイド →
🔐 セキュリティ	認証／Saga シークレットのための NaCl SecretBox（XSalsa20-Poly1305）エンベロープ暗号化、マスターキーのチェーン、レート制限
🛠️ 運用	自動バックアップ cron、Saga ロールバックパターン、Prometheus メトリクス、読み取り専用レプリカ、1 時間ごとのセルフメンテナンス（減衰＋統合＋自動 VACUUM）
🌐 Wiki	FTS5 でインデックス化された Markdown ファイル――Obsidian／VS Code で編集し、MCP から検索可能、6 つの分析的視点（wiki_summarize）、保存時のスキーマリント、外部ディレクトリとの同期

---

アーキテクチャ

graph TD
    A[LLM Agent] -->|MCP Protocol| B[mcp_server]
    B --> C{Importance Scoring}
    C --> D[L1: ReflexBuffer]
    D --> E[L2: SessionStore]
    E --> F{EmotionTrigger?}
    F -->|high emotion| G[L3: EpisodicMemory]
    F -->|normal| H[L4: CoreMemory]

    B --> I[RAG Engine]
    I --> J[FTS5 Search]
    I --> K[MIB Binary Search]
    I --> L[Hybrid RRF Ranking]

    B --> M[Wiki System]
    M --> N[.md Files]
    M --> O[SQLite Index]

    B --> P[Knowledge Graphs]
    P --> Q[Epistemic Graph]
    P --> R[Temporal Graph]

    B --> S[Project Store]
    S --> T[Decisions / Artifacts / Code Index]

    U[Hourly Sweep] -->|consolidate| G
    U -->|promote| H
    U -->|auto-VACUUM| V[(SQLite)]

---

比較

	a-memory	mem0	letta (memgpt)	chroma
MCP ネイティブ	✅ 7 つのプリミティブ	❌ MCP サーバーなし	❌	❌
レイヤーの分離	✅ ユーザーとエージェントの名前空間	❌	❌	❌
ローカルのみ（クラウド不要）	✅ SQLite — インフラ不要	⚠️ API またはセルフホスト Docker	❌ LLM API が必要	✅ ローカル OSS ＋ Cloud オプション
独自のセマンティック検索（API 不要）	✅ FTS5 ＋ MIB バイナリハイブリッド	⚠️ BM25 ＋ エンティティ（LLM に依存）	❌ LLM のみ	⚠️ Cloud のみでハイブリッド
ナレッジグラフ	✅ 型付きノード ＋ エッジ ＋ 時系列タイムライン	⚠️ エンティティのみ	❌	❌
エンベロープ暗号化（シークレット）	✅ NaCl SecretBox（認証／Saga のシークレット。メモリーデータは SQLite に平文で保存）	❌	❌	❌
ライフサイクルフック	✅ 19 個の名前（ユーザー用 12 個 ＋ エージェント用スロット 13 個）、レイヤーごと、設定で制御	限定的	限定的	なし
セルフメンテナンス	✅ 1 時間ごとの統合 ＋ 自動 VACUUM	❌	❌	❌
バックアップ／復元	✅ 自動 cron ＋ Saga ロールバック	❌	❌	❌

注（2026 年 9 月）：mem0 はセルフホスト Docker イメージと、ハイブリッド BM25 ＋ エンティティ検索を備えたマネージドクラウドを提供するようになりました。chroma は 29k★で、Cloud ティアにハイブリッド検索 ＋ FTS5 を追加しました（OSS サーバーは引き続きベクトル検索のみです）。a-memory の差別化要素として残るのは、インフラ不要の SQLite（Docker 不要）、NaCl で暗号化された認証／Saga のシークレット、レイヤーの分離、1 時間ごとのセルフメンテナンス、時系列グラフのタイムラインです。

---

ロードマップ

• レイヤーを分離した4層メモリ階層
• ハイブリッド検索（FTS5 + MIB バイナリ埋め込み）
• ナレッジグラフ（認識論的 + 時間的）
• 毎時の統合スイープ + DB の自己メンテナンス
• mcp 2.x ネイティブ SDK
• リポジトリ名を Cipher208/a-memory に変更。PyPI パッケージを公開済み（pip install a-memory）
• 時間軸のタイムラインをエンドツーエンドで接続（think/evolve/project イベント + dream の最新ダイジェスト）
• Dream サイクルへの注入 + 自動生成される CONTEXT.md スナップショット（厳選したコンテキスト + 6 つの wiki の視点 + 直近のエピソードをレイヤー別、エージェント別に表示）
• Phase C — 自動フックの要（プッシュ型メモリ：エージェントごとの会話デーモン、外部イベントディスパッチャー、重要度に応じた自動保存、レビュー／復元可能なステージ済み変更、dream マーカー、セッション開始時の注入、ギャップレポート。ガイド）
• Phase D — コンパクションを考慮した再水和（ドリフトログ + 要約器への救済情報の投入 + 1 回限りの再水和ブロック。MiMoCode プラグイン / Hermes ネイティブ MemoryProvider / CowAgent フック — 統合ガイド）
• Phase D — /recall プロトコル（複数の軸に基づく比例的な想起：マーカー → セッション → 意味検索 → 展開 → 日単位。Hermes のターンごとのプリフェッチを実行）
• Phase D — スキル = メモリ（Markdown スキルを第一級の wiki タイプとして扱い、段階的な情報開示 wiki_list → wiki_search → wiki_read、4KB の lint 上限、昇格パイプライン、共有 SSOT 同期、使用状況に基づく進化を実現 — スキルガイド）
• Phase D — ワーキングメモリ + メタメモリ（エージェントのスクラッチパッドをセッション開始時に再注入、決定論的な振り返り、重み付き下限を用いたスマートなコンテキスト予算、反実仮想メモ、was_useful による品質フィードバックループ）
• Phase D — メモリツール D1.2-D1.9（セッション継続性の要約 + 誘導ヒント、ツール出力の圧縮 + 想起の検証、出典に基づく事実の帰属、Memory Query DSL、型付きメモリスキーマ、宣言型ルールエンジン。一貫性のある ARIEL_EXPOSE の段階：context / insight / write）
• Phase E — 強化と仕上げ（3 つのウェーブにわたる 18 項目）：耐久性 — アトミックな L1 永続化（temp→fsync→os.replace）+ インスタンスごとのリングファイル、埋め込みモデルのパスを保護するサーキットブレーカー（3 回失敗すると 30 秒間オープンし、ハッシュフォールバックで想起を継続）、最小権限の wiki ルート + パストラバーサルに安全なバックアップ復元。運用 — memory_diagnose/memory_heal（DB／マイグレーション／L1 ファイル／ブレーカーチェック + 再マイグレーション／ブレーカーのリセット／消去）、レポートカードへの整合性スコア追加、プロバイダーのプロンプトキャッシュ向け <cache:break> マーカー + 安定項目を優先する注入順序。検索 — ファセット付きタグクエリ（dimension:value、同じ次元は OR／次元をまたぐ場合は AND）、ACT-R スコアリングでのメモリ種別の重み付け、開示トリガー（「X のとき、Y を提示」する想起側のルール）。接続 — 実際に動作する context_threshold/memory_pressure エミッター（Hermes プラグイン + 自動フックデーモン）、on_turn_end イベント、復元可能な wiki_write のステージ済み変更、遷移レベルの統合復元、memory_graph_add での因果リンク生成。検証 — DREAM マーカーをメッセージ開始位置に固定（ドキュメント断片による誤検出を排除）、コンパクション後の意味監査（L4 セットによるエピソードのカバー率）
• Phase F — L0→L4 パイプライン（双時間の事実区間、CLACK エクスポート対応のホット／ウォーム／コールド L0 階層、SHA-256 による取り込み重複排除、ハッシュチェーンジャーナル、出典の詳細追跡）
• Phase G — 自己接続型グラフ（12 個の決定論的マイナー：セッション、マーカー、出典、共検索、エンティティ、結果ゼロの質問、wiki↔事実ブリッジ）
• Phase H の仕上げ — EDM/ITS デュアルルート再ランキング + 評価ハーネス（NDCG@5、ドリフトスコア、ネガティブコントロールプロトコル、LongMemEval-S アダプター）
• S17 Stage-1 の残項目 — 決定論的検索モード、ENGRAM 手続き型種別、AdaptiveRAG の事前ゲート（LLM を使わないクエリ特徴量 27 個）、EMA 重要度ゲート、反対シグナルのエイリアス、SHA-256 による L0 重複排除、結果ゼロのマイナー、ru-NER プライバシーゲート
• S18-19 ウェーブ（15 項目）— グローバルな is_current ビュー + changed_since 差分モード、クエリごとの ACT-R min-max、ブロックごとの max_chars、意味的重複排除ゲート、チャネル単位のソース、3 択の競合契約（置換／保持／注釈）、孤立アンカーの GC、夜間ギャップレジストリ、エージェントごとのハーネスブレーカー、出典エッジフィルター、wiki↔事実のメタデータバックリンク、wiki_read による関連事実の補完、RU レンマキー（pymorphy3）、2 クラステキスト分類パイロット（フラグで有効化）、S17 の追加項目 8〜11（コールドアーカイブの詳細追跡、確認レイヤー、ジャンクベクトル検出器、HDBSCAN クラスタ）、B6 アンチハブ次数上限
• S20 評価 — MINI + LongMemEval-S（50 問刻み）での第 11 番アブレーション。完全なデュアルルート構成が両方のデータセットで優位となり、公表済みベースラインと比較（GPT-4o の長文コンテキスト部門で ChatGPT-memory を上回る）。密な e5-small の実行 3：この分割ではハッシュ方式に対する同等性の向上なし — 本番ではハッシュ方式を維持
• 強化ウェーブ（1.12.0） — 書き込み側の話者レイヤーの不具合を修正（distill_and_route は話者が必要な箇所で種別を読み取っていた）し、すでに誤分類された 65 行を出典情報に基づいて一括削除。ハーネスの定型文や複合語（pre-commit、mergeCommit）に恒久的なラベルを付けなくなった種別分類器。S18 で読み取り側が計画されていたものの実装されていなかったギャップレジストリ。L3 の基準ではなく L4 の基準に照らして L4 の期待値を測定（diff_gap バックログの 71% は、この誤った数値が原因でした）。そして、失敗できなかった quality ゲートが正しく失敗するようになりました — ピン留めされていないスキャナーが JSON スキーマをひそかに変更していたためです
• README のスクリーンショット／asciinema デモ
• 決定論的スイープに基づくLLM 支援型統合
• Stage 2 — ツールサーフェスの再設計（スロットシステム、URI キー、注入／キーの統合 — A-remainder とともに計画中）
• LongMemEval の 500 問フル分割 + 密ベクトル対応の閾値再学習（e5-small との同等性は確認済みですが、50 問刻みでは優位性なし）

貢献

プルリクエストを歓迎します！CONTRIBUTING.mdをご覧ください。

ライセンス

MIT © Cipher208

---

⭐ このプロジェクトが役に立ったら、GitHubでスターを付けてください。