todox

todox

開発者とそのエージェントのための作業メモリ。 チェックリストではありません。次のセッションが実際に再開できるログです。

課題トラッカーは人と人とのやり取りを想定して書かれています。todox はエージェント同士のやり取りを想定し、人がその様子を横から見られるように書かれています。各タスクには、その背景にある判断、失敗したアプローチ、未解決の疑問、そして前回のセッションが残したメモが記録されています。

新しいエージェントは get_context を呼び出して内容を読み、前のエージェントが止まったところから作業を始めます。すでに誰かがぶつかった壁に、またぶつかることはありません。ブリーフィングには上限があり、行数 と バイト数の両方で制限されます。また、何も言わずに切り詰めるのではなく、上限によって省かれた内容を報告します。文の途中で切り取られることはありません。すべての記録には名前と日付が付いており、冒頭の一行が返されます。body が null の場合は、予算を使い切ったことを意味し、記録が空という意味ではありません。

仕組み

エージェントが記録し、あなたはその様子を横から読みます。リポジトリごとにログは一つで、最後に触れたマシンやエージェントにかかわらず共有されます。

プロジェクト一覧	1 つのプロジェクト

ログに記録する内容

種類	意味
decision	選んだ内容と、他の案を選ばなかった理由
dead_end	うまくいかなかったアプローチ。繰り返しを防げるため、最も価値の高い記録です
question	人間にしか答えられないこと
handoff	セッション終了時の状況を、事情を知らない人に向けて記したもの
note	その他すべて

ログを成果物として扱うことで、次の 2 つが実現します。

• 古くなったコンテキストにはフラグが立ち、偽装されることはありません。 リンク先のファイルは、それを確認できる側、つまりエージェントがハッシュ化し、サーバーがそのハッシュを保存して比較します。コードが変更されていれば、get_context はメモが間違っている可能性を伝えます。エージェントが実際に確認するまでは、新しい情報だと主張せず、未確認として記録されます。コンテキストが嘘をつくのは、何もないより悪く、確信度について嘘をつく場合も同じです。
• レポートはコミットではなくログから作られます。 ステータス変更はすべてイベントとして記録されるため、今日何を終えたか、どれくらいかかったか、どのモデルが作業したかは、考古学のように掘り起こすのではなく、クエリで取得できます。doing に設定したタスクを放置した場合、何週間も経過した期間ではなく、設定した日の午前の作業として数えられます。また、レポートは省かれた内容の量も伝え、見出しに紛れ込ませません。
• ファイルに、そのファイルについて分かっていることを尋ねられます。 ハッシュを保持するリンクは、反対側からも読み取れます。get_file_context にパスを渡すと、そのファイルに関わったタスク、各タスクの行き止まり、関連付けられた継続中のメモが返されます。パスはリポジトリ相対形式に統一されるため、あるマシンで作成されたリンクを別のマシンからも見つけられます。

エージェントがすでに持っているメモリーでは不十分なのはなぜですか？

Claude Code は独自のメモを自動で記録するようになりました（自動メモリー。2026 年 2 月以降、デフォルトで有効）。Cursor と Codex にも同様の機能があります。ぜひ活用してください。pnpm を好むといったことを覚えておくには便利です。それぞれのドキュメントには、これらの機能はリポジトリごと、マシンごと（「マシン内に保存され、マシン間では共有されない」）、ツールごとに使われ、誰とも共有されない（「自分だけが使う」）と記載されています。todox が扱うのは、その範囲から外れる情報です。

• 2 台のマシンで、1 つのログ。 リポジトリはリモートによって識別されるため、ノート PC に残したメモをデスクトップで読めます。
• どのエージェントでも、1 つのログ。 Claude Code、Codex、Cursor、VS Code はすべて MCP に対応しています。次に使うエージェントがどれであっても、前のエージェントが引き継ぎとして残した内容を読めます。
• チームのメンバーも利用できます。 プロジェクトは共有でき、ログには誰が何を書いたか、どのモデルが処理したかが記録されます。
• ファイル内のメモにはない構造。 開始と完了があるタスク、独立した種類として記録される行き詰まり、ログから読み取れるレポート、古くなったことが明示されるメモ、そして上限によって何が省かれたかを伝えるブリーフィングがあります。

