ai-memory — Chat History → AGENTS.md + Cursor Rules + MCP

ai-memory

AI エディターのチャット履歴を、型付き Markdown と AGENTS.md のルールに変換します。ローカルファーストで、Git で追跡でき、.remember() の呼び出しは不要です。

npx ai-memory-cli extract                     # read your editor's chat history → typed Markdown
npx ai-memory-cli rules --target agents-md    # → AGENTS.md (Cursor / Claude / Windsurf / Copilot / Codex all read it)
npx ai-memory-cli recall "OAuth"              # show the full git lineage of any decision
npx ai-memory-cli context --copy              # resume any session with full context

ほかの「AI メモリー」ツールはどれも、まず remember() API から始まり、コードに計測処理を組み込むよう求めます。ai-memory はエディターのチャット履歴を直接読み取ります。Cursor、Claude Code、Windsurf、Copilot Chat、Codex CLI に対応し、型付きで Git 追跡可能な Markdown に変換します。その内容は各 AI エディターが AGENTS.md を通じて読み込みます。新たに覚える API も、セッション間で維持するランタイムメモリーストアも必要ありません。

デフォルトでローカルファーストです。 会話がマシンの外に出ることはありません。ネットワーク通信は、抽出用に設定した LLM プロバイダーへの呼び出しだけです。または、Ollama／LM Studio を使って完全にオフラインで動作させることもできます。

中国語ドキュメント

---

ai-memory だけが実現すること

ほかでは見つからない、4 つの特長です。最初の 3 つは構造上の特長で、4 つ目はほかの誰も取り組んでいない技術への投資です。

1. .remember() のボイラープレートが不要です。 すでに書いた内容を読み取ります。ディスク上にすでにある Cursor／Claude Code／Windsurf／Copilot Chat／Codex CLI のトランスクリプトです。インポートする SDK も、維持するランタイムメモリーストアも必要ありません。アプリケーションコードから client.add(...) の呼び出しが必要な mem0／Letta／Zep／cortexmem と比べてみてください。

2. ネイティブな AGENTS.md 出力です。 ai-memory rules --target agents-md を実行すると、Cursor、Claude Code、Windsurf、Copilot、OpenAI Codex CLI が共通して読み込む標準のルールファイルが作成されます。マージは冪等です。変更されるのは ... end --> の間のセクションだけで、AGENTS.md に手書きした内容はバイト単位で保持されます。AGENTS.md の採用は 6 万以上のリポジトリに広がり、現在は Linux Foundation の管理下にあります。ほとんどのプロジェクトでは一から手書きしていますが、私たちは会話履歴から生成します。

3. Git で管理できるプレーンな Markdown。データベースは不要です。 .ai-memory/ が信頼できる情報源です。Markdown ファイルを git diff で確認し、コードレビューし、ブランチを作成し、元に戻せます。「Git で追跡可能な」メモリーをうたうほかのツールは、内部ストアのスナップショットを Git で追跡します。私たちは人間が読みやすいファイル形式を提供し、すべてを Git に任せます。マシン間の同期は git pull で行えます。

4. Git 履歴によるタイムトラベル検索です。 ai-memory recall <query> を実行すると、すべてのメモリーのコミットごとの完全な履歴が表示されます。4 月 1 日に決定事項に何が書かれ、4 月 15 日にどう変わり、何が変わったのか、誰が変更したのかを確認できます。ほかのメモリーツールが返すのは「最新」の内容だけで、以前のバージョンは気付かれないまま上書きされます。新たなランタイム依存関係はありません。recall は既存の git を 10 秒のタイムアウト付きで呼び出します。

私たちが測定していること

CCEB — Cursor 会話抽出ベンチマーク、gpt-4o-mini、手作業で厳選した 30 個のフィクスチャ（v1.1 拡張）：

指標	v1.1（2026-04-27、30 個のフィクスチャ）	v1.0 / v2.5-01（2026-04-26、9 個のフィクスチャ）	v2.4（2026-04-25、9 個のフィクスチャ）
全体 F1	64.1%（P 56.8% / R 73.5%）	76.2%（P 66.7% / R 88.9%）	56.0%（P 43.8% / R 77.8%）
decision / issue F1	78.3% / 100%	75.0% / 100%	66.7% / 66.7%
architecture F1	72.7%（再現率が新たなボトルネックです）	100%	50%
ノイズの除外（雑談 / 保留 / 仮定）	100% — 4 個のノイズ用フィクスチャのいずれにも、幻覚による記憶はありません	100%（2 個のフィクスチャ）	100%（2 個のフィクスチャ）
実時間	239.7 s	47.9 s	70.5 s
費用	≈ $0.02	≈ $0.006	≈ $0.005

v1.1 の拡張（cceb-001 — cceb-030）では、v1.0 で検証していなかった、より難しいケースを意図的に追加しました。たとえば、1 つの会話から複数の記憶を抽出するケース（アーキテクチャと規約の両方）、コミットメントの形式が曖昧なケース（プロセス上の TODO と技術的な TODO）、CJK／複数言語が混在する会話、意思決定への影響と後続作業の TODO を見分けるケースです。上記の 9 個のフィクスチャの行と比べて F1 は 12 ポイント低下しましたが、これはモデルの性能低下ではありません。同じプロンプトで v1.0 のフィクスチャだけを実行すると、引き続き 76% のスコアです。64% という数値は、同じ抽出器を、恣意的な選別を抑えたフィクスチャ分布で測定した、より率直な結果です。残る最大の改善余地は todo の適合率です（偽陽性 19 件のうち 11 件が TODO です）。ベースラインドキュメントの分析に基づき、次の施策として、抽出後に内容のペア単位で重複を除去する処理を追加する予定です。これは v2.6 向けに追跡しています。

