Cursor-Cortex: AIアシスタントのための構造化メモリ

Cursor、Claude Code、およびMCP互換のAIアシスタントで動作します。

AIアシスタントのメモリ喪失とコンテキスト混乱を解決します。 Cursor-Cortexは、あなたのAIに、ソフトウェア開発を実際に支援するために必要な構造化された思考と長期メモリを提供します。

🧠 AIアシスタントの問題点

LLMベースのAIアシスタントは、コード生成や概念の説明には優れていますが、以下の点に課題があります：

• ❌ メモリ喪失: 「昨日は何をやっていたっけ？」

• ❌ コンテキストスイッチング: 「待って、このプロジェクトは何についてのものだっけ？」

• ❌ エージェントの失敗: 迷子になる、幻覚を起こす、目標を見失う

• ❌ 構造の欠如: 体系的な思考なしにアイデアを行き来する

• ❌ 知識のギャップ: 企業固有またはプロジェクト固有の洞察にアクセスできない

結果: 問題を実際に解決するよりも、コンテキストの説明に多くの時間を費やしてしまいます。

Related MCP server: BuildAutomata Memory MCP Server

🎯 Cursor-Cortexのソリューション

Cursor-Cortexは、あなたのAIに構造化された外部メモリを提供します：

📋 コンテキストファイル → 「このプロジェクトは何についてのもの？」

あなたのAIは、プロジェクトの目標、アーキテクチャ上の決定、現在の焦点を常に把握しています。

📝 ブランチノート → 「これまで何に取り組んできた？」

継続的な開発ログにより、あなたのAIは中断したところから正確に再開できます。

🧠 暗黙知 → 「この種の問題はどう解決する？」

LLMが知らない、企業固有のソリューション、パターン、苦労して得た洞察。

✅ チェックリスト → 「私たちの体系的なアプローチは？」

AI（とあなた）を整理整頓し、徹底させる構造化思考フレームワーク。

💡 導入前と導入後

❌ Cursor-Cortexなし：

You: "Help me continue the authentication work"
AI: "I need more context. What authentication system? What issues were you facing?"
You: "Ugh, let me explain everything again..."

✅ Cursor-Cortexあり：

You: "Help me continue the authentication work"  
AI: *reads context + branch notes + knowledge base*
"I see you're implementing JWT refresh tokens and hit CORS issues yesterday. 
Based on our company knowledge doc about API security, let's check the middleware..."

🚀 中核となる利点

あなたのAIを、賢いインターンから経験豊富なチームメイトに変えます。 すべてを記憶し、構造化された思考に従い、組織の知識にアクセスできます。

⚡ 完全セットアップガイド

1. 依存関係のインストール

npm install --legacy-peer-deps

注記: TensorFlow.jsのv3.xとv4.xバージョン間のピア依存関係の競合のため、--legacy-peer-depsフラグが必要です。

2. フルパスを取得

pwd
# Copy the output - you'll need it for configuration

3. ベクトル検索のセットアップ（オプション）

AIを活用したセマンティック検索機能の場合：

システム要件：

• Node.js 18以上

• ベクトルモデル用に2GBのRAM

• 500MBのディスク容量

セットアップ手順：

# Step 1: Generate embeddings for all knowledge files
node generate-all-embeddings-cpu.js

# This creates vector embeddings for:
# - All tacit knowledge documents
# - All branch notes
# - All context files
# Duration varies by document count and system specs

# Step 2 (Optional): Force regenerate if content changes
node generate-all-embeddings-cpu.js --force

# Step 3 (Optional): View progress during generation
node generate-all-embeddings-cpu.js --verbose

これが重要な理由：

• 埋め込みがない場合、セマンティック検索はテキスト検索にフォールバックします

• 事前計算された埋め込みにより、検索が100倍高速になります

• 一度生成すれば、すべてのセマンティッククエリに使用できます

• 埋め込みは~/.cursor-cortex/embeddings/に保存されます

4. Cursor MCPの設定

~/.cursor/mcp.jsonを作成または編集します：

"cursor-cortex": {
      "command": "node",
      "args": ["/YOUR/FULL/PATH/TO/cursor-cortex/index.js"],
      "tools": [
        "update_branch_note", 
        "add_commit_separator",
        "read_branch_notes",
        "update_context_file", 
        "read_project_context",
        "read_branch_context", 
        "list_context_files", 
        "generate_commit_message", 
        "generate_jira_comment", 
        "create_tacit_knowledge",
        "read_tacit_knowledge", 
        "search_branch_notes",
        "generate_embeddings",
        "create_completion_checklist",
        "read_checklist",
        "update_checklist",
        "sign_off_checklist",
        "archive_branch_note",
        "clear_branch_note",
        "list_all_branch_notes",
        "enhanced_branch_survey",
        "comprehensive_knowledge_search",
        "construct_project_narrative",
        "timeline_reconstruction",
        "context_sync_guidance",
        "analyze_documentation_gaps",
        "migrate_context_files",
        "request_critical_thinking_space",
        "check_critical_thinking_status",
        "request_thinking_guidance",
        "add_perspective",
        "request_synthesis_space",
        "request_synthesis_step_guidance",
        "complete_synthesis_step",
        "generate_context_zip",
        "unpack_context"
      ],
      "stdio": true,
      "env": {
        "DEBUG": "true"
      }
    },

