memory-os解説｜AIエージェントの記憶をローカル完結でOS的に階層管理する7層メモリ基盤OSS

この記事ではHermes Agent向けの記憶基盤に絞って解説します。 AIエージェントそのものの全体像は AIエージェントとは｜2026年の定義・仕組み・主要OSS を先に押さえると、本記事の位置づけが掴みやすくなります。

30秒で理解するmemory-os

memory-osは、AIエージェントに永続的な記憶を持たせるためのローカル完結型の基盤だ。 要点を先に並べる。

・memory-osはHermes Agent専用の記憶レイヤー。GitHubで約1,151★、ライセンスはMIT、実装はPythonとShell
・記憶インフラ（Qdrant＋Redis＋ARQ Worker＋SQLite）はすべて自分のマシン上で動く。記憶の置き場が外部SaaSに出ない
・7つのレイヤーで構成され、平文ファイル・全文検索DB・構造化ファクト・ベクトルDB・自己更新Wikiまでを束ねる
・最大の独自性はLayer 7「Ground Truth階層」。注入された記憶をエージェントに無視させないための識別レイヤーだ
・埋め込みやLLM抽出は任意のプロバイダ（OpenRouter／OpenAI／Anthropic／Ollama）に向けられる。プロバイダのロックインを避ける設計

LLMのコンテキスト長が伸びても、「エージェントがユーザーを覚えている」状態は別に設計しないと成立しない。 memory-osはその記憶層を、クラウドではなく手元のインフラに外出しするための選択肢のひとつだ。 本記事は、既存のAIメモリOSSと並べて、これがどのレイヤーを担当する道具なのかを切り分ける。

memory-osとは（作者・スター・ライセンス・スコープ）

memory-osは、ブラジル・ペロタス在住のClaudio Drews氏が公開したOSSだ。 GitHubプロフィールによると本人は臨床心理士で、心理学とAI・ロボティクスの接点を関心領域に挙げている。 プロジェクトは2026年5月31日に公開された。

リポジトリの実測値を並べる。

・スター数：約1,151（執筆時点）
・フォーク数：109
・未解決Issue：6件
・ライセンス：MIT
・主要言語：Python（約37万行相当）とShell（約7.5万行相当）、Dockerfile
・主要コントリビュータ：ClaudioDrews（12コミット）、Davidsoff、brian-doherty、aaronjmars

バージョンはGitHubのReleasesにタグが切られておらず、READMEとCHANGELOG上でv0.2.0として管理されている。 v0.2.0ではcurl ... | bashによるワンコマンド導入と、Issueテンプレート・PRチェックリスト・コントリビューションガイドの整備、監査由来の20件超の修正が入った。

スコープを誤解しないために、最初に依存関係を押さえておく。 memory-osは単体で完結するメモリAPIではない。 Hermes Agent（NousResearch/hermes-agent、約196,000★、MIT）というエージェント本体に対して、記憶機能を丸ごと足すプラグイン群だ。 記憶の注入はHermesのプラグインフックに乗り、Layer 7の振る舞い矯正はHermesの識別ファイルを書き換えて効かせる。 さらに、横断記憶を担うIcarus Plugin（上流：esaradev/icarus-plugin、約137★、MIT）の改変フォークを同梱する。 このフォークは上流非互換で、後述するLLM抽出や多ソース注入が足されている。

なぜ「OS的な記憶管理」が必要か

memory-osが解こうとしている課題は、保存と検索だけではない。 作者が本番セッションで繰り返し踏んだのは、「記憶は注入されているのにエージェントが使わない」という症状だった。

Layer 7のドキュメントには、その症状が具体的に記録されている。

・[qdrant]ブロックがプロンプトに入っているのに、エージェントはQdrant APIを叩いて中身を再確認する
・[fabric]エントリが注入済みなのに、fabric_recallを呼んで同じ情報を探し直す
・セッション履歴が注入済みなのに、session_searchで再発見しようとする
・ファクトが注入済みなのに、fact_storeを再度プローブして裏取りする

作者はこれを「memory-zero behavior（記憶ゼロ挙動）」と呼ぶ。 注入は完璧でも、再発見のたびにトークンとコンテキストと時間が燃える。

