memory-journal-mcp

Memory Journal MCP Server

📚 ドキュメント全文（Wiki） • 変更履歴 • セキュリティ • リリース記事

🎯 AI コンテキスト＋プロジェクトインテリジェンス： 永続的なプロジェクトメモリと自動セッション引き継ぎによって、分断された AI セッションをつなぎます。GitHub ワークフローとの完全な統合も備えています。

🚀 クイックデプロイ：

• npm パッケージ - npm install -g memory-journal-mcp
• Docker Hub - セマンティック検索を完全に備えた Alpine ベース

🧠 AI の記憶喪失に悩まされるのはもう終わり

AI の支援を受けて大規模なプロジェクトを管理する際、次のような重大な課題に直面します。

• スレッドの記憶喪失 - AI との会話を新しく始めるたびに、それまでの作業を把握していない状態から始まります。
• コンテキストの喪失 - 判断、実装、学びが、分断されたスレッドのあちこちに散らばります。
• 作業の繰り返し - AI が、すでに試した解決策や採用しなかった解決策を提案します。
• コンテキストの過負荷 - 新しい会話を始めるたびに、プロジェクトの履歴を手作業でコピーする必要があります。

Memory Journal はプロジェクトの長期記憶として機能し、分断された AI セッションの隔たりを埋めます。

真のコンテキスト認識型開発を体験しましょう：

• 「先月、このサービスで Postgres ではなく SQLite を選んだ理由は何でしたか？」（セマンティック検索）
• 「カンバンボードで最優先のチケットに /issue-triage ワークフローを実行して。」（GitHub 操作）
• 「最近、認証モジュールを変更したのは誰ですか？ チームのコラボレーション密度はどのくらいですか？」（チーム分析）
• 「このデータベースエラーで行き詰まっています。@sarah に向けて「blocker」フラグを立て、次のセッションで彼女のエージェントに表示されるようにして。」（Hush Protocol）
• 「イシュー #42 をクローズして、パーサーのバグに対するアーキテクチャ上の修正を説明する記録を残して。」（コンテキストのライフサイクル）
• 「直近10件のアーキテクチャ上の決定がどのように関連しているかを示すグラフを描いて。」（ナレッジグラフ）

例とプロンプトの全文を見る →

🎯 選ばれる理由

73 MCP ツール · 19 ワークフロープロンプト · 46 リソース · 10 ツールグループ · コードモード · GitHub Commander（イシュートリアージ、PR レビュー、マイルストーンスプリント、セキュリティ／品質／パフォーマンス監査） · GitHub 統合（イシュー、PR、Actions、カンバン、マイルストーン、インサイト） · チームコラボレーション（共有 DB、ベクトル検索、プロジェクト横断インサイト、Hush Protocol フラグ）

flowchart TB
    subgraph Session["🤖 AI Session Start"]
        Briefing["📋 Read Briefing<br/>(memory://briefing)"]
    end

    subgraph Core["📝 Journal Operations"]
        Create["Create Entry"]
        Retrieve["Retrieve & Search"]
        Link["Link Entries"]
    end

    subgraph Search["🔍 Hybrid Search"]
        FTS["Keyword (FTS5)"]
        Semantic["Semantic (Vector)"]
        DateRange["Date Range"]
        RRF["Reciprocal Rank Fusion"]
    end

    subgraph GitHub["🐙 GitHub Integration"]
        Issues["Issues & Milestones"]
        PRs["Pull Requests"]
        Actions["GitHub Actions"]
        Kanban["Kanban Boards"]
        Insights["Repository Insights"]
    end

    subgraph Outputs["📊 Outputs"]
        Reports["Standups & Retrospectives"]
        Graphs["Knowledge Graphs"]
        Timeline["Project Timelines"]
    end

    Session --> Core
    Core --> Search
    Core <--> GitHub
    Search --> Outputs
    GitHub --> Outputs

推奨ルール（AGENTS.md、GEMINI.md、システムプロンプトなどに追加してください）

ツールのフィルタリング

重要

すべてのショートカットとツールグループには、トークン効率のよい操作のため、デフォルトで Code Mode（mj_execute_code）が含まれています。除外するには、フィルターに -codemode を追加してください：--tool-filter starter,-codemode

MEMORY_JOURNAL_MCP_TOOL_FILTER（または CLI：--tool-filter）を使って、公開するツールを制御できます。