サンプルの取りこぼしと偽陽性、フィクスチャごとの詳細、v1.0 → v1.1 の差分分析、手法はすべてベースラインドキュメントに記載しています。上流のモデルが更新されるたびに変動するリーダーボードのスコアを追うよりも、厳しい検証にも耐えられる数値を公開したいと考えています。

LongMemEval-50（コーパス横断の妥当性確認、bench/longmemeval/）：LongMemEval-S-cleaned の決定論的な 50 問のサブセットに対して、文字どおりのトークンに基づく証拠保持ルーブリックで評価すると、gpt-4o-mini では 完全一致 0 / 50 + 部分一致 2 / 50 となります（約 12 分、約 $0.40）。これは意図的に厳しくした代理指標です（「上流の回答に含まれる重要なトークンがすべて、抽出した記憶に残っているか」を測定します。LongMemEval のネイティブ QA 正答率ではありません。ルーブリックについてはスパイクドキュメント §4.3を参照してください）。0/50 という結果は、ai-memory が 500 ターンの大量データを対象としたオープンドメイン QA を目的としていないことを示しています。また、ベースラインドキュメントの質問ごとの一致数／合計数から、部分的なシグナルが得られる箇所（単一セッション内の好み：17〜43 トークン中、安定して 3〜6 トークン）も確認できます。LongMemEval、LoCoMo などは実行時の想起（エージェントが事実を記憶していたか）を測定します。一方、私たちが測定するのは抽出（チャットから適切な構造化成果物を取得できたか）です。対象とするレイヤーも問いも異なります。カテゴリ位置付け ADRも参照してください。

その他の機能

• トークンを節約 — context を使うと、何千ものターンを焦点を絞ったプロンプトに圧縮できます（通常、生の会話履歴をそのまま貼り付ける場合と比べて 90% 以上削減）。
• チーム対応 — .ai-memory/{author}/ の作成者別サブディレクトリにより、同じプロジェクトの記憶を 2 人がコミットしてもマージ競合が発生しません。
• デバイス間で持ち運び可能 — export / import により、ストア全体をバージョン付き JSON バンドルとしてエクスポート／インポートできます。
• 設定不要、API キー不要 — npx ai-memory-cli extract は、組み込みの無料モデルですぐに動作します。独自のキーを設定すると、会話数の上限が 2 件でなくなります。

---

よくある質問

「100 万トークンのコンテキストがあれば、もう不要なのでは？」

簡単に言うと、長いコンテキストと ai-memory は、同じ問題の異なる部分を解決します。100 万トークンのウィンドウを使えば、モデルは 1 回のクエリで長い会話を見ることができます。一方、ai-memory は、その会話の決定事項をセッション、マシン、チームメイトをまたいで永続化し、確認・共有できるようにします。構造化メモリツールに対する Hacker News で最も多く寄せられる反論なので、以下でこの質問に真剣に答えます。

履歴をクエリごとに再送すると、コストが積み重なります。 2026-04 時点で、最先端モデルの入力料金は 100 万トークンあたり約 $1～$3 です （Anthropic／ OpenAI／ Google AI）。ツール呼び出しのペイロードとファイルの差分を含めると、2 週間の Cursor セッションでは通常 100～300K トークンになります。それを毎回のターンに貼り付けると、何も質問する前からクエリあたり $0.20～$0.60かかります。同じ会話から生成した AGENTS.md は 1～5K トークン程度で、セッションごとに 1 回読み込まれます。チームの人数と 1 日あたりのクエリ数を掛け合わせれば、その差は 2 桁になります。

長いコンテキストを使った検索でも、見出しにならない情報の取得精度は低下します。 「Lost in the Middle」 （Liu et al. 2023）と、100 万トークン規模での干し草の山から針を探すテスト （BABILong, Kuratov et al. 2024）は、どちらも 100 万トークンのウィンドウをうたうモデルであっても、約 128～256K トークンを超えるマルチホップ検索で、再現率が測定可能なほど低下することを示しています。長いコンテキストは直近のターンや目立つターンにはよく機能しますが、「そういえば、3 週間前に X について何を決めたんだっけ？」という日常的な質問では精度が低下します。これはまさに、メモリツールが解決するよう設計されている検索です。抽出では、重要な唯一のシグナル（型付けされた決定事項／規約／アーキテクチャ）が失われません。

長いコンテキストはマシンごとですが、AGENTS.md はリポジトリごとです。 あなたのノート PC のチャット履歴は、チームメイトが初日に作業する助けにはなりません。Git にコミットされた .ai-memory/ ディレクトリなら役立ちます。PR でレビューでき、ブランチを作成でき、元に戻せます。また、リポジトリをクローンしたすべてのマシン上のあらゆるエディターで読み込めます。ai-memory にしかできないことをご覧ください。ポイント 3 と 4 では、これについて詳しく説明しています。