他のメモリーサーバーとの比較

各プロジェクトの README に記載された内容に基づいています（2026-10-16 に確認）。README に説明がない項目は、推測せずその旨を記載しています。

	todox	MCP memory server	Basic Memory	Mem0
保存する内容	タスクごとに、判断、行き詰まり、質問、引き継ぎを記録したログ。継続的に参照するメモ	知識グラフ：エンティティ、関係、観察事項	Markdown ノート。ローカルに SQLite インデックスを作成	LLM が会話から抽出した事実
保存場所	ホスト型または自分で用意した Postgres	ローカルの JSONL ファイル	ディスク上のファイル。有料のクラウドオプションで同期可能	セルフホスト型サーバーまたはマネージドプラットフォーム
2 台のマシンでの利用	1 つのログを共有。リポジトリは Git リモートによって識別	説明なし。ネットワークファイルシステムでのファイル利用は安全ではない	手動（Git、Syncthing）またはクラウドオプション	サーバーまたはプラットフォーム経由
構造化された情報を扱えるか	はい。タスクは開始・完了でき、行き詰まりは独立した種類として記録される	説明なし	カテゴリ付きの自由形式の観察事項。タスクや行き詰まりの種類についての説明はない	説明なし
コードの変更を検知するか	はい。エージェントが関連ファイルのハッシュを計算し、変更されたファイルにフラグを付ける	説明なし	説明なし	説明なし
LLM API キーが必要か	いいえ	説明なし	説明なし	はい。デフォルトは OpenAI

それぞれ異なる問題を解決します。知識グラフやノート保管庫は、人物や分野についての情報を記録するのに適しています。todox は、リポジトリ内の作業状況を記録し、そこで失敗したことを繰り返さないためのものです。

試してみる

todox.dev — 誰でも登録できます。個人向けの小規模なデプロイで、稼働時間は保証されません。ログが大切なら、セルフホストしてください。

自分で実行する

pnpm install
cp .env.example .env.local     # any Postgres 15+; see below for a container
pnpm db:migrate                # idempotent
pnpm seed                      # optional demo account: demo / todox-demo
pnpm dev

エージェントを接続する

todox はリモート MCP サーバーです。インストールもリポジトリのクローンも必要ありません。エージェントトークンを使って、任意の MCP クライアントを URL に接続してください。

アカウントページでトークンを作成すると、使用しているエージェントにそのまま貼り付けられるテキストと、よく使われる4つのエージェント向けの設定スニペットが表示されます。形式は常に同じで、URLが1つ、ヘッダーが1つです。

Claude Code には、もっと手軽な方法があります。 プラグインにはサーバー、スキルとしてのセッションプロトコル、セッション開始時のリマインダーが含まれています。トークンの入力を一度だけ求め、その後は Claude Code の設定に保存します。

claude plugin marketplace add beydemirfurkan/todox
claude plugin install todox@todox

以下の説明はすべてプラグインにも当てはまります。プラグインも同じ4行ですが、貼り付けるのではなくインストールします。機能の詳細については、plugin/README.md を参照してください。

# Claude Code. --scope user, because the default is this directory only.
claude mcp add --scope user --transport http todox https://www.todox.dev/api/mcp \
  --header "Authorization: Bearer todox_…"

// OpenCode v1 — ~/.config/opencode/opencode.json.
// MCP key is `mcp` (server name is a direct key under it), NOT `mcpServers`.
// `type` is `"remote"`, NOT `"http"` — the Claude/Cursor/VS Code value is
// silently ignored on OpenCode.
{
  "mcp": {
    "todox": {
      "type": "remote",
      "url": "https://www.todox.dev/api/mcp",
      "headers": { "Authorization": "Bearer todox_…" }
    }
  }
}

// OpenCode v2 — same key, server now nested under `mcp.servers`.
{
  "mcp": {
    "servers": {
      "todox": {
        "type": "remote",
        "url": "https://www.todox.dev/api/mcp",
        "headers": { "Authorization": "Bearer todox_…" }
      }
    }
  }
}

