open-memex

open-memex

AI コーディングエージェントのための永続メモリ — お使いのマシン上にプレーンな Markdown で保存し、利用するすべてのツールで共有できます。

中文文档

AI コーディングセッションは毎回、ゼロから始まります。プロジェクトについて説明し直し、エージェントは同じ落とし穴を再発見し、昨日の決定事項はチャットが終わると消えてしまいます。open-memex を使えば、セッションをまたいで残るメモリをエージェントに持たせられます。「覚えておいて：金曜日にデプロイする」と一度伝えれば、翌週には Copilot、Cursor、opencode、Claude Code がすでに把握しています。すべてが、お使いのマシン上にある同じローカルメモリを読み書きするからです。

• 無料のオープンソース（Apache-2.0）。アカウントもクラウドもテレメトリも不要です。すべてはお使いのマシン上にあり、開いて編集できるファイルとして保存されます。
• ローカルファースト：メモリはプレーンな Markdown ファイル（信頼できる唯一の情報源）と、再構築可能な SQLite キーワードインデックスで構成されます。明示的に共有しない限り、データがマシンの外に出ることはありません。
• ひとつのメモリをすべてのエージェントで共有：ひとつのコマンドで複数のエディターを接続できます。それぞれが別々にメモリを保持するのではなく、同じメモリを共有します。
• 正確な同義語検索：ship で deploy が見つかり、单点登录 で SSO が見つかります。同等表現をまとめた厳選済みの多言語マップが、書き込み時にすべてのメモリとともにインデックス化されるため、関連する表現を取りこぼさず、適切な答えを見つけられます。決定論的で監査可能な仕組みのため、埋め込みモデルは不要です。

初めての方へ：この README では、インストールから実際に使えるメモリのセットアップまでを約1分で案内します。起動後は、コンセプトガイドで基本的な考え方を詳しく説明しています。

目次

• クイックスタート
• 基本概念
• 対応エディターと機能
• インストール
• エディターのセットアップ
• init がマシンに加える変更
• 記録：メモリの保存方法
• エージェントが使えるツール
• メモリの種類
• チームのワークフロー：Git を使ったメモリの共有
• 検索：メモリの呼び出し方法
• セキュリティとデータ
• 制限事項
• アップグレード
• ストレージ構成
• 設定
• CLI リファレンス
• MCP サーバー
• スコープの詳細
• トラブルシューティング
• FAQ
• プロジェクトのステータス

クイックスタート

Node.js ≥ 22.14 が必要です（node -v で確認してください）。次に：

npm install -g open-memex
open-memex init

init はインストール済みのエディター（VS Code、Cursor、opencode、およびプロジェクトにソリューションファイルがある場合は Visual Studio）を検出し、それぞれを open-memex に接続します。その後、エディターを再起動してください。

動作を確認する（30秒）：

open-memex add "This project deploys on Fridays"

エディターで新しいチャットを開き、エージェントに 「このプロジェクトはいつデプロイしますか？」 と尋ねてください。説明し直さなくても、すでに答えを知っています。一度記録すれば、いつまでも呼び出せる。この一連の流れが製品のすべてです。以下では詳細を説明します。

任意ですが、推奨します — すべて正しく接続されているか確認してください：

open-memex doctor

コアコンセプト

open-memex の仕組みは、次の4つの考え方でほぼすべて説明できます。

1. 2つのスコープ：project と personal。 すべてのメモリは、次のいずれかに属します。

• project — 1つのコードベースに関する知識（決定事項、制約、教訓）。 現在のリポジトリが自動的にスコープとなるため、手動で設定する必要はありません。
• personal — あらゆるプロジェクトに適用される、あなた自身に関する知識（好み、習慣）。 このマシン上にのみ保存され、リポジトリに共有されることはありません。

「簡潔な差分が好みです」のようなあなた自身に関する情報は personal に保存され、それ以外はすべて現在のプロジェクトに保存されます。

2. 記録 → 呼び出し。 メモリは、1つの事実につき1つの小さな Markdown ファイルとして保存されます。新しいセッションの最初のターンごとに、open-memex は最も関連性の高いメモリをエージェントに自動的に渡すため、エージェントは最初からそれらを把握した状態でセッションを開始できます。また、エージェントは必要に応じてメモリ全体を検索できます。自分で何かを「読み込む」必要はありません。

3. ファイルもルールも自分のものです。 Markdown ファイルが信頼できる唯一の情報源です。開いて編集したり、削除したり、grep したりできます。隣にある SQLite インデックスは検索を高速化するだけのもので、いつでもファイルから再構築できます（open-memex reindex）。チームで共有する場合も、コードと同じレビューの流れを通します。何も自動的に共有されることはありません（チームのワークフローを参照してください）。

4. 知識を常に最新の状態に保ちます。 事実は変わります。決定事項が覆されたり、ツールが置き換えられたり、昨日の問題が修正されたりします。open-memex では、古いバージョンが気付かれないまま残ることはありません。memory_supersede はメモリを新しいバージョンに置き換えて履歴をつなげるため、履歴の監査可能性を保ちながら、検索では現在の事実が返されます。単に古くなったメモリは非推奨にできます。また、open-memex audit では、重複、古いエントリ、壊れた履歴チェーンが報告されます。不要なメモリの整理は機能の一部であり、単なる保守作業ではありません。共有メモリは、整理しなければ劣化します。

対応エディターと機能

open-memex は、ネイティブなopencode プラグインと、MCP に対応するあらゆるエディターで使える標準のMCP サーバーという、2 つの方法でエディターと連携します。（MCP — Model Context Protocol — は、エージェントに追加のツールを提供するためにエディターが使用するオープン標準です。open-memex は、エディター内で memory_* ツールのセットとして表示されます。）利用できる機能は、エディターがどちらの方法を使うかによって異なります。

エディター	セットアップ	ツール	セッション開始時の想起	キーワードによる自動記録
opencode（ネイティブプラグイン、推奨）	open-memex init --client opencode --global	コアツール 5 個	組み込み — すべてのセッションの最初のターン	はい — remember …、记住…
VS Code（Copilot）	open-memex init --client vscode	MCP 経由で 11 個すべて	MCP のガイダンス経由*	いいえ — エージェントは依頼されたときに保存します
Cursor	open-memex init --client cursor	MCP 経由で 11 個すべて	MCP のガイダンス経由*	いいえ — エージェントは依頼されたときに保存します
Claude Code	claude mcp add open-memex -- open-memex mcp	MCP 経由で 11 個すべて	MCP のガイダンス経由*	いいえ — エージェントは依頼されたときに保存します
Visual Studio 2022 17.14+ / 2026	open-memex init --client visualstudio	MCP 経由で 11 個すべて	MCP のガイダンス経由*	いいえ — エージェントは依頼されたときに保存します
Codex およびその他の MCP クライアント	open-memex mcp --print-config	MCP 経由で 11 個すべて	MCP のガイダンス経由*	いいえ — エージェントは依頼されたときに保存します