(a) 最先端モデルの料金が 100 万トークンあたり $0.50 未満になる、(b) 長いコンテキストのベンチマークで、500K トークンを超えても検索精度の低下が 5% 未満になる、または (c) エディターにセッションをまたぐ会話の圧縮機能が標準搭載される場合は、この FAQ を改めて検証します。トリガーの一覧と詳しい根拠は docs/1m-context-faq-spike-2026-04-27.mdにあります。

---

クイックスタート

# Initialise project (optionally register ai-memory as an MCP server)
npx ai-memory-cli init --with-mcp

# Extract — works out of the box with the built-in free model (no API key needed)
# Limited to 2 conversations per run on the built-in key.
npx ai-memory-cli extract

# Unlock unlimited extractions — set your own key (any OpenAI-compatible provider)
export AI_REVIEW_API_KEY=sk-...    # or OPENAI_API_KEY

# One-shot health check — verifies editors, API key, store, MCP config
npx ai-memory-cli doctor

# Search your knowledge base
npx ai-memory-cli search "authentication"

# Generate Cursor Rules from conventions
npx ai-memory-cli rules

# Generate a context prompt and copy to clipboard
npx ai-memory-cli context --copy

# Commit to git
git add .ai-memory/ && git commit -m "chore: add ai-memory knowledge base"

---

コマンド

try — API キー不要のデモ（30 秒、認証情報不要）

一時ディレクトリに手動で厳選した 3 件のメモリストアを構築し、それに対して実際の rules --target agents-md パイプラインを実行して、生成された AGENTS.md をその場に表示します。LLM の呼び出しも API キーも不要で、作業ディレクトリにも変更を加えません。セットアップを始める前に、「これは実際に何を生成するのか？」への具体的な答えを確認できます。

npx ai-memory-cli try                     # full demo, tmp dir cleaned up afterwards
npx ai-memory-cli try --keep              # leave the tmp scenario on disk for inspection
npx ai-memory-cli try --json              # structured output (counts, AGENTS.md content, paths)

付属のシナリオには、2 人の作成者による、1 件の決定事項（PKCE 認証フロー）、1 件のアーキテクチャ記録（イベントソーシングによる請求監査ログ）、1 件の規約（Relay スタイルのカーソルページネーション）が含まれます。AGENTS.md に追加されるのは規約と決定事項のみです。これは、実際に自分のメモリに対して rules コマンドを使うときと同じフィルターです。

doctor — 1 回で完了するヘルスチェック

try の後、実際のチャット履歴を使って ai-memory を設定する場合に実行してください。最も一般的な 6 つのセットアップ上の問題を診断し、それぞれの修正方法を正確に示します。

npx ai-memory-cli doctor                 # human-readable report
npx ai-memory-cli doctor --no-llm-check  # skip live API call (offline / CI)
npx ai-memory-cli doctor --json          # structured output for automation / bug reports

チェック項目は、Node.js のバージョン、検出されたエディター（Cursor／Claude Code／Windsurf／Copilot／Codex CLI と会話数）、LLM プロバイダーと接続のライブプローブ、メモリストアと作成者の解決、埋め込みの最新性、MCP 設定への登録です。すべてのチェックに合格すると終了コードは 0、いずれかのチェックに失敗すると 1 になります。API キーが設定されていない場合、doctor は API キー不要の最短手段として try を案内するようになりました。

list — 利用可能な会話を表示

npx ai-memory-cli list                            # show all conversations
npx ai-memory-cli list --source cursor             # only Cursor conversations
npx ai-memory-cli list --json                      # JSON output

extract — 会話からメモリを抽出する

npx ai-memory-cli extract                          # extract all conversations
npx ai-memory-cli extract --incremental             # only new conversations
npx ai-memory-cli extract --pick 3                  # only conversation #3
npx ai-memory-cli extract --pick 1,4,7              # multiple conversations
npx ai-memory-cli extract --id b5677be8             # match by ID prefix
npx ai-memory-cli extract --since "3 days ago"      # only recent conversations
npx ai-memory-cli extract --type decision,todo      # only specific types
npx ai-memory-cli extract --dry-run                 # preview without writing
npx ai-memory-cli extract --force                   # overwrite existing files
npx ai-memory-cli extract --author "alice"          # override author name
npx ai-memory-cli extract --redact                  # scrub secrets / PII before LLM call (v2.5+)
npx ai-memory-cli extract --verbose                 # show LLM request details
npx ai-memory-cli extract --json                    # JSON output (CI friendly)

API キーがありませんか？ extract は自動的に組み込みの無料モデル（SiliconFlow 経由の DeepSeek-V4-Flash）にフォールバックします。この場合、1 回の実行につき 2 件の会話、1 件の会話につき 20 チャンク（均等にサンプリングするため、冒頭のやり取りだけでなく会話全体をカバーします）に制限されます。AI_REVIEW_API_KEY または OPENAI_API_KEY を設定すると、どちらの制限も解除されます。

--redact — LLM に送信する前にシークレット／個人情報／内部ホスト名を除去する（v2.5 以降）

