Memex

散らばった Codex の会話を収集し、永続的な知識を蒸留し、それを結びつけ、 インデックス化し、必要なときに適切な記憶を取り戻す。

Memex は Codex のためのローカルファーストの個人知識システムです。ローカルの ロールアウトセッションを、検索可能な会話アーカイブ、永続的な事実、オントロジー ベースの知識グラフ、そして Codex が後続の作業で再利用できる制限付きコンテキスト に変換します。

한국어 README · ドキュメント · インストールと運用 · アーキテクチャ · スキーマ

Memex は、MIT ライセンスの jung-wan-kim/memory-bank から派生した 独立した Codex ネイティブプロジェクトであり、さらに obra/episodic-memory から派生しています。 知識システムの機能は保持していますが、Claude Code 互換コードは含みません。 系譜と移行 を参照してください。

なぜ 0.1.0 なのか?

0.1.0 は最初の公開リリースとして適切です。機能セットは充実しておりテスト済みですが、 リポジトリは新しく独立したものであり、Codex マーケットプレイス、ホストアダプター、 インストール契約は安定版の 1.0.0 の前に変更される可能性があります。バージョン 1.0.0 は、これらの公開契約が意図的に安定していることを意味し、単に多くの機能が 存在することを意味するものではありません。

Related MCP server: coding-memory-mcp

機能

• Codex の会話履歴に対するセマンティック検索、FTS5/BM25 検索、ハイブリッド検索

• LLM 呼び出しを必要としない決定的な全履歴分析

• インクリメンタルな事実抽出、信頼度ゲート、統合、改訂、来歴

• ドメイン/カテゴリのオントロジーと型付き知識グラフの関係

• プロジェクト、グローバル、明示的に要求された全プロジェクトのスコープ分離

• 1〜3 ホップのグラフ探索とクロスプロジェクトの洞察

• 関連性とセッションごとの重複排除を備えた制限付き RAG コンテキスト注入

• 圧縮された .jsonl.zst アーカイブに対する透過的な制限付き読み取り

• 会話、事実、オントロジー、グラフ、来歴のための 9 つの MCP ツール

• 想起、履歴分析、ダッシュボードワークフローのための 3 つの Codex スキル

• 事実、パイプラインの健全性、3D ナレッジギャラクシーを備えたループバックのみの Web UI

• Codex ネイティブの SessionStart、UserPromptSubmit、SessionEnd フック

アーキテクチャの概要

flowchart LR
    R[Codex rollout JSONL] --> S[Sync and parser]
    S --> A[Immutable local archive]
    S --> C[(Conversation index)]
    C --> X[Incremental fact extraction]
    X --> F[(Facts and revisions)]
    F --> O[(Ontology and typed relations)]
    C --> Q[Hybrid retrieval]
    F --> Q
    O --> Q
    Q --> M[MCP tools and skills]
    Q --> H[Prompt context hook]
    C --> UI[Loopback Web UI]
    F --> UI
    O --> UI

ソースのロールアウトは読み取り専用です。アーカイブ、SQLite/FTS/ベクトルインデックス、 事実、グラフデータは派生したローカル状態です。モデルを利用した作業は、分離された 一時的なローカル codex exec を通じて実行されます。Claude へのフォールバックや 別の API キープロバイダーはありません。

詳細なメカニズムについては、以下を参照してください:

• システムアーキテクチャ

• 会話ライフサイクル

• 事実ライフサイクル

• 知識グラフ

• 検索とコンテキスト注入

• MCP とスキル

• Web UI と 3D ビジュアライゼーション

要件

• Node.js 22.15 以降

• 認証済みの Codex CLI

• 現在のフックと Unix ソケットランタイムには macOS または Linux

このプラグインは、Node にバンドルされている npx ランチャーを使用して、BongSuCHOI/memex#main から 最新のランタイムを npm の分離キャッシュに解決します。プロジェクト内でクローンやビルドを 行ったり、グローバルパッケージをインストールしたり、Codex プラグインキャッシュに依存関係を 書き込んだりすることはありません。

推奨インストール

公開リポジトリから直接インストールします:

codex plugin marketplace add BongSuCHOI/memex
codex plugin add memex@memex

これでユーザーインストールは完了です。プラグインマニフェスト、3 つのスキル、MCP 宣言、 ライフサイクルフック、CLI ランチャー、UI ランチャーがインストールされます。最初の ランタイム呼び出しは、npx がネイティブの SQLite、ベクトル、埋め込み依存関係でキャッシュを 満たす間、時間がかかる場合があります。

既存の手動マーケットプレイスフロー

外部マーケットプレイスのレイアウトは、開発およびエアギャップ/ローカルテストのために 引き続きサポートされています:

memex-local-marketplace/
├── .agents/plugins/marketplace.json
└── plugins/memex -> /absolute/path/to/memex

そのエントリを ./plugins/memex に向け、codex plugin marketplace add /absolute/path/memex-local-marketplace で登録し、memex@<marketplace-name> をインストールします。ソースインストーラーは、 ローカル開発の検証のために引き続き利用できます。完全な JSON とロールバックの動作は、 運用ガイド に残っています。

初回起動時のオンボーディング

インストール後、Codex を再起動 して、新しくインストールされた MCP サーバー、スキル、 プラグイン管理のフックが新しいセッションで読み込まれるようにします。

読みやすいターミナルコマンドのために、このセッションローカルのシェル関数を定義します。 これは常に最新の main ランタイムをターゲットにしており、グローバルにはインストールしません:

