Mnemon — Persistent Layered Memory for AI Agents

mnemon-mcp

AI エージェントのための、永続的な階層型メモリです。 ローカルファースト。クラウド不要。単一の SQLite ファイル。

ランディングページ · npm · GitHub

AI エージェントはセッションごとにすべてを忘れてしまいます。Mnemon がそれを解決します。

OpenClaw、Claude Code、Cursor、Windsurf、自作のクライアントなど、あらゆる MCP 対応クライアントに、マシン上の単一の SQLite データベースを基盤とする、構造化された長期メモリを提供します。API キー不要、クラウド不要、テレメトリなし。npm install するだけで、エージェントが記憶できるようになります。

階層型メモリが必要な理由

フラットなキーと値のストアでは、「昨日あったこと」と「テストなしでコミットしないこと」が同じように扱われます。それは適切ではありません。知識の種類によって、保持期間やアクセス方法は異なるからです。

Mnemon はメモリを4 つの層に整理します。

先週火曜日の日記と、変わることのないコーディングルールは、異なる層に保存されます。それが本来あるべき姿だからです。

検索品質

検索品質は、実際の 797 件のメモリを含むバイリンガル（RU/EN）コーパスを使った 50 ケースのゴールデンセットに対して、再実装ではなく実際の MCP サーバーを通して測定しています。現在の数値（評価方法と履歴）：

ハイブリッド方式は両方の方式を個別に上回ります。これこそが、両者を融合させる理由です。語彙検索は生の再現率に優れ、ベクトル検索はランキングに優れています。RRF は両者を平均化して差を消すのではなく、その長所を保ちます。

評価ドキュメントでは、コーパスの拡大に伴うスコアの変動、評価で見つかった BM25 のフィールド重み付けのバグ、融合方式が純粋な語彙検索に劣る 2 つのケース、そしてゴールデンセットが対象としていない項目も追跡しています。監査できない数値は宣伝文句にすぎません。数値の算出方法をご覧ください。

アーキテクチャ

flowchart LR
    C["MCP client<br/>Claude Code · Cursor · …"] -- "stdio / HTTP" --> T["10 tools · 4 resources · 3 prompts"]
    T --> R["retrieval pipeline<br/>FTS5 · vector · RRF fusion"]
    T --> M["memories + supersede chains"]
    I["KB import pipeline<br/>markdown → memories"] --> M
    M -- triggers --> F["FTS5 index (stemmed EN+RU)"]
    R --> F
    R --> V["sqlite-vec (optional, BYOK)"]

1 つの SQLite ファイルに、メモリ、FTS5 インデックス、オプションのベクトルインデックスが保存されます。書き込みは、置き換えチェーンの不変条件を維持するトランザクションを通して行われます。読み取りでは、検索で説明する段階的な検索パイプラインが実行されます。

モジュールの境界、書き込み／読み取り経路、不変条件、既知の制限事項を含む全体像は、docs/ARCHITECTURE.mdにあります。設計上の決定は ADR として記録されています：SQLite+FTS5 コア、ハイブリッド RRF 検索、同期ドライバー、階層型メモリモデル。

クイックスタート

インストール

npm install -g mnemon-mcp

またはソースからインストールします。

git clone https://github.com/nikitacometa/mnemon-memory-mcp.git
cd mnemon-memory-mcp && npm install && npm run build

MCP クライアントを設定する

openclaw mcp register mnemon-mcp --command="mnemon-mcp"

{
  "mnemon-mcp": {
    "command": "mnemon-mcp"
  }
}

{
  "mcpServers": {
    "mnemon-mcp": {
      "command": "mnemon-mcp"
    }
  }
}

{
  "mcpServers": {
    "mnemon-mcp": {
      "command": "mnemon-mcp"
    }
  }
}

{
  "mnemon-mcp": {
    "command": "node",
    "args": ["/absolute/path/to/mnemon-mcp/dist/index.js"]
  }
}

確認

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | mnemon-mcp

応答には 10 個のツールが表示されます。データベース（~/.mnemon-mcp/memory.db）は初回実行時に自動作成されます。

これで完了です。エージェントが永続的なメモリを利用できるようになりました。

できること

10 個の MCP ツール

MCP リソースとプロンプト

リソース — エージェントが読み取れる最新データです。

プロンプト — 事前に構築されたワークフローです。

検索

4 つのモードがあり、すべてでレイヤー／エンティティ／スコープ／日付／信頼度による絞り込みに対応しています。

FTS モード（埋め込みがない場合のデフォルト） — BM25 ランキングを使用するトークン化された全文検索です。複数語のクエリでは AND を使用し、結果が少なすぎる場合はスコアにペナルティを加えて OR で補います。段階的な AND 緩和では、完全な OR に切り替える前に、最も具体的な上位 3 語で検索を試みます。

ハイブリッドモード（埋め込みを設定した場合のデフォルト） — Reciprocal Rank Fusion によって FTS5 とベクトル検索を組み合わせます。クエリ内の引用符で囲まれたエンティティ（例：'Essentialism'）を検出し、相互参照検索用の重み付きサブクエリを実行します。

ベクトルモード — 埋め込みに対するコサイン類似度のみを使用する検索です。

