memex

memex

Claude があなたについてより賢く理解できるようにします。

npm install -g @evan-moon/memex

Claude があなたについてより賢く理解できるようにします。

MCP 経由で Claude と連携する、ローカルファーストの第二の脳です。メモはプレーンな Markdown として保存され、ローカルの ML モデルでインデックス化されます。完全にオフラインで動作し、API キーは不要で、データがマシンの外に出ることはありません。

---

問題

Claude の賢さは、会話に含まれる情報に左右されます。あなたの決定、背景、考えは、毎回貼り付けない限り見えません。

You:    What did we decide about the auth approach last sprint?
Claude: I don't have context from previous conversations...

解決策

You:    What did we decide about the auth approach last sprint?

Claude: [memex · search_notes · "auth approach decision"]

        Found 2 notes:

        Auth Architecture Decision  Apr 14  #auth #backend
        ─────────────────────────────────────────────────────
        Chose JWT + refresh tokens over sessions. Rationale:
        stateless design fits horizontal scaling plan.

        Based on your April 14th note: you went with JWT +
        refresh tokens. Tom also flagged keeping auth decoupled
        from payment logic, separate bounded contexts.

Claude は回答する前にメモを検索し、会話の最後に得られた知見を、頼まれなくても自動的に保存します。

---

インストール

npm install -g @evan-moon/memex

アプリを接続します：

memex mcp install

これにより、このマシン上のすべての MCP クライアント（Claude、Claude Code、Codex、Cursor）に memex が登録されます。それぞれの設定ファイルに書き込みます。登録後、クライアントを再起動してください。

以上です。初回実行時に、埋め込みモデル（約450MB）が ~/.memex/models/ に一度だけダウンロードされます。

自動呼び出し（任意）

memex recall install

検索するかどうかを Claude が 判断する 方式から、自動的に検索される方式に切り替わります。入力した各プロンプトはメモと意味的に照合され、上位3件のタイトルが Claude の回答前にコンテキストとして挿入されます。ネイティブのメモリと同じ仕組みです。その後、タイトルが関連しているように見える場合、Claude は get_note を使ってメモ全体を取得します。

バックグラウンドデーモンが埋め込みモデルをメモリ上に保持します（~/.memex/recall.sock）。そのため、検索にかかる時間は、モデルの読み込みに約1.5秒かかるコールド状態の CLI 検索ではなく、約30ミリ秒です。2時間後にアイドル状態になります。

コスト：モデルがウォーム状態の間は約200MBのメモリを使用し、各プロンプトに最大3件のメモのタイトルがコンテキストとして追加されます。削除するには memex recall uninstall を実行してください。

---

機能