memex() { npx --yes --package=github:BongSuCHOI/memex#main memex "$@"; }

次に、一度だけのコーパスセットアップを実行します:

memex setup
memex sync
memex backfill extract --foreground
memex backfill ontology --foreground
memex backfill embeddings --foreground
memex status

memex setup は、有効な Codex の memories 機能をチェックします。組み込みの Memory が有効な場合、Memex は二重メモリ/競合メモリのリスクを説明し、無効にすることを 推奨します。対話型ターミナルは確認を求めます。自動化および非対話型シェルは、明示的な memex setup --disable-codex-memory 承認フラグなしに設定を変更することはありません。 この変更は Codex 自身の codex features disable memories コマンドを使用し、その後検証されます。

各ステージの内容:

1. sync は既存の $CODEX_HOME/sessions を読み取り、新しいロールアウトをアーカイブし、 会話検索インデックスを構築します。

2. backfill extract は、すでにインデックス化された交換から永続的な事実を蒸留します。

3. backfill ontology は事実を分類し、グラフ構造を構築します。

4. backfill embeddings は欠落しているセマンティックベクトルを埋めます。

5. status は、会話、事実、グラフの準備状況を個別に報告します。

大規模な履歴とローカルモデルを利用した抽出には、数分以上かかる場合があります。 初回の明確な完了のために、コマンドをフォアグラウンドで実行してください。--background を 選択した場合、「開始」は「完了」を意味しません。保留中のカウントが期待される状態に達するまで、 memex status を確認し続けてください。

マーケットプレイスのインストールは、このオンボーディングステップの前にソースのロールアウトや 派生データを変更しません。sync は冪等であり、繰り返し実行しても安全です。

日常的な使用

memex sync
memex search "why did we choose SQLite?"
memex search --both "authentication migration"
memex stats
memex analyze --top 30 --out ~/memex-report.md
memex status

MCP ツールとスキル

プラグインは以下を公開します:

search, read, search_facts, search_ontology, ask_avatar,
trace_fact, explore_graph, cross_project_insights, graph_stats

プロジェクトに依存するツールには、正規の絶対プロジェクトパスまたは明示的な global/all スコープが必要です。MCP プロセスは、自身の cwd からスコープを推測することは ありません。スキーマと例については、MCP とスキル を参照してください。

ローカル Web UI

npx --yes --package=github:BongSuCHOI/memex#main memex-ui
# http://localhost:3847

ルート:

• / — 会話、プロジェクト、検索、交換

• /facts — 事実、改訂、来歴、保護された変更

• /graph — スコープ付きライブ 3D 知識グラフ

• /pipeline — 準備状況とバックログの健全性

サーバーはループバックのみにバインドします。ビジュアライゼーション を参照してください。

更新

プレビューしてから、Git マーケットプレイススナップショットを更新し、プラグインを再インストールします:

memex update --dry-run
memex update

ランタイムランチャーはすでに最新の main を追跡しています。memex update はマーケットプレイスの スナップショットも更新するため、更新されたスキル、フック、MCP メタデータが一緒にインストールされます。 その後、Codex を再起動してください。永続的な Memex データは保持されます。

想起の来歴と自己取り込みの安全性

Memex は、フックの想起を、セッションと人間のプロンプトハッシュによってキー付けされた、 永続的なイベントごとの memex_recall レシートとして記録します。Memex MCP の検索結果も 同じ方法で分類されます。来歴は証拠レベルであり、ターン単位ではありません。人間の主張と 許可リストに登録されたローカルリポジトリ、Git 履歴、テスト実行の結果は、想起の隣にあっても 学習可能なままです。Memex の結果、外部/不明なツールの出力、アシスタントが生成した合成は 学習されません。完全な交換は検索可能なままです。これにより、「想起 → エージェントのエコー → 新しい事実 → 想起」の増幅を防ぎながら、証拠に裏付けられた事実の進化を維持します。

アンインストール

プラグイン管理のフックは、プラグインが削除されると消えます。古い/手動のインストールで setup-hooks を使用した場合は、プラグインを削除する前に、フィンガープリントされたエントリのみを 削除してください:

npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks --dry-run
npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks
codex plugin remove memex@memex --json
codex plugin marketplace remove memex --json

アンインストールでは、$CODEX_HOME/sessions と Memex の派生データの両方が保持されます。 手動で削除する前に、正確なデータパスを確認してください。 運用ガイド を参照してください。

データとプライバシー

デフォルトの派生データは、永続データの互換性のために ~/.config/memory-bank に残ります。 解決順序:

1. MEMORY_BANK_HOME

2. MEMORY_BANK_CONFIG_DIR

3. $XDG_CONFIG_HOME/memory-bank

4. ~/.config/memory-bank

この命名は歴史的なストレージ互換性のためであり、Claude ランタイムアダプターではありません。 スキーマ と セキュリティ境界 を参照してください。

検証

npm run typecheck
npm run build
npm test
npm run test:marketplace
npm run test:package
node --test test/codex-slice.test.mjs
node --test test/*slice.test.mjs
node scripts/validate-plugin.mjs

Codex CLI 0.149.1 は codex plugin validate を公開していません。リポジトリはそのバージョン 境界を記録し、代わりに分離されたインストール済みアーティファクトの代替を実行します。 現在のレシートと残りの制限は、検証 に文書化されています。

貢献

開発または貢献のためだけにクローンしてビルドします:

git clone https://github.com/BongSuCHOI/memex.git
cd memex
npm ci
npm run build
npm test

製品の不変条件、所有権の境界、必要なチェックについては AGENTS.md を読んでください。 動作を変更する場合は、同じ変更内で ドキュメントマップ で識別される所有者 ドキュメントを更新してください。

ライセンス

MIT。上流の帰属とサードパーティの通知は、docs/LINEAGE.md と THIRD_PARTY_NOTICES.md にあります。