* MCP にはセッション開始時に実行される固定のフックがないため、open-memex は MCP ハンドシェイクでエージェントにガイダンスを送信します（保留中の下書きの数も含みます）。また、init はより詳しい内容をエディターの指示ファイルに書き込みます。実際にはエージェントはこれに従いますが、最初のターンに真の組み込みインジェクションを行えるのは opencode プラグインだけです。ツールのセクションでは、5 個のコアツールと 6 個の追加ワークフローツールを一覧にし、「5 対 11」の違いを明示しています。

同じマシン上のすべてのエディターは、同じメモリを読み書きします。VS Code で記録された制約は opencode でも尊重され、Cursor で得た教訓は Claude Code にも反映されます。（異なるマシン間では自動的に同期されません。FAQを参照してください。）

init は VS Code と Cursor、さらにプロジェクト単位の MCP モードでの opencode にエージェントスキル（スキル対応エージェントに CLI の使い方を教える短い指示ファイル）もインストールします。opencode のネイティブプラグインを接続した場合、スキルはインストールされません。プラグインがすでにメモリツールを提供しており、指示を重ねてもエージェントの発話が冗長になるだけだったためです。

比較

	open-memex	指示ファイル（CLAUDE.md、AGENTS.md、…）	クラウドメモリサービス	チャット履歴
保存場所	お使いのマシンとリポジトリ	リポジトリ内	ベンダーのサーバー	チャット終了時に消去
管理者	作業中に記録し、内容を確認します	手作業で作成・更新します	サービス	—
情報が変わったとき	置き換えられ、古い情報が黙って残ることはありません — 検索では現在のバージョンが返され、履歴は保持されます	手作業で編集します。古いコピーが残ります	サービスによって異なります。古い情報が黙って残ることもよくあります	—
AI ツール間で利用可能	はい — あらゆる MCP クライアント（同じマシン上）	ツールごとにファイルが必要	連携ごと	いいえ
共有前に確認	はい — outbox とプルリクエスト	はい — ただのファイルです	サービスによって異なります	いいえ
人が読みやすい	プレーンな Markdown ファイル	はい	ダッシュボード / API	いいえ

指示ファイルは、少数の常設ルールには最適です。そのまま使い続けてください（open-memex では、メモリから指示ファイルの下書きを作成することもできます。以下の distill-agents を参照してください）。open-memex は、増え続ける決定事項、教訓、好みのうち、誰も書き留めることを思い出さないものをカバーします。

インストール

必要条件

• Node.js ≥ 22.14（open-memex doctor で確認できます）。下限は SQLite ドライバーの要件によるものです。better-sqlite3 13 は Node-API 10 を対象にビルドされており、Node で Node-API 10 が導入されたのは 22.14.0 です。これより古い Node では、最初にデータベースを開く際にセグメンテーション違反が発生します。

CLI のインストール

npm install -g open-memex

これは安定版のリリースです。パッケージのインストール時に open-memex init の実行を促すメッセージが表示されることがあります。エディターの設定は別の手順です（ エディターの設定を参照してください）。このメッセージが 表示されなくても心配はいりません。次に init を実行してください。

次の 2 つの方法もあります。

• インストールせずに実行 — npx を使用： npx -y open-memex <command> を実行すると、インストールせずに任意のコマンドを実行できます （例：npx -y open-memex init --client vscode）。起動は遅くなりますが、 アンインストールする必要はありません。
• アルファビルド（最新の機能を含みますが、まだ不安定なため、テスター向けです）： npm install -g open-memex@alpha。公開済みのバージョンは npm view open-memex version（安定版）および npm view open-memex@alpha version （アルファ版）で確認できます。

インストール後に open-memex が見つからない場合は、PATH の設定を確認してください。 トラブルシューティングを参照してください。

ソースからインストール（コントリビューター向け）

git clone -b main https://github.com/stoneskin/open-memex.git
cd open-memex
npm install
node --experimental-strip-types src/cli.ts <command>

エディターの設定

作業対象リポジトリにプロジェクトのスコープを合わせるため、プロジェクトのルート（作業中のリポジトリの最上位フォルダー）で init を実行してください。

open-memex init --yes
# …or without installing the package first:
npx -y open-memex init --yes

--yes を指定すると、init で尋ねられるすべての項目（設定するエディター、自動キャプチャ、初回ターンでの想起）に推奨される既定値が適用されます。各項目に回答する場合は、--yes を省略してください。--client を指定しない場合、init はインストール済みのエディターを検出し、すべてを設定します。1 回の初期化で、すべてのプロジェクトに対応できます。エディターを 1 つだけ設定する場合は、--client を指定してください。

VS Code（Copilot）：

open-memex init --client vscode

MCP サーバーのエントリーを書き込みます。その後、ウィンドウを再読み込みし、Copilot Chat の MCP パネルで open-memex サーバーが起動していることを確認してください。既定では、プロジェクトレベルの .vscode/mcp.json に書き込みます（対話形式で実行すると、使用するレベルを尋ねられます）。代わりに VS Code のユーザーレベルの設定に書き込むには、--global を追加してください。これにより、すべてのプロジェクトで使える設定になります。

Cursor：

open-memex init --client cursor

VS Code と同じ構成です。既定ではプロジェクトレベルの .cursor/mcp.json に書き込み、--global を指定するとユーザーレベルの MCP 設定に書き込みます。また、Copilot 形式の指示も設定します。

opencode（ネイティブプラグイン — 推奨）：

open-memex init --client opencode --global --yes

ユーザーレベルの ~/.config/opencode/opencode.json（または、すでに opencode.jsonc を使用している場合はそのファイル）にネイティブプラグインをマージします。設定は一度だけで済み、すべてのプロジェクトで適用されるため、プロジェクトごとに init を実行する必要はありません。コアツール 5 つ、キーワードによる自動キャプチャ、初回ターンでのコンテキスト注入を利用できます。（コメントを含む設定ファイルは変更されません。init が手動で追加する行を表示します。）

同じインストールで、opencode の両方の世代に対応します。init は opencode 1 の表記（"plugin"）と opencode 2 の表記（"plugins"）を書き込みます。それぞれのホストが対応するキーを読み取ります。この機能には、opencode 1 のバージョン 1.18.29 以降が必要です。設定とインストール済みのホストのバージョンが一致しない場合は、open-memex doctor で確認できます。

opencode（通常の MCP クライアントとして使用）：

open-memex init --client opencode

MCP サーバーを含むプロジェクトレベルの opencode.jsonc を書き込みます。ネイティブプラグインではなく通常の MCP を使用する場合にのみ必要です。キーワードキャプチャと組み込みの注入機能は利用できません。

Claude Code（プロジェクトのルートから実行）：