根本原因は識別ファイルの序列にあった。 memory-osは記憶をプロンプトに注入していたが、HermesのSOUL.mdとrulebook.mdに「注入記憶」の順位が書かれていなかった。 順位がなければ、注入された文脈は暗黙に「任意の提案」扱いになり、端末出力や公式ドキュメントより下に置かれる。

ここがmem0やsupermemoryのような保存・検索APIとの分岐点になる。 保存と検索の質を上げても、エージェントが注入記憶を信用しなければ価値は出ない。 memory-osは、保存・検索（Layer 1〜6）に加えて、エージェントの判断序列そのもの（Layer 7）まで設計対象に含める。

アーキテクチャ全体像

memory-osのデータの流れは、Hermesの2つのフックを軸に回る。 pre_llm_callで4ソースから関連記憶を集めて注入し、post_llm_callとon_session_endで学習を抽出して書き戻す。 全体像を図にする。

注入には無駄打ちを抑える工夫が複数入っている。 各ソースは関連度のしきい値でゲートされ、セッション単位の重複排除で同じ文脈が二度入らないようにする。 社交辞令フィルタは「ok」「ありがとう」のような些末なメッセージで検索と埋め込みを丸ごとスキップする。 作者の言葉では「パディングなし、消火栓のような垂れ流しもなし。LLMには必要なものだけを渡す」という方針だ。

7つのレイヤーを一段ずつ

memory-osの「7層」は、保存形式の異なる記憶を役割ごとに積み上げた構造だ。 下の図が階層の全体像になる。

各レイヤーの中身を順に見ていく。

Layer 1 ワークスペースは、MEMORY.md・USER.md・CREATIVE.mdの3つの平文マークダウンだ。 毎ターン、システムプロンプトに丸ごと注入される。 MEMORY.mdはエージェントのmemoryツールが§区切りで書き、USER.mdは人間が手書きするユーザープロフィール、CREATIVE.mdはIcarusがエージェントの学びや未解決の問いを書く。 かつてIcarusがMEMORY.mdを毎セッション上書きして§区切りを破壊する不具合があり、書き込み先をCREATIVE.mdに分離して解決した経緯がドキュメントに残っている。

Layer 2 セッションは、state.dbというSQLite＋FTS5のデータベースだ。 ゲートウェイが送受信した全メッセージを自動で記録し、session_searchで全文検索できる。 Icarusフォークはここに_search_sessions()を足し、pre_llm_callで過去会話を自動注入する。 FTS5は字面の一致なので、言語をまたぐ検索は弱いという制限もドキュメントに明記されている。

Layer 3 構造化ファクトは、memory_store.dbに信頼スコア付きでファクトを貯める層だ。 fact_storeツールがadd・search・probe・reason・contradict・update/removeの6アクションを持つ。 信頼スコアは初期値0.50のベイズ事前分布から始まり、取得回数と「役に立った」回数の比率で動く。 ファクトを参照したら同じターンでfact_feedbackを呼ぶのが必須ルールで、これを怠ると信頼スコアは飾りになり品質が静かに劣化する。

Layer 4 fabric（横断記憶）は、同梱されたIcarusフォークが担う。 セッション終了ごとに、YAMLフロントマター付きのマークダウンを1件以上生成する。 エントリ種別はdecision・resolution・note・code-session・review・research・taskなど。 fabric_recallやfabric_writeを含む16ツールと、4つのライフサイクルフックを持つ。 上流からの主な改変は、text[:500]の素朴な切り詰めをLLMによる構造化抽出に置き換えた点、fabric以外（Qdrant・セッション・ファクト）も自動注入する多ソース化、§区切り破壊の回避、些末メッセージの検出などだ。

Layer 5 ベクトルDBは、Qdrant 1.17系で動く。 コレクション名はknowledge_base、4096次元のコサイン類似度に加えてBM25のスパースベクトルを持つ。 デフォルト埋め込みはQwen3-Embedding-8Bで、多言語対応とMTEB上位の品質、OpenRouter経由で100万トークンあたり0.025ドルという低コストが採用理由に挙げられている。 検索は4段のフォールバック（ハイブリッド→密ベクトル→字句→SQLite）で、Qdrantが落ちても空振りせず順に劣化する。 週次の減衰スキャナと月次の意味的重複排除（コサイン0.92超を統合）で、古く重要度の低いAI生成点を自動的に整理する。