extract、summary、および context --summarize は、会話の抜粋を設定済みの LLM プロバイダーに送信します。「ローカル優先」が適用されるのは ストレージ層 です。.ai-memory/ はプレーンな Markdown であり、アップロードされることはありませんが、抽出リクエスト は必然的に HTTPS で外部へ送信されます。チャット履歴に、誤って貼り付けた API キー、スタックトレース内の内部ホスト名、ログ内の顧客のメールアドレスが含まれている場合、--redact はリクエストがマシンから送信される前にそれらを除去します。

$ ai-memory extract --redact
   ...
Redaction: 5 items scrubbed before LLM (118 chars) — 3 openai-key, 2 email

デフォルトで有効なルール（10 件）：OpenAI／Anthropic／AWS／GitHub／Slack／GCP／Stripe の API キー、RFC5322 のメールアドレス、および *.internal／*.corp／*.local／*.lan／*.intra のホスト名。オプトインのルール（jwt、aws-secret-key）は、長い base64 文字列に対する誤検出率が高いため、デフォルトでは無効です。.ai-memory/.config.json で有効にできます。

{
  "redact": {
    "enabled": true,
    "enableOptional": ["jwt"],
    "rules": [{ "name": "internal-jira", "pattern": "JIRA-[0-9]{4,}" }]
  }
}

CLI の設定は構成ファイルより優先されます。--no-redact は常に無効化し、--redact は常に有効化します。監査記録（ルールごとの検出件数）は、リダクションが有効な場合、人間向けの出力と --json 出力のどちらでも常に記録されます。一致した値がログに記録されることは ありません。それでは目的に反してしまいます。

脅威モデル。 多層防御を目的とするものであり、適切なシークレット管理の代替ではありません。対象外の項目（画像添付、既存メモリの遡及的な除去、構造化された個人情報を含む保管庫の検査）や脅威モデルの境界を含むポリシーの全文は、docs/redaction-policy-2026-04-26.md にあります。

search — 抽出したメモリを検索する

npx ai-memory-cli search "OAuth"                   # keyword search across all memories
npx ai-memory-cli search "payment" --type decision  # filter by type
npx ai-memory-cli search "auth" --author alice      # filter by author
npx ai-memory-cli search "API" --include-resolved   # include resolved memories
npx ai-memory-cli search "config" --json            # JSON output

結果は関連度順（タイトルの一致 > 内容 > コンテキスト）に並び、キーワードが強調表示されます。

recall — git 履歴をたどってメモリの過去を確認する

ほかの「メモリ」ツールはすべて、保存内容を「最新の状態」へと平坦化し、置き換えられた各バージョンは気付かれないまま上書きされます。.ai-memory/ は git リポジトリ内のプレーンな Markdown であるため、すべての事実の完全な系譜はすでにディスク上にあります。recall は、それを第一級のコマンドとして提供します。

npx ai-memory-cli recall "OAuth"                   # show how the OAuth decision evolved
npx ai-memory-cli recall "OAuth" --include-resolved # include superseded / resolved memories
npx ai-memory-cli recall "API" --type decision      # filter by type
npx ai-memory-cli recall "auth" --all-authors       # search across the whole team
npx ai-memory-cli recall "OAuth" --json             # structured output (one entry per memory + its commit list)

出力例：

Recall: "OAuth" — 1 memory, 4 commits of lineage

[+] CURRENT  Use OAuth 2.0 PKCE for SPA  @conor (2026-04-20)
    .ai-memory/conor/decisions/2026-04-20-use-oauth-pkce.md
    History (4 commits):
      a1b2c3d  2026-04-20  conor   ~ Tighten OAuth PKCE: require HTTPS-only token endpoint
      e4f5g6h  2026-04-15  conor   ~ Switch from implicit flow to PKCE
      i7j8k9l  2026-03-20  conor   + Add OAuth library notes
    > git log --follow .ai-memory/conor/decisions/2026-04-20-use-oauth-pkce.md  for full diffs

• git log --follow を使用するため、.ai-memory/ 内の名前変更も透過的に追跡されます。
• 各行には、短縮 SHA、ISO 日付、作成者、ステータスコード（+ 追加、~ 変更、- 削除、R 名前変更）、コミットの説明が表示されます。
• ソフトフォールバック — git リポジトリの外、または .ai-memory/ の最初のコミットより前でも、recall は不足しているものを説明するヒントとともに、一致するメモリを返します。recall が search より劣る状況はありません。
• 新たな実行時依存関係はありません。既存の git に対して node:child_process.execFile のみを使用し、タイムアウトは 10 秒に制限されています。

rules — Cursor Rules、AGENTS.md、および Anthropic Skills として規約をエクスポートする

すべての AI ツールがネイティブに読み込めるエディタールールを生成します。

npx ai-memory-cli rules                            # default: .cursor/rules/ai-memory-conventions.mdc
npx ai-memory-cli rules --target agents-md         # AGENTS.md (Codex / Cursor / Windsurf / Copilot / Amp)
npx ai-memory-cli rules --target skills            # Anthropic Skills (Claude Code) — v2.5+
npx ai-memory-cli rules --target both              # write Cursor Rules + AGENTS.md at default paths
npx ai-memory-cli rules --output my-rules.mdc      # custom output (single-target only)
npx ai-memory-cli rules --all-authors              # include team conventions