/YOUR/FULL/PATH/TO/cursor-cortex/を手順2の出力に置き換えます

注: この設定はCursor-Cortex v1.2.0以降用です。古いバージョンを使用している場合、一部のツールが利用できない可能性があります。package.jsonのバージョンを確認し、アップデートを検討してください。

5. Cursorを再起動

Cursorを完全に閉じて再度開きます。

Claude Codeのインストール

プロジェクトルート（またはグローバルに~/.claude/settings.json）に.claude/settings.jsonを作成または編集します：

{
  "mcpServers": {
    "cursor-cortex": {
      "command": "node",
      "args": ["/YOUR/FULL/PATH/TO/cursor-cortex/index.js"]
    }
  }
}

/YOUR/FULL/PATH/TO/cursor-cortex/を手順2の出力に置き換えて、Claude Codeを再起動します。

6. MCPサーバーを有効化

1. Cursor設定に移動します（Cmd/Ctrl + ,）

2. Features → Model Context Protocolに移動します

3. cursor-cortexを見つけてONに切り替えます

4. Storage directory created at /Users/yourname/.cursor-cortexという表示が確認できます

7. テスト

Cursorの任意のチャットで、次を試します：

"Update my branch notes: Testing Cursor-Cortex setup"

動作すれば、Successfully updated branch note with: "Testing Cursor-Cortex setup"という表示が確認できます

8. ナレッジエクスプローラー（ビジュアルグラフ）

すべてのセットアップが完了したら、ナレッジベースをインタラクティブなネットワークグラフとして探索できます：

npm run explorer

次に、ブラウザで**http://localhost:4000**を開きます。

機能：

• 3層ビジュアライゼーション: プロジェクト、ブランチノート、暗黙知が相互接続されたノードとして表示されます

• 類似性に基づくレイアウト: 埋め込みコサイン類似度を使用して、意味的に類似したプロジェクトがクラスタリングされます

• ニューラルパルスアニメーション: 信号が知識ネットワークをリアルタイムで伝播する様子を確認できます

• アクティビティベースの色: 明るいノード = 最近更新されたプロジェクト

• クリックして探索: 任意のノードをクリックして、詳細、類似プロジェクト、タグを表示します

• 深さの切り替え: コンパクト（プロジェクトのみ）、ブランチ、フルビューを切り替えます

🔧 トラブルシューティング

一般的な問題：

❌ 「Tool not found」エラー

• 設定後にCursorを完全に再起動します

• MCPサーバーが設定で有効になっていることを確認します

• mcp.jsonのファイルパスが正しいことを確認します（タイプミスがないか）

❌ MCP設定が機能しない

• jsonlint.comでJSON構文を検証します

• カンマと引用符が正しいことを確認します

• mcp.jsonのファイル権限を確認します

❌ ベクトル検索が機能しない

• npm installを実行してTensorFlow.jsがインストールされていることを確認します

• システムに2GB以上のRAMがあることを確認します

• ベクトル検索が失敗する場合は、テキスト検索モードを試します

ヘルプが必要ですか？ エラーメッセージを添えて問題を作成してください。迅速なサポートを提供します。

9. 使用を開始

• 「未コミットの作業を表示」 - 取り組んできた内容を確認します

• 「コミットメッセージを生成」 - ノートからコミットを作成します

• 「暗黙知ドキュメントを作成」 - 後で使用するための解決策を保存します

📖 基本的な使い方

思考を記録する

コードを書くときに、AIアシスタントに伝えます：

"Update branch notes: Fixed the login validation bug by adding proper error handling 
for expired tokens. Had to modify the JWT middleware."

方向性を維持

作業に戻るとき：

"Show me my uncommitted work"

スマートコミット

コミットする準備ができたら：

"Generate a commit message"

AIがすべてのノートを読み取り、「Fix JWT token validation and error handling」を作成します

🏗️ プロジェクト構造

Cursor-Cortexは、あなたの知識を次のように整理します：

• 📝 ブランチノート: 現在取り組んでいる内容

• 📋 コンテキストファイル: プロジェクトのドキュメントと決定事項

• 🧠 ナレッジベース: 将来の参照用の解決策と洞察

• ✅ チェックリスト: プロジェクトの完了状況を追跡

すべて~/.cursor-cortex/に保存され、AIからアクセスできます。

🎓 パワーユーザー機能