Layer 6 LLM Wikiは、raw/に置いた原文から概念・実体・比較のページを自動生成する自己更新ナレッジベースだ。 2系統のパイプラインが走る。 Wikiエージェントが定期cronでraw/を読んで構造化ページを作り、継続取り込みが毎時SHA-256差分を見てQdrantへ反映する。 ページはYAMLフロントマター、最低1つのウィキリンク、1行サマリ、出典リンクを必須とし、タグは閉じた語彙から選ぶ。

Layer 7 Ground Truth階層は、前章で見た振る舞い矯正の層だ。 SOUL.mdに4段階の真実序列を書き加える。

・第1位：端末出力（stdout/stderr/終了コード）はシステム状態の真実
・第2位：注入記憶（fabric/qdrant/sessions/facts）は文書化済み知識と過去決定の真実
・第3位：公式ドキュメントはAPIや設定の権威
・第4位：学習知識は参照のみ。常に1〜3で裏取りする

さらに2026年6月7日の追記では、序列を知っていても実行できないギャップが報告されている。 ルールはプロンプトに入って毎ターン読まれているのに、エージェントは「速く片付けるモード」に流れて検証を飛ばした。 その対策として、rulebook.mdに「在庫確認→照合→使用か宣言→実行」の4ステップを毎ツール呼び出し前に機械的に走らせるMandatory Pre-Action Protocolが足された。

ストレージと永続化の設計

memory-osのストレージは、用途ごとに3種類の置き場に分かれている。 この分担が、保存形式と検索特性の違いをそのまま反映している。

これらを支える常駐サービスはDocker Composeで3つ立ち上がる。

・Qdrant（qdrant/qdrant:v1.17.1）：ベクトルストア。ポート6333をlocalhostにのみ公開
・Redis（redis:7-alpine）：ARQのジョブキュー。パスワード必須、appendonlyで永続化
・ARQ Worker：埋め込み生成と取り込みの非同期処理。Qdrantとredisの両方がhealthyになってから起動する

ホスト側のPython依存はrequirements.txtに並ぶ。 qdrant-client、arq、redis、fastembed（ローカルでBM25スパースを生成）、httpx、aiohttp、pyyamlなどが中心だ。 埋め込みの次元EMBEDDING_DIMS=4096はQdrantコレクションのスキーマと一致させる必要があり、ずれると無言で品質が落ちる。

定期ジョブも記憶の健全性を保つ役割を持つ。 継続取り込みは毎時、減衰スキャナとバックアップは週次、デッドレターキュー監視とヘルスチェックは6時間ごと、といったスケジュールがドキュメントに示されている。

記憶の書き込みから検索・更新まで

記憶が実際にどう流れるかを、書き込み・検索・更新の3経路で追う。

書き込みは2系統ある。 ひとつはセッション終了時に、会話からLLMが構造化した学習を抽出してfabricに書く経路。 もうひとつは、人間がraw/に置いた原文を、Wikiエージェントが概念・実体・比較ページへ整形する経路だ。

取り込みは毎時のcronが担う。 SHA-256で差分を検出し、新規・変更ファイルだけをRedisキューに積む。 Workerが密ベクトル（Qwen3-Embedding-8B、4096次元）とスパースベクトル（fastembedのBM25、ローカル生成）を作り、重複チェック付きでQdrantにupsertする。

検索は4段フォールバックで、どこかが落ちても空にならない。 ハイブリッド検索（密＋スパースのRRF統合）を第一とし、スパースが失敗すれば密のみ、Qdrantが落ちればvault内の字句検索、最後はSQLiteのキーワードへ順に劣化する。

整理は自動だ。 週次の減衰スキャナが古く重要度の低いAI生成点を退避し、人間生成や重要度0.7超の点は除外する。 月次の意味的重複排除が、コサイン0.92超のニアデュープを統合する。

Hermes AgentとIcarusへの依存

memory-osを理解するうえで外せないのが、土台となる2つのプロジェクトだ。

Hermes Agentは、Nous Researchが公開するCLIベースの自己改善型エージェントだ。 リポジトリは約196,000★、MIT、2025年7月公開で、執筆時点の最新は0.16系にあたる。 プラグインはPythonファイルを~/.hermes/plugins/に置く形式で、config.yamlで有効化する。 memory-osが乗る4つのフック（pre_llm_call・post_llm_call・on_session_start・on_session_end）は公式ドキュメントに記載がある。 メッセージ用のゲートウェイ（hermes gateway）はCLIと別サービスとして動き、Layer 7の編集後はゲートウェイ再起動が要る。

