Memento

Memento

記憶は、永続化しておくのが最適な場合があります。

SQLite ベースのナレッジグラフを通じて永続的なメモリ機能を提供します。エンティティ、観察事項、関係を保存し、BGE-M3 埋め込みを使用したセマンティック検索により、会話をまたいで関連するコンテキストをインテリジェントに取得できます。

特徴

• セマンティックベクトル検索（sqlite-vec/pgvector、1024d）
• オフライン埋め込みモデル（bge-m3）
• SQLite および PostgreSQL バックエンドに対応したモジュール式リポジトリ層
• 時間、人気度、コンテキスト、重要度の各要素を考慮した関連性スコアリングの強化
• entities、observations、relations で構成される構造化グラフ
• Claude Desktop との簡単な統合（MCP 経由）

前提条件

システムの SQLite バージョンの確認

Memento には SQLite 3.38 以降が必要です。ほとんどの macOS および Linux ディストリビューションには sqlite3 が標準で付属していますが、インストールされていることと、バージョンが十分に新しいことを確認してください。

sqlite3 --version       # should print a version string, e.g. 3.46.0

重要な注意： この確認は、SQLite がシステムにインストールされているかどうかを確認するためだけのものです。Memento は動作に sqlite3 CLI を使用せず、内部では Node.js の sqlite3 モジュールを使用します。

「command not found」と表示される場合（またはバージョンが 3.38 より古い場合）は、SQLite をインストールしてください。

プラットフォーム	インストールコマンド
macOS（Homebrew）	brew install sqlite
Debian / Ubuntu	sudo apt update && sudo apt install sqlite3

設定

Memento は、プラグイン可能なストレージバックエンドに対応しました。設定はすべて環境変数で行うため、MCP ワークフローに簡単に組み込めます。

変数	説明
MEMORY_DB_DRIVER	データベースバックエンドを指定する任意の設定です。デフォルトは sqlite です。PostgreSQL マネージャーを有効にするには postgres を設定します。
MEMORY_DB_PATH	SQLite データベースファイルのファイルシステムパスです（ドライバーが sqlite の場合のみ使用されます）。
SQLITE_VEC_PATH	ビルド済みの sqlite-vec 拡張共有ライブラリへの任意の絶対パスです。
MEMORY_DB_DSN / DATABASE_URL	pg クライアントで使用する PostgreSQL 接続文字列です。
PGHOST、PGPORT、PGUSER、PGPASSWORD、PGDATABASE	PostgreSQL の個別の接続パラメーターです。DSN が指定されていない場合に使用されます。
PGSSLMODE	require に設定すると、rejectUnauthorized: false で SSL が有効になります。
MEMENTO_WRITE_HOOK_PATH	JSON Lines ファイルへの任意のパスです。設定すると、グラフの変更が成功するたびに Memento がイベントを追記します。

書き込みフックイベント

グラフ全体をポーリングせずに別のプロセスがメモリへの書き込みに反応できるようにするには、MEMENTO_WRITE_HOOK_PATH を設定します。

MEMENTO_WRITE_HOOK_PATH=/tmp/memento-events.jsonl memento

各行は、ISO 形式の timestamp、operation、変更されたエンティティまたは関係のペイロードを含む JSON オブジェクトです。例：

{"timestamp":"2026-05-05T16:33:16.619Z","operation":"create_entity","entity":{"name":"Hook Test","entityType":"test"}}

対応する操作は create_entity、add_observations、create_relation、delete_entities、delete_relations、delete_observations、set_importance です。削除イベントは、実際に削除されたレコードについてのみ発行されます。

フックへの書き込みに失敗すると標準エラー出力に記録されますが、すでに成功したグラフの変更が失敗扱いになることはありません。厳密な整合性確認が必要な場合は、フックと併せて read_graph または対象を絞った open_nodes の確認を定期的に実行してください。

PostgreSQL に関する注意事項

• PostgreSQL マネージャーには pgvector 拡張機能が必要です。CREATE EXTENSION IF NOT EXISTS vector によって自動的に初期化されます。

Claude Desktop：

{
  "mcpServers": {
    "memory": {
      "description": "Custom memory backed by SQLite + vec + FTS5",
      "command": "npx",
      "args": [
        "@iachilles/memento@latest"
      ],
      "env": {
        "MEMORY_DB_PATH": "/Path/To/Your/memory.db"
      },
      "options": {
        "autoStart": true,
        "restartOnCrash": true
      }
    }
  }
}

トラブルシューティング

sqlite-vec 拡張機能の問題

重要： Memento は sqlite-vec 拡張機能を sqlite3 CLI ではなく、Node.js 経由でプログラムから読み込みます。

よくある誤解：

• ❌ sqlite3 CLI 用のシェルエイリアスを作成しても、Memento には影響しません
• ❌ sqlite3 CLI で拡張機能を読み込んでも、Memento には役立ちません
• ✅ npm でインストールした sqlite-vec を使うか、自動検出に失敗した場合は SQLITE_VEC_PATH 環境変数を設定してください。これは Node.js 互換版の拡張機能を指す必要があります。通常は node_modules ディレクトリ内にあります。

vec の自動読み込みに失敗した場合：

# Find the Node.js-compatible vec extension
find node_modules -name "vec0.dylib"  # macOS
find node_modules -name "vec0.so"     # Linux

# Use it via environment variable
SQLITE_VEC_PATH="/full/path/to/node_modules/sqlite-vec-darwin-x64/vec0.dylib" memento

API の概要

このサーバーは次の MCP ツールを公開します：

• create_entities
• create_relations
• add_observations
• delete_entities
• delete_relations
• delete_observations
• read_graph
• search_nodes
• open_nodes
• set_importance - 重要度レベルを設定します（critical/important/normal/temporary/deprecated）

MEMENTO_WRITE_HOOK_PATH が設定されている場合、状態を変更するツールは、下流の利用者向けに JSONL 書き込みイベントも追記します。

LLM が効果的なメモリ処理のために把握しておくべき指示セットの例（MEMORY_PROTOCOL.md を参照）

埋め込みモデル

このプロジェクトでは @xenova/transformers を使用し、量子化された bge-m3 を Node.js 上で完全にオフラインで実行します。

ライセンス

MIT