--target agents-md は冪等なマージを実行します。変更されるのは ... end --> の間のセクションだけなので、 AGENTS.md に手書きされた内容はバイト単位でそのまま保持されます。新しいメモリがない状態で再実行しても何も変更されず（already-up-to-date）、不完全な編集によるマーカーの不整合は競合として報告され、ファイルは変更されません。

--target skills は Anthropic Skills を .claude/skills/ に書き込みます。長期的に保持されるメモリの種類ごとに、3 つのスキルが生成されます。

スキル	ソース	Claude に指示する内容
.claude/skills/ai-memory-coding-conventions/SKILL.md	convention メモリ	新しいコードの記述、命名、API の設計を行うとき
.claude/skills/ai-memory-decision-log/SKILL.md	decision メモリ（ステータス ≠ resolved）	アーキテクチャの変更を提案するとき、または選択の理由を尋ねられたとき
.claude/skills/ai-memory-system-architecture/SKILL.md	architecture メモリ	コンポーネントをまたぐ機能を実装するとき、または連携の問題をデバッグするとき

スキルは、YAML フロントマターの description がリクエストに一致するかどうかに基づいて、Claude Code によって動的に読み込まれます。常に有効なコンテキストである AGENTS.md とは異なり、スキルの本文は関連する場合にのみコンテキストに追加されます。対象とするスキーマ（2026-04-26 に固定）は docs/skills-schema-snapshot-2026-04-26.md にあります。スキル名の ai-memory- プレフィックスは所有権を示します。.claude/skills/ai-memory-*/ 内のものは実行のたびに完全に再生成され、それ以外のディレクトリ名でユーザーが作成したスキルはそのまま残ります。

これは会話からルールを生成するパイプラインです。チャット履歴から規約を抽出し、すべての AI エディターが読み込めるルールファイルを自動生成します。1 つのチャット履歴を入力として、Cursor Rules、AGENTS.md、Anthropic Skills の 3 つすべてを出力するツールはほかにありません。

resolve — メモリを解決済みにする

決定は覆ることがあります。TODO は完了します。ナレッジベースを最新の状態に保ちましょう。

npx ai-memory-cli resolve "OAuth"                  # mark matching memories as resolved
npx ai-memory-cli resolve "OAuth" --undo           # reactivate resolved memories

解決済みのメモリは、context、summary、search の結果から自動的に除外されます。強制的に含めるには --include-resolved を使用してください。

summary — プロジェクトレベルの概要を生成する

npx ai-memory-cli summary                          # write/update SUMMARY.md
npx ai-memory-cli summary --output MEMORY.md       # custom output path
npx ai-memory-cli summary --focus "payment module"  # focus on a topic
npx ai-memory-cli summary --all-authors             # include all team members
npx ai-memory-cli summary --include-resolved        # include resolved memories

# Scope summary to a single conversation (no LLM cost for the wrong chats)
npx ai-memory-cli summary --list-sources           # list conversations first
npx ai-memory-cli summary --source-id b5677be8     # summarize ONE chat
npx ai-memory-cli summary --convo "payment refactor"

context — 作業継続用のプロンプトを生成する

新しい会話や別のマシンで、作業をシームレスに再開できます。

npx ai-memory-cli context                          # generate context block (instant, no LLM)
npx ai-memory-cli context --copy                   # generate and copy to clipboard
npx ai-memory-cli context --topic "coupon system"  # focus on a specific topic
npx ai-memory-cli context --recent 7               # only last 7 days of memories
npx ai-memory-cli context --output CONTEXT.md      # write to file
npx ai-memory-cli context --summarize              # use LLM for condensed prose summary
npx ai-memory-cli context --all-authors            # include all team members
npx ai-memory-cli context --include-resolved       # include resolved memories

コンテキストを 1 つの会話に絞り込みます。実際には、すべての情報をまとめて出力するのではなく、通常は特定の 1 つのチャットを再開したいからです。

# 1. See which conversations produced memories
npx ai-memory-cli context --list-sources
#  #  Date        Source        ID        Count  Types              Title
#  ------------------------------------------------------------------------------
#   1  2026-04-01  cursor        b5677be8    12  D:4 A:3 C:5        resume tool
#   2  2026-03-28  claude-code   ff12abc3     7  A:4 T:3            ai-lab

# 2. Copy context from ONE conversation (ID prefix, like git short hash)
npx ai-memory-cli context --source-id b5677be8 --copy

# 3. Or match by conversation title — picks the most recent if multiple match
npx ai-memory-cli context --convo "resume tool" --copy
npx ai-memory-cli context --convo "resume" --all-matching --copy   # include every "resume*" chat

link — メモリを、それを実装したコミットにリンクする（v2.6）

npx ai-memory-cli link                             # scan last 30 days of commits
npx ai-memory-cli link --since "7 days ago"        # custom time window
npx ai-memory-cli link --dry-run                   # preview links without writing
npx ai-memory-cli link --clear-auto                # remove all auto-generated links

git ログをスキャンし、重み付きのトークン重複度を使って各（メモリ、コミット）のペアをスコア付けします。メモリのタイトル × 3、種類 × 2、内容 × 1 と、コミットのサブジェクト × 3、変更されたパス × 2、本文 × 1 を比較します。信頼度の高い一致（score ≥ 0.70）は、ダッシュボードに表示できる、不可視の HTML コメントブロックとしてメモリファイルに書き込まれます。デフォルトのしきい値は慎重な設定です。誤った自動リンクは、リンクがないよりも望ましくありません。実際のリポジトリで、まず --dry-run を使って調整してください。

