Mnemos

mnemos

コーディングエージェントのための自動操縦ナレッジベース。

一度インストールすれば、あとはコーディング中にエージェントがプロジェクトの構造化されたナレッジベースを自動で構築します。覚えておくプロンプトも、remember() の呼び出しも、習得する API も必要ありません。

単一の Go バイナリ。SQLite を組み込み。クラウド不要。Docker 不要。Python 不要。Node ランタイム不要。

Agent (Claude Code / Cursor / Kiro / Gemini CLI / Codex / ...)
    ↓ MCP stdio
mnemos serve
    ↓
Auto-compiled knowledge base (~/.mnemos/mnemos.db)

---

mnemos の特長

あらゆるメモリサーバーが保存するのはテキストです。Mnemos はナレッジベースを構築します。

ほかのサーバーでは、保存するタイミングや取得するタイミングをユーザー（または慎重に調整したプロンプト）が決める必要がありますが、mnemos はバックグラウンドで完全なパイプラインを実行します。

Agent action → mnemos auto-pipeline:
                ├── Quality gate        (reject/rewrite low-value content)
                ├── 3-tier dedup        (hash → fuzzy → semantic)
                ├── Auto-summarize      (extractive, fast; LLM if available)
                ├── File linking        (extract identifiers, link to code)
                ├── Type classification (episodic / long_term / semantic / skill)
                ├── Quality scoring     (for retrieval ranking)
                └── Decay scheduling    (so knowledge base stays relevant)

Retrieval:
                ├── Hybrid search       (FTS5 + optional semantic + RRF)
                ├── File-overlap boost  (memories about active files rank higher)
                ├── MMR diversity       (kill redundant results)
                ├── Adaptive packing    (full content or summary based on budget)
                └── Token-budget cap    (always fits in context)

このパイプラインは MCP とフックのインターフェースの背後で動作します。エージェントは通常のメモリツールを使うだけで、重複排除、要約、ランキング、パッキング、ライフサイクル管理を自分で調整する必要はありません。

---

現在利用できる3つのレイヤー

レイヤー 1 — MCP トランスポート。 標準の MCP サーバーで、stdio に対応し、あらゆる MCP クライアントで動作します。

レイヤー 2 — 自動操縦フック。 1つのコマンド（mnemos setup claude）でフック、ステアリング、MCP 設定を構成します。セッション開始時に関連するコンテキストを自動で注入します。プロンプトの送信時には、トピックの変更を検知して自動検索します。セッション終了時には、網羅性を確認します。

レイヤー 3 — 自動構築されるナレッジベース。 品質ゲート、3段階の重複排除、自動要約、ファイルのリンク付け、MMR によるコンテキストの組み立てをすべて自動で行います。これらを手動で実行する必要はありません。メモリベース全体を対象に、古くなった情報、矛盾、欠けている関係を継続的に検出する、受動的なバックグラウンドデーモンも含まれます。

---

正直な比較

	Mem0	Zep/Graphiti	engram	OMEGA	mnemos
MCP ネイティブ	✓	✓	✓	✓	✓
単一バイナリ、ランタイム依存関係なし	—	—	✓	—	✓
クラウド不要／ローカル優先	一部	—	✓	✓	✓
1コマンドで自動操縦をセットアップ	—	—	—	—	✓
自動品質ゲート	—	—	—	—	✓
自動要約	—	—	—	—	✓
ファイルの自動リンク付け（git を認識）	—	—	—	—	✓
MMR によるコンテキストの組み立て	—	—	—	—	✓
受動的なバックグラウンドデーモン	—	—	—	—	✓
時間的知識グラフ	—	✓	—	—	一部（減衰＋置き換え）
セルフホストのコスト	クラウド費用 $0	約 $50/月（Neo4j）	$0	$0	$0

Mnemos は Zep を目指しているわけではありません。目指す方向が異なります。業務上の事実に対する時間的推論が必要で、エンタープライズ向けのインフラを備えているなら、Zep が最適です。ノート PC 上で自律的に動作する自動操縦ナレッジベースを求めるコーディングエージェントのユーザーなら、Mnemos が最適です。

---

インストール

# Homebrew (macOS / Linux)
brew install s60yucca/tap/mnemos && mnemos setup claude

# curl (verify mnemos.dev is live before using)
curl -fsSL https://mnemos.dev/install.sh | bash && mnemos setup claude

# npm wrapper
npx -y @s60yucca/mnemos setup claude

# Build from source (requires Go 1.23+)
git clone https://github.com/s60yucca/mnemos
cd mnemos && make build