フィルターの構文： shortcut、group、tool_name（ホワイトリストモード） · -group（グループを無効化） · -tool（ツールを無効化） · +tool（グループを無効化した後に再度有効化）

カスタム選択： 個別のツール名を列挙して、独自のホワイトリストを作成できます：--tool-filter "create_entry,search_entries,semantic_search"

グループ： core、search、analytics、relationships、io、admin、github、backup、team、codemode

ツールのフィルタリングに関する完全ガイド →

📋 コア機能

🛠️ 73 個の MCP ツール（10 グループ）

ツールの完全なリファレンス →

🎯 19 個のワークフロープロンプト

• find-related - セマンティック類似性を使って関連するエントリーを見つけます
• prepare-standup - 毎日のスタンドアップ用サマリー
• prepare-retro - スプリントの振り返り
• weekly-digest - 日ごとの週次サマリー
• analyze-period - インサイトを含む期間の詳細分析
• goal-tracker - マイルストーンと達成状況の追跡
• get-context-bundle - Git／GitHub／カンバンを含むプロジェクトコンテキスト
• get-recent-entries - 直近のエントリーを整形して表示
• project-status-summary - GitHub Project のステータスレポート
• pr-summary - プルリクエストのジャーナル活動サマリー
• code-review-prep - PR レビューの包括的な準備
• pr-retrospective - 完了した PR の分析と得られた知見
• actions-failure-digest - CI/CD の失敗分析
• project-milestone-tracker - マイルストーンの進捗状況の追跡
• confirm-briefing - セッションコンテキストをユーザーに確認
• session-summary - 成果、保留項目、次回セッションのコンテキストを含むセッションサマリーのエントリーを作成
• team-session-summary - チームデータベース内に安全に分離された、チームセッションの振り返りサマリーエントリーを作成
• adversarial-plan-review - 構造化された評価項目、採点基準、過去の計画コンテキストを用いた複数パスの敵対的計画レビュー
• flag-dashboard - 優先度の評価と解決に向けたガイダンスを用いて、対応中のフラグをトリアージ

プロンプトガイドの完全版 →

📡 46 個のリソース（29 個の静的リソース＋17 個のテンプレート）

29 個の静的リソース（リソース一覧に表示されます）：

• memory://briefing - セッションの初期化：AI エージェント向けの簡潔なコンテキスト（約 350 トークン）。サーバーのバージョン、提供機能（ツール／リソース／プロンプト）、テストの健全性、未リリースの変更、分析情報、localTime、および任意の activeFlags を含みます
• memory://instructions - 動作ガイダンス：AI エージェント向けのサーバー指示全文
• memory://recent - 直近 10 件のエントリ
• memory://significant - 重要なマイルストーンと画期的な成果
• memory://graph/recent - 最近の関係性を示すライブ Mermaid 図
• memory://health - サーバーの健全性と診断情報
• memory://graph/actions - CI/CD のナラティブグラフ
• memory://actions/recent - 最近のワークフロー実行
• memory://tags - 使用回数を含むすべてのタグ
• memory://statistics - ジャーナルの統計情報
• memory://rules - エージェントが認識するためのユーザールールファイルの内容
• memory://workflows - 利用可能なエージェントのワークフロー概要
• memory://skills - エージェントのスキルインデックス（名前、パス、抜粋）
• memory://github/status - GitHub リポジトリのステータス概要
• memory://github/insights - リポジトリのスター数、フォーク数、過去 14 日間のトラフィック概要
• memory://github/milestones - 完了率付きのオープンなマイルストーン
• memory://team/recent - 作成者情報付きの最近のチームエントリ
• memory://team/statistics - チームエントリの件数、種類、作成者別の内訳
• memory://help - 説明とツール数を含むツールグループのインデックス
• memory://metrics/summary - サーバー起動後のツール呼び出しメトリクスの集計（呼び出し、エラー、トークンの推定値、所要時間）— 優先度：高
• memory://metrics/tokens - 出力トークンコスト順のツール別トークン使用量の内訳 — 優先度：中
• memory://metrics/system - プロセスレベルのメトリクス：メモリ（MB）、稼働時間（s）、Node.js のバージョン、プラットフォーム — 優先度：中
• memory://metrics/users - ユーザー別の呼び出し回数（OAuth ユーザー識別子が存在する場合に設定）— 優先度：低
• memory://audit - JSONL 運用テレメトリログから取得した、直近 50 件の書き込み／管理ツール呼び出しエントリ（AUDIT_LOG_PATH が必要）
• memory://flags - アクティブ（未解決）のチームフラグのダッシュボード（TEAM_DB_PATH が必要）
• memory://flags/vocabulary - 設定済みのフラグ用語
• memory://flags/history - 解決の詳細と平均解決時間を含む、最近解決されたフラグ（過去 7 日間）