init — 設定を初期化する

npx ai-memory-cli init                             # detect editors, create config
npx ai-memory-cli init --with-mcp                  # also register ai-memory as MCP server
npx ai-memory-cli init --schedule                  # register a daily extract --incremental cron job
npx ai-memory-cli init --unschedule                # remove the scheduled task

--with-mcp を指定すると、ai-memory は .cursor/mcp.json と .windsurf/mcp.json を書き込みまたはマージし、エディターが MCP サーバーを自動的に読み込めるようにします。--schedule を指定すると、OS ネイティブのスケジューラー（macOS では launchd、Linux では crontab、Windows では Task Scheduler）に日次の抽出ジョブが登録されるため、手動で実行しなくてもナレッジベースを最新の状態に保てます。どちらのフラグも冪等で安全です。

export / import — マシン間でメモリーを移行（新機能）

Cursor / Claude Code の会話は各マシンのローカル状態に保存されるため、新しいノート PC では履歴がありません。export と import を使うと、持ち運び可能な JSON バンドルを作成して、問題なく往復できます。移行先でもファイル、会話のグループ化、context --source-id の動作はそのままです。

# On the old machine — export everything (or scope with --source-id / --convo / --type)
npx ai-memory-cli export --output backup.ai-memory.json
npx ai-memory-cli export --source-id b5677be8 --output resume-tool.json  # one chat only
npx ai-memory-cli export --convo "coupon" --output coupons.json          # match by title

# Copy / commit / share the bundle (it's a plain JSON file)

# On the new machine — preview first, then apply
npx ai-memory-cli import backup.ai-memory.json --dry-run
npx ai-memory-cli import backup.ai-memory.json               # default: skip duplicates
npx ai-memory-cli import teammate-bundle.json --author me    # remap teammate's memories
npx ai-memory-cli import stale.json --overwrite              # replace local copies

# Rebuild embeddings so semantic search/MCP work on the imported memories
npx ai-memory-cli reindex

バンドル形式はバージョン管理されており（version: 1）、インポートは冪等です。同じインポートを 2 回実行しても何も起こりません（author + type + date + title で重複を排除します）。

---

MCP サーバー（新機能）

ai-memory はMCP サーバーとして動作し、AI エディター（Cursor、Claude Code）からナレッジベースに直接アクセスできるようになります。手動でコマンドを実行する必要はありません。

セットアップ

Cursor の MCP 設定（.cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "ai-memory": {
      "command": "npx",
      "args": ["ai-memory-cli", "serve"]
    }
  }
}

または、Claude Code の場合（.claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ai-memory": {
      "command": "npx",
      "args": ["ai-memory-cli", "serve"]
    }
  }
}

AI が利用できる機能

MCP の機能	内容
remember ツール	AI が会話中に決定事項／規約／ToDo を保存します（自動でインデックス化）
recall ツール	セマンティック検索とキーワード検索を組み合わせて、関連するメモリーを取得します
search_memories ツール	タイプ／作成者／解決状況による絞り込みに対応した、セマンティック検索対応の総合検索
project-context リソース	会話の開始時にプロジェクトのコンテキストを自動で提供します

設定が完了すると、AI は重要な決定事項を自動で記憶し、今後のセッションで呼び出せるようになります。コマンドを実行する必要はありません。

セマンティック検索

ai-memory は、セマンティック類似度（埋め込みを使用）、キーワードの一致度、時間経過による重みの減衰を組み合わせたハイブリッド検索を使用します。つまり、完全一致のキーワードだけでなく、意味に基づいて検索できます。

# Build search index (uses your existing LLM API for embeddings)
npx ai-memory-cli reindex

# Now search works semantically — "database choice" finds "PostgreSQL decision"
npx ai-memory-cli search "database choice"

MCP の recall ツールと search_memories ツールでは、ハイブリッド検索が自動的に使用されます。埋め込みは .ai-memory/.embeddings.json にローカル保存され、remember ツールの使用時に自動でインデックス化されます。

手動での起動（テスト用）

npx ai-memory-cli serve           # start MCP server
npx ai-memory-cli serve --debug   # with debug logging

---

ウォッチモード（新機能）

会話に変更があったときに、手作業なしでナレッジを自動抽出します。

npx ai-memory-cli watch

ウォッチモードは、検出されたすべてのソースを監視し、新しい会話アクティビティを検出すると自動で抽出を実行します。変更の検出には、ファイルシステムイベント（Cursor / Claude Code の場合）と定期的なポーリング（すべてのソースの場合）を使用します。

ai-memory watch — auto-extract on conversation changes

   Author: conor
   Output: .ai-memory/
   [+] Watching: Cursor
   [+] Watching: Claude Code

Initial scan complete — watching for changes...

10:15:32 [Cursor] "OAuth refactor discussion" (+8 turns) — extracting...
10:15:37 [+] 2 decision, 1 convention

停止するには Ctrl+C を押します。

---

ダッシュボード（新機能）

ローカルの Web UI で、ナレッジベースを閲覧、検索、可視化できます。