• セマンティック検索。キーワードだけでなく、意味に基づいてノートを検索します。多言語（韓国語＋英語）に対応し、multilingual-e5-base を使って完全にオフラインで動作します
• ハイブリッド検索。ベクトル検索＋BM25 全文検索＋タグ照合を、Reciprocal Rank Fusion で統合します
• チャンク単位の埋め込み。長いノートは約 340 トークンの文章に分割して個別に埋め込まれるため、3 ページ目に埋もれた回答も冒頭の段落と同じように見つけられます。検索結果にはノートの最初の行ではなく、一致した文章が返されます
• クロスエンコーダーによる再ランキング（オプトイン、MEMEX_RERANK=1）。候補を通常の 2 倍取得し、bge-reranker-v2-m3 を使って並べ替えます。golden set で hit@1 が約 20 ポイント向上し、検索 1 回あたり約 1.8 秒かかります。自動想起と CLI は即時検索を前提に構築されているため、デフォルトでは無効です
• 日付フィルター。--from／--to を使って検索対象を期間で絞り込めます
• ノートレイヤー。すべてのノートは past（不変の記録）、state（変更可能な計画）、または rule（Claude の動作ガイド）のいずれかです。past ノートは更新を拒否し、rule ノートは Claude のシステムプロンプトに自動挿入されます
• フラッシュバック。保存時と検索時に、意味的に関連する別フォルダー内の古いノートが自動的に表示されます。「別の文脈で 124 日前にこれについて書いていました」
• 推論エンジン。決定論的な シグナル により、統合されていないパターン（年をまたぐ流れ、古くなった state ノート、再び使われたタグ）を提示します。有用なものは、出典情報を持つ仮説である 推論 に昇格できます。推論は、元になったノートが変更されると自動的に無効になります。中核部分に LLM は使いません
• MCP サーバー。Claude が自動的に検索して保存します。追加の CLAUDE.md 設定は不要です
• 自動想起。オプトインのフックで、プロンプトごとにノートを検索し、Claude が回答する前に検索結果を挿入します。これにより、想起が Claude の検索し忘れに左右されません
• 重複検出。save_note は意味的に類似したノートがすでに存在する場合に警告し、新規作成ではなく更新するよう Claude に促します
• バックリンク。[[Title]] 構文でノートをリンクできます。get_note では、そのノートを参照しているノートが表示されます
• シリーズの集約。日付付きの作業ログ（「… 2026-07-20」、「… 2026-07-23」）が検索結果ページで占める枠は最大 2 つです。検索結果には、ほかに何件が保留されたかも表示されます
• 修正記録。修正には、修正対象（amends）が記録されるため、検索時に置き換えられたノートにフラグを付け、すでに誤りだとわかっている主張ではなく最新の修正を示します
• ダイジェスト。memex digest は、過去 N 日間に保存されたノートをフォルダーごとにまとめます
• CLI。ターミナルからノートの追加、検索、タグ付け、閲覧、インデックス作成ができます
• Obsidian 互換。ノートは .md ファイルとして保存され、既存の保管庫と併用できます
• ローカル DB。~/.memex/memex.db に SQLite ＋ sqlite-vec を使用します

---

CLI

# Add notes
memex add                                    # interactive prompt (asks for layer)
memex add --title "Note title" --content "..." --layer past
memex add --title "Note title" --file ./note.md --layer state
memex add --title "Note title" --content "..." --folder work/people/tom --layer past
memex add --title "Note title" --content "..." -T typescript -T architecture --layer past

# Layers
memex layer                               # distribution of past / state / rule
memex layer <id> state                     # move a note to a different layer

# Search
memex search "semantic search query"         # multilingual
memex search "knowledge management" --limit 10    # multilingual: matches Korean/Japanese notes too
memex search "query" --tag typescript        # filter by tag
memex search "query" --from 2026-04-01       # notes since a date
memex search "query" --from 2026-04-01 --to 2026-04-30

# Browse
memex list                                   # recent 10 notes
memex list --limit 20
memex show <id>
memex tags                                   # all tags with counts
memex related <id>                           # semantically related notes
memex digest                                 # last 7 days + signals + inferences
memex digest --days 30                       # summary of last 30 days

# Insights (inference engine)
memex signals                                # detect un-synthesized patterns
memex signals --type hidden_arc              # one type only
memex signals dismiss <id>                   # triage (also: snooze)
memex signals mint <signalId>                        # print evidence bundle to synthesize
memex signals mint <signalId> --title "..." --summary "..." --confidence 0.7
memex inferences                             # list inferences (auto-flags stale)
memex schedule                               # print cron/launchd snippet (no daemon)

# Edit / delete
memex edit <id>
memex delete <id>
memex delete --yes <id>                      # skip confirmation

# Index external directories
memex source add ~/Documents/My\ Notes       # register a vault
memex source list
memex source remove ~/Documents/My\ Notes
memex index                                  # scan vault + all sources
memex index --force                          # re-index everything
memex reembed                                # re-embed with current model

# Config
memex config show
memex config set vault-path ~/Documents/Second\ Brain

# MCP
memex mcp install                            # register with every MCP client on this machine

# Auto-recall
memex recall install                         # search notes on every prompt, inject hits
memex recall uninstall                       # remove the hook
memex mcp path                               # print MCP binary path

---

MCP サーバー

Claude、Claude Code、Codex、Cursor

memex mcp install

各クライアント専用の設定ファイルに書き込み、すでに登録されているサーバーには手を加えません。クライアントで古いバージョンの memex がまだ動作している場合は、新しいものに接続し直します。memex mcp path を実行すると、memex がまだ認識していないクライアント向けのサーバーパスが表示されます。