claude を cursor、kiro、gemini-cli、codex、または trae に置き換えます。クライアントを再起動すれば、あとは自動操縦で動作します。

---

autopilot の実際の動作

mnemos setup <client> は、次のファイルを書き込みます。

• ステアリングファイル（CLAUDE.md、.cursorrules、.kiro/steering/mnemos.md）— 保存する価値がある情報をエージェントに伝えます
• フック設定（.claude/hooks.json または同等のファイル）— ライフサイクルイベントを接続します
• MCP 設定（.mcp.json）— mnemos serve をツールプロバイダーとして登録します

3 つのフックが自動的に実行されます。

セッション開始 → mnemos hook session-start トークン予算内で関連する記憶を収集します（MMR による多様化、ファイルによるブースト）。コンテキストに挿入します。コールドスタートは 200 ms 未満です。

プロンプト送信 → mnemos hook prompt-submit トピックや意図の変化を検出します。変化が重要な場合、ナレッジベースを自動検索します。ノイズを避けるため、クールダウンを適用します。

セッション終了 → mnemos hook session-end 永続的な記憶が保存されたかを確認します。必要に応じて、最小限の記録を保存します。セッション状態をクリーンアップします。

ステアリングファイルは、何を記憶する価値があるかをエージェントに伝えます。フックは検索、重複排除、要約、リンク付けを処理するため、エージェントが記憶管理について考えるのにトークンを浪費しません。

Mnemos のアップグレード後は、CLI と実行中の MCP サーバーの両方を確認してください。

mnemos version
mnemos doctor all

次に、エージェントに mnemos_runtime を呼び出すよう依頼してください。これにより、ツール呼び出しを処理している実際の MCP サーバープロセスについて、version、host、pid、started_at、executable、data_dir、project_id が報告されます。古いバージョンが表示される場合は、MCP クライアントを終了して再度開いてください。pkill -f "mnemos serve" を使うのは、アクティブな MCP クライアントを終了した後、またはすべてのアクティブな Mnemos トランスポートを意図的に再接続させる場合に限ってください。

返された JSON は、次のコマンドで検証できます。

mnemos doctor runtime --from-json runtime.json
mnemos check --mcp-runtime runtime.json

日常的な mnemos check では、MCP ランタイム JSON は不要です。一般公開前またはアップグレード時の検証では、リリース前に古い MCP サーバーを検出できるよう、--mcp-runtime を指定してください。

---

パッシブ autopilot デーモン

フックに加えて、mnemos はバックグラウンドデーモンを実行し、ナレッジベースを継続的に改善します。

• 古さの検出 — 削除済みのファイルや古くなったパターンを参照する記憶を検出します
• 矛盾の検出 — 相互に矛盾する記憶を見つけます
• 関連性の推定 — 関連する記憶を自動的にリンクします
• バックフィル — 要約がない記憶の要約を遡って生成します
• 自動コンパイル — 条件を満たすソース記憶を、再利用可能なプロジェクト知識にコンパイルします

mnemos autopilot status          # check daemon state
mnemos autopilot run             # trigger immediate run
mnemos autopilot run --dry-run   # preview findings without writing
mnemos autopilot report          # view latest findings

---

自動ループを検証する

Mnemos は、設定、生のアクティビティ、知識の品質、エンドツーエンドのループの準備状況について、それぞれ個別のビューを提供します。

mnemos status                    # effective data path and automatic feature settings
mnemos health                    # raw feature firing rates and denominators
mnemos eval --project myapp      # memory quality, duplication, freshness, usefulness
mnemos check --project myapp     # consolidated read-only loop verification
mnemos check --launch            # stricter public-launch readiness gates

mnemos check はデータベースを読み取り専用で開きます。マイグレーションを実行したり、ワーカーを起動したり、記憶を変更したりすることはありません。mnemos check --fix の対象は意図的に限定されています。検証済みのクリーンアップ計画を作成した後、古い自動操縦レポートのみをアーカイブします。

---

パフォーマンスベンチマーク（レイテンシー）

操作	350 件の記憶	1,500 件の記憶
store（新規、完全なパイプラインあり）	57 ms	24 ms
store（重複排除ヒット）	55 ms	22 ms
search ハイブリッド（RRF + ファイルブースト）	42 ms	39 ms
maintain（減衰 + GC）	27 ms	108 ms
フックの session-start（コールド）	200 ms 未満	—
バイナリサイズ	約 12 MB	—

ハードウェア：M1 Pro、16 GB RAM、SSD 上の SQLite。レイテンシーは環境によって異なる場合があります。