# Codex — ~/.codex/config.toml
[mcp_servers.todox]
url = "https://www.todox.dev/api/mcp"
http_headers = { Authorization = "Bearer todox_…" }

// Cursor — ~/.cursor/mcp.json, the one in your home directory.
{
  "mcpServers": {
    "todox": {
      "type": "http",
      "url": "https://www.todox.dev/api/mcp",
      "headers": { "Authorization": "Bearer todox_…" }
    }
  }
}

// VS Code — the user-level mcp.json ("MCP: Open User Configuration").
// The root key is "servers", NOT "mcpServers". This is the one client
// that differs, and getting it wrong is silent.
{
  "servers": {
    "todox": {
      "type": "http",
      "url": "https://www.todox.dev/api/mcp",
      "headers": { "Authorization": "Bearer todox_…" }
    }
  }
}

MCP 設定のキーと type の値はエージェントごとに異なります。組み合わせを間違えても通知されず、エラーも警告も出ないまま、ツールが表示されません。

エージェント	キー	type
Claude Code	mcpServers.NAME	"http"
OpenCode v1	mcp.NAME	"remote"
OpenCode v2	mcp.servers.NAME	"remote"
Cursor	mcpServers.NAME	"http"
VS Code（Copilot Chat）	servers.NAME	"http"
Codex	TOML [mcp_servers.NAME]	n/a

ファイルの保存場所はプラットフォームによって異なります。また、VS Code の場所は Linux で一般的な場所とは異なります。

エージェント	macOS	Linux	Windows
Claude Code	~/.claude.json	同じ	同じ
Cursor	~/.cursor/mcp.json	同じ	同じ
Codex	~/.codex/config.toml	同じ	同じ
OpenCode	~/.config/opencode/opencode.json	同じ	同じ
VS Code	~/Library/Application Support/Code/User/mcp.json	~/.config/Code/User/mcp.json	%APPDATA%\Code\User\mcp.json

プロジェクトごとではなく、グローバルにインストールしてください。 これらのツールはすべて、現在いるディレクトリに設定を保存するのがデフォルトです。たとえば、スコープを指定しない claude mcp add、.cursor/mcp.json、.vscode/mcp.json などです。特定のリポジトリにしか存在しないメモリでは、本来の目的を果たせません。また、次のプロジェクトでツールが使えず、エージェントもそれについて何も言わないため、気づかないまま失敗します。

"type": "http" を明示してください。url を見つけても type がないクライアントは、ローカルコマンドだと判断しがちで、分かりにくいエラーを返します。

それから、エージェントに使うよう伝えます

接続されていることと、実際に使われていることは同じではありません。その差は見た目以上に大きいものです。 MCP サーバーの instructions は背景情報として読むものであり、スキルや CLAUDE.md のルールは指示です。両者が食い違うと、サーバー側の指示は後回しになります。これは、todox を接続したまま一度も呼び出さずに、新しいプロジェクトで確認されています。

そこで、エージェントが実際に従うメモリファイルに、次の4行を記載してください。

todox MCP is installed here — persistent memory across projects.

- Call `get_context` before starting non-trivial work (cwd = your working
  directory). It registers a new repo by itself.
- `create_task` for anything that will not finish this session.
- Before stopping, `session_status` lists what you touched; leave a
  `log_entry(kind:'handoff')` on each, and `dead_end` for approaches that failed.
- Always pass your own model id.

または、インストーラーに任せることもできます。

pnpm install:mcp claude-code --write-memory

このファイルは私たちではなくあなたのものなので、明示的に求められない限り変更しません。また、冪等に動作します。ブロックは HTML コメントで囲まれているため、2回目の実行では置き換えられ、古い指示が優先されるような形で2組残ることはありません。先に正確なブロックを確認するには、--dry-run を追加してください。

ツールがまったく表示されない場合、気づきにくい原因は通常、上記2つの表のどちらかです。各クライアントがファイルを読み取る方法に沿って内容を調べ、原因を示すコマンドがあります。