claude mcp add open-memex -- open-memex mcp
# …or print the config snippet: open-memex mcp --print-config claude

Visual Studio（ソリューションのディレクトリから実行）：

open-memex init --client visualstudio

ソリューションレベルの .mcp.json に書き込みます。Visual Studio 2022 17.14 以降、または Visual Studio 2026 が必要です（Windows のみ）。Visual Studio は .vscode/mcp.json と .cursor/mcp.json も自動検出するため、上記の VS Code の設定も使用できます。

Codex： init のクライアントはまだありません。open-memex mcp --print-config を出発点として、手動でサーバーを追加してください（config.toml の [mcp_servers]、または codex mcp add）。

すべてのプロジェクトで使うための一度限りのセットアップ（VS Code / Cursor）

open-memex init --client vscode --global --yes

2 種類の「グローバル」を混同しないでください。

• npm install -g open-memex はパッケージをグローバルにインストールします。これにより、open-memex コマンドが PATH に追加されます。
• init --global はプロジェクトではなくユーザーレベルにエディター設定を書き込みます。一度初期化すれば、どのプロジェクトでも連携が機能します。パッケージをグローバルにインストールした場合でも、npx 経由で実行した場合でも同じように機能します。

--global を指定すると、プロジェクトではなく、エディターのユーザーレベル MCP 設定（Windows では %APPDATA%\Code\User\mcp.json、macOS では ~/Library/Application Support/Code/User/mcp.json、Linux では ~/.config/Code/User/mcp.json、Cursor では ~/.cursor/mcp.json）にサーバーエントリーを書き込みます。一度初期化すれば、どのプロジェクトでもサーバーが起動します。プロジェクトで独自の設定を定義している場合は、プロジェクトごとの .vscode/mcp.json が優先されます。ユーザーレベルのファイルにコメントが含まれている場合（エディターは JSONC を受け付けます）、init はファイルを変更せず、手動で貼り付けるための正確なスニペットを表示します。

init の動作に関する注意事項

• 既存の設定ファイルは上書きせず、常にマージされます。init を再実行しても安全です。--force を指定すると、open-memex のエントリーを書き換えます。
• open-memex が PATH 上に永続的に存在しない場合（例：一度限りの npx 実行）、init は設定に npx -y open-memex mcp サーバーコマンドを書き込み、セットアップが継続して機能するようにします。後から npm i -g open-memex + open-memex init --force を実行すると、より高速な直接コマンドに切り替わります。
• 対話型ターミナルでは、init は検出したエディターを表示して確認を求めます。スクリプトや CI ではプロンプトを表示せず、検出したすべてのエディターを設定します。
• 初期化が完了していないマシンで open-memex を引数なしで実行すると、（対話型ターミナルに限り）初期化の実行を提案します。

連携設定の削除

open-memex uninstall --yes

init の変更を元に戻し、MCP サーバーエントリー、opencode プラグイン行、Agent Skill、エディターの指示から open-memex のセクションを削除します。--client を指定しない場合は、検出されたすべてのエディターをクリーンアップします。--global を指定すると、クリーンアップはユーザーレベルの連携設定に限定されます。メモリには一切手を加えません。

init がマシン上で変更する内容

init が書き込む内容をまとめています。

• メモリデータ（初回使用時に作成され、init 自体では作成されません）： Windows では %APPDATA%\open-memex\、macOS/Linux では ~/.local/share/open-memex/ に作成されます。メモリファイルと検索インデックスが含まれます。uninstall がこれらを変更することはありません。
• エディター連携設定（open-memex uninstall で削除されます）：
  • opencode：~/.config/opencode/opencode.json（または .jsonc）にマージされる "plugin" エントリー（opencode 1）と "plugins" エントリー（opencode 2）。名前の変更前に作成された古い my-o-memory エントリーも同時に削除されます。
  • VS Code / Cursor：ユーザーレベルまたはプロジェクトレベルの MCP 設定に追加される open-memex サーバーエントリー、および Copilot の指示に追加される open-memex セクション（デフォルトではユーザーレベルの ~/.copilot/copilot-instructions.md。--instructions project を指定すると、全員が open-memex を使うチーム向けに、リポジトリ内の .github/copilot-instructions.md に書き込みます）。
  • Visual Studio：ソリューションと同じ場所にある .mcp.json。
  • Agent Skill：VS Code（~/.copilot/skills/）、Cursor（~/.cursor/skills/）、またはプロジェクトごとの MCP モードの opencode（~/.config/opencode/skills/）用の skills/open-memex/ フォルダー。
• リポジトリ：何も変更されません。リポジトリにファイルが追加されるのは、明示的に submit を実行した場合のみです（「チームのワークフロー」を参照）。これはローカルコミットであり、自動的にプッシュされることはありません。

コメントを含むファイル（JSONC）は書き換えません。init は貼り付けるための正確なスニペットを表示します。

キャプチャ：記憶が保存される仕組み

記憶を追加する方法は3つあります。

• キーワードトリガー（opencode のネイティブプラグインのみ）：remember …、 note that …、don't forget: …、TIL …、save this … — または中国語の 记住… / 记一下… / 记录一下… / 别忘了：… — と言うと、ツール呼び出しなしで 文がキャプチャされます。デフォルトでは、キャプチャは現在のプロジェクトに保存されます。 「これは自分についてのこと」と示す表現 — remember for me …、help me remember: …、 记住我…、替我记…、帮我记…、我觉得…、我喜欢… — の場合は、代わりに 個人用に保存されます。また、チームに関する表現（我们决定…、帮我们记住…）は プロジェクトに保存されます。ノイズを抑えるため、2つのルールがあります（D67）。トリガーは ストアへの記録指示である必要があるため、记得… / remind me to… / 别忘了带伞 / don't forget the wifi password のような語りかけの表現では起動しません （区切りを加えて 别忘了：…、don't forget: … とするか、that を加えて指示にします）。 また、キャプチャされた本文が3文字未満の場合は、保存せず断片として拒否されます。 capture --dry-run を使うと、黙って破棄されるのではなく、その旨が表示されます。 トリガーはそれ自体の文も記録します。プラグインは、保存した内容をエージェントに伝えます。 その後数分以内に memory_add で同じ語句を再保存しようとすると、保存済みの ID とともに拒否されます （D73） — 1回の発言は1つの記憶であり、同じ内容を3つ保存するわけではありません。
• エージェントによる保存：どのエディターでも、エージェントに何かを覚えるよう頼むと （または、保存する価値のある事実を伝えたときにエージェントが自動で保存すると）、 memory_add が呼び出されます。上記の振り分けはヒューリスティックです。 「これを自分の個人用メモリに保存して」と伝えるか、CLI で --scope を指定すれば、 いつでも明示できます。
• チェックポイントの提案：タスクが完了すると、エージェントはセッションから抽出した 1～3件の短い記憶候補（決定事項とその理由、慣例、注意点、試したものの採用しなかった方法）を 提案し、あなたが承認したものだけを保存します。何も黙って書き込まれることはありません。 あなたに内緒で下書きが作られることもありません。
• CLI：open-memex add "…" に、必要に応じて --scope / --tag / --type / --aliases を指定します。