17 個のテンプレートリソース（基本テンプレート 9 個＋動的な {repo} バリアント 8 個）：

• memory://projects/{number}/timeline - プロジェクトのアクティビティタイムライン
• memory://issues/{issue_number}/entries - イシューに関連付けられたエントリ
• memory://prs/{pr_number}/entries - PR に関連付けられたエントリ
• memory://prs/{pr_number}/timeline - PR とジャーナルを統合したタイムライン
• memory://kanban/{project_number} - GitHub Project のカンバンボード
• memory://kanban/{project_number}/diagram - カンバンの Mermaid ビジュアライゼーション
• memory://milestones/{number} - 完了状況の進捗を含むマイルストーンの詳細
• memory://help/{group} - パラメーターと注釈を含むグループ別のツールリファレンス
• memory://briefing/{repo} - 特定のリポジトリを対象としたコンテキスト

注：memory://github/status、memory://github/insights、memory://github/milestones、および memory://milestones/{number} リソースでは、リポジトリをまたいだ対象指定に、任意の /{repo} パスサフィックスも使用できます。

⚡ コードモード：最大限の効率（トークンを90％節約）

コードモード（mj_execute_code）は、トークン使用量を最大90％大幅に削減する画期的なアプローチで、すべてのプリセットでデフォルトで有効になっています。逐次的なツール呼び出しに数千トークンを費やす代わりに、AI エージェントはサンドボックス内で一度実行するだけで、より速く推論できます。

コードは、安全なマルチテナントプロセス分離環境として設計された worker_threads サンドボックスで実行されます。すべての mj.* API 呼び出しはサンドボックス内でジャーナルに対して実行され、以下の機能を提供します。

• V8 コード生成の制限 — V8 エンジンレベルで codeGeneration: { strings: false, wasm: false } によって、文字列からの eval() と Function() の構築を無効化
• プロトタイプの凍結 — 動的なコンストラクターチェーンを介したサンドボックスからの脱出を防ぐため、vm コンテキスト内ですべての組み込みプロトタイプ（Object、Function、Array、Error など）を凍結
• 静的コード検証 — require()、process、eval()、Reflect.*、Symbol.*、new Proxy()、ファイルシステムおよびネットワークへのアクセスをブロックする18個の正規表現ルール
• Proxy コンストラクターの無効化 — サンドボックス内で Proxy: undefined とすることで、メタオブジェクトプロトコルの悪用を防止
• RPC 許可リスト — ホスト側の検証により、ワーカーが許可されていない API メソッドを呼び出すことを防止
• レート制限 — クライアントごとに1分あたり60回まで実行可能
• 厳格なタイムアウト — 設定可能な実行時間の上限（デフォルトは30秒）
• 送信境界の適用 — サイズの大きすぎるペイロードによる OOM を防ぐため、結果のシリアライズに上限を設定
• API への完全なアクセス — mj.* を介して10個すべてのツールグループを利用可能（例：mj.core.createEntry()、mj.search.searchEntries()、mj.github.getGithubIssues()、mj.team.passTeamFlag()）
• 厳格な読み取り専用契約 — --tool-filter readonly のもとで変更メソッドを呼び出すと、実行を防ぐためにサンドボックスが安全に停止し、未加工の MCP プロトコル例外ではなく、構造化された { success: false, error: "..." } レスポンスをエージェントに返します。

⚡ コードモードのみ（トークンを最大限に節約）

コードモードのみを有効にして実行します。mj.* API を通じて69個のツールに相当する機能へアクセスできる、単一のツールです。

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "args": ["--tool-filter", "codemode"]
    }
  }
}

これにより、mj_execute_code のみが公開されます。エージェントは型付きの mj.* SDK を使って JavaScript を記述し、10個すべてのツールグループにまたがる操作を組み合わせて、必要なデータだけを1回の実行で返します。これは、Cloudflare が API 全体向けに先駆けて採用したコードモードパターンを踏襲したもので、機能の数にかかわらずトークンコストが一定です。

コードモードを無効にする

個別にツールを呼び出す場合は、codemode を除外します。

{
  "args": ["--tool-filter", "starter,-codemode"]
}

