openchronicle-mcp

OpenChronicle

_{· claude-fable-5 · 2026-08-30 · 詳細}

LLM エージェント向けのメモリデータベースです。永続的なセマンティック検索とキーワード検索によるメモリ、プロジェクトごとの名前空間、Git オンボーディングを備え、単一の ASGI プロセスから HTTP REST と MCP 経由で提供します。お使いのハードウェア上で動作します。

できること

• セッションをまたいだ永続メモリ。 コンテキストの圧縮や新しい会話の開始後も残る、決定事項、マイルストーン、却下したアプローチを保存できます。Reciprocal Rank Fusion による全文検索とセマンティック検索のハイブリッド検索で取得できます。
• プロジェクトごとの名前空間。 メモリの範囲をプロジェクトごとに設定できるため、ある作業ストリームのコンテキストが別の作業ストリームに漏れません。
• Git オンボーディング。 リポジトリをクローンし、関連性に基づいてコミットをクラスタリングし、メモリへの取り込みにすぐ使える要約を返します。既存コードの背景にある WHY を長期メモリに登録します。
• 1 つのプロセス、2 つのトランスポート。 FastAPI が REST インターフェース（/api/v1/*）と MCP のストリーム可能な HTTP トランスポート（/mcp）の両方を同じポートでホストします。コンテナ 1 つ、ポートマッピング 1 つ、ヘルスチェック 1 つで済みます。
• 埋め込み生成の障害時も縮退運転。 埋め込みプロバイダーが停止すると、検索は問題なく FTS5 のみに縮退し、/api/v1/health と MCP の health ツールを通じて縮退状態を示します。プロバイダーの復旧後にバックフィルが追いつきます。静的な /health エンドポイントは、最小限の稼働確認プローブとして維持されます。
• 任意の運用メトリクス。 リリース済みイメージ（v3.4.0 以降）には、上限付き Prometheus レコーダーと保護された /metrics エンドポイントが含まれます。既定では無効です。有効にするには OC_METRICS_ENABLED=true を設定します。本番環境での有効化には、パフォーマンスゲートへの準拠が引き続き必要です。メトリクスの設定と、任意のローカル監視ランブックを参照してください。
• スキーママイグレーションフレームワーク。 セーブポイントによるアトミック性を備えた、バージョン管理された .sql マイグレーションです。再実行しても冪等です。今後のスキーマ変更は NNN_<slug>.sql ファイルとして追加できます。
• 検証済みのオンラインバックアップ。 SQLite のオンラインバックアップ API を使用します。毎晩のスナップショットは検証済みマニフェストとともに OC_BACKUP_DIR に公開され、検証に失敗したものは隔離されます。破壊的操作の前にはバックアップを取る方針で、VACUUM は同じジョブの一部として先にバックアップを実行します。整合性チェックに失敗すると、緊急バックアップが実行されます。
• 任意の暗号化オフサイトコピー。 毎晩のジョブで最新のスナップショットを age で暗号化し、任意の rclone リモートに追記専用でコピーします。cloud_backup.mdを参照してください。

できないこと

• 会話エンジンではありません。v3 には LLM がありません。MCP サーバー経由で Claude Code、Goose、Open WebUI などを使用してください。
• マルチテナントではありません。シングルユーザー向けです。OC_API_KEY によるベアラートークン認証に対応していますが、任意であり、信頼できる LAN 環境へのデプロイでは既定で無効です。有効にするタイミングについては docs/configuration/security_posture.md を参照してください。
• クラウド同期レイヤーではありません。データベースはお使いのハードウェア上にあります。バックアップはローカルのバックアップディレクトリに保存され、任意で暗号化してクラウドリモートにコピーされますが、バックアップ専用です。デバイス間の同期機能は組み込まれていません（docs/design/0001-cloud-backup.md）。

これは設計上の仕様です。

インストール

ソースから：

pip install -e ".[mcp,openai]"
oc init
oc serve

デフォルトでは、oc serve は 127.0.0.1:8000 にバインドします。--host／--port または OC_API_HOST／OC_API_PORT で変更できます。

Docker（単一コンテナー、NAS に適しています）：

docker run --rm \
  -p 8000:8000 \
  -e OC_API_HOST=0.0.0.0 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config \
  ghcr.io/carldog/openchronicle-mcp:latest

コンテナー内では OC_API_HOST=0.0.0.0 が必要です。アプリのデフォルト設定ではコンテナーのループバックアドレスにバインドされるため、ポートマッピングから接続できません。サーバーを localhost 以外（NAS のホスト名や LAN の IP アドレスなど）で呼び出す場合は、OC_MCP_ALLOWED_HOSTS=your-host:* も設定してください。設定しないと、すべてのリクエストで 421 が返されます（env_vars.md を参照）。

NAS 上の Portainer スタックでは、リポジトリのルートにある docker-compose.nas.yml を使用してください。事前に 3 つの準備が必要です。OC_TAG にリリースタグを設定すること（:latest へのフォールバックはありません）、データボリュームを一度作成すること（docker volume create openchronicle-mcp_oc-data。compose はボリュームを作成しないため、ボリュームがない場合は空の状態で起動せず、デプロイに失敗します）、そしてホスト側のエクスポートディレクトリを作成し、uid 1000 の所有にすることです。このファイルの先頭コメントに、すべての変数が記載されています。

クイックスタート

# Bootstrap the runtime tree
oc init

# Create a project
PROJECT_ID=$(oc init-project "my-project")

# Save your first memory
oc memory add "Decision: SQLite for storage; AGPL for license" \
    --project-id $PROJECT_ID --tags decision

# Search it
oc memory search "storage decision" --project-id $PROJECT_ID

または、MCP 経由で同じ操作を行います。Claude Code にサーバーを登録してください。

claude mcp add --scope user --transport http openchronicle \
    http://127.0.0.1:8000/mcp

続いて、Claude に memory_save と memory_search を呼び出すよう依頼します。

アーキテクチャ

ヘキサゴナルアーキテクチャです。domain/（純粋な型とポート）→ application/（ユースケース、サービス）→ infrastructure/（SQLite、埋め込みアダプター、メンテナンスループ）。ドライバー側のアダプターは interfaces/ にあり、HTTP、MCP、CLI の各インターフェイスを提供します。

全体の構成については、docs/architecture/ARCHITECTURE.md を参照してください。

ドキュメント

• docs/architecture/ARCHITECTURE.md — 構成、スキーマ、ASGI 設計
• docs/architecture/MAINTENANCE.md — メンテナンスループと劣化ポリシー
• docs/cli/commands.md — oc サブコマンドのリファレンス
• docs/configuration/env_vars.md — 環境変数
• docs/configuration/config_files.md — core.json スキーマ
• docs/configuration/security_posture.md — セキュリティモデル
• docs/integrations/mcp_client_setup.md — MCP サーバーの登録
• docs/integrations/mcp_server_spec.md — MCP ツールのインターフェイス
• docs/api/STABILITY.md — バージョニングと非推奨化ポリシー
• docs/design/README.md — 提案中の設計とリポジトリの比較レビュー

開発

uv sync --locked --extra dev --extra mcp --extra openai --extra ollama --extra metrics
pre-commit install
uv run pytest

依存関係は uv.lock で固定されており、CI と Docker イメージはこのファイルからインストールします。pyproject.toml の [project] 内を変更した場合（バージョンを含む）は、uv lock を実行してください。

アーキテクチャはテストによって検証されます。

• tests/test_hexagonal_boundaries.py — domain／application／infrastructure のレイヤー構成
• tests/test_architectural_posture.py — core が MCP SDK に依存しないこと
• tests/test_no_secrets_committed.py、tests/test_no_soft_deprecation.py — リポジトリの衛生状態

ライセンス

Copyright (C) 2025-2026 CarlDog

AGPL-3.0。このプログラムはフリーソフトウェアです。Free Software Foundation が公開する GNU Affero General Public License の条件に従って、バージョン 3、または（任意で）それ以降のバージョンのもとで、再配布および改変できます。このプログラムは一切の保証なしで配布されます。詳細はライセンスを参照してください。

著作権表示は LICENSE ではなくここに記載されています。このファイルは AGPL の本文そのものであり、末尾の付録にある <year> <name of author> というプレースホルダーは、ソースファイルに記載する内容についてのライセンス独自の指示であり、埋めるための空欄ではありません。これらを書き換えると、ライセンス本文そのものを変更することになります。