別名。 保存する記憶には、最大4つの別表現（同義語や別の言語での表現）を付けられます。 別名は記憶とともにインデックス化されるため、質問の言い回しが異なっていても記憶を見つけられます。 たとえば、「休暇日数」と尋ねると休暇ポリシーが見つかります。常に有効です — エージェントは 1件の記憶につき最大4つの別名を付けられます。また、open-memex add --aliases で 自分で指定することもできます。

別名を追加する方法は3つあります。open-memex add "text" --aliases "phrase one; phrase two" を使う（セミコロン区切りで最大4つ）、エージェントに頼む （「remember: Fluffy is my AI agent, alias it as Momo」）、または記憶の aliases: フロントマターを直接編集する方法です — Markdown が信頼できる唯一の情報源であり、 同期によって変更が取り込まれます。

これとは別に、選定済みの同義語／翻訳マップが書き込み時に自動でインデックスに展開されます （D80） — 記憶に別名がなくても、ship で deploy が見つかります。個人的なニックネームは 別名に、共有する開発ドメインの語彙は選定済みのマップに登録してください。 検索：記憶が呼び出される仕組みを参照してください。

秘匿化。 機密情報を <private>…</private> で囲むと、保存前に取り除かれます。 認識されたシークレット（API キー、トークン、高エントロピーの認証情報）は、その場でマスクされます — どのキーだったか判別できるよう最初の4文字は残し、それ以降を置き換えます — そのうえで記憶は保存されます。 メッセージがキャプチャする内容を、安全に、いつでも正確にプレビューできます。

open-memex capture --dry-run "…"

それでもシークレットが保存されてしまった場合は、open-memex forget <id> で記憶を削除できます。

エージェントが利用できるツール

MCP サーバーは11個のツールを公開し、opencode のネイティブプラグインは中核となる5個（●印）を公開します。残りの6個はチームレビューのワークフローツールで、Git を通じてメモリを共有する場合にのみ必要です。

ツール	機能
● memory_add	事実、好み、決定、メモを保存します
● memory_search	プロジェクトと個人のメモリをキーワード検索（BM25）します
● memory_list	スコープ（project、personal、または both）内のメモリを番号付き一覧として表示します。include=all は監査用ビューです
● memory_supersede	メモリを新しいバージョンに置き換えます（置き換えの連鎖は維持されます）
● memory_forget	ID でメモリを削除します（soft=true にすると、削除せずに非表示にします。一度だけ実行できます）
memory_status	同期キューを表示します。送信トレイの下書き、リポジトリのレビュー状態、未コミットのファイルが含まれます
memory_submit	名前を指定した下書きをリポジトリのメモリディレクトリに移します（ローカルブランチ＋コミット）
memory_propose	個人のメモリをレビュー候補としてプロジェクトスコープにコピーします
memory_promote	proposed → approved → published と進めます（または却下／再提出します）
memory_resolve	競合しているメモリファイルを一覧表示し、そのうち1つを3方向マージします
memory_pr_status	ブランチの PR の GitHub 状態を各メモリのレビュー状態に対応付けます

つまり、MCP に接続されたエディターでは常にすべてのツールを利用できます。opencode のプラグインは記録と想起を担い、ワークフローに関わる操作は CLI または MCP に接続されたエディターから行います。

メモリの種類

各メモリには type（メモリの種類）と tags（メモリの内容に関するタグ）があります。組み込みの種類は11個です。

種類	記録する内容
fact	プロジェクトや世界に関する、安定した事実
preference	物事の進め方に関する好み
decision	決定した内容、その理由とトレードオフ
constraint	違反してはならないルール
todo	後で何かを行うという約束
knowledge	長期的に役立つドメイン知識やアーキテクチャ知識
howto	うまくいった手順
gotcha	避けるべき落とし穴
lesson	インシデントや間違いから得た教訓
observation	気づいたこと。まだ結論には至っていない内容
reference	正式なドキュメントへのポインター（内容のコピーはしません）

--type には任意の文字列を指定できますが、組み込みの種類を使うと、セッション開始時のラベル、検索、distill-agents の出力を予測しやすく保てます。

チームのワークフロー：Git を通じたメモリの共有

一人で作業していますか？ このセクションは読み飛ばして構いません — 一人で使う場合は、ここまでの内容が製品のすべてです。以下で説明する処理は、自動で実行されることはありません。

個人のメモは非公開のままです。共有することにしたプロジェクトの知識は、コードレビューに似た、明示的でレビュー可能なパイプラインを通ります。

capture → outbox (draft, local) → submit → repo (.ai/open-memex/) → PR review → published → recall

1. 記録 — 通常の作業中に、決定、落とし穴、教訓を下書きとして保存します。
2. レビュー — 下書きはローカルの送信トレイで待機します（自分のマシン上にあり、Git からは見えません）。open-memex sync-status を実行するか、チャットで「sync memory」と伝えると、保留中の項目が表示されます。
3. 提出 — メモリを指定すると、現在のブランチ上でローカルコミットが行われ、<repo>/.ai/open-memex/ に移されます。open-memex が自らプッシュすることはありません。プッシュと PR のコマンドが表示され、明示的な許可を得たエージェントがそれらを実行できます。
4. PR レビュー — メモリは通常の Markdown 形式です。レビュー担当者は通常のブランチ／PR プロセスを通じて、承認、変更要求、または却下を行います。
5. 想起 — 公開済みのメモリはセッション開始時に挿入され、必要に応じて検索できます。人間もエージェントも同様に利用できます。

共有メモリを管理する人は、キュレーターの慣例に従います。承認する内容、差し戻す内容、共有メモリの劣化を防ぐための整理ルールが記載されています。

検索：記憶がどう呼び戻されるか

各セッションの最初のターンで、open-memex は最新のプロジェクトの記憶（デフォルト：上位 8 件）と個人設定（デフォルト：上位 5 件）を含む [OPEN-MEMEX] ブロックをエージェントのコンテキストに挿入します。次のような形式です：

[OPEN-MEMEX]

User profile / preferences:
- I prefer concise diffs

Project knowledge (my-repo):
- [decision] We deploy on Fridays; the release train leaves at 10:00

Use the `memory_search` tool to look up more. Use `memory_add` to save new facts.
Do not mention this block to the user unless asked.

これはスナップショットであり、記憶全体ではありません。エージェントはいつでも memory_search を呼び出して、残りを検索できます。どちらの上位 N 件の数も設定可能です（設定を参照）。MCP クライアントでは、このブロックはエージェントが従うハンドシェイクのガイダンスとして配信されます。opencode プラグインは最初のターンに直接挿入します。