npx ai-memory-cli dashboard

http://localhost:3141 を開くと、次の機能を利用できます。

• 概要 — 統計カード、月ごとのタイムラインチャート、作成者の内訳、最近のアクティビティ
• メモリーブラウザー — リアルタイム検索、タイプ／作成者／ステータスによる絞り込み、詳細モーダル
• 会話 — メモリーを生成したチャットウィンドウごとに 1 枚のカードを表示。ワンクリックで context --source-id をコピーでき、「どのチャットでその決定をしたか？」から「新しいセッションでそのチャットを再開する」へ移行できます
• ナレッジグラフ — インタラクティブな D3.js の力学ベースグラフ（ノードはタイプ別に色分けされ、エッジは会話またはキーワードの共通性を示します）
• 品質 — 具体性のヒストグラム、曖昧な内容のリスト、重複／包含された項目のペア（v2.2 アルゴリズムスタックを使用）
• エクスポート — JSON または Obsidian vault（YAML frontmatter 付き）としてダウンロード、またはクリップボードにコピー

npx ai-memory-cli dashboard --port 8080   # custom port

新しいアルゴリズムで既存のメモリーを整理する

以前のバージョンからアップグレードし、蓄積した曖昧なメモリーや重複したメモリーを削除するため、v2.2 の品質アルゴリズムをさかのぼって適用したい場合：

npx ai-memory-cli reindex --dedup --dry-run   # preview what would be deleted
npx ai-memory-cli reindex --dedup             # actually delete + update index

メモリーが 200 件以上ある場合、通常、整理によって曖昧／重複／包含された項目の 20～30% が削除されます。

---

ローカル LLM のサポート（新機能）

クラウド API の代わりに Ollama または LM Studio を使用できます。API キーは不要です。

Ollama

# Install Ollama: https://ollama.ai
ollama pull llama3.2              # download a model
ollama pull nomic-embed-text      # (optional) for semantic search

export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=llama3.2      # extraction model
npx ai-memory-cli extract

LM Studio

# Start LM Studio and load a model
export LM_STUDIO_BASE_URL=http://localhost:1234/v1
export LM_STUDIO_MODEL=your-model-name
npx ai-memory-cli extract

クラウド API キーは、常にローカル LLM より優先されます。OPENAI_API_KEY または AI_REVIEW_API_KEY が設定されている場合は、そちらが使用されます。

変数	説明
OLLAMA_HOST	Ollama サーバーの URL（デフォルト：http://localhost:11434）
OLLAMA_MODEL	抽出に使用するモデル（デフォルト：llama3.2）
OLLAMA_EMBEDDING_MODEL	セマンティック検索に使用するモデル（デフォルト：nomic-embed-text）
LM_STUDIO_BASE_URL	LM Studio サーバーの URL（デフォルト：http://localhost:1234/v1）
LM_STUDIO_MODEL	モデル名

---

対応ソース