🤫 Hush Protocol：非同期チームコラボレーション

Hush Protocol は、ノイズの多い Slack／Teams メッセージを、構造化された機械処理可能なフラグに置き換えることで、AI を活用したワークフローにおけるチームコラボレーションを再構想します。

作業を妨げる問題が発生したとき、レビューが必要なとき、またはマイルストーンを共有したいとき、AI エージェントは共有チームデータベースにフラグを立てることができます。

• 対応につながる可視性：有効なフラグは、すべてのチームメンバー向けの memory://briefing ペイロードの最上部に自動的に表示されます。別の開発者のエージェントがセッションを開始すると、あなたの作業を妨げる問題をすぐに確認し、自律的に解決を支援できます。
• 構造化された種類：特定の種類のフラグ（blocker、needs_review、help_requested、fyi）を立てられます。--flag-vocabulary 設定を使って、チームの用語をカスタマイズできます。
• 検索可能な履歴：チャットメッセージのようにどこかへ消えてしまうことはなく、Hush フラグは永続的で検索可能な AI ジャーナルエントリーです。エージェントは過去の needs_review フラグを検索し、アーキテクチャ上の障害がどのように克服されたかを把握できます。
• スタンドアップとレトロスペクティブのシグナルを統合：有効なフラグは、prepare-standup プロンプトと prepare-retro プロンプトにコンテキストシグナルとして自動的に表示されるため、毎日のスタンドアップやスプリントレトロスペクティブで、未解決の問題を常に確認できます。
• ライフサイクル全体の管理：team_list_flags を使って、ステータス、種類、担当者でフラグを一覧表示および絞り込めます。team_update_flag を使ってメタデータを更新（重大度の引き上げ、担当者の変更、リンクの追加）したり、解決済みのフラグを再オープンしたりできます。team_get_flag_analytics を使って、解決速度、ユーザーごとの作業負荷、傾向を追跡できます。

ダッシュボードと運用：アクティブなダッシュボードには memory://flags を、最近解決されたフラグには memory://flags/history を参照してください。重大度別のグループ化と古さの検出を含む、ガイド付きトリアージには /flag-dashboard プロンプトを使用してください。また、Code Mode でプログラムからフラグを管理するには、mj.team.passTeamFlag()／mj.team.resolveTeamFlag()／mj.team.teamListFlags()／mj.team.teamUpdateFlag()／mj.team.teamGetFlagAnalytics() を使用してください。

Hush Protocol の完全ガイドと Mermaid シーケンス図 →

🚀 クイックスタート

オプション 1：npm（推奨）

npm install -g memory-journal-mcp

オプション 2：ソースから

git clone https://github.com/neverinfamous/memory-journal-mcp.git
cd memory-journal-mcp
npm install
npm run build

MCP 設定に追加

~/.cursor/mcp.json、Claude Desktop の設定、または同等の設定ファイルに追加してください。

基本設定

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "PROJECT_REGISTRY": "{\"my-repo\":{\"path\":\"/path/to/your/git/repo\",\"project_number\":1}}",
        "ALLOWED_IO_ROOTS": "/path/to/your/git/repo"
      }
    }
  }
}

高度な設定（推奨）

マルチプロジェクトルーティング、チームコラボレーション、Copilot の認識、コンテキストインジェクションなど、サーバーの機能を最大限に活用する設定です。

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "DB_PATH": "/path/to/your/memory_journal.db",
        "TEAM_DB_PATH": "/path/to/shared/team.db",
        "GITHUB_TOKEN": "ghp_your_token_here",
        "PROJECT_REGISTRY": "{\"my-repo\":{\"path\":\"/path/to/repo\",\"project_number\":1},\"other-repo\":{\"path\":\"/path/to/other\",\"project_number\":5}}",
        "ALLOWED_IO_ROOTS": "/path/to/repo,/path/to/other,/path/to/your/skills",
        "AUTO_REBUILD_INDEX": "true",
        "MEMORY_JOURNAL_MCP_TOOL_FILTER": "codemode",
        "CODEMODE_INTERNAL_FULL_ACCESS": "true",
        "BRIEFING_ENTRY_COUNT": "3",
        "BRIEFING_SUMMARY_COUNT": "1",
        "BRIEFING_INCLUDE_TEAM": "true",
        "BRIEFING_ISSUE_COUNT": "3",
        "BRIEFING_PR_COUNT": "3",
        "BRIEFING_PR_STATUS": "true",
        "BRIEFING_WORKFLOW_COUNT": "3",
        "BRIEFING_WORKFLOW_STATUS": "true",
        "BRIEFING_COPILOT_REVIEWS": "true",
        "RULES_FILE_PATH": "/path/to/your/RULES.md",
        "SKILLS_DIR_PATH": "/path/to/your/skills",
        "MEMORY_JOURNAL_WORKFLOW_SUMMARY": "/deploy: prod deployment | /audit: security scan",
        "AUDIT_LOG_PATH": "/path/to/your/mcp-audit.jsonl",
        "TEAM_AUTHOR": "your_username"
      }
    }
  }
}