検索評価

評価は、アサーションを行うのではなく、チェックイン済みの合成フィクスチャで再現率を測定します。54 件の記憶と 44 件のクエリ（完全一致する語、言い換え、同義語、中国語、言語横断の難しいケース、同義語のみのクエリ、D81 のユーザー定義エイリアスのクエリ）を使用します。次のコマンドで再現できます。 node --experimental-strip-types scripts/retrieval-eval.ts インデックス作成時の同義語／翻訳の拡張（D80）と、クエリ時のユーザーエイリアスの拡張（D81）を含む現在のベースラインは、recall@1 0.75、recall@5 0.98、MRR 0.86です。 小規模な合成コーパスであるため、実環境での結果ではなく、回帰防止と出発点として捉えてください。

3 つのレイヤーがそれぞれ他のレイヤーでカバーできない部分を補います。BM25 キーワード検索（SQLite FTS5 — 完全一致する語を高速に検索し、search --explain で結果の根拠を確認できます）。2 つの方式による同義語の拡張 — (a) インデックス作成時（D80：開発ドメインの同等語と EN↔ZH の翻訳ペアをまとめた、チェックイン済みのマップを、書き込み時にインデックスへ展開します。これにより、モデルをダウンロードせずに、通常の 1 回のクエリで ship から deploy を、bug から defect を検索できます）；(b) クエリ時のユーザーエイリアス（D81：alias:／target: のフロントマターを含むエイリアス記憶によって、スコープごとに語彙を一度定義できます。たとえば、Banana Plan → 決済システムのリファクタリングプロジェクトなどです。どちらか一方に言及するクエリは、もう一方を対象とする 2 回目の検索を両方向で実行し、1 回目の検索と均等に統合するため、エイリアスによる検索結果の重みが下がることはありません。エイリアスが変更されても再インデックスは不要です）。そして、オプトインで試験的に利用できるセマンティックベクトルです（ローカルの多言語埋め込みは、言語横断フィクスチャの一部で R@5 92.7% を記録しています。docs/retrieval-ablation-study.md §4.7 を参照してください。明示的にオプトインしない限り、埋め込みモデルがダウンロードされることはありません）。

公開データによる外部評価では、同じパイプラインが LongMemEval-S（470 件の質問、検索段階のみ。回答生成と判定モデルは含まず、公式の LongMemEval スコアではありません）で recall@5 97.0%／MRR 0.909 を記録します。参考までに、同じプロトコルにおける agentmemory の公開値は、BM25 のみで 86.2%／0.715、BM25＋ベクトルで 95.2%／0.882 です。22k 件の記憶をプールしたストレステストでは、recall@5 は 40.6% に低下します。語彙検索の上限を、主張ではなく測定によって示したものです。次のコマンドで再現できます。 node --experimental-strip-types scripts/bench-longmemeval.ts --data <path> （データセット：xiaowu0162/longmemeval-cleaned、MIT）。

セキュリティとデータ

• **ローカルファースト：**すべてのデータは、選択したリポジトリとともに、ご利用のマシン上に保存されます（Windows では %APPDATA%\open-memex、macOS/Linux では ~/.local/share/open-memex）。クラウドへの接続、アカウント、サードパーティ API、テレメトリーは一切ありません。
• シークレットを除外：<private>…</private> で囲まれた範囲は削除され、検出された API キー／トークンは保存前に該当箇所でマスクされます。open-memex capture --dry-run "…" でプレビューできます。
• 個人データは同期されません：personal スコープはこのマシンでのみ使用されます。デフォルトでエクスポートから除外され、リポジトリに入ることはありません。
• **共有の監査が可能：**チームの記憶は、明示的な submit によってのみ移動し、ブランチ／PR のレビューを経由します。また、すべての promote の移行は、実行者／日時／理由とともに記憶の review_history に追記されます。
• **ファイルはご自身で管理できます：**Markdown が信頼できる唯一の情報源です。ファイルは手動で確認、編集、削除できます。SQLite インデックスはファイルから再構築されます。

制限事項

意図しない驚きがないよう、制限事項を正直にお伝えします。

• キーワード検索であり、セマンティック検索ではありません。 検索は BM25 によるキーワードマッチングに加え、キュレーションされた同義語マップをインデックスの書き込み時に展開します（ship で deploy が、bug で defect が見つかります）。キュレーションされたマップにない言い換えは一致しません。そのための機能が、オプトインのセマンティックレイヤーです。（「どうすれば……」や「请问……」のような普通の質問は問題ありません。マッチングの前に除外されるため、自然な聞き方をしても結果の質は下がりません。）明示的にオプトインしない限り、埋め込みモデルがダウンロードされることはありません。（同義語の展開結果は、独自のエイリアスとは別のインデックス列に保存されます。ただし、展開語句だけで一致するクエリは、直接一致する結果より順位が低くなる場合があります。これは BM25 の長さ正規化によるもので、バグではありません。）
• 1 台のマシンのみです。 同じマシン上のエディターはメモリを共有しますが、マシン間の同期機能はありません。マシン間でメモリを移動するには、以下の export／import バンドルを手動で使用します。
• スナップショットであり、すべてではありません。 セッション開始時の想起は上位 N 件のスナップショットです（デフォルトではプロジェクト用 8 件、個人用 5 件）。古いメモリは memory_search で検索できますが、一度にすべてがコンテキストに含まれるわけではありません。
• MCP のガイダンスは助言的なものです。 opencode 以外では、先回りした記録と想起はエージェントがハンドシェイクの指示に従うかどうかに左右されます。MCP にはセッション開始時に必ず実行されるフックはありません。ツール自体は呼び出せば常に動作します。
• 記録先の振り分けはヒューリスティックです。 個人に関する表現（remember for me …、我喜欢…）は個人用に振り分けられ、それ以外はすべて現在のプロジェクト用になります。誤って振り分けられた場合は、スコープを明示するか、CLI で --scope を使用してください。

アップグレード

npm install -g open-memex@latest   # or @alpha

エディターの設定はインストール済みの open-memex コマンドを参照するため、アップグレード時に再設定は不要です。メジャーアップグレード後は、open-memex init --force を 1 回実行して、インストール済みの Agent Skill と指示ファイルを最新の表現に更新してください。ソースからインストールした場合やパッケージを移動した場合は、--force によって opencode プラグインのパスも再設定されます。

各バージョンの変更点については、CHANGELOG をご覧ください。

ストレージの構成

%APPDATA%\open-memex\               (Windows)
~/.local/share/open-memex/          (macOS/Linux; $XDG_DATA_HOME if set)
├── index.db                         # SQLite FTS5 index (rebuildable)
└── memories/
    ├── personal/
    │   └── <id>.md
    └── project__<name>__<hash12>/
        └── <id>.md