Icarus Pluginは、esaradev氏による「self-memory and replacement models」のプラグインだ。 約137★、MIT。 fabricと呼ぶマークダウンファイル群で複数のHermesインスタンスが横断的に記憶を共有し、training_valueで学習用データを選別できる。 memory-osはこれを改変フォークとして同梱し、LLM抽出や多ソース注入を足している。 作者自身のフォーク（ClaudioDrews/icarus-plugin）も別リポジトリとして存在する。

MCP連携については、memory-osは記憶をHermesのフックで直接注入する方式を採るため、外部MCPサーバーとして記憶を公開する設計ではない。 この点は、CursorやClaude CodeにMCP経由でメモリを足すagentmemory（AIエージェント向け永続メモリMCP）のような道具とは前提が異なる。

mem0 / supermemory / claude-memory-compilerとの対比

AIメモリOSSは2026年に入って一気に増えた。 memory-osがどこに立つのかを、保存方式・実行形態・依存先・思想で対比する。

位置づけを図にすると、解いている問題のレイヤーの違いが見える。

差別化軸を言葉でまとめる。 mem0やsupermemoryは、アプリに後付けできるクラウド前提のメモリAPIとして、保存と検索の質と手軽さを競う。 memory-osは逆に、特定エージェントにローカル完結の記憶基盤を丸ごと足し、さらにエージェントの判断序列まで矯正する。 保存・検索のAPIを売るOSSと、注入記憶を使わせるところまでを設計対象にするmemory-osは、同じ「AIメモリ」でも担当レイヤーが違う。

同じローカル志向の隣接OSSとしては、Claude Memory Compilerとはが会話を知識ベースへコンパイルする方向、cognee｜ナレッジグラフ型AIメモリがグラフ型の記憶を志向する。 クラウド側のMemory APIの全体像はsupermemory入門が詳しい。

導入手順（最小例）

導入はワンコマンドのインストーラが用意されている。 前提はDocker、Python 3.11以上、Hermes Agent、そしてOpenRouterのAPIキー（または埋め込み用のローカルOllama）だ。

# ワンコマンド導入（Docker・SQLite・Icarusプラグイン・環境変数まで一括）
curl -sSL https://raw.githubusercontent.com/ClaudioDrews/memory-os/main/setup.sh | bash

外部スクリプトをbashに直接パイプする形なので、実行前にsetup.shの中身を読んでおくのが安全だ。 手動で段階的に入れたい場合はsetup/install.mdに検証チェックポイント付きの手順がある。

導入後の確認は3点を見る。

# Dockerサービスが healthy か
docker compose ps        # qdrant + redis + worker が healthy

# Qdrant の死活
curl -s http://localhost:6333/healthz    # ok が返る

# Icarusプラグインが認識されているか
hermes plugins list | grep icarus

記憶を足すのは、vaultにファイルを置くだけでよい。

# vaultパスは自分の環境に合わせる
mkdir -p ~/vault/wiki/raw
echo "# 私のメモ" > ~/vault/wiki/raw/notes.md
# 毎時の継続取り込みが差分を検出してQdrantへ反映する

最低限の環境変数は3つだ。 FABRIC_DIR（fabricの書き込み先、絶対パス必須）、OPENROUTER_API_KEY（埋め込みとLLM抽出）、REDIS_PASSWORD（自動生成）。 加えて、fabric抽出が途中で切れるのを避けるためICARUS_EXTRACTION_MAX_TOKENS=4096が強く推奨されている。

想定ユースケース

memory-osの設計が噛み合うのは、次のような使い方だ。

ひとつは、長期にわたる個人エージェントの運用だ。 毎セッションで前提を説明し直す手間をなくし、過去の決定や好みをエージェントが覚えている状態を作る。 作者自身が「アムネジア（記憶喪失）なエージェントに疲れた人のために作った」と書いている用途がこれにあたる。

もうひとつは、複数インスタンスでの記憶共有だ。 fabricはファイルベースの共有メモリなので、同じFABRIC_DIRを見る複数のHermesインスタンスが横断的に記憶を持てる。 片方が解決した不具合を、もう片方がfabric_recallで引ける。