💡 ヒント： コンテキストウィンドウを最適化しましょう！ジャーナルエントリー（BRIEFING_ENTRY_COUNT）には、頻繁に行われる細かなアクション（バグ修正、実装手順など）が記録されます。セッションサマリー（BRIEFING_SUMMARY_COUNT）には、異なる AI セッション間で戦略的なコンテキストを継続的に引き継ぐための、概要レベルのレトロスペクティブが表示されます。両方を適切に使い分けて、エージェントへのブリーフィングを的確に保ちましょう！

📋 セッションブリーフィングのカスタマイズ

memory://briefing リソースは、セッション開始時に動的に組み立てられ、豊富でトークン効率の高いアンビエントコンテキストを提供します。デフォルトでは、次の内容が自動的に表示されます。

• システム状態： サーバーのバージョン、機能のステータス、リソース／ツール数、テストの健全性、memory://metrics/summary のブレッドクラム。
• リポジトリのコンテキスト： Git のワーキングツリーの状態、未リリースの変更、正確なコードマップのパス、優先順位付けされたゲートキーパー CI ワークフロー。
• アンビエントコンテキスト： アクティブなワークスペースのパス、現地時刻、アナリティクス、アクティブな Hush Protocol フラグ。

エージェントに表示する追加コンテンツは、次の 3 つの観点から細かく制御できます。

コンテキストの注入： RULES_FILE_PATH と SKILLS_DIR_PATH を設定すると、ブリーフィングと併せてユーザールールとエージェントスキルを関連リソース（memory://rules、memory://skills）として表示できます。

リポジトリの指定： 複数のリポジトリを扱う環境では、エージェントは memory://briefing/{repo} を読み取り、PROJECT_REGISTRY に登録された特定のリポジトリに限定したブリーフィングを取得します。

"BRIEFING_ENTRY_COUNT": "1",
"BRIEFING_SUMMARY_COUNT": "0",
"INSTRUCTION_LEVEL": "essential"

"BRIEFING_ENTRY_COUNT": "5",
"BRIEFING_SUMMARY_COUNT": "3",
"BRIEFING_INCLUDE_TEAM": "true",
"BRIEFING_ISSUE_COUNT": "5",
"BRIEFING_PR_COUNT": "3",
"BRIEFING_PR_STATUS": "true",
"BRIEFING_COPILOT_REVIEWS": "true",
"INSTRUCTION_LEVEL": "full"

"BRIEFING_WORKFLOW_COUNT": "5",
"BRIEFING_WORKFLOW_STATUS": "true",
"BRIEFING_ISSUE_COUNT": "3",
"BRIEFING_PR_COUNT": "3",
"BRIEFING_PR_STATUS": "true",
"BRIEFING_COPILOT_REVIEWS": "true"

ブリーフィングのカスタマイズに関する完全ガイド →

バリエーション（上記の設定を変更します）：

MCP クライアントを再起動して、ジャーナリングを始めましょう！

オプション 3：HTTP/SSE トランスポート（リモートアクセス）

🔒 セキュリティ体制：Stdio と HTTP の比較

• Stdio（デフォルト）： ローカル IDE またはコマンドライン環境のセキュアな境界内で暗黙的に実行されます。実行コンテキストはすでに信頼されているため、明示的な認証は不要です。
• HTTP/SSE： ネットワークソケット経由でサーバーを公開します。デフォルトでは、HTTP は localhost にのみバインドし、不正アクセスや CSRF 攻撃を防ぐためにワイルドカード CORS をブロックします。パブリックネットワークへのバインド（--server-host 0.0.0.0）には、明示的な認証（--auth-token または --oauth-enabled）が必要です。 セキュリティ対策なしでサーバーをパブリックに公開しようとすると、サーバーは致命的なエラーをスローします。

