pindoc

Pindoc

コードにひも付けた、AI 支援開発のためのチームメモリーです。 エージェントが永続的な記録を残し、人間がレビュー、議論し、方向性を示します。

Pindoc は、AI コーディングエージェントと開発するチーム向けのセルフホスト可能なプロジェクトメモリーシステムです。エージェントが得た有用な知見を、意思決定、デバッグ手順、タスクの完了記録、検証メモ、コードにひも付いた分析など、型付きの成果物に変換します。各成果物はプロジェクト内の領域に紐付けられ、コミット、ファイル、URL、リソース、関連する Pindoc の成果物にひも付けられます。

入力する必要のないウィキであることに変わりはありませんが、自動化そのものが目的ではありません。Pindoc は、チームメイトや将来のエージェントが再利用できるエージェントの作業内容を保持します。

存在する理由

AI コーディングセッションは生産性を高めますが、チームのコンテキストは今も見落とされがちです。

• デバッグ手順がターミナルセッションとともに失われる。
• 同じ意思決定を新しいエージェントごとに説明し直す。
• 有用な分析がチームの知識にならず、担当者のチャットに留まる。
• ウィキ、課題トラッカー、PR、コミットメッセージに重複したドキュメントが蓄積する。
• 実際のプロジェクト環境では、問題を見つけた人がすぐにコードを変更できるとは限らない。構造化された証拠があれば、チームで議論して判断できます。

Pindoc は、残しておく価値のあるエージェントの作業を、検索可能でコードにひも付いたチームメモリーに変換します。次のチームメイトやコーディングエージェントは、編集を始める前に Pindoc に重要な情報を尋ねられます。

Pindoc の特徴

• 共同作業のためのメモリーレイヤー：成果物は、個人的なチャットの要約ではなく、チームメイトや将来のエージェントが使うことを想定して作成されます。
• 書き込みはエージェント専用：Reader UI は閲覧とレビューに使い、永続的な書き込みはエージェントを通じて行います。
• MCP ネイティブのワークフロー：pindoc.context_for_task、pindoc.artifact.propose、pindoc.task.queue などのツールは、薄い CRUD API として動作するのではなく、エージェントの動作を制御します。
• 型付き成果物：Decision、Analysis、Debug、Flow、Task、TC、Glossary、ドメインパックの各タイプに対応します。
• コードにひも付いたメモリー：成果物は、コミット、ファイル、行範囲、リソース、URL、関連する成果物を参照できます。
• 記録する価値を重視した設計：Pindoc は生のチャット履歴を避け、将来役立つ意思決定、分析、デバッグ手順、検証、タスクのコンテキストだけを保持します。
• マルチプロジェクト対応デーモン：1 つの /mcp エンドポイントで複数のプロジェクトに対応できます。各ツール呼び出しには project_slug が含まれます。
• セルフホストを第一に：Docker Compose で Postgres、pgvector、Pindoc デーモン、Reader SPA を起動できます。

公開デモ

読み取り専用の公開デモは今後の取り組みであり、この OSS リリースには含まれません。公開までの間は、README、docs/、セルフホストしたクローンが主な確認手段です。Pindoc を一通り評価したい運用者は、docker compose up -d --build を実行して、自分の成果物を確認してください。

ホストされたインスタンスが適切な段階になった際に備え、今後のデモ計画は公開デモ計画に記載しています。

クイックスタート

前提条件：

• Docker 27+
• ローカルでのドッグフーディングや少人数チームでの利用には、2 CPU コアと 4 GB RAM を推奨します
• Docker イメージ、Postgres データ、埋め込みキャッシュ用に 5 GB の空きディスク容量を推奨します。新規にクローンした直後の軽量構成では、最低 2 GB が必要です
• 初回実行時に、同梱の EmbeddingGemma モデルとランタイムをキャッシュするための送信 HTTPS 接続
• ホストネイティブ開発を行う場合のみ Go 1.25+
• Docker の外で Web 開発を行う場合のみ Node 20.15+ と pnpm 10+

デフォルトの Docker 構成には、同梱の EmbeddingGemma Q4 ONNX プロバイダーによるセマンティック検索が含まれているため、埋め込み用サイドカーは不要です。最小構成およびオプションのデプロイプロファイルについては、システム要件を参照してください。

git clone https://github.com/var-gg/pindoc.git
cd pindoc
docker compose up -d --build

実行中のデーモンに正確なソースリビジョンを報告させるには、ビルド前に現在のコミットを Compose のビルド引数として渡します。

export PINDOC_BUILD_COMMIT="$(git rev-parse HEAD)"
docker compose up -d --build

PowerShell ユーザーは、同じ値を git rev-parse HEAD によって $env:PINDOC_BUILD_COMMIT に設定できます。make compose-up は、このスタンプ付けを自動的に行います。

Reader を開きます。

http://localhost:5830/

データベースの台帳が、イメージに埋め込まれたマイグレーションと一致していることを確認します。