ソース	データの場所	ステータス
Cursor	~/.cursor/projects/{name}/agent-transcripts/	安定版
Claude Code	~/.claude/projects/{path}/*.jsonl	安定版
Windsurf	~/AppData/Windsurf/User/workspaceStorage/*/state.vscdb	ベータ版
VS Code Copilot	~/AppData/Code/User/workspaceStorage/*/chatSessions/*.json	ベータ版
Codex CLI	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	ベータ版 — v2.5+

---

一般的なワークフロー

初回の抽出

npx ai-memory-cli list                    # see what conversations are available
npx ai-memory-cli extract                 # extract everything (few minutes on first run)
npx ai-memory-cli rules                   # generate Cursor Rules
git add .ai-memory/ .cursor/rules/
git commit -m "chore: add ai-memory knowledge base"

日常的な使用（差分抽出）

npx ai-memory-cli extract --incremental   # after a productive coding session
npx ai-memory-cli rules                   # refresh Cursor Rules
git add .ai-memory/ && git commit -m "chore: update memories"

新しい会話の開始

npx ai-memory-cli context --copy          # copy context to clipboard
# Paste into new Cursor/Claude Code session

出力は次のようになります。

## Project Context

### Key Decisions (follow without re-discussion)
- **Use OAuth Bridge pattern**: WebView cannot receive redirect directly...

### Conventions (always follow)
- **Never call getServerSideProps in this project**: ...

### Active TODOs
- [ ] Add retry logic to payment webhook handler

特定のナレッジを探す

npx ai-memory-cli search "payment"        # find all payment-related memories
npx ai-memory-cli search "auth" --type decision  # only decisions about auth

---

チームでのワークフロー

複数の人が同じ git リポジトリで ai-memory を使用する場合、各自のメモリはそれぞれのサブディレクトリに自動的に保存されます。

仕組み

作成者の識別情報は自動検出されます（優先順位：--author CLI フラグ > config.author > git config user.name > OS のユーザー名）。手動で設定する必要はありません。

.ai-memory/
├── conor/
│   ├── decisions/
│   │   └── 2026-04-15-oauth-bridge.md
│   └── todos/
│       └── 2026-04-15-add-retry.md
├── alice/
│   ├── decisions/
│   │   └── 2026-04-16-payment-design.md
│   └── architecture/
│       └── 2026-04-16-module-split.md
└── .config.json

使用方法

# Everyone extracts normally — writes to their own directory
npx ai-memory-cli extract --incremental

# Generate your own context (default: only your memories)
npx ai-memory-cli context --copy

# Include the whole team's memories
npx ai-memory-cli summary --all-authors
npx ai-memory-cli context --all-authors --copy

# Override author name
npx ai-memory-cli extract --author "alice"

既存プロジェクトのアップグレード

v1.3 より前に作成されたメモリは、フラットなディレクトリ（.ai-memory/decisions/）に保存されています。アップグレード後は次のようになります。

• 古いファイルは引き続き通常どおり読み込まれます（後方互換性あり）。author は空です
• 新しい抽出結果は .ai-memory/{author}/decisions/ などに保存されます
• 手動での移行は不要です

---

デバイス間のワークフロー

Work machine                                   Home machine
────────────                                   ────────────
Cursor / Claude Code dev work
        -> npx ai-memory-cli extract --incremental
        -> git add .ai-memory/
git commit && git push
                                               git pull
                                               -> npx ai-memory-cli context --topic "today's work"
                                               -> Paste context into new conversation
                                               -> Seamlessly resume

---

設定

ai-memory は設定なしで動作します。カスタマイズするには、npx ai-memory-cli init を実行するか、.ai-memory/.config.json を手動で作成してください。

{
  "sources": {
    "cursor": { "enabled": true, "projectName": "my-project" },
    "claudeCode": { "enabled": true },
    "windsurf": { "enabled": true },
    "copilot": { "enabled": true }
  },
  "extract": {
    "types": ["decision", "architecture", "convention", "todo", "issue"],
    "ignoreConversations": [],    // conversation UUIDs to skip
    "minConversationLength": 5   // skip very short conversations
  },
  "output": {
    "dir": ".ai-memory",
    "summaryFile": "SUMMARY.md",
    "language": "zh"             // "zh" or "en" — output language for summaries
  },
  "model": "",                   // leave empty for auto-selection
  "author": ""                   // leave empty to auto-detect from git config user.name
}

環境変数

変数	説明
AI_REVIEW_API_KEY	API キー（優先して使用。ai-review-pipeline と共有）
OPENAI_API_KEY	OpenAI API キー
OPENAI_BASE_URL	カスタム OpenAI 互換 API のベース URL
OPENAI_MODEL	OpenAI 用のモデル上書き設定
ANTHROPIC_API_KEY	Anthropic API キー（互換プロキシが必要）
ANTHROPIC_BASE_URL	Anthropic プロキシのベース URL
AI_REVIEW_BASE_URL	カスタム API のベース URL
AI_REVIEW_MODEL	使用するモデル（デフォルト：gpt-4o-mini）
OLLAMA_HOST	Ollama サーバーの URL（デフォルト：http://localhost:11434）
OLLAMA_MODEL	抽出に使用する Ollama モデル
OLLAMA_EMBEDDING_MODEL	セマンティック検索の埋め込みに使用する Ollama モデル
LM_STUDIO_BASE_URL	LM Studio API の URL
LM_STUDIO_MODEL	LM Studio のモデル名

---

出力構成

各メモリは個別のファイルで、作成者と種類ごとに整理されます。

.ai-memory/
├── SUMMARY.md                              # Project summary (from `summary` command)
├── conor/                                  # Per-author subdirectory
│   ├── decisions/
│   │   ├── 2026-04-12-oauth-bridge-pattern.md
│   │   └── 2026-04-13-async-job-queue-design.md
│   ├── architecture/
│   │   └── 2026-04-10-payment-module-design.md
│   ├── conventions/
│   │   └── 2026-04-08-coding-conventions.md
│   ├── todos/
│   │   └── 2026-04-12-add-retry-logic.md
│   └── issues/
│       └── 2026-04-11-sqlite-locking-fix.md
├── .index/                                 # Extraction index (auto-managed)
├── .config.json                            # Configuration (commit this)
└── .state.json                             # Extraction state (add to .gitignore)

.ai-memory/.state.json を .gitignore に追加してください。このファイルには処理済みの会話が記録され、マシン固有の情報が含まれます。

---

CI との統合

# .github/workflows/memory.yml
- name: Extract AI memories
  run: npx ai-memory-cli extract --incremental --json
  env:
    AI_REVIEW_API_KEY: ${{ secrets.AI_REVIEW_API_KEY }}

---

要件

• Node.js >= 18
• 利用開始に API キーは不要です — キーが設定されていない場合は、無料の組み込みモデル（SiliconFlow 経由の DeepSeek-V4-Flash）が自動的に使用されます。1 回の実行につき、会話は 2 件までに制限されます。
• 抽出を無制限に行うには、任意の OpenAI 互換プロバイダーの AI_REVIEW_API_KEY（または OPENAI_API_KEY）を設定するか、ローカル LLM（Ollama / LM Studio）を使用してください。

ヒント： Node.js 22+ では、Cursor/Windsurf のデータベースを読み込むことで、より詳細な会話タイトルを取得できます。Node 18-20 では、タイトルは最初のメッセージから抽出されます（こちらも問題なく動作します）。

コミュニティ

• Linux DO ディスカッション — 中国語の開発者コミュニティのスレッド

ライセンス

MIT — Conor Liu