npx https://github.com/beydemirfurkan/todox/releases/latest/download/todox-mcp.tgz doctor

クライアントごとに、エントリー、その type、ルートキー、クライアントが読み取らない場所に残った設定、メモリファイルに習慣が記載されているか、そしてサーバーが見つかったトークンに応答するかどうか（出力ではマスキングされます）を表示します。また、現在のチェックアウトにある独自の設定内にある todox エントリーも、何であるかを明示します。変更は行いません。詳しくは docs/mcp.md をご覧ください。

これを省略して、アカウントがツールを呼び出さないまま数日間接続されていると、次のセッションでサーバーは instructions の冒頭に「N 日間接続されており、ツールを呼び出していません」と表示します。そして、4行とクライアントのメモリファイルのパスをエージェントに渡し、それらを追記して、完了したことをあなたに伝えるよう指示します。これは tool_usage を基準にしているため、該当する状態の間だけ表示され、ツールが呼び出された時点で表示されなくなります。これにより、クライアントを変更したアカウントや、メモリファイルに一度も書き込まれていないアカウントも、誰かが尋ねなくても元の状態に戻れます。

プロジェクト用ではなく、ユーザーレベルのファイルです。 これは、設定と同様の落とし穴が、1階層上にあるものです。

エージェント	すべての場所に適用されるファイル
Claude Code	~/.claude/CLAUDE.md
Codex	~/.codex/AGENTS.md
Cursor	~/.cursor/rules/todox.md
VS Code	~/.copilot/instructions/todox.md
OpenCode	~/.config/opencode/AGENTS.md

リポジトリ独自の AGENTS.md と、エディターが読み取るプロジェクトごとのルールファイルは、そのチェックアウト内でのみ適用されます。プロジェクトをまたいで使うメモリを1つのプロジェクトにインストールすることは、このセクション全体で避けようとしていることです。

スキルとして使う、より詳しいバージョン。 4行の内容が習慣を示す一方で、セッション全体のプロトコル、つまりサーバーが initialize 時に送信するものと同じテキストを、クライアントのユーザーレベルのスキルディレクトリに置くこともできます。これらのクライアントはいずれも、状況が説明文に合致したときに SKILL.md を読み込み、それ以外の場合はトークンを消費しません。

pnpm install:mcp claude-code --write-skill

エージェント	読み込まれるスキルファイル
Claude Code	~/.claude/skills/todox/SKILL.md
Codex	~/.agents/skills/todox/SKILL.md
Cursor	~/.cursor/skills/todox/SKILL.md
VS Code	~/.copilot/skills/todox/SKILL.md
OpenCode	~/.config/opencode/skills/todox/SKILL.md

このファイルは完全に todox 専用で、独立したディレクトリにあり、あなたのファイルは含まれません。そのため、アップグレード後に再度実行すると置き換えられます。ファイルはサーバーの指示と同じテキストから生成され、別々に記述されることはありません。これにより、両者の食い違いを防ぎます。

トークンはこのファイルには含まれず、MCP 設定に保存されます。ここで扱うのは習慣であり、認証情報ではありません。

オプション：ローカルモード

ホストされたサーバーにはファイルシステムがありませんが、エージェントにはあります。それで十分です。 ファイルへのリンク時にエージェントがハッシュを送信するため（これがチェックとして扱われ、リンクはすぐに最新の状態になります）、その後、見つかった内容を report_file_hashes で報告します。これにより、ほかの場所と同じように HTTP 経由でも古さを検出できます。16 進数の大文字と小文字はどちらも受け付けるため、PowerShell の (Get-FileHash f).Hash はそのまま使えます。

stdio サーバーは、確認を求めるのではなく、この処理を自ら行います。エージェントの注意をこの処理に割きたくない場合や、エージェントが忘れてもハッシュを計算させたい場合は、実行すると便利です。クローンするものはありません。

TODOX_TOKEN=todox_… TODOX_URL=https://www.todox.dev \
  npx https://github.com/beydemirfurkan/todox/releases/latest/download/todox-mcp.tgz