データセットのサイズにかかわらず、ほとんどの操作は 60 ms 未満で完了します。フックのサブコマンドでは InitLight モードを使用し、バックグラウンドワーカーを起動せず、セッションを中断しません。

価値のベンチマーク（トークン削減、精度、落とし穴の回避）は現在進行中です。 評価方法については DOGFOODING_RUNBOOK.md をご覧ください。一般公開前に、このプレースホルダーを実測値に置き換える予定です。

---

MCP ツール

ツール	機能
mnemos_store	メモリを保存します（完全自動のパイプラインが透過的に実行されます）
mnemos_search	FTS、セマンティック検索、ファイル重複検索を組み合わせて検索します
mnemos_context	予算を考慮し、MMR で多様化したコンテキストを組み立てます
mnemos_get	ID で取得します
mnemos_update	内容、要約、タグを更新します
mnemos_delete	論理削除します（maintain で復元可能です）
mnemos_relate	2 つのメモリを関連付けます（supersedes、caused_by、depends_on）
mnemos_maintain	減衰、アーカイブ、GC、古いデータの検出を実行します
mnemos_runtime	実行中の MCP サーバーのバージョン、ホスト、PID、実行ファイル、稼働時間、データディレクトリ、プロジェクトのスコープを報告します

---

インストール後のクイックスタート

# Agents call these automatically via MCP. You can also use directly:
mnemos store "JWT uses RS256, 1h expiry, config in auth/config.go"
mnemos search "token expiry"
mnemos stats
mnemos maintain

---

設定

ほとんどのユーザーは設定を変更する必要はありません。必要な場合は次のとおりです。

# .mnemos/config.yaml (project-local) or ~/.mnemos/config.yaml (global)
embeddings:
  provider: noop              # noop (default) | ollama | openai
  # Pure FTS works fine. Enable semantic for meaning-based search.

quality_gate:
  min_words: 5
  max_words: 200
  min_density: 0.3
  require_specific: true      # long_term memories need project identifiers
  duplicate_threshold: 0.8

summarization:
  extractive: true             # always on, fast, offline

file_linking:
  enabled: true                # auto-disables outside git

hook:
  enabled: true
  search_cooldown: 5m
  session_start_max_tokens: 2000
  mmr_lambda: 0.7              # 0=max diversity, 1=max relevance
  file_boost: 0.3

autopilot:
  enabled: true
  interval: 15m
  contradiction_enabled: false
  auto_compile_enabled: true
  min_auto_compile_sources: 5

設定の適用順序は、明示的に指定した --config、プロジェクトローカルの .mnemos/config.yaml、その後に ~/.mnemos/config.yaml です。環境変数には MNEMOS_ プレフィックスを使用します。

---

メモリの種類

Mnemos は自動的に分類します。手動で変更するには --type フラグを使います。

種類	減衰率	用途
short_term	速い（約 1 日）	TODO、一時的なメモ、作業中の内容
episodic	中程度（約 1 か月）	セッション中の出来事、バグ修正
long_term	遅い（約 6 か月）	アーキテクチャ上の決定
semantic	非常に遅い	事実、定義、知識
skill	遅い	繰り返し使える手順や運用ワークフロー
compiled	管理対象	自動コンパイルされたプロジェクトの知識

---

開発した理由

毎朝 Claude Code に自分のプロジェクトについて説明し直すのに、うんざりしていました。

既存のメモリサーバーを試しました。ほとんどはテキストを問題なく保存できました。しかし、どれも保存するタイミングと取得するタイミングを、私自身か、綿密に調整したプロンプトに判断させるものでした。それはナレッジベースではありません。MCP のラッパーを付けたデータベースです。

Mnemos は、それを本当に自動化するために作りました。mnemos setup claude を実行してエディターを再起動すれば、ナレッジベースが自動でコンパイルされます。

---

オートパイロット設定 — クライアントごとに 1 つのコマンド

mnemos setup claude       # writes CLAUDE.md, .claude/hooks.json, .mcp.json
mnemos setup cursor       # writes .cursorrules, .mcp.json
mnemos setup kiro         # writes .kiro/steering/mnemos.md, .kiro/mcp.json
mnemos setup gemini-cli   # writes GEMINI.md, .gemini/settings.json, .mcp.json
mnemos setup codex        # writes ~/.codex/config.toml (global, CLI + VSCode)

フラグ：--global（すべてのプロジェクトにインストール）、--force（既存の設定を上書き）、--project <id>（プロジェクト ID を上書き）。