利用可能なツール

ツール	説明
save_note	メモを保存します。layer が必要です。類似するメモがすでに存在する場合は警告し、フラッシュバックを表示します
search_notes	セマンティック検索を行います。category、tag、date_from、date_to フィルターをサポートし、最上位の結果にフラッシュバックを追加します
list_notes	最近のメモを一覧表示します
list_tags	メモ数とともにすべてのタグを一覧表示します
list_folders	メモ数とともにすべてのフォルダーを一覧表示します
get_note	ID を指定して、メモの全文とバックリンクを取得します
update_note	タイトルまたは内容を更新します。past メモ（代わりに [Amendment] を提案）と rule メモ（ユーザーのみ編集可能）の更新は拒否します
delete_note	ID を指定してメモを削除します
get_signals	決定論的で未合成のパターン（hidden_arc / stale_state / dangling_link / tag_burst）を取得します
update_signal_status	シグナルをトリアージし、却下またはスヌーズします
list_inferences	合成された仮説を一覧表示します（最初に古さを再確認します）
get_inference	出典情報と変更・削除マーカーを含む、1 件の推論を取得します
mint_inference	承認済みの仮説を保存します。明示的な確認が必要です

推論はメモとは別に保持され（検索対象外）、事実ではなく仮説として引用されます。検出は決定論的なままで、唯一の LLM 処理は推論の要約を合成することです。これは Claude が行い、memex は行いません。

メモのレイヤー

すべてのメモは、変更可能性に基づいて次の 3 つのレイヤーのいずれかに分類されます。

レイヤー	意味	Claude の権限
past	起きたことの記録、振り返り、会議、意思決定の根拠、デバッグセッション	追記のみ。update_note は拒否し、代わりに [Amendment] メモを提案します
state	現在の状態や計画、プロジェクトの進捗、ロードマップ、人物の現在の役割	自由に更新できます
rule	Claude 向けの行動指針、コーディングスタイル、検索ポリシー	Claude は読み取り専用です。書き込めるのはユーザーのみです

CLI では、list、search、show の各コマンドで、メモの横に色分けされた [past] / [state] / [rule] バッジが表示されます。

• save_note（MCP）と memex add（CLI）では、明示的な layer の指定が必要です。分類ルールはツールの説明に記載されているため、Claude は適切なレイヤーを選択できます。
• 初回実行時、既存のメモにはフォルダーに基づいてレイヤーが割り当てられます。projects/dev/herald → state、coding → rule、それ以外はすべて past になります。移行は冪等です。
• rule メモは MCP サーバーの指示にも自動挿入されます。詳しくは、以下のルールレイヤーの自動挿入を参照してください。

フラッシュバック

メモを保存または検索すると、memex は別のフォルダーにある、意味的に類似した古いメモを自動的に表示します。「別の文脈で、124 日前にこのことについて書いています」といった内容です。これはシステム生成のバックリンク（note_links.source = 'flashback'）として保存され、[[wikilinks]]（source = 'wiki'）とは別に扱われます。

環境変数で調整できます。

環境変数	デフォルト	動作
MEMEX_FLASHBACK_DAYS	90	最小経過日数（日単位）
MEMEX_FLASHBACK_DIST	0.4	最大ベクトル距離（値が小さいほど一致条件が厳しくなります）
MEMEX_FLASHBACK_LIMIT	3	表示ごとの提案の最大数

ルールレイヤーの自動挿入

layer = 'rule' のメモは、起動時に MCP サーバーの指示へ ## House Rules セクションとして追加されます。Claude はすべての会話の開始時にこれらを参照できるため、search_notes の呼び出しは不要です。コーディングスタイルガイドなど、行動に関する指針を置くのに適した場所です。

環境変数	デフォルト	動作
MEMEX_INJECT_RULES	enabled	0 に設定すると、挿入を完全に無効にします
MEMEX_RULES_MAX_CHARS	8000	挿入されるセクションのバイト数の上限。超過分は切り詰められ、console.warn が出力されます

ルールメモへの更新は、次回の Claude Desktop / Claude Code の再起動時に反映されます。

---

Configuration

設定は ~/.memex/config.json にあります。