基本に慣れたら、これらの高度な機能を探索してください：

クロスプロジェクト知識検索

"Search all my projects for JWT authentication solutions"

自動コミット追跡

node setup-hooks.js  # Auto-separates pre/post commit work

プロジェクトチェックリスト

要件、テスト、承認を追跡します：

"Create a completion checklist for the user auth feature"

チーム知識共有

再利用可能なソリューションドキュメントを作成します：

"Create tacit knowledge document about our JWT implementation approach"

知識考古学とプロジェクトインテリジェンス

プロジェクト知識を分析して統合します：

"Survey all my branch documentation and show completeness scores"
"Construct a project narrative for the user authentication system"
"Show me a timeline of all development across projects"
"Analyze this folder structure for documentation gaps"

🛠️ 利用可能なすべてのツール

• update_branch_note - 開発ログにエントリを追加します

• read_branch_notes - デフォルトはファイル全体（COMMITセパレータを含む）です。mode=uncommittedまたはuncommittedOnly=trueで最後のコミット以降の作業を表示します。オプションでbeforeDate、afterDate、またはcommitHashでフィルタリングできます

• add_commit_separator - コミット境界をマークします（gitフックで自動）

• generate_commit_message - AIがノートからコミットを作成します

• update_context_file - プロジェクトの目標と決定事項をドキュメント化します

• read_project_context - ブランチに依存しないプロジェクトコンテキストのみを読み取ります

• read_branch_context - ブランチ固有のコンテキストのみを読み取ります

• list_context_files - クロスプロジェクト警告付きで、すべてのプロジェクトドキュメントを閲覧します

• create_tacit_knowledge - 将来の参照用に解決策をドキュメント化します

• read_tacit_knowledge - タグとコンテンツ検索で、すべてのプロジェクトの知識を検索します

• search_branch_notes - セマンティック検索で、プロジェクト間のブランチノートを検索します

• generate_embeddings - セマンティック検索用のベクトル埋め込みを生成または再生成します

• comprehensive_knowledge_search - すべてのCursor-Cortex知識を横断するグローバルなセマンティック検索

• create_completion_checklist - 要件と成果物を追跡します

• read_checklist - 進捗状況を表示します

• update_checklist - 項目を完了としてマークします（手動または自動検出）

• sign_off_checklist - 署名付きの正式な承認

• archive_branch_note - 完了した作業をアーカイブします

• clear_branch_note - ブランチドキュメントをリセットします

• migrate_context_files - 既存のコンテキストファイルをSmart Hybrid Context Systemに移行します

• list_all_branch_notes - 優先順位付けされた順序で、すべてのプロジェクトのすべてのブランチノートを表示します

• enhanced_branch_survey - 完全性スコアリングと関係マッピングによるドキュメントの包括的な分析

• construct_project_narrative - 散在する技術的詳細を一貫した本番ストーリーに織り込みます

• timeline_reconstruction - ブランチノートとコミットセパレータから時系列データを抽出します

• context_sync_guidance - タイムラインデータに基づいて、プロジェクトコンテキストを同期するためのコンテキストガイダンスを取得します

• analyze_documentation_gaps - フォルダ構造を分析してドキュメントのニーズを特定し、チェックリストを自動作成します

• request_critical_thinking_space - シックスシンキングハットの方法論を使用して体系的な分析ワークスペースを作成します

• check_critical_thinking_status - 批判的思考分析の完了ステータスを確認します

• request_thinking_guidance - 特定のシックスシンキングハットの視点に関するガイダンスを取得します

• add_perspective - 批判的思考ワークスペースに特定の視点分析を追加します

• request_synthesis_space - 統合のために視点をシンセシスワークスペースにロードします

• request_synthesis_step_guidance - シンセシスステップの詳細なガイダンスを取得します

• complete_synthesis_step - 特定のシンセシスステップを完了し、プロセスを更新します

• generate_context_zip - ユーザー/環境間で共有するための知識をポータブルなZIPアーカイブにパッケージ化します

• unpack_context - 安全な競合解決で共有コンテキストパッケージをインポートします

🎛️ 高度な設定

Git統合

自動コミットセパレータには、MCPサーバーが実行されている必要があります：

node setup-hooks.js  # Install git hooks

CLIインターフェース

AIなしで直接アクセス：

node cursor-cortex-cli.js  # Interactive menu

🤝 貢献

バグを見つけた、またはアイデアがありますか？ 問題を開くか、プルリクエストを送信してください。貢献を歓迎します！

著者: Manuel Flores-Ramirez

📄 ライセンス

このプロジェクトは、Parachute Public License (PPL) v1.0の下でライセンスされています。

PPLは、政府、軍、監視、その他の有害なエンティティによる使用に対する制限を含む倫理的なライセンスです。詳細と根拠については、parachute.pubを参照してください。

© 2025 Manuel Flores-Ramirez.