完全一致モード — 正確なフレーズ検索に LIKE による部分文字列一致を使用します。

スコア：bm25 × (0.3 + 0.7 × importance) × decay(layer) × recency

新しさのブースト：1 / (1 + daysSince / 365) — 最近作成されたメモリを緩やかに優先し、古いメモリにはペナルティを課しません。

ステミング

英語とロシア語では、インデックス作成時とクエリ時の両方で Snowball ステマーを適用します。つまり、"running" は "runs" に一致し、"книги" は "книга" に一致します。精度を高めるため、クエリからストップワードを除外します。

事実のバージョン管理

知識は変化します。Mnemon は古い事実を削除せず、チェーン化します。

v1: "Team uses React 17"  →  superseded_by: v2
v2: "Team uses React 19"  →  supersedes: v1 (active)

検索では最新のバージョンのみが返されます。include_history: true を指定した memory_inspect では、チェーン全体を確認できます。memory_delete を実行すると前の項目が再び有効になり、何も失われません。

ベクトル検索（オプション、BYOK）

独自の埋め込み API を指定して、意味的類似性検索を有効にします。

# OpenAI
MNEMON_EMBEDDING_PROVIDER=openai MNEMON_EMBEDDING_API_KEY=sk-... mnemon-mcp

# Ollama (local, free)
MNEMON_EMBEDDING_PROVIDER=ollama mnemon-mcp

これにより、次の 2 つの検索モードが追加されます。

• mode: "vector" — コサイン類似度による純粋な検索
• mode: "hybrid" — Reciprocal Rank Fusion を使用して FTS5 とベクトルを組み合わせた検索

sqlite-vec（オプションの依存関係としてインストール）が必要です。新しいメモは追加時に埋め込まれ、既存のメモは後から埋め込みを追加できます。

ナレッジベースのインポート

Markdown ファイルのフォルダーがあれば、一括でインポートできます。

cp config.example.json ~/.mnemon-mcp/config.json   # edit this first
npm run import:kb -- --kb-path /path/to/your/kb     # incremental (skips unchanged files)

設定では、glob パターンをメモリレイヤーに割り当てます。

{
  "owner_name": "your-name",
  "extra_stop_words": [],
  "mappings": [
    {
      "glob": "journal/*.md",
      "layer": "episodic",
      "entity_type": "user",
      "entity_name": "$owner",
      "importance": 0.6,
      "split": "h2"
    },
    {
      "glob": "people/*.md",
      "layer": "semantic",
      "entity_type": "person",
      "entity_name": "from-heading",
      "importance": 0.8,
      "split": "h3"
    }
  ]
}

設定フィールド

HTTP トランスポート

リモート環境または複数のクライアントで使用する場合：

MNEMON_AUTH_TOKEN=your-secret MNEMON_HOST=0.0.0.0 MNEMON_PORT=3000 npm run start:http

デフォルトでは 127.0.0.1 にバインドします。他のホストにバインドするには MNEMON_AUTH_TOKEN が必要です。サーバーは、認証なしでメモリストアをネットワークに公開することを拒否します（信頼できるネットワークでは MNEMON_ALLOW_INSECURE_HTTP=1 で上書きできます）。デフォルトで毎分 100 件／IP のレート制限、オプトイン方式の CORS、1MB の本文サイズ制限、タイミングセーフな認証、SIGTERM 時の正常なシャットダウンに対応しています。

設定リファレンス

ツールリファレンス

比較

出典付きの詳細な競合分析：docs/COMPETITORS.md。

開発

npm run dev        # run via tsx (no build step)
npm run build      # TypeScript → dist/
npm run lint       # eslint (flat config)
npm test           # vitest — unit + integration + MCP dispatch + HTTP transport + hybrid RRF
npm run bench      # performance benchmarks
npm run db:backup  # backup database

CI では Node 20 と 22 でビルド、lint、テストを実行した後、実際の JSON-RPC を使用してコンパイル済みサーバーのスモークテストを実施します（tools/list がツールセットと完全に一致する必要があります）。

技術スタック： TypeScript 5.9（厳格モード）、better-sqlite3、@modelcontextprotocol/sdk、Snowball stemmer、Zod、vitest。

コーディングガイドラインについては、CONTRIBUTING.md を参照してください。

設計原則

• デフォルトでエアギャップ — テレメトリーは一切ありません。初期状態ではマシンの外部にデータが送信されることはありません。ネットワークと通信するコンポーネントはオプションの埋め込み機能だけで、設定したプロバイダー（ローカルの Ollama を含む）とのみ通信します。
• 単一ファイル — SQLite データベースは 1 つだけで、運用作業は不要、ファイルをコピーするだけですぐにバックアップできます。
• 決定論的な検索 — デフォルトは埋め込みではなく FTS5 です。解釈可能で再現性があり、GPU も不要です。
• フラット構造より構造化 — レイヤーでアクセスパターンを表現し、上書きチェーンで時間を表現します。
• 最小限 — 本番環境の依存関係は 4 つです。Node が動作する環境ならどこでも使えます。
• 主張ではなく測定 — 検索結果の変更は、リグレッションを含むゴールデンセットで評価します。

ライセンス

MIT