Claude Code では、--project <id> を指定すると、MCP エントリーとフックコマンドに MNEMOS_PROJECT_ID が書き込まれます。これはフックと mnemos serve が使用する標準のプロジェクトスコープです。手動コマンドでの mnemos --project <id> ... も、同じランタイム環境に引き継がれます。

Claude のサブエージェントには、セッション開始フックのコンテキストが渡されないことがあります。委任する前にメインエージェントが mnemos_context を呼び出し、関連するメモリまたはメモリ ID をサブエージェントのタスクプロンプトに含めてください。

Codex に関する注意： Codex は CLI と VSCode 拡張機能で共有する単一のグローバル設定を使用します。--global と --local は無視されます。セットアップコマンドは MNEMOS_PROJECT_ID を書き込み、明示的な上書きとして --project <id> を受け付けます。セットアップ後は Codex CLI と VSCode 拡張機能の両方を再起動してください。

---

🤖 Trae、OpenClaw、Paperclip、または任意の MCP クライアントでの使用

Trae（Solo Agent）、OpenClaw（Claw bot）、Paperclip、Claude Desktop などの新しい AI フレームワークを使用している場合、Mnemos を手動で簡単に接続できます。Mnemos は stdio 経由で標準の MCP を使用します。

次の JSON スニペットを、クライアントの MCP 設定ファイル（例：trae.json、openclaw.json、paperclip.config.json、claude_desktop_config.json）に追加してください。

{
  "mcpServers": {
    "mnemos": {
      "command": "mnemos",
      "args": ["serve"]
    }
  }
}

---

CLI リファレンス

mnemos init                                           # first-time setup
mnemos store "..."                                    # store (auto-pipeline)
mnemos search "auth"                                  # hybrid search
mnemos list --project myapp                           # list memories
mnemos get <id>                                       # fetch by id
mnemos update <id> --content "..."                    # update
mnemos delete <id>                                    # soft delete
mnemos relate <src> <tgt> --type supersedes           # typed relation
mnemos stats                                          # storage + quality stats
mnemos maintain                                       # decay + stale + GC
mnemos status                                         # automatic feature configuration
mnemos eval [--project myapp]                         # knowledge quality metrics
mnemos health [--project myapp]                       # raw feature activity
mnemos check [--project myapp] [--mcp-runtime runtime.json]  # verify the automatic knowledge loop
mnemos doctor runtime --from-json runtime.json        # validate live MCP server identity
mnemos check --launch                                 # apply public-launch readiness gates
mnemos check --fix                                    # archive older generated reports safely
mnemos serve                                          # MCP server (stdio)
mnemos version

# Autopilot setup
mnemos setup claude | cursor | kiro | gemini-cli | codex | trae [--global] [--force] [--project <id>]

# Passive autopilot daemon
mnemos autopilot status
mnemos autopilot run [--dry-run] [--project <id>]
mnemos autopilot report [--project <id>]

# Backfill
mnemos backfill summaries --project <id> [--dry-run] [--limit N]

# Benchmark readiness
mnemos bench status
mnemos bench mode on | off
mnemos bench export [--project <id>] [--include-mixed] [--output sessions.csv]

# Hook subcommands (called by clients, not manually)
mnemos hook session-start
mnemos hook prompt-submit
mnemos hook session-end

---

mnemos が対象としないもの

• チャットボット向けのメモリ SaaS ではありません。 カスタマーサポートボットでユーザーの好みを記憶するには、Mem0 をお使いください。
• 時間的知識グラフデータベースではありません。 ビジネス上の事実について有効時点・無効時点に基づく推論を行うには、Zep をお使いください。
• クラウド製品ではありません。 mnemos のクラウド版はありません。今後も提供する予定はありません。
• 特定のフレームワーク専用ではありません。 MCP ネイティブです。MCP に対応するあらゆるものと連携できます。

Mnemos の機能は 1 つです。自動でコンパイルされるナレッジベースをエージェントに提供します。

---

ロードマップ

ROADMAP.md をご覧ください。概要：

• v1.1.14（現在）： 完全な自動パイプライン、自動コンパイル、受動的な自動注入、ループ検証、来歴に裏付けられたベンチマーク、Codex 対応
• v1.2（次期）： 配布、公開ベンチマークのエビデンス、MCP Registry、HN でのローンチ
• v1.3（予定）： Git を介したチームメモリー — チームメイトのナレッジを共有する .mnemos/shared/
• v2.0 以降（未定）： プロジェクト間のメモリースコープ、メモリーの圧縮。ユーザーフィードバックをもとに決定します

---

コミュニティ

• GitHub Discussions
• GitHub Issues

---

ライセンス

MIT