リモートアクセスまたはウェブベースのクライアントを利用する場合は、サーバーを HTTP モードで実行します。

memory-journal-mcp --transport http --port 3000

すべてのインターフェースにバインドし（コンテナーで必須）、自動プロアクティブ分析スケジューラー（例：日次ダイジェスト）を有効にするには、認証トークンを指定する必要があります。

export MCP_AUTH_TOKEN="your_secure_random_token"
memory-journal-mcp --transport http --port 3000 --server-host 0.0.0.0 --digest-interval 1440

エンドポイント：

セッション管理： サーバーはデフォルトでステートフルセッションを使用します。後続のリクエストには、初期化時に返される mcp-session-id ヘッダーを含めてください。

• OAuth 2.1 — RFC 9728/8414、JWT/JWKS、細かなスコープ（--oauth-enabled でオプトイン）
• 7 つのセキュリティヘッダー — CSP、HSTS（オプトイン）、X-Frame-Options など
• レート制限 — IP ごとに 100 req/min · CORS — 設定可能な複数オリジン（完全一致） · 1MB のボディ制限
• サーバーのタイムアウト — リクエスト（120 秒）、キープアライブ（65 秒）、ヘッダー（66 秒） · 404 ハンドラー · クロスプロトコルガード
• ビルドの来歴 · SBOM · サプライチェーンの証明 · 非 root での実行

curl の使用例：

セッションを初期化します（mcp-session-id ヘッダーが返されます）。

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

ツールを一覧表示します（セッションを指定）。

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

ステートレスモード（サーバーレス）

サーバーレスデプロイ（Lambda、Workers、Vercel）では、ステートレスモードを使用します。

memory-journal-mcp --transport http --port 3000 --stateless

自動スケジューリング（HTTP のみ）

HTTP/SSE モードで実行する場合は、CLI フラグを使って定期メンテナンスジョブを有効にできます。これらのジョブは setInterval でプロセス内実行されるため、外部 cron は不要です。

Note: stdio セッションは短時間で終了する（IDE セッションに紐づいている）ため、stdio トランスポートではこれらのフラグは無視されます。stdio の場合は、OS レベルのスケジューリング（Task Scheduler、cron）を使用するか、バックアップ／クリーンアップツールを手動で実行してください。

memory-journal-mcp --transport http --port 3000 \
  --backup-interval 60 --keep-backups 10 \
  --vacuum-interval 1440 \
  --rebuild-index-interval 720

各ジョブのエラーは個別に処理されるため、あるジョブの失敗がほかのジョブに影響することはありません。スケジューラーの状態（最終実行時刻、結果、次回実行時刻）は memory://health で確認できます。

GitHub 連携の設定

get_github_issues、get_github_prs などの GitHub ツールは、PROJECT_REGISTRY が設定されている場合、または MCP サーバーが Git リポジトリ内で実行されている場合、Git コンテキストからリポジトリを自動検出します。

動的なコンテキスト解決と自動検出

GitHub ツール（issue、PR、コンテキストなど）の実行時に、サーバーは次の順序でリポジトリのコンテキストを解決します。

1. 動的なプロジェクトルーティング：エージェントが渡した repo 文字列が PROJECT_REGISTRY のキーと一致する場合、サーバーはそのプロジェクトにマッピングされた物理ディレクトリを動的にマウントします。ローカルで git コマンドを実行し、owner を自動的に推定します。
2. 明示的な上書き：エージェントが owner と repo の両方を明示的に指定した場合、それらの値が API 呼び出しでの自動検出に優先します。
3. コンテキストがない場合：PROJECT_REGISTRY も明示的なパラメーターもない場合、サーバーは実行をブロックし、エージェントに入力を促すため {requiresUserInput: true} を返します。

自動プロジェクトルーティング（カンバン／Issue）

Issue を開いたり、カンバンカードを表示または移動したりする際、サーバーには GitHub Project 番号が必要です。次の方法でこれを特定します。

1. エージェントから渡された project_number 引数を確認します。
2. repo 文字列が PROJECT_REGISTRY のエントリーと完全に一致するかを確認し、事前設定された project_number にシームレスにマッピングします。
3. 設定されている場合は、グローバルに定義された DEFAULT_PROJECT_NUMBER にフォールバックします。

🔐 OAuth 2.1 認証

本番環境へのデプロイでは、HTTP トランスポートで OAuth 2.1 認証を有効にしてください。