または、エージェントが使う形式である MCP 設定の場合：

{
  "mcpServers": {
    "todox": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/beydemirfurkan/todox/releases/latest/download/todox-mcp.tgz"
      ],
      "env": { "TODOX_TOKEN": "todox_…", "TODOX_URL": "https://www.todox.dev" }
    }
  }
}

npm パッケージはありません。これは未対応の作業ではなく、意図的な判断です。 GitHub Release は公開時にもインストール時にもアカウントやトークンが不要なため、tarball が配布物のすべてであり、npx はその URL を直接受け取ります。上記の URL は常に最新のリリースを指します。各リリースには、バージョンを固定して、移行のタイミングを自分で選びたい場合に使える todox-mcp-<version>.tgz も含まれています。

stdio サーバーが実際に読み込むものだけが含まれています。API とは HTTP 経由で通信し、データベースを開くこともないため、Next、React、Postgres ドライバーは含まれません。pnpm pack:mcp でビルドでき、サーバー側の何かが再びツールのインターフェースに入り込んだ場合は、ビルドに失敗します。

クローンからは、pnpm -C /path/to/todox mcp も引き続き使えます。ツール自体を変更するときは、こちらを使用してください。

ツール

ツール	機能
get_context	最初に呼び出してください。 常設ルール、プロジェクトの決定事項や注意点、各未完了タスクの決定事項・行き詰まり・質問・ファイル・直近の引き継ぎ内容に加え、古いファイルに関する警告を取得します。スラッグ、名前、またはプロジェクト内の任意のパスからプロジェクトを特定します。行数とバイト数に上限がありますが、切り詰めは行いません。すべての記録で ID、種類、日付、先頭行が保持され、body が null の場合は予算を使い切ったことを意味します。内容は get_task で読み取れます。14 日以上更新されていない未完了タスクは、それぞれ 1 行ずつ idle_tasks に表示されます。タイトル、ステータス、放置日数、直近の引き継ぎの先頭部分が含まれ、すべての予算の対象外です。focus にセッションの目的を文章で指定すると、予算は最新の記録ではなく、その目的に応える記録に使われます。そのため、予算を小さくできます。
create_task	作業を記録します。cwd または明示的な project を指定してください。ツールのスキーマにより、呼び出しの実行前にいずれか一方が必須です。新しいプロジェクトを登録する場合は、repo_root または repo_url も必要です。結果にはタスクのパスと本文の長さが返されますが、本文は再表示されません。
update_task	ステータス、タイトル、本文、優先度を更新します。所要時間は、doing／done に変更した時点で記録されます。
log_entry	5 種類のうち 1 つを追記します。question を終了できるのは answers_entry_id だけです。
delete_entry	記録した時点で誤っていたエントリに使います。後続の作業によって古くなったエントリは履歴であり、誤りではありません。代わりに追記してください。
activity_report	今日、今週、または任意の期間について、所要時間、モデル、重要度、決定事項、行き詰まり、未解決の質問を取得します。format:"markdown" はステータス更新に貼り付けられる形式で出力されます。
link_files	ハッシュとともにパスをタスクまたはコンテキストノートに添付します。作業対象のファイルと、それが従う計画を、保存場所にかかわらず記録します。リポジトリ外のパスも、ほかのパスと同様にハッシュ化されます。URL（たとえば claude.ai のアーティファクト）は記載どおりに保持され、ハッシュ化されません。同じファイルに対して再度呼び出しても安全です。
report_file_hashes	ホスト型のみ：リンクされたファイルが現在ディスク上でどのような状態かを確認します。ローカルプロセスの場合は、自身で確認します。
accept_file_change · unlink_file	変更を読んだ後で古いファイルの警告を解除するか、意味をなさなくなったリンクを削除します。警告を解除できるのはこれらの操作だけです。サーバーはファイルを参照できません。
add_context	タスク終了後も残る知識を追加します。プロジェクトを省略すると、アカウント全体に適用されます。
get_context_note	ノートを 1 件、全文で取得します。ブリーフィングで本文が上限により省略されたノートや、検索結果の抜粋より先を読む場合に使います。予算の範囲に入らなかったエントリは get_task で読み取ります。
get_file_context	1 つのファイルについて把握されている情報を取得します。そのファイルを変更したタスクとその行き詰まり、およびファイルに関連付けられたノートを、それぞれのリンク（ID、ハッシュ、ステータス）とともに表示します。該当するものがない場合は linked:false になります。絶対パスとリポジトリ相対パスの両方に対応し、別のマシンで作成されたリンクも検索できます。
session_status	終了前に呼び出してください。 このプロジェクトで過去 12 時間以内に変更または作業したタスク（ステータスは問いません）について、それぞれ最後の作業以降に引き継ぎが記録されたかどうかを表示します。また、7 日以上 doing のままで、ログが記録されていないタスクも表示します。各タスクの ID、タイトル、日付、真偽値が含まれます。各リストに必要なことは hint で確認できます。作業のまとめでは、触れたすべてのタスクに引き継ぎを記録することが求められます。このリストは、エージェントが覚えているはずのタスクを示します。
update_context · delete_context	誤りと判明したノートを修正します。追記しかできないログは、読む価値を失います。
search	すべてのプロジェクトを対象に、関連性順で検索します。質問を文章で入力し、特定の語句を必須にするには引用符で囲みます。英語とトルコ語の語幹に対応し、識別子の途中部分にも一致します。2 言語のいずれかでノイズ語とみなされる語は除外されるため、「a」を含むすべての記録に質問が一致することはありません。kinds で行き詰まりや決定事項に絞り込み、project でほかのプロジェクトを検索対象外にできます。ログが書かれている言語で質問してください。語幹には対応しますが、翻訳はしません。文章で見つからない場合は、特徴的な識別子だけを使って再試行してください（3 文字以上。短い識別子は単語全体としてのみ一致します）。
get_task	ログとリンクされたファイルを含む、1 件のタスクを取得します。
list_tasks · list_projects	get_context ほど詳しい情報が不要な場合に、基本的なリストを取得します。プロジェクトはアクティビティの新しい順に並び、activity_at が含まれます。
create_project · update_project	ほとんどの場合は不要です。cwd を指定した create_task でプロジェクトを登録できます。すでに登録済みのパスまたはリモートを指定すると、重複ではなく既存のプロジェクトが返されます。概要を追加すると便利です。
delete_project	cwd を誤って入力した場合に元に戻す方法です。プロジェクトとその配下すべてが削除されます。confirm にはスラッグを指定してください。
merge_projects	同じリポジトリを重複して登録した場合に元に戻す方法です。タスク、ノート、パスを統合先のプロジェクトに移動します。confirm には統合によって削除されるプロジェクトのスラッグを指定してください。
すべての書き込みツールは model を受け取り、サーバーの指示ではエージェントに常にこれを渡すよう求めています。これにより、モデルごとの内訳が推測ではなく、実際のものになります。