docker compose exec pindoc-server-daemon pindoc-admin schema doctor --json

このコマンドは読み取り専用で、未知の適用済みマイグレーション、未適用のマイグレーション、またはチェックサムの不一致がある場合は、ゼロ以外の終了コードで終了します。未知のスキーマ変更を自動的に削除したり受け入れたりすることはありません。

未知、古い、失敗したインデックスや、異なる埋め込みモデルで構築されたセマンティックインデックスをプレビューして修復します。

docker compose exec pindoc-server-daemon pindoc-reembed -dry-run -state needs-refresh
docker compose exec pindoc-server-daemon pindoc-reembed -state needs-refresh

Pindoc は、インデックス対象のリビジョン、タイトル／本文のハッシュ、モデルの識別情報、試行回数、最終エラーを artifact_index_state に記録します。古いチャンクを置き換える前に、埋め込みをすべて準備します。プロバイダーが失敗した場合でも、アーティファクトの書き込みは index_state.status="failed" かつ retryable=true の状態で成功することがあり、その場合も最後に正常だったチャンクは引き続き検索できます。再埋め込みコマンドは各アーティファクトを個別のトランザクションで処理し、いずれかの再試行が失敗した場合はゼロ以外の終了コードで終了します。

新しいインスタンスでは、/ を開くとまずオーナーの識別情報（表示名とメールアドレス）が求められ、その後、最初のプロジェクト用ウィザードに移動します。識別情報の設定後にプロジェクト用ウィザードを直接開くには、次のコマンドを実行します。

http://localhost:5830/projects/new?welcome=1

古い REST ビルドでオーナーがいないプロジェクトを修復する

古いビルドでは、対応するオーナーの project_members 行がないまま、POST /api/projects を通じてプロジェクトを作成できる場合がありました。アップグレード後、影響を受けたプロジェクトに設定済みのループバックオーナーを割り当てて修復してください。

INSERT INTO project_members (project_id, user_id, role)
SELECT p.id, s.default_loopback_user_id::uuid, 'owner'
FROM projects p
CROSS JOIN server_settings s
WHERE p.slug = '<project-slug>'
  AND s.default_loopback_user_id IS NOT NULL
ON CONFLICT (project_id, user_id) DO UPDATE SET role = 'owner';

MCP クライアントを接続する

Docker デーモンは、アカウントレベルの MCP エンドポイントを 1 つ公開します。

{
  "mcpServers": {
    "pindoc": {
      "type": "http",
      "url": "http://127.0.0.1:5830/mcp"
    }
  }
}

プロジェクトのスコープは URL に含まれません。エージェントは、プロジェクトスコープのツール呼び出しで project_slug を渡します。pindoc.harness.install が生成するワークスペースは、そのスラッグを PINDOC.md のフロントマターに保存します。pindoc.workspace.detect は現在のワークスペースに該当する可能性が高いスラッグを特定しますが、デーモン全体の PINDOC_PROJECT デフォルト値は変更しません。複数プロジェクトの Docker デーモンでは、セッションの確認後も、検出した project_slug を明示的に渡し続けてください。

completeness=draft は成熟度／信頼状態を示すものであり、未公開の非公開ドラフトではありません。受け付けられた MCP の書き込みは、可視性の設定で許可されている場合、公開され Reader から閲覧できます。通常のユーザー向け画面に表示してはならないコンテンツには、visibility=private またはレビューのワークフローを使用してください。

一般的なワークフロー

エージェントに、プロジェクトのコンテキストを踏まえて作業を開始するよう依頼します。

Use Pindoc context before editing. Find the current project, inspect assigned
Tasks, then implement the next acceptance item.

一般的な MCP の流れ：

1. pindoc.workspace.detect
2. pindoc.task.queue
3. pindoc.context_for_task
4. コードまたはドキュメントの作業
5. pindoc.artifact.propose
6. Task の受け入れ条件とクローズアウト状態を更新

Docker Desktop／Windows からのアセットアップロード

pindoc.asset.upload(local_path=...) は、Windows クライアントではなく、MCP サーバーの ホスト／コンテナ上のパスを読み取ります。Docker Desktop の場合は、まずホスト上の ファイルを pindoc-server-daemon コンテナにコピーしてください。

pwsh -File tools/push-asset.ps1 A:\path\image.png -ProjectSlug survival-manager

このスクリプトは、コンテナ内の /tmp/pindoc-asset-upload/... パスを含む、 pindoc.asset.upload 用の JSON 入力を出力します。

Reader に表示されるインライン画像については、意図的に次の 2 つの手順を分けています。

1. body_markdown に ![alt](<asset.blob_url>) を記述します。これはレンダリングを制御します。
2. role="inline_image" を指定して pindoc.asset.attach を呼び出します。これにより、リビジョンのメタデータとエビデンスが記録されます。

設定

Docker のデフォルト構成は、単一ユーザー向けで、ループバックのみを使用します。