各 .md ファイルが 1 件のメモリです。YAML フロントマター（id, scope, type, tags, created_at, schema_version、…）に続いて本文が記載されています。手動で編集できます。インデックスはファイルから再同期され、Markdown が常に信頼できる唯一の情報源です（open-memex reindex を実行すると、インデックスが最初から再構築されます）。

submit を実行すると、プロジェクト用のメモリも <repo>/.ai/open-memex/（memoryDir で設定可能）以下に Markdown ファイルとして保存されます。ほかのファイルと同様に、ブランチや PR とともに移動します。

設定

設定は ~/.config/opencode/open-memex.jsonc に保存されます。パス内の opencode は歴史的な名残で、このファイルはすべてのクライアントで共有されます。OPEN_MEMEX_CONFIG で設定ファイルのパスを、OPEN_MEMEX_HOME でストレージのルートを上書きできます（旧名称の MY_O_MEMORY_CONFIG／MY_O_MEMORY_HOME も、引き続きフォールバックとして使用できます）。

デフォルト値：

{
  "maxProjectMemories": 8,    // top-N project memories injected on first turn
  "maxProfileItems": 5,       // top-N personal items injected on first turn
  "injectOnFirstTurn": true,  // [OPEN-MEMEX] system-prompt block
  "keywordCaptureEnabled": true,
  "logLevel": "info",          // info | debug
  "memoryDir": ".ai/open-memex" // in-repo project-memory dir, relative to repo root
}

open-memex config を実行すると、有効な設定（デフォルト値とファイルの設定）が表示されます。インストール後に設定を変更するには、次のようにします。

open-memex config set keywordCaptureEnabled false
open-memex config set maxProjectMemories 12
open-memex config set sync.autoPull true   # best-effort pull at MCP session start

設定可能なキー：maxProjectMemories、maxProfileItems、injectOnFirstTurn、keywordCaptureEnabled、captureAliases、logLevel、memoryDir、sync.autoPull（ネストされた sync オブジェクトに書き込むドット区切りのキー）。設計の詳細については、docs/V2-DESIGN.md をご覧ください。

CLI リファレンス

セットアップとヘルスチェック：

open-memex init [--client vscode|cursor|opencode|visualstudio]
              [--instructions personal|project] [--global] [--force] [--yes]
open-memex uninstall [--client vscode|cursor|opencode|visualstudio] [--global] [--yes]
open-memex config                                  # print effective config
open-memex config set <key> <value>                # change a setting
open-memex doctor                                  # environment health check (incl. plugin entry)
open-memex audit                                   # memory health check (duplicates, stale, broken chains)
open-memex capture --dry-run "remember that I like concise answers"  # preview keyword capture
open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
open-memex --help      # this reference
open-memex <command> --help  # help for one command
open-memex --version   # installed version

メモリ操作：

open-memex add "This repo uses better-sqlite3" --type fact
open-memex search "auth flow"
open-memex search "auth flow" --explain   # show FTS expression, scores, lifecycle-hidden counts
open-memex list --scope project
open-memex list --scope both       # each scope's newest under its own header
open-memex list --include all      # audit view: superseded versions, retracted, archived
open-memex supersede <id> "Updated content"
open-memex status <id> deprecated
open-memex forget <id>
open-memex forget <id> --soft      # hide instead of delete (retracted; one-way)

open-memex inventory                        # everything remembered, as readable text
open-memex inventory --format json          # the same data, for agents
open-memex inventory --format html          # the same data as a local page (writes <data dir>/inventory.html)
# Personal + current project, outbox drafts in their own section, hidden
# history counted. Refuses to write a personal-bearing report inside a
# git working tree unless you pass --allow-personal.
# `list` numbers every entry in one listing and says how many it left out.

チームレビューのワークフロー（2 つの保存先、それぞれ 1 つのステージ）：

プロジェクトの下書きは appdata outbox（Git から見えず、ブランチにも依存しない）に保存されます。承認した下書きだけが <repo>/.ai/open-memex/ に移され、そこでブランチや PR に従います。あなたが指定しない限り、何も移動しません。MCP サーバーに接続した AI チャットで、「sync memory」（または「同步记忆」）と言うだけで、エージェントがステータスを確認し、outbox の下書きを要約して、どれを同期するか尋ねます。サーバーはエージェントに独自に情報も伝えます。セッション開始時のハンドシェイクで、待機中の下書きの数を通知し、メモリを変更する各ツールの結果には、0 以外の場合に現在の件数が含まれます。

open-memex sync-status
# show when the index was last synced (and what triggered it), the outbox
# (pending sync), the repo review states
# (draft / proposed / approved / published / rejected),
# and any uncommitted repo memory files.

open-memex submit <id...> [--branch <name>] [--base <branch>]
# move your named drafts into .ai/open-memex/ as "proposed":
# copies, flips review_state, local git commit ON THE CURRENT BRANCH.
# Never creates a branch on its own — branch creation is your call
# (or the agent's, only with your explicit approval for the full chain).
# All-or-nothing; conflicts (same id, different content) abort cleanly.
# Prints the push + gh pr commands; an agent holding your Yes carries
# through push/PR itself. --branch <name> creates the branch first
# (agent full-chain path). Default PR base is the current branch (memory
# PRs stack onto your working branch); --base redirects it to main or
# wherever you review.

open-memex pr-status [--apply]
# read the branch's GitHub PR and map its state onto each in-repo memory:
# merged PR → published, PR approval → approved (approved_by = reviewer),
# changes-requested → suggestion only. Report by default; --apply performs
# the mapped transitions locally (no push).

open-memex pull
# pull shared memories from the git remote: fetch + fast-forward ONLY.
# A diverged branch fails with a clear message — open-memex never
# force-merges; resolve it by hand, then pull again. On success the
# local index re-syncs. Pulls are explicit by default; set
# `open-memex config set sync.autoPull true` for a best-effort pull
# at MCP session start (a failed pull never blocks the session).

open-memex push
# push the current branch (with its submitted memories) to the git remote.
# Explicit only — open-memex never pushes on its own.

open-memex export [--scope project|personal|both] [--type T] [--tag t] [--all] [-o <file>]
# bundle memories into a portable .tar.gz (markdown + manifest.json) for
# moving to another machine or another app. Excludes visibility:private
# memories by default; --all / -a includes everything (full migration).

open-memex import <bundle.tar.gz> [--dry-run]
# restore a bundle: personal memories go to the personal dir; project
# memories are re-keyed to the current project and land in the outbox as
# drafts. Identical ids are skipped; conflicting ids are reported,
# never overwritten.

open-memex distill-agents [--scope project|personal] [--type t1,t2] [--limit N] [-o <file>]
# propose an AGENTS.md snippet distilled from project memories
# (decisions, constraints, lessons, gotchas, howtos). Prints markdown;
# -o writes it to a file. You review and merge by hand — open-memex
# never rewrites your AGENTS.md on its own. The snippet ends with a
# "memory hygiene" section so agents reading AGENTS.md learn to propose
# distilled captures when a task ends.