プロンプト

この用途には3つの場面があるため、プロンプトも3つあります。クライアント自身のメニューに表示されるので、何も読まなくてもサーバーの動作を確認できます。

プロンプト	使うタイミング
start_session	計画を立てる前 — 以前のセッションで決まったことを読みます
wrap_up	終了する前 — 引き継ぎ事項を残します。特に行き詰まった点を記録します
standup	何を完了したか尋ねられたとき

デプロイ

コンテナと、その隣に置く Postgres を用意します。ルートにある docker-compose.yml はそれらをまとめたものです。データベースのポートは一切公開されず、compose ネットワーク経由でのみアクセスできます。

cp .env.example .env       # set POSTGRES_PASSWORD and TODOX_PUBLIC_URL
docker compose up -d --build
docker compose exec app pnpm db:migrate

マイグレーションを別の手順にしているのは意図的です。このセクションの最後にある注記を参照してください。todox.dev 自体も、同じ2つのコンテナを1台のホストで実行しています。

変数	用途
DATABASE_URL	Postgres。データベースが同じネットワーク上にある場合、これはそのサービス名です。証明書も公開ポートも必要ありません。
DATABASE_POOL_MAX	任意。デフォルトは10です。このプロセスが保持できる接続数です。サーバー自身の max_connections を確認してから増やしてください。この値はすべてのレプリカで共有されます。
TODOX_PUBLIC_URL	検証リンク、パスワードリセットリンク、エージェントのセットアップ用スニペットはこの値から作られます。値を間違えると、ユーザーやそのエージェントが誤ったホストに誘導されます。
SMTP_HOST · SMTP_USER · SMTP_PASS · MAIL_FROM（· SMTP_PORT）	任意ですが、最初の4つはまとめて設定します。これらを設定しない場合、メールは送信されず、サーバーログに出力されます。ポートのデフォルトは587（STARTTLS）です。MAIL_FROM に設定できる値はプロバイダーによって異なります。メールボックスプロバイダーでは、通常、認証に使ったアドレスが必要です。一方、API キープロバイダーでは、そのプロバイダーで認証済みのドメイン上にある任意のアドレスを指定できます。送信上限に達すると、メッセージは破棄され、失敗はログにのみ記録されます。