サポートされるスコープ：

クイックスタート：

memory-journal-mcp --transport http --port 3000 \
  --oauth-enabled \
  --oauth-issuer https://auth.example.com/realms/mcp \
  --oauth-audience memory-journal-mcp \
  --oauth-jwks-uri https://auth.example.com/realms/mcp/protocol/openid-connect/certs

または環境変数を使用します。

export OAUTH_ENABLED=true
export OAUTH_ISSUER=https://auth.example.com/realms/mcp
export OAUTH_AUDIENCE=memory-journal-mcp
export OAUTH_CLOCK_TOLERANCE=5
memory-journal-mcp --transport http --port 3000

注： OAuth はオプトインです。有効にしない場合、サーバーは環境変数 MCP_AUTH_TOKEN を使用したシンプルなトークン認証にフォールバックするか、認証なしで実行されます。

🔄 セッション管理

1. セッション開始 → エージェントが memory://briefing（または memory://briefing/{repo}）を読み取り、プロジェクトのコンテキストを表示します
2. セッションの要約 → /session-summary を使用して、進捗と次のセッションに必要なコンテキストを記録します
3. 次のセッションのブリーフィングには前回の要約が含まれ、コンテキストがシームレスに引き継がれます

🔧 設定

GitHub 連携（任意）

export GITHUB_TOKEN="your_token"              # For Projects/Issues/PRs

スコープ： repo、project、read:org（組織レベルのプロジェクト検出のみ）

GitHub 管理機能

Memory Journal は、GitHub 管理にハイブリッド方式を採用しています。

MCP サーバーのツール（読み取り＋カンバン＋マイルストーン＋issue ライフサイクル）：

• get_github_issues / get_github_issue - issue を検索します
• get_github_prs / get_github_pr - プルリクエストを検索します
• get_github_context - リポジトリの全コンテキストを取得します
• get_kanban_board / add_kanban_item / move_kanban_item / delete_kanban_item - カンバンを管理します
• get_github_milestones / get_github_milestone - 完了率を含むマイルストーンの追跡
• create_github_milestone / update_github_milestone / delete_github_milestone - マイルストーンの CRUD
• get_repo_insights - リポジトリのトラフィックと分析情報（スター、クローン、閲覧数、参照元、人気のパス）
• create_github_issue_with_entry / close_github_issue_with_entry - ジャーナルとのリンクを含む issue のライフサイクル

この設計の理由 MCP サーバーは、ジャーナルエントリーと GitHub を統合する付加価値機能（カンバンビュー、マイルストーン、タイムラインリソース、コンテキストのリンク）に重点を置いています。標準的な GitHub の変更（issue の作成・クローズ、PR のマージ、リリースの管理）は、gh CLI を介してエージェントが直接処理します。

GitHub 統合ガイドの全文 →

GitHub Commander のワークフロー

サーバーには github-commander エージェントスキルが標準でバンドルされています（memory://skills/github-commander から利用可能）。このスキルにより、リポジトリ管理のための9つの自律型 DevOps ワークフローが AI アシスタントに追加されます：issue のトリアージ、マイルストーンスプリント、PR レビュー、Copilot 監査、セキュリティ監査、コード品質監査、パフォーマンス監査、ロードマップの開始、依存関係の更新。PROJECT_* 環境変数によるオーバーライドを使用して検証レイヤーを設定し、エージェントのタスク実行時にローカルで CI と一致する実行を強制できます。

🏗️ アーキテクチャ

データフロー

flowchart TB
    AI["🤖 AI Agent<br/>(Cursor, Windsurf, Claude)"]

    subgraph MCP["Memory Journal MCP Server"]
        Tools["🛠️ 73 Tools"]
        Resources["📡 46 Resources"]
        Prompts["💬 19 Prompts"]
    end

    subgraph Storage["Persistence Layer"]
        SQLite[("💾 SQLite<br/>Entries, Tags, Relationships")]
        Vector[("🔍 Vector Index<br/>Semantic Embeddings")]
        Backups["📦 Backups"]
    end

    subgraph External["External Integrations"]
        GitHub["🐙 GitHub API<br/>Issues, PRs, Actions"]
        Kanban["📋 Projects v2<br/>Kanban Boards"]
    end

    AI <-->|"MCP Protocol"| MCP
    Tools --> Storage
    Tools --> External
    Resources --> Storage
    Resources --> External

スタック