Key	Default	Description
vault_path	~/Documents/Second Brain	.md ファイルの保存先ディレクトリ
sources	[]	インデックス対象に追加するディレクトリ（例：既存の Obsidian ボルト）
aliases	{}	検索エイリアスマップ。例：{ "js": ["javascript", "ecmascript"] }。値には、スクリプト間の橋渡しとして任意の言語を指定できます

memex config set vault-path ~/my-vault

---

Architecture

~/.memex/
  config.json, vault path, sources, and aliases
  memex.db, SQLite DB (notes + note/chunk vec embeddings + FTS5 index)
  models/, cached embedding model

<vault>/
  *.md, notes (Obsidian-compatible)

Package	Role
@memex/db	SQLite スキーマ、drizzle クエリ、sqlite-vec と FTS5 の統合
@memex/embed	@huggingface/transformers を使用したローカル埋め込みモデル
@memex/rerank	ローカルのクロスエンコーダーによる再ランキング（オプトイン）
@memex/core	CLI と MCP で共有するノートサービス：保存、編集、検索、ベクトルインデックス作成
@memex/utils	設定、パスヘルパー、共有ユーティリティ
@memex/mcp	MCP サーバー（CLI の dist にバンドル）

---

The ecosystem

memex は、ひとつの原則を共有するローカルファーストのツール3つのうちのひとつです。データはあなたのマシンに置いたまま、AI がそのデータを利用します。 これらのツールは任意の MCP クライアントを通じて相互運用でき、互いに依存しません。

flowchart TB
    U([You])
    subgraph I["Interfaces, talk to your tools"]
        direction LR
        CD[Claude Desktop]
        CC[Claude Code]
        CU[Cursor]
    end
    subgraph T["Local-first tools, each owns its data, on your machine"]
        direction LR
        F["firma · money<br/>~/.firma"]
        M["memex · memory<br/>~/.memex"]
        S["skope · news<br/>~/.skope"]
    end
    U --> I
    I -- MCP --> F & M & S
    F <-. never call each other .-> M
    M <-.-> S

• firma · 資産、お金、純資産、キャッシュフロー
• memex · セッションをまたいで記憶、ノート、それらを取り巻くコンテキストを管理
• skope · ニュース、世界を捉えるパーソナライズされた視点

Claude Desktop、Claude Code、Cursor、その他の MCP クライアントから利用できます。ツール同士を呼び出すのではなく、モデルを通じて連携します。

---

Where this is going

memex は記憶エンジンであり、読むための場所ではありません。ウィンドウもエディターも、常に把握しておく必要のある画面もありません。人が手作業で見極めていたすべてのこと――何がまだ有効か、後から書かれたノートのどれが以前の内容を訂正したか、書かれたときとは異なる表現の質問にどのノートが答えるか――は、エージェントが質問したその時点で、検索経路そのものが判断しなければなりません。

デスクトップアプリを廃止した理由は、LLM が書いた文書は誰も読まないからです。整理し続けなければならないボルトは、いずれ朽ちます。そのため目標は、読まなくても、メンテナンスしなくても正しく検索できる構造です。

Goal	Status
質問の表現ではなく、質問そのものに答える検索（ハイブリッド検索＋再ランキング＋チャンク分割）	リリース済み
訂正内容を、訂正されたノートを返すすべての場所に反映	リリース済み
何が古くなったかを、シグナルと推論によって決定論的に特定	リリース済み
ノートの有効期間を作成時に明示するレイヤーとテンプレート	リリース済み
人がキューを消化するのではなく、読み取り時に古さを判断	進行中
推測なしで主張を再検証できるよう、エビデンス（derives_from）を必須化	進行中

対象外：GUI、同期、コラボレーション、公開、プラグインシステム、グラフキャンバス。

設計記録は docs/plans/ にあります。これらの文書は決定の履歴であり、ロードマップではありません。デスクトップアプリ向けに書かれた文書は削除済みです。

---

llms.txt

llms.txt は、llms.txt 標準に従い、ドキュメントへのリンクを含む簡潔な説明をまとめた、このプロジェクトに関する機械可読な LLM エージェント向けの概要です。

---

License

MIT