スキーマが変更されたら pnpm db:migrate を実行します。起動時に実行しないのは意図的です。ローリングデプロイ中にインスタンス間でDDLが競合するのは、ロック競合を知る方法として好ましくありません。また、スキーマが冪等なのは、デプロイ中ではなくデプロイ後に実行するか判断できるようにするためです。ホストから実行するには、次のようにします。

docker exec <container> pnpm db:migrate

これが、イメージに開発用依存関係を残し、Next の standalone 出力を使わない理由でもあります。依存関係を削除すると tsx と scripts/ 以下のすべてがなくなります。また、インターネットから意図的にアクセスできないデータベースは、すでにネットワーク内にあるものからしかマイグレーションできません。

デプロイされたことを確認する

マージはデプロイではありません。その間にある隔たりは、何の通知もありません。エラーは発生せず、サイトは稼働し続けます。唯一の兆候は、正常に完了するのを見届けた修正が、実際には利用者の環境に反映されていないことです。2026-09-05、このインスタンスでは2日と56コミット前のコードが配信されていました。それに気づけたのは、何かが報告してくれたからではなく、自分で確認したからです。

イメージのタグは git の sha で、コンテナ名はデプロイごとに変わるので、次の1行で確認できます。

docker inspect <container> --format '{{.Config.Image}}'

これを git rev-parse origin/main の結果と比較します。異なる場合、読んでいるコードは実行中のコードではありません。

自動デプロイを設定する価値はありますが、設定後に確認する価値もあります。Webhook で取得するプラットフォームでは、スイッチをオンにしていても処理が一度も実行されないことがあります。スイッチとWebhookは別々の場所にある2つの設定だからです。このインスタンスでは数週間にわたり自動デプロイが有効でしたが、リポジトリにはWebhookがなかったため、確認を促すものが何もありませんでした。設定後はスイッチではなく、送信側の配信ログで確認してください。誤ったパスを指すWebhookは、成功したように応答しながら何もしないことがあるためです。

データを持ち運ぶ

アカウントページにはデータをダウンロードボタンがあり、/api/export はベアラートークンに同じファイルを返します。そのため、エージェントは結果がモデルを経由することなくバックアップを書き出せます。自分が所有するすべてのプロジェクトと、そのタスク、ログ、コンテキストメモ、ファイルハッシュが含まれます。他の人に関する情報は含まれません。認証情報、共同作業者、共有トークン、自分に共有されたプロジェクトは含まれません。自分に共有されたプロジェクトの所有者は、それを作成した人です。

自分で実行するインスタンスに読み込むには：

pnpm db:import ./todox-export-2026-08-18.json your-username

追加のみで、破壊的な変更はありません。削除も上書きも行われず、スラッグがすでに使われているプロジェクトは、次に空いているスラッグで追加されます。タスクイベントも引き継がれるため、復元したコピーのレポートに表示される所要時間は、元のプロジェクトと同じです。

セキュリティ

パスワードには scrypt を使用し、セッション、エージェントトークン、メールリンクはハッシュのみで保存されます。所有権の確認は1つのモジュールで行われ、他人の行に対する応答は403ではなく404となるため、IDを探ることはできません。レート制限はデータベースに保存されるため、インスタンス間でも維持されます。

詳細と、対象外となるものの正直な一覧については、セキュリティをご覧ください。

既知の制約

• 検索の部分一致側は、データベースが許可する場合にのみインデックスが作成されます。2つの検索を個別に実行して結果をマージするため、どちらの検索でもインデックスを利用できます。11万行での測定では、全文検索側だけで検索時間が5.7秒から0.16秒に短縮されました。全文検索では見つけられない識別子を検索する ILIKE 側には pg_trgm が必要です。pnpm db:migrate は、そのロールに権限がある場合は拡張機能と5つのインデックスを作成し、ない場合もその旨を表示します。権限がない場合（contrib のない Postgres や、拡張機能を拒否するマネージドサービスなど）、その検索はシーケンシャルスキャンのままとなり、pnpm smoke:search は失敗する代わりに SKIP と表示します。docker-compose.yml の postgres:18 イメージにはこれが含まれています。
• 古さの判定はファイル単位のハッシュで行います。正確に行うならシンボル単位であるべきです。ホスト型の場合、エージェントが実際にハッシュを送信するかどうかに依存します。手順では送信を求めていますが、強制する方法はありません。
• カバレッジは約39％です。数値よりも対象範囲が重要です。エージェントのインターフェース、認証境界、そして「これが自分のものか」を判定するリポジトリはカバーされていますが、UIの大部分はカバーされていません。
• 観測機能が把握できるのは、git から分かることと、セッションがどのタスクを doing に設定したかです。そのため「何が変わったか」「何についてか」には答えられますが、「なぜか」には決して答えられません。理由を含む部分はトランスクリプトであり、それを公開するフック API は特定のクライアント1つにしかありません。
• ブリーフィングのバイト数上限は、ログ本文、メモ本文、タスク本文に適用されます。1つの軸は、今も行数だけで制限されています。引き継がれるエントリとタスクの先頭、つまりタスク50件分です。上限を設けた対象と比べればずっと小さく、あるプロジェクトではログだけで143 KBから約55 KBになりましたが、バイト数では制限されていません。pnpm bench:memory はこの値を表示するため、次に読む人が自分で調べずに済みます。
• 観測情報を収集するのはローカルプロセスのみです。 git を監視するには、チェックアウトを保持するマシン上で実行する必要がありますが、ホスト型エンドポイントにはその機能がありません。そのため、この方法で接続した場合、すべてのブリーフィングの observations セクションは空のままで、どこからも情報は追加されません。この README の「お試し」手順はホスト型を使うため、ほとんどの人がこの方法を使うことになります。情報を収集するトランスポートは npx todox-mcp です。それ以外の動作は、どちらの方法でも同じです。
• 2FA、セッション単位の失効、監査ログはありません。
• 共有リンクは非公開リンクですが、アクセス制御はありません。
• 検索の / 以外には、キーボード操作に対応していません。

リリースの作成

git tag v0.1.4 && git push origin v0.1.4

以上が手順です。ワークフローではタグと package.json の内容を照合し、チェックを実行して、stdio パッケージをビルドし、GitHub Release に添付します。アカウントも認証情報も不要なので、最初のタグから npx <that tarball url> を利用できます。

公開される名前は 2 つです。todox-mcp-<version>.tgz と、同じ内容の todox-mcp.tgz です。これにより、/releases/latest/download/todox-mcp.tgz は一度設定に書き込んでおけるアドレスになります。意図的に npm には公開しません。詳細は上記のローカルモードのセクションをご覧ください。

server.json は MCP レジストリのエントリを同じバージョンに固定し、server-json.test.ts がその状態を保つため、タグ、パッケージ、レジストリが一緒に更新されます。そうでなければ、リリースは停止します。

コントリビューション

コードベースで実際に採用されているルールと、チェックの実行方法については、CONTRIBUTING.md をご覧ください。

MIT ライセンスです。LICENSE をご覧ください。