┌─────────────────────────────────────────────────────────────┐
│ MCP Server Layer (TypeScript)                               │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │ Tools (73)      │  │ Resources (47)  │  │ Prompts (19)│  │
│  │ with Annotations│  │ with Annotations│  │             │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│ Native SQLite Engine                                        │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐  │
│  │ better-sqlite3  │  │ sqlite-vec      │  │ transformers│  │
│  │ (High-Perf I/O) │  │ (Vector Index)  │  │ (Embeddings)│  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│ SQLite Database with Hybrid Search                          │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ entries + tags + relationships + embeddings + backups   ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

🔧 技術的な特長

パフォーマンスと移植性

• TypeScript＋ネイティブ SQLite - 同期 I/O による高性能な better-sqlite3
• sqlite-vec - SQLite 拡張機能によるベクトル類似性検索
• @huggingface/transformers - JavaScript で動作するローカル ML 埋め込みモデル
• バックグラウンドでのウォームアップ - 初回リクエストの遅延を避けるため、サーバーの起動時にモデルの重み（約23MB）を非同期でメモリに読み込みます。ウォームアップの完了前にサーバーが呼び出された場合、最初のセマンティック検索またはベクトルの挿入では、重みがローカルにキャッシュされるまでネットワーク経由のコールドスタート（約1.5秒～3秒）が発生します。

パフォーマンスベンチマーク

Memory Journal は、AI タスクの実行時にオーバーヘッドを極めて低く抑えるよう設計されています。これらの基準を維持するため、vitest bench スイートを用意しています。

• データベース読み取り：操作は1ミリ秒未満で実行されます。calculateImportance は、直近50件のエントリー取得より約13～14倍高速です。
• ベクトル検索エンジン：sqlite-vec と SQL ネイティブの KNN クエリにより、検索（約140～220 ops/sec）とインデックス作成（約1600～1900+ ops/sec）の両方で高いスループットを実現します。
• MCP のコアルーチン：getTools はキャッシュされた O(1) ディスパッチを使用します（get_recent_entries より約4800～7000倍高速）。create_entry と search_entries は MCP レイヤー全体を通じて実行され、オーバーヘッドは1ミリ秒未満です。

ベンチマークスイートをローカルで実行するには：

npm run bench

テスト

2 つのフレームワークで徹底的にテストされています：

npm test          # Unit + integration tests
npm run test:e2e  # End-to-end HTTP/SSE transport tests

セキュリティ

• 一貫性のあるエラー処理 - すべてのツールは、実行可能なコンテキストを含む構造化された {success, error, code, category, suggestion, recoverable} レスポンスを返します。生の例外、サイレントな失敗、誤解を招くメッセージはありません
• ローカル優先 - すべてのデータはローカルに保存され、外部 API 呼び出しはありません（任意の GitHub を除く）
• 入力検証 - Zod スキーマ、コンテンツサイズ制限、SQL インジェクション防止
• パストラバーサル対策 - バックアップファイル名を検証します
• MCP 2025-03-26 アノテーション - 動作ヒント（readOnlyHint、destructiveHint など）
• HTTP トランスポートの強化 - 7 つのセキュリティヘッダー、設定可能な複数オリジン CORS、1MB の本文サイズ制限、組み込みレート制限（100 件／分）、サーバータイムアウト、HSTS（オプトイン）、30 分のセッションタイムアウト、404 ハンドラー、クロスプロトコルガード
• トークンのマスキング - GitHub トークンと認証情報はエラーログから自動的に伏せられます

データとプライバシー

• 単一の SQLite ファイル - データはご自身で管理できます
• ポータブル - .db ファイルをどこにでも移動できます
• ソフトデリート - エントリーを復元できます
• 復元時の自動バックアップ - 誤ってデータを失うことはありません

📚 ドキュメントとリソース

• GitHub Wiki - 完全なドキュメント
• Copilot セットアップガイド - IDE エージェントと GitHub Copilot 間のエージェント横断メモリブリッジ
• デプロイガイド - CI/CD パイプライン、環境、バージョン更新チェックリスト
• Docker Hub - コンテナーイメージ
• npm パッケージ - Node.js ディストリビューション
• Issues - バグ報告と機能リクエスト

📄 ライセンス

MIT ライセンス - 詳細は LICENSE ファイルをご覧ください。

🤝 コントリビューション

開発者による、開発者のためのプロジェクトです。プルリクエストを歓迎します！ガイドラインについては CONTRIBUTING.md をご覧ください。