Private Journal MCP Server

Private Journal MCP Server

Claude に、思考、振り返り、洞察を処理するためのプライベートなジャーナリング機能とセマンティック検索機能を提供する、包括的な MCP（Model Context Protocol）サーバーです。

機能

ジャーナリング

• 複数セクションでのジャーナリング：振り返り、観察、プロジェクトメモ、ユーザーコンテキスト、技術的な洞察、世界に関する知識を個別のカテゴリに分けて記録できます
• 二重ストレージ：プロジェクトメモはプロジェクトとともに保管され、個人的な思考はユーザーのホームディレクトリに保管されます
• タイムスタンプ付きエントリ：各エントリにマイクロ秒単位の精度で自動的に日付が記録されます
• YAML フロントマター：各エントリの構造化メタデータ

検索と発見

• セマンティック検索：ローカル AI 埋め込みを使用した自然言語クエリ
• ベクトル類似性：キーワードの一致だけでなく、概念的に関連するエントリを見つけます
• ローカル AI 処理：@xenova/transformers を使用し、外部 API 呼び出しは不要です
• 自動インデックス作成：起動時および継続的に、すべてのエントリの埋め込みを生成します

プライバシーとパフォーマンス

• 完全なプライバシー：すべての処理はローカルで実行され、データがマシンの外に出ることはありません
• 高速な動作：最適化されたファイル構成とメモリ内の類似度計算
• 堅牢なフォールバック：プラットフォームを問わないインテリジェントなパス解決

インストール

このサーバーは npx を使って GitHub から直接実行できるため、インストールは不要です。

MCP の設定

Claude Code（ワンライナー）

claude mcp add-json private-journal '{"type":"stdio","command":"npx","args":["github:obra/private-journal-mcp"]}' -s user

手動設定

MCP の設定に追加します（例：Claude Desktop の設定）。

{
  "mcpServers": {
    "private-journal": {
      "command": "npx",
      "args": ["github:obra/private-journal-mcp"]
    }
  }
}

サーバーはジャーナルファイルに適した場所を自動的に見つけます。

設定

PRIVATE_JOURNAL_PATH 環境変数

PRIVATE_JOURNAL_PATH を設定すると、すべてのジャーナルの保存先を単一のディレクトリに変更できます。デフォルトのホームディレクトリ解決が適用されないコンテナ化されたデプロイで便利です。

{
  "mcpServers": {
    "private-journal": {
      "command": "npx",
      "args": ["github:obra/private-journal-mcp"],
      "env": {
        "PRIVATE_JOURNAL_PATH": "/data/journals"
      }
    }
  }
}

この変数を設定すると、プロジェクトジャーナルとユーザージャーナルの両方が指定したパスに書き込まれ、すべてのフォールバック解決ロジックが回避されます。

--journal-path CLI 引数

CLI 引数を使ってプロジェクトジャーナルのパスを設定することもできます。

npx github:obra/private-journal-mcp --journal-path /path/to/journals

これはプロジェクトジャーナルのパスのみを上書きします。ユーザージャーナルのパスは、引き続き PRIVATE_JOURNAL_PATH またはデフォルトのホームディレクトリ解決ロジックによって決定されます。

MCP ツール

このサーバーは、包括的なジャーナリング機能と検索機能を提供します。

process_thoughts

次の任意カテゴリを使った、複数セクションでのプライベートなジャーナリングです。

• reflections：統合的な思考 — 気づいたこと、感じたこと、理解したこと、または考えを整理したこと
• observations：短く個別の気づき — それぞれ1、2文程度
• project_notes：現在のプロジェクトに固有の技術的な洞察
• user_context：人間との協働に関するメモ
• technical_insights：ソフトウェアエンジニアリング全般に関する学び
• world_knowledge：分野に関する知識や興味深い発見

search_journal

すべてのジャーナルエントリを対象としたセマンティック検索です。

• query（必須）：自然言語による検索クエリ
• limit：結果の最大数（デフォルト：10）
• type：検索範囲 — 'project'、'user'、または 'both'（デフォルト：'both'）
• sections：特定のカテゴリで絞り込みます

read_journal_entry

指定したエントリの全文を読み込みます。

• path（必須）：検索結果に含まれるファイルパス

list_recent_entries

最近のエントリを時系列で確認できます。

• limit：エントリの最大数（デフォルト：10）
• type：エントリの範囲 — 'project'、'user'、または 'both'（デフォルト：'both'）
• days：遡って検索する日数（デフォルト：30）

ファイル構成

プロジェクトジャーナル（プロジェクトごと）

.private-journal/
├── 2025-05-31/
│   ├── 14-30-45-123456.md          # Project notes entry
│   ├── 14-30-45-123456.embedding   # Search index
│   └── ...

ユーザージャーナル（全体）

~/.private-journal/
├── 2025-05-31/
│   ├── 14-32-15-789012.md          # Personal thoughts entry
│   ├── 14-32-15-789012.embedding   # Search index
│   └── ...

エントリ形式

各 Markdown ファイルには、YAML フロントマターと構造化されたセクションが含まれます。

---
title: "2:30:45 PM - May 31, 2025"
date: 2025-05-31T14:30:45.123Z
timestamp: 1717160645123
---

## Reflections

I'm excited about this new search feature...

## Technical Insights

Vector embeddings provide semantic understanding...

開発

ビルド

npm run build

テスト

npm test

開発モード

npm run dev

Claude のパフォーマンスを向上させる

Claude が時間とともに学習し、改善できるように、~/.claude/CLAUDE.md ファイルにジャーナルの使用方法に関するガイダンスを追加することを検討してください。

## Learning and Memory Management

- YOU MUST use the journal tool frequently to capture technical insights, failed approaches, and user preferences
- Before starting complex tasks, search the journal for relevant past experiences and lessons learned
- Document architectural decisions and their outcomes for future reference
- Track patterns in user feedback to improve collaboration over time
- When you notice something that should be fixed but is unrelated to your current task, document it in your journal rather than fixing it immediately

これにより、Claude は会話をまたいで永続的なメモリを構築できるようになり、エンジニアリング上の判断やコラボレーションのパターンが改善されます。

作者

Jesse Vincent [email protected]

この取り組みの動機と設計については、ブログ記事をご覧ください。

ライセンス

MIT