知識ベースを育てる用途にも向く。 raw/に技術ドキュメントや調査結果を流し込むと、Wikiエージェントが概念・実体・比較のページへ整形し、Qdrantで意味検索できる状態に保つ。 減衰と重複排除が自動で走るので、貯めっぱなしで腐らせにくい。

逆に噛み合わないのは、Hermes以外のフレームワークへすぐ差し込みたい場合や、ノートPCで一時的に動かしたい場合だ。 3コンテナ常駐と8GB以上のRAMを前提とするため、軽量な後付けメモリを探しているなら別の選択肢が合う。

制限事項と既知の課題

ドキュメントには、作者が実運用で踏んだ落とし穴が率直に記録されている。 これは導入前に把握しておく価値がある。

Qdrant注入が暗黙に壊れていた事例がある。 hooks.pyのfrom scripts.context_enhancer import ...が、ファイルの存在しないパスに解決され、except Exception: return []がそのModuleNotFoundErrorを握りつぶしていた。 結果、[qdrant]が2026年5月29日から検出されないまま注入されていなかった。 対策としてsetup.shにシンボリックリンクのステップ（Phase 5b）が足された。

埋め込み次元の不一致も無言で効く。 環境変数が1024でコレクションが4096だと、OpenRouterがMatryoshkaで切り詰めてベクトル自体は有効になるが、品質は劣化する。

減衰スキャナはペイロードのメタデータがないと動かない。 importance_scoreやlast_accessed_atがない点はすべてdecay_score=1.0になり、何も退避されない。

そのほか、FABRIC_DIRはsystemdが~を展開しないため絶対パス必須、ICARUS_EXTRACTION_MAX_TOKENSはインポート時に固定されるため.env変更後はゲートウェイ再起動が要る、といった運用上の注意がドキュメントに並ぶ。

成熟度としては、公開から2週間あまりの新興プロジェクトだ。 外部からの大規模な実運用報告はまだ多くなく、検証目的での試用が現実的だ。 リポジトリにはスモークテストと取り込みテストが同梱されているので、自分の環境で再現確認してから本格運用へ進むのが妥当だろう。

今後のロードマップ

公開ロードマップとしての明示的なドキュメントは置かれていないが、リポジトリの状態から方向性は読める。 v0.2.0でIssueテンプレート・PRチェックリスト・コントリビューションガイドが整い、外部コントリビュータを受け入れる体制になった。 実際にDavidsoff・brian-doherty・aaronjmarsという作者以外のコントリビュータが入っている。

作者は本番セッションで遭遇した課題をそのままLayerドキュメントへ書き戻す運用をしており、「知っていても実行できない」ギャップへの対策（Mandatory Pre-Action Protocol）のように、振る舞い側の改善が継続している。 未解決Issueは6件と少なく、活発な大規模開発というより、作者の実運用に駆動された地道な改善が続く段階と読める。

関連プロジェクトの動きも見ておくとよい。 Wiki層を強化するVault Curator（ClaudioDrews/vault-curator）はフロントマター補完と意味的リンク付け、INDEX生成を担う別リポジトリだ。 作者は「Ground Truth Gap」を扱う実験リポジトリも公開しており、Layer 7の思想はこのテーマと地続きにある。

まとめ

memory-osは、Hermes Agentにローカル完結の記憶を足す7層構成のOSSだ。 平文ファイルから始まり、全文検索DB、信頼スコア付きファクト、fabric横断記憶、Qdrantベクトル検索、自己更新Wikiまでを束ねる。

ほかのAIメモリOSSと一線を画すのは、最上段のLayer 7だ。 記憶を注入するだけでは足りず、エージェントに注入記憶を権威ある情報として使わせる。 保存・検索のAPIを競うmem0やsupermemoryとは、解いている問題のレイヤーが違う。

向くのは、常時起動の環境で長期エージェントや複数インスタンスの記憶共有を回したい場合だ。 Hermes以外へすぐ差し込みたい場合や軽量さを求める場合は、別の選択肢が合う。 新興プロジェクトゆえ、まずは検証目的で試し、自分の環境でスモークテストを通してから判断するのが現実的だろう。

参照ソース

・ClaudioDrews/memory-os（公式リポジトリ）
・memory-os Layer 7（Ground Truth Hierarchy）
・memory-os infrastructure/architecture.md
・NousResearch/hermes-agent
・esaradev/icarus-plugin