open-memex propose <id...> --to project [--local-approve]
# propose one or several personal memories at once (one branch, one PR);
# each is copied with its own new id. All-or-nothing: a bad id aborts the
# whole batch, never a half-proposed one.
# copy a personal memory into the project scope as a review candidate
# (never moves — the personal original stays). Result lands in the outbox;
# run sync-status / submit when you're ready to put it in the repo.
open-memex promote <id> [--reject] [--resubmit] [--note "..."] [--by NAME]
# advance one step: proposed → approved → published (or reject with a note).
# Every transition is appended to the memory's review_history (who/when/why).
# A rejection never deletes the file — your call: accept it (close the PR,
# delete the branch), revise + --resubmit for another round, or keep it as
# a [rejected] record.
open-memex resolve [id-or-path]
# list conflicted memory files, or field-level 3-way merge one of them.
# Semantic conflicts are reported, never auto-resolved.

共有メモリを管理する担当者は、キュレーターの規約に従います — docs/CURATOR.md：承認する内容、差し戻す内容、共有メモリの劣化を防ぐための衛生ルールが記載されています。

メンテナンス：

open-memex where        # show storage + config paths
open-memex scopes       # list project scopes with memory counts
open-memex reindex      # rebuild the SQLite index from markdown
open-memex audit        # memory health: duplicate pairs, stale memories, broken chains
open-memex migrate --to-v2 [--dry-run]   # v1 data → v2 (renames user scope to personal)

CLI は Node 22 で動作します。ソースチェックアウトからは、組み込みの実験的な TypeScript ローダーを使用するため、ビルド手順は不要です。公開される npm パッケージには、コンパイル済みの JS が含まれます（公開時に npm run build を実行）。ソースチェックアウトから実行する場合は、すべてのコマンドの先頭に node --experimental-strip-types src/cli.ts を付けてください（簡単な場合は npm run cli -- <command> も使えますが、npm は未知の --flag 引数を無視するため、直接 node を使うことをおすすめします）。

MCP サーバー

stdio サーバーを介して、Model Context Protocol 経由で同じメモリツールを利用できます。ホスト固有のプラグインは不要です。open-memex はどの MCP クライアントからでも利用できます。

open-memex mcp               # after a global install
npx -y open-memex mcp        # no install needed

プロジェクトのスコープはプロセスの作業ディレクトリから解決されるため、サーバーの cwd をプロジェクトのルートに設定してください（init が自動で設定します）。

注記： MCP はリクエスト／レスポンス方式です。エージェントにツールを提供しますが、opencode プラグインの自動キーワードキャプチャや初回ターンへのインジェクションは行いません。 先を見越したメモリの利用は、エージェントの指示に依存します。サーバーは MCP ハンドシェイクの instructions でセッション開始時のガイダンスを送信します（セッション開始時の最新の outbox 下書き件数と、0 以外の場合にメモリを変更するツールの結果に追加される保留件数を含みます）。また、init はより詳しい内容をエディターの指示ファイルに書き込みます。どちらも参考情報であり、セッション開始時に確実に実行されるフックを提供する MCP コンシューマーはありません。

スコープの詳細

• project — 現在のリポジトリを対象とし、Git の origin URL のハッシュをキーとして使用します（同じリポジトリのクローンは同じスコープを共有します）。リモートがない場合は cwd パスをキーとします。新しいメモリのデフォルトです。
• personal — このマシン上のすべてのプロジェクトで共通ですが、同期されません。個人的な好みに使用します。（v1 では user と呼ばれていましたが、migrate --to-v2 で名前が変更されます。）

スコープモデル全体（キーの導出、移行、可視性、予約名）については、docs/SCOPES.md をご覧ください。概念ガイドでは、メンタルモデルを最初から最後まで説明しています。

トラブルシューティング

すべてのコマンドが出力なしで終了する、またはプロセスがクラッシュする（exit 139、 0xC0000005、「Segmentation fault」）。 Node のバージョンが 22.14 より古く、同梱の SQLite ドライバーを読み込めません。 better-sqlite3 13 は Node-API 10 を対象にコンパイルされていますが、Node がこれに対応したのは 22.14.0 です。それより古いバージョンでは、require() は成功しても、最初にデータベースを開くと診断メッセージなしでプロセスがセグメンテーションフォールトを起こします。現在の open-memex はドライバーの読み込みを拒否し、その理由を表示しますが、すでにクラッシュしていた場合は、ほぼ間違いなくこれが原因です。node -v で確認し、Node をアップグレードする（nvm install 22.14 && nvm use 22.14、または現行の 22.x/24.x を使用する）か、npm install better-sqlite3@^12.11.1 でドライバーのバージョンを固定してください。open-memex doctor は Node の最低バージョンと、ドライバーの実動プローブ結果を報告します。既知のアップストリーム issue：WiseLibs/better-sqlite3#1514。

open-memex が認識されない／コマンドが見つからない。 グローバルな npm install -g は、npm のグローバル bin フォルダーに open-memex ランチャーを配置します。ターミナルから見つからない場合、そのフォルダーが PATH に含まれていません。

1. フォルダーを確認します：npm config get prefix
   • Windows： ランチャー（open-memex.cmd）はそのフォルダー直下にあります。例：C:\Users\<you>\AppData\Roaming\npm
   • macOS / Linux： <prefix>/bin にあります。例：/usr/local/bin または ~/.nvm/versions/node/v22.x.x/bin
2. PATH に追加します：
   • Windows： 設定 → システム → バージョン情報 → システムの詳細設定 → 環境変数 → ユーザー の Path にフォルダーを追加 → ターミナルを再起動します。where open-memex で確認してください。
   • macOS / Linux： export PATH="$(npm prefix -g)/bin:$PATH" を ~/.zshrc（または ~/.bashrc）に追加し、シェルを再起動してから、command -v open-memex で確認してください。
3. 管理者権限がない、または PATH を変更したくない場合は、npx 形式を使います。 npx -y open-memex <command> はパッケージ自体を解決するため、PATH の変更は不要です。

Windows で better_sqlite3.node に対して EBUSY / EPERM が発生する。 Windows では、読み込み済みの DLL はロックされます。open-memex MCP サーバーが実行中（VS Code の MCP パネル、Cursor など）の場合、npm install -g open-memex は better_sqlite3.node を置き換えられず、EBUSY / EPERM で失敗します。まず MCP サーバーを停止するか、エディターを終了してから、インストールを再実行してください。それでも失敗する場合は、グローバル npm ルートにある node_modules/open-memex と node_modules/.open-memex-* の一時フォルダーを削除してから、再度インストールしてください。

init が設定ファイルを変更せずに残したと表示する。 エディターの設定にコメント（JSONC）が含まれているか、JSON が無効です。open-memex は安全に解析できないファイルを書き換えません。init は手動で追加する正確なスニペットを表示しています。それを貼り付ければ完了です。opencode の設定にも同じことが当てはまります。コメントが含まれている場合は、"plugin" の行を手動で追加してください。

何かおかしい場合は、open-memex doctor を実行してください。 Node のバージョン、設定の参照元、現在のディレクトリに対するスコープ解決、ストレージへの書き込み可否を確認します。VS Code で MCP が無効化されていないことも検証します。その後、実際の MCP サーバーを起動し、initialize と tools/list を実行して、11 個すべてのツールが表示されることを確認します。また、いずれかのエディター設定が旧パッケージ名を参照している場合は、名前変更前の my-o-memory の残存設定も報告します。

FAQ

git は必要ですか？ いいえ。キャプチャと想起はどのフォルダーでも機能します。git リポジトリがない場合、プロジェクトのスコープはフォルダーのパスを基準にします。git が必要なのはチームのワークフロー（submit / PR レビュー）のみで、これは任意です。

複数のエディターを使っています。本当に同じメモリを共有できますか？ はい。同じマシン上であれば共有できます。接続されているすべてのエディターが同じローカルメモリを読み書きします。各エディターで利用できる機能については、機能マトリックスを参照してください。VS Code で記録した決定は、opencode でも尊重されます。 2 台のコンピューター（職場と自宅）を使っています。メモリは同期されますか？ 自動では同期されません。メモリは設計上、マシンごとに管理され、個人スコープが作成元のマシンから外に出ることはありません。メモリを手動で移動するには、一方のマシンで open-memex export を実行し、もう一方のマシンで open-memex import を実行してください。Git 経由で共有されるプロジェクトメモリ（チームワークフロー）はリポジトリと一緒に移動するため、2 台目のマシンでリポジトリをクローンすると、公開済みのプロジェクトメモリも一緒に取得されます。個人メモリは意図的に元のマシンに残ります。

本当に無料ですか？アカウントは必要ですか？ 無料のオープンソース（Apache-2.0）です。アカウントも登録も不要で、テレメトリーもクラウドへの通信もありません。外部に接続できないのであれば、接続先もありません。open-memex がネットワークにアクセスするのは、自分の git リモートだけです。しかも、明示的にプッシュした場合に限ります。

誤って秘密情報をメモリに貼り付けてしまいました。どうすればよいですか？ open-memex search "<part of it>" でメモリを検索し、open-memex forget <id> で削除してください。次回からこれを防ぐには、機密テキストを <private>…</private> で囲んでください（保存前に取り除かれます）。認識された API キーとトークンも自動的にマスクされます。open-memex capture --dry-run "…" を使うと、メッセージを安全にプレビューできます。

プロジェクトごとに init を実行する必要がありますか？ いいえ。データレイヤーには何も必要ありません。プロジェクトスコープは、現在の作業ディレクトリの git リモートまたはパスから自動的に決定されるため、設定なしでメモリがプロジェクトごとに名前空間で分けられます。エディターとの連携設定は、マシンごとに open-memex init を 1 回実行するだけです（エディターが対応している場合はユーザーレベルで設定されます）。アップグレード時（--force）またはエディターを切り替える場合にのみ、再度実行してください。

opencode では init が必要ですか？ 方法は 2 つあります。推奨される方法は open-memex init --client opencode --global です。ネイティブの open-memex プラグインが ~/.config/opencode/opencode.json にマージされます。初回のみの設定で、すべてのプロジェクトに適用され、キーワードによる自動キャプチャと最初のターンでのメモリ注入も有効になります。手動で設定する場合は、代わりに "plugin": ["file:///absolute/path/to/open-memex/src/index.ts"]（インストールされたパッケージのパス）をそのファイルに追加してください。通常の MCP クライアントとして使う場合は、open-memex init --client opencode を実行すると、プロジェクトレベルの opencode.jsonc が作成されます（フックなし）。ユーザーレベルの設定にコメントが含まれている場合、init はその設定に手を加えず、手動で行う手順を表示します。

VS Code — init は 1 回だけですか、それともプロジェクトごとですか？ 1 回だけです。通常の open-memex init は VS Code を自動検出し、MCP サーバーのエントリを VS Code のユーザーレベルの mcp.json に書き込みます（Windows では %APPDATA%/Code/User/mcp.json、macOS では ~/Library/Application Support/Code/User/mcp.json、Linux では ~/.config/Code/User/mcp.json）。これにより、すべてのプロジェクトでサーバーが起動します。プロジェクトごとの .vscode/mcp.json がある場合は、そちらが優先されます。また、エントリには cwd=${workspaceFolder} が設定されているため、ウィンドウごとのプロジェクトスコープの解決も引き続き機能します。ユーザーレベルの mcp.json にコメントがある場合（VS Code は JSONC を受け入れます）、init は変更せず、手動で追加するための正確なスニペットを表示します。空のファイルは空白のファイルとして扱われ、そのまま書き込まれます。

エディターとの連携設定を削除するにはどうすればよいですか？ open-memex uninstall は init の変更を元に戻します。MCP サーバーのエントリ、opencode プラグインの行、Agent Skill ディレクトリ、Copilot の指示にある open-memex のセクションを削除します。--client を指定しない場合は、検出されたすべてのエディターをクリーンアップします。--global を指定すると、ユーザーレベルの連携設定のみが対象になります。メモリには一切手を加えません。

Node をアップグレードした、または nvm でバージョンを切り替えました。再インストールは必要ですか？ パッケージ自体は影響を受けません。SQLite ドライバーは Node-API のビルド済みバイナリなので、再コンパイルなしで、サポート対象の任意の Node（≥ 22.14）で読み込めます。また、メモリはインストール先の外に保存されます。ただし、バージョンマネージャー（nvm など）は Node のバージョンごとに別のグローバルパッケージフォルダーを使うため、切り替え後に open-memex が「見つからない」ことがあります。新しい Node で npm install -g open-memex を 1 回実行し、続けて open-memex doctor を実行して、ドライバーが読み込まれることを確認してください。

プロジェクトの状況

open-memex は安定しており、日常的に使用されています。現在の安定版は npm で latest として公開され、テスター向けに alpha ビルドも提供されています。リリース履歴は GitHub Releases にあり、設計上の決定は追記専用ログの docs/V2-DESIGN.md に記録されています。

今後の展望（バージョンの約束はありません）：同じ MCP ツールを拡張する、より多くのエディター向けのネイティブなエージェントプラグイン。オプトイン形式の実験としてのローカル埋め込み（確認なしにモデルがダウンロードされることはありません）。実際の複数リポジトリ共有、ACL、またはコンプライアンス上のニーズが求められる場合に限った組織レイヤー。

ライセンス

Apache-2.0