変数	デフォルト値	用途
PINDOC_DAEMON_PORT	5830	Docker Compose が使用するホストポートです。
PINDOC_PROJECT	pindoc	スコープ指定のない読み取り／設定に使用するデフォルトのプロジェクトです。
PINDOC_PUBLIC_BASE_URL	http://127.0.0.1:${PINDOC_DAEMON_PORT}	生成されるリンクと OAuth メタデータで使用する公開ベース URL です。
PINDOC_BIND_ADDR	127.0.0.1:5830	セキュリティ上の意図を示します。ループバック以外の値を使用するには、IdP または明示的なパブリック未認証アクセスの許可が必要です。
PINDOC_AUTH_PROVIDERS	空	外部リクエストで有効にする ID プロバイダーです。現在のプロバイダー：github。
PINDOC_ALLOW_PUBLIC_UNAUTHENTICATED	false	IdP を使用せずに外部公開するための明示的な許可です。信頼できるネットワーク／リバースプロキシの背後でのみ使用してください。
PINDOC_FORCE_OAUTH_LOCAL	false	ローカル QA 用に、ループバックの /mcp 呼び出しを OAuth ベアラー認証経由にする開発用フラグです。
PINDOC_ALLOWED_ORIGINS	空	カンマ区切りの CORS 許可リストです。空の場合は同一オリジンのみを許可します。オリジン間のフロントエンドには、許可するオリジンを明示的に設定してください。
PINDOC_DEV_MODE	false	ローカルツールでのワイルドカード CORS を許可する開発専用フラグです。公開インスタンスでは有効にしないでください。

ID プロバイダーなしで、書き込み可能なデーモンをパブリックインターネットに公開しないでください。 公開読み取り専用デモでは、リバースプロキシで /mcp と変更を伴う HTTP ルートをブロックしてください。SECURITY.md と docs/22-public-demo.md を参照してください。 デーモン自体も、nosniff、クリックジャッキング対策、リファラーポリシー、 強化されたアセット Blob の CSP など、基本的なセキュリティヘッダーを設定します。

書き込み可能な公開インスタンスやデバイス間で使用するインスタンスについては、 docs/oauth-setup.md に従ってください。GitHub OAuth App の設定、 ${PINDOC_PUBLIC_BASE_URL}/auth/github/callback というコールバックルール、 実行時の MCP クライアント登録、および PINDOC_FORCE_OAUTH_LOCAL を使ったローカル OAuth QA について説明しています。

開発

# Run Go tests. Integration tests that need Postgres are skipped unless
# PINDOC_TEST_DATABASE_URL is set.
go test ./...

# Web checks.
cd web
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test:unit
pnpm build

# Full image build.
docker build -t pindoc-server:local .

127.0.0.1 経由で接続したまま OAuth ベアラーパスをローカルでテストするには、 PINDOC_FORCE_OAUTH_LOCAL=true を設定してください。デーモンは起動時に警告を出し、 ループバックの /mcp 呼び出しに Bearer トークンを必須とします。

ローカル C ツールチェーンがない Windows ホストでは、Docker 経由で Go テストを実行してください。

docker run --rm -v "${PWD}:/work" -w /work golang:1.25 go test ./...

使い捨ての Postgres／pgvector データベースに対してデータベース統合テストを実行してください。 PINDOC_TEST_DATABASE_URL を、個人用または本番用の Pindoc データベースに決して指定しないでください。テストおよびプラグインのフィクスチャでは、Reader の分離を明示的に有効にする必要があります。 projects.CreateProjectInput.ReaderHidden を true に設定するか、SQL で挿入する際に projects.reader_hidden = TRUE を設定してください。スラッグ接頭辞の検出は非推奨であり、リクエスト時には実行されなくなりました。マイグレーション 0070 は、以前の Pindoc リリースで使用されていたフィクスチャ接頭辞を一度だけバックフィルします。

ドキュメント

• ドキュメントハブ
• 公開デモ計画
• 公開デモのストーリーパス
• 記録に値するアーティファクトのポリシー
• 公開リリースチェックリスト
• コントリビューション
• セキュリティ
• 設計のソースノート

フィードバック

長文の質問、機能リクエスト、設計に関する議論は GitHub Discussions にお寄せください。バグ報告は GitHub Issues にお寄せください。メンテナーは 通常1日以内に返信します。

ステータス

Pindoc は現在、積極的にドッグフーディングを行っています。ローカルでのセルフホスト経路、Reader UI、プロジェクト／エリアモデル、成果物の提案フロー、タスクキュー、リビジョン履歴、要約、実際の埋め込みプロバイダー経路が実装されています。公開 OSS ローンチに向けては、初回実行時の信頼性、読み取り専用のドッグフーディングデモ、CI、セキュリティドキュメント、より明確な共同作業の位置づけに注力しています。

ライセンス

Apache License 2.0 です。LICENSE をご覧ください。