Memento

AI アシスタント向けの、ローカルファーストで LLM に依存しないメモリレイヤー
runmemento.com

AI セッションは毎回同じことから始まります。好み、プロジェクトの慣例、先週決めたこと、避けるべき行き詰まりを改めて説明する必要があります。各ツールはそれぞれ分断された方法（CLAUDE.md、.cursorrules、copilot-instructions.md、ChatGPT Memory）でこの問題を解決しますが、人間であるあなたは常に一人です。あなたの記憶がベンダーごとに分断されるべきではありません。

Memento は、そうした記憶を一か所に保存します。ローカルの SQLite ファイル上でMCPサーバーを実行するため、MCP に対応したあらゆる AI アシスタント（Claude Desktop、Claude Code、Cursor、GitHub Copilot、Cline、OpenCode、Aider、リサーチボット、カスタムエージェント）が、あなた自身、仕事、意思決定についての永続的で構造化された記憶を読み書きできます。ローカルファーストで、デフォルトでは外部へのネットワーク通信を行わず、ベンダーロックインもありません。

_{以前のコンテキストがない新しいチャットでも、Memento が先週決めたことを記憶から補います。}

クイックスタート

ゼロの状態から、使えるメモリレイヤーを構築するまでの 3 ステップです。

1. init を実行する（TTY では対話形式）

npx @psraghuveer/memento init

XDG のデフォルトに従ってデータベースを作成し（$XDG_DATA_HOME/memento/memento.db、POSIX では通常 ~/.local/share/memento/memento.db）、マイグレーションを実行します。また、TTY では 1 キーで回答できる 4 つのセットアップ質問が表示されます。

• 希望する名前。 user.preferredName 設定キーに保存されるため、記憶には「ユーザーは……を好みます」ではなく「Raghu は……を好みます」と表示されます。
• 同梱のスキルをインストールしますか？ y/N で回答します。Anthropic 形式のスキルを読み込むクライアント向けに、skills/memento/ を ~/.claude/skills/ にコピーします。
• スターターパックを使って初期データを設定しますか？ 同梱されている 4 つのパック（engineering-simplicity、pragmatic-programmer、twelve-factor-app、google-sre）から 1 つ選ぶと、初日からストアに役立つ記憶が追加されます。何も入れずに始める場合はスキップしてください。
• ペルソナのスニペットを自動インストールしますか？ マシン上の AI クライアントを検出し、各クライアントのユーザースコープのカスタム指示ファイルに、マーカーで囲まれたブロックを書き込みます（Claude Code の場合は ~/.claude/CLAUDE.md、OpenCode の場合は ~/.config/opencode/AGENTS.md、Cline の場合は ~/Documents/Cline/Rules/memento.md）。何度実行しても安全で、削除も可能です。UI のみのクライアント（Cowork、Claude Desktop、Claude Chat、Cursor User Rules）には、貼り付け手順が表示されます。

最後に、対応しているすべてのクライアント向けのコピー＆ペースト用 MCP スニペットが表示されます。何度実行しても安全です。いつでも再実行してスニペットを再表示し、スキップした質問に回答できます。対話形式のフローを抑制するには --no-prompt を渡してください（CI、スクリプト向け）。

2. AI クライアントを接続する

init は、クライアントにサブコマンドが付属している場合は1行のサブコマンドを、それ以外の場合はクライアントの MCP 設定にマージする JSON スニペットを出力します。使用するクライアントのものを選んで貼り付け、クライアントを再起動して、新しい MCP サーバーを読み込ませてください。

クライアントごとの詳しい手順は、docs/guides/mcp-client-setup.md をご覧ください。

3. ペルソナスニペットがアシスタントに届くことを確認する

Memento には3つの学習用インターフェースがあります。通信時に使用する MCP instructions の中核、スキル対応クライアント向けのバンドル済みスキル、そしてペルソナスニペットです。この3つのうち、すべてのメッセージでアシスタントのシステムプロンプトに確実に届くのは、ペルソナスニペットだけです。MCP 仕様では instructions は任意とされており、クライアントによってそれを表示するかどうかが異なります。また、スキルはユーザーの意図に応じて起動するため、意図が明確でない最初のメッセージでは実行されません。

ステップ1のペルソナ自動インストールの確認で Y を選んだ場合、マシン上で検出されたファイルベースの AI クライアントにはすでに設定済みです。該当する場合は、スニペットが ~/.claude/CLAUDE.md、~/.config/opencode/AGENTS.md、および／または ~/Documents/Cline/Rules/memento.md に書き込まれています。UI のみのクライアント（Cowork、Claude Desktop、claude.ai の Claude Chat、Cursor User Rules）や、自動インストーラーが実行されなかったクライアントでは、docs/guides/teach-your-assistant.md からペルソナスニペットをコピーし、クライアントのカスタム指示／システムプロンプト欄に貼り付けてください（欄の名前はクライアントによって異なり、設定 UI の「カスタム指示」などがあります）。

これで完了です。npx @psraghuveer/memento verify-setup を実行して、通信が最初から最後まで機能することを確認してください。このコマンドは書き込み／検索／クリーンアップを一巡させ、アシスタントが実際に Memento を呼び出せることを検証します。

次に、新しいセッションを開始して、「Node のプロジェクトでは npm より pnpm を使うのが好みだと覚えておいてください。」 と伝えてみてください。次のセッションで 「私が使っているパッケージマネージャーは何ですか？」 と尋ねると、説明し直さなくてもアシスタントが思い出せるはずです。

パックでストアを初期登録する

新しくインストールした Memento は空です。パックは、ワンステップでインストールできる、厳選された YAML 形式のメモリ一式です。スタックガイド（Rust + Axum、TypeScript + pnpm、Python + uv など）、チームの規約、あるいは別のマシンで作成した個人用セットなどがあります。

memento pack install engineering-simplicity

このコマンドは、バンドル済みパックの1つをインストールします。John Maeda の The Laws of Simplicity から抽出した11件のメモリが含まれています。engineering-simplicity、pragmatic-programmer（Hunt と Thomas のヒント）、twelve-factor-app（Wiggins / Heroku）、google-sre（Google の SRE 書籍）の4つのパックが、最初から同梱されています。インストール前に memento pack preview <id-or-path> でプレビューできます。memento pack list でインストール済みのパックを一覧表示できます。memento pack uninstall <id> --confirm でいつでも削除できます（デフォルトではドライランです）。

パックを使えば、共有もできます。既存のメモリから memento pack create でパックを作成し、ファイルや HTTPS URL、またはコミュニティへの投稿として配布できます。予約済みの pack:<id>:<version> タグが、パックからインストールされたすべてのメモリに付与されるため、出所が常に追跡できます。詳しいガイドは docs/guides/packs.md をご覧ください。設計の背景については ADR-0020 をご覧ください。

はじめに

前提条件。 Node.js ≥ 22.11、および、プリビルドがないプラットフォームで better-sqlite3 をコンパイルするための C/C++ ツールチェーン（macOS では Xcode コマンドラインツール、Debian/Ubuntu では build-essential）。

初回に init を実行して、セットアップしてください。

npx @psraghuveer/memento init

init はデータベースの保存先として XDG データディレクトリをデフォルトで使用します。デフォルト以外の場所を使う場合は、--db /custom/path/memento.db を渡すか、MEMENTO_DB=/custom/path/memento.db を設定してください。

サーバーを直接実行する場合（デバッグなど）：

npx @psraghuveer/memento serve

サーバーは MCP リクエストを stdio で受け付けます。追加のフラグ（カスタムのデータベース保存先など）を渡すには、次のようにします。

npx @psraghuveer/memento serve --db ~/.local/share/memento/memento.db

MEMENTO_DB 環境変数を使って既存のデータベースを指定することもできます。

npx @psraghuveer/memento doctor を実行してインストールを検証してください（--quick を追加すると、DB とエンベッダーのプローブを省略できます。--mcp を追加すると、既知の MCP クライアント設定ファイルもスキャンします）。ストアの内容を一画面で確認するには、npx @psraghuveer/memento status を実行してください。MCP を介さずに、インストールで利用できる機能（登録済みコマンド、現在の設定、データベースの保存先）を確認するには、npx @psraghuveer/memento context を実行してください。MCP トランスポートをエンドツーエンドで簡易テストするには、npx @psraghuveer/memento ping を実行してください。

MCP クライアントへの Memento の接続方法（Claude Desktop、Claude Code、Cursor、Cline、OpenCode、VS Code Agent mode など）は、docs/guides/mcp-client-setup.md で手順を追って説明しています。要点は、上記の 3 ステップのクイックスタートです。まず init を実行し（Y と答えると、検出されたファイルベースのクライアントにペルソナのスニペットが自動インストールされます）、次に MCP サーバーのスニペットをクライアントに貼り付けます。その後、UI のみで設定するクライアントの場合は、ペルソナのスニペットを手動で貼り付けてください。

ベクトル検索（FTS に加えて言い換えを照合する機能）は、デフォルトで有効です。初回の検索時にモデルが一度だけダウンロードされ（約 110 MB）、$XDG_CACHE_HOME/memento/models（または ~/.cache/memento/models／%LOCALAPPDATA%\memento\Cache\models）に保存されます。それ以降は、FTS とベクトル検索の両方が自動で実行されます。モデルがまだダウンロードされていない場合、検索は FTS のみで動作を続けます。設定オプションとライブラリの接続方法については、docs/guides/embeddings.md を参照してください。

日々のストアの運用（compact、backup、status、スケジュール設定）については、docs/guides/operations.md を参照してください。競合のワークフローについては、docs/guides/conflicts.md を参照してください。Memento の使い方を AI アシスタントに学習させるには、docs/guides/teach-your-assistant.md を参照してください。また、クライアントが Anthropic 形式のスキルを読み込む場合は、同梱の スキル をインストールして、ペルソナのスニペットを補完するコンテキストとして利用してください。

ブラウザーでストアを確認、整理できます。 npx @psraghuveer/memento dashboard を実行すると、ローカルファーストの Web UI が起動し、MEMENTO_DB を読み取ります。メモリーの種類とスコープごとの件数、監査証跡、競合のトリアージ、設定の確認、インストール済みパックを確認できます。localhost からのみアクセスでき、ランチャーがブラウザーに渡す URL 内の起動ごとにランダム生成されるトークンで保護されており、テレメトリーはありません。ダッシュボードは ADR-0018 に基づいて提供される兄弟パッケージ（@psraghuveer/memento-dashboard）です。詳しい手順は docs/guides/dashboard.md を参照してください。

困ったときは？ よくある障害（better-sqlite3 のビルドエラー、command not found: memento、STORAGE_ERROR、エンベッダー依存関係の不足）については、docs/guides/troubleshooting.md で説明しています。

コントリビューター向けのワークフロー（ブランチ運用、コミット規約、PR チェックリスト）については、CONTRIBUTING.md を参照してください。コードベースに取り組む AI エージェントは、AGENTS.md も必ず読んでください。

設計原則

設計上のあらゆる判断は、次の4つの原則に照らして評価されます。詳しくはARCHITECTURE.mdに記載されています。

1. 第一原理。 ものごとが通常そう行われているからではなく、必要性を確認したうえで各構成要素を採用します。
2. モジュール性。 どのコンポーネントも、ほかの部分を書き直すことなく置き換えられます。
3. 拡張性。 新しいバリエーションを追加しても、互換性を損なう変更は必要ありません。
4. ユーザー主導の設定。 動作はコードではなく、設定によって決まります。

Memento とは

4つの柱です。ほかの説明でも、同じ4つの言葉を使っています。

• ローカル。 ホームディレクトリに保存される1つの SQLite ファイルです。クラウド、テレメトリー、デフォルトでの外部ネットワーク呼び出しはありません。完全にオフラインで使えます。
• 型付き。 5種類のメモリー（fact、preference、decision、todo、snippet）があり、それぞれの種類に応じたフィールドを備えています（decision には根拠、todo には期限、snippet には言語が含まれます）。アシスタントは、テキストの塊を検索するだけでなく、何が今も正しいのかを推論できます。
• 監査可能。 書き込みのたびに、追記専用ログにイベントが記録されます。競合は気付かれないまま併存するのではなく、トリアージできるように表面化します。確認しなければメモリーは時間とともに減衰します。「なぜこれがここにあるのか？」「いつ変更されたのか？」に、いつでも答えられます。
• あなたのもの。 動作（検索時の重み、減衰の半減期、スクラバーのルールなど）はすべて設定でき、JSONL のエクスポートとインポートに対応し、ライセンスは Apache-2.0 です。マシン間でメモリーを持ち運べ、いつでも利用をやめられます。ベンダーロックインはありません。

さらに、LLM に依存せず（クライアントが利用するあらゆるモデルで動作します）、MCP をネイティブにサポートし（Claude Desktop、Claude Code、Cursor、GitHub Copilot、Cline、OpenCode、Aider、カスタムエージェントに対応）、プライバシーに配慮しています（正規表現スクラバーが保存前にシークレットを取り除き、パターンはユーザーが設定できます）。

Memento ではないもの

• チャット履歴ストアではありません。生の会話記録ではなく、好み、事実、エピソード、教訓など、要約された構造化メモリーを記録します。
• ナレッジグラフやセマンティックデータベースではありません。その用途に適したツールをお使いください。
• クラウドサービスではありません。メモリーはお使いのマシンに保存されます。クラウド埋め込み、マシン間の同期、チームで共有するメモリーは製品の対象外です。
• プラグインプラットフォームではありません。アーキテクチャ上は将来の可能性を残していますが、品質を維持するため、Memento が提供する機能は固定されています。

対象外の機能と現在の制限事項の全一覧は、KNOWN_LIMITATIONS.mdをご覧ください。

全体の仕組み

┌─────────────────────────────────────────────────────────┐
│  Clients: Claude Desktop, Claude Code, Cursor, Copilot, │
│           OpenCode, custom agents, …                    │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP (stdio)
┌──────────────────────▼──────────────────────────────────┐
│  memento-server (MCP adapter)                           │
└──────────────────────┬──────────────────────────────────┘
                       │ Command registry
┌──────────────────────▼──────────────────────────────────┐
│  memento-core: services, scope resolver, scrubber,      │
│                conflict detector, decay engine          │
└──────────────────────┬──────────────────────────────────┘
                       │ Repository interfaces
┌──────────────────────▼──────────────────────────────────┐
│  SQLite (better-sqlite3) + FTS5 + optional sqlite-vec   │
└─────────────────────────────────────────────────────────┘

アーキテクチャの全体像はARCHITECTURE.mdをご覧ください。重要な設計判断ごとに、アーキテクチャ決定記録があります。

コントリビューターの皆様へ（人間・AI）

人間の著者と AI の支援を受けた著者の、どちらからのコントリビューションも歓迎します。どちらにも同じ基準を適用します。

• AI エージェント、または AI エージェントと作業する方は、AGENTS.mdをお読みください。 これが正式な指示書です。CLAUDE.mdと.github/copilot-instructions.mdは、ここを参照するための簡潔なファイルです。
• 開発環境のセットアップ、ブランチ運用、コミット規約、PR のライフサイクルについては、CONTRIBUTING.mdをお読みください。
• 大きな変更を行う前に、設計提案の issueを作成してください。
• PR テンプレートを使用してください。 変更の説明だけでなく、変更の正当性を示すよう求めています。

質問やアイデアにはGitHub Discussionsを、バグ報告や承認済みの作業にはissue トラッカーをご利用ください。

ライセンス

Apache-2.0です。著作権表示についてはNOTICEをご覧ください。

パッケージ

Memento は、目的を絞った小規模なパッケージ群で構成されたワークスペースです。アーキテクチャはdocs/architecture/に、設計上の決定事項はdocs/adr/に記載されています。どちらも、Memento の機能とその理由に関する信頼できる情報源です。

パッケージ	備考
@psraghuveer/memento-schema	メモリ／イベント／スコープ／スクラバー／競合／設定／結果のスキーマと、ConfigKey ごとの値スキーマです。
@psraghuveer/memento-core	ストレージとマイグレーション、メモリおよびイベントのリポジトリ、スコープリゾルバー、スクラバー、compact アーカイブ処理を含む減衰エンジン、競合検出と置換ワークフロー、埋め込みフックと一括再埋め込みドライバー、EmbeddingProvider インターフェース、FTS とブルートフォースベクトル検索のパイプラインおよびランカー、検証付き実行パスを備えたコマンドレジストリ（ADR 0003）です。
@psraghuveer/memento-server	MCP アダプターです。buildMementoServer は @psraghuveer/memento-core のコマンドレジストリを MCP ツールとして公開し、serveStdio はそれを stdio に接続します。memento serve で使用されます。
@psraghuveer/memento-embedder-local	transformers.js と bge-base-en-v1.5 を利用するローカルの EmbeddingProvider です。通常の依存関係として提供され、遅延シングルフライト初期化により、初回使用時にモデルをダウンロードします。ADR 0006を参照してください。
@psraghuveer/memento (CLI)	公開されている memento バイナリ（npx @psraghuveer/memento または npm i -g @psraghuveer/memento）です。ライフサイクルコマンド（init、serve、dashboard、context、doctor、verify-setup、status、ping、backup、export、import、pack、store migrate、completions、explain、skill-path、uninstall）に加え、レジストリのサーフェスを汎用的に公開します（memento <namespace> <verb>）。docs/reference/cli.mdを参照してください。
@psraghuveer/memento-dashboard	ローカルファーストのウェブダッシュボードです。エンジンと同一プロセス内で動作する Hono サーバーと、Vite でビルドされた React SPA で構成されます。memento dashboard で起動し、127.0.0.1 のみにバインドします。ADR-0018とdocs/guides/dashboard.mdを参照してください。
@psraghuveer/memento-landing	マーケティング用のランディングページです。静的な SPA で、packages/landing/** に変更がある状態で main にプッシュされるたびに GitHub Pages にデプロイされます。ダッシュボードのデザイントークンを反映し、ライト／ダークを切り替えられます。非公開（npm では公開されていません）。