Todox
io.github.beydemirfurkan由 GitHub 账号 beydemirfurkan 发布v0.1.4更新于 Oct 24, 2026
Memory for coding agents: the decisions, the dead ends, and where the last session stopped.
概览
Todox 是面向编码智能体的托管记忆日志：保存任务及其决策、死路、待答问题与交接记录，让新会话能从上次停下的地方继续。
- 可以做什么
- 读取会话简报：常驻规则、项目决策、未完成任务及其决策、死路、问题、关联文件与上次交接，并附文件过期警告
- 创建和更新任务，追加五类日志条目（决策、死路、问题、交接、备注），并可用回答关闭一个问题
- 为文件关联哈希、上报当前哈希、确认变更或取消关联，并按路径查询已知信息
- 新增、读取、修正和删除可跨任务保留的上下文笔记
- 跨项目按相关度搜索，可按类型或项目筛选
- 生成当天、本周或任意时间段的活跃报告，并在收尾前列出本次会话改动过的任务
- 适用场景
- 适合工作跨多个会话、多台机器或多个智能体进行，希望把推理过程、失败尝试和收尾状态延续下去而不是重新摸索的场景。尤其适合仓库开发，让新智能体从上次交接处开始。
- 运行要求
- 远程 MCP 端点，无需安装。需要托管服务账号，并在账户页面创建智能体令牌，通过 Authorization 的 bearer 头发送。也可选用经 npx 运行的本地 stdio 版本，需设置 TODOX_TOKEN 与 TODOX_URL；或自托管，需 Postgres 15 及以上。
安装
在 SourceWeft 中
- 打开 控制台中的 Todox，将其添加到工作区。
- 连接 Authorization token 凭据。它们会被私密存储，绝不会在公开页面上展示。
- 为需要使用其工具的对话启用该服务。
Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。
交给智能体安装
把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体，或 SourceWeft 对话中。智能体会读取该服务器的安装指南，先向你展示发布者、端点和登录方式，经你同意后再把它添加到你的客户端。密钥不会写进任何命令。
阅读 https://sourceweft.com/mcp/io.github.beydemirfurkan%2Ftodox/install.md，并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前，先告诉我它的发布者、端点和登录方式，等我确认。不要把 API 密钥写进命令或我会提交的文件；问我密钥应从哪里获取。其他 MCP 客户端
把它添加到你客户端的 mcpServers 配置中。
{
"mcpServers": {
"todox": {
"type": "http",
"url": "https://www.todox.dev/api/mcp",
"headers": {
"Authorization": "Bearer <YOUR_TOKEN>"
}
}
}
}README
todox
Working memory for developers and their agents. Not a checklist — a log your next session can actually resume from.
An issue tracker is written human-to-human. todox is written agent-to-agent, with a human reading over its shoulder. Every task carries the decisions behind it, the approaches that failed, the questions still open, and the note the last session left behind.
A fresh agent calls get_context, reads that, and starts where the last one
stopped — without walking into a wall somebody already hit. The briefing is
capped rather than unbounded, in rows and in bytes, and it reports what the
caps left out instead of trimming in silence. Nothing is ever cut mid-sentence:
every record comes back named and dated with its first line, and a body of
null means the budget was spent, not that the record is empty.
[A task in todox: its status, and a log of a decision, a dead end and a handoff, newest last]
How it works
[The agent on your machine talks MCP to todox: it reads a briefing with get_context, writes tasks and log entries while it works, and sends the sha256 of the files it links, because the server has no copy of your code. You read the same log in the browser.]Your agent does the writing; you read over its shoulder. One log per repository, whichever machine or agent touched it last:
What goes in a log
Two things fall out of treating the log as the product:
- Stale context is flagged, and never faked. Linked files are hashed by the
side that can see them — the agent — and the server stores the hashes and
compares. If the code moves on,
get_contextsays the note may be lying. Until an agent has actually looked, the note is marked as never checked rather than claimed to be fresh: context that lies is worse than none, and that includes lying about how sure we are. - Reports come from the log, not from commits. Every status change is an
event, so what did I finish today, how long did it take, which model did it
is a query rather than archaeology. A task set
doingand walked away from counts as the morning it was set, not the weeks since -- and the report says how much it left out, rather than folding it into the headline. - A file can be asked what is known about it. The same links that carry the
hashes are readable from the other end:
get_file_contexttakes a path and answers with the tasks that touched it, their dead ends, and any standing note attached to it. Paths are folded to their repo-relative form, so a link made on one machine is found from another.
Why not the memory your agent already has?
Claude Code writes its own notes now (auto memory, on by default since February 2026), and Cursor and Codex have theirs. Use them: they are good at remembering that you prefer pnpm. What their documentation says, in its own words, is that they are per repository, per machine ("machine-local … not shared across machines") and per tool, and shared with nobody ("just you"). todox is for what falls outside that line:
- Two machines, one log. A repository is identified by its remote, so the note left on the laptop is read on the desktop.
- Every agent, one log. Claude Code, Codex, Cursor and VS Code all speak MCP; the handoff one leaves is what the next one reads, whichever it is.
- The people, too. A project can be shared, and the log carries who wrote what and which model did it.
- A shape a note in a file does not have. Tasks that open and close, dead ends as their own kind, a report read from the log, a stale note that says so — and a briefing that reports what its caps left out.
Beside other memory servers
Compared with what each project's own README says (read 2026-10-16). Where a README does not describe something, the cell says so rather than guessing.
They solve different problems. A knowledge graph or a notes vault is a good place for what is true about a person or a domain; todox is for the state of work in a repository, and for not repeating what already failed there.
Try it
todox.dev — anyone can register. Small personal deployment, no uptime promise. Self-host if the log matters to you.
Run your own
Connect an agent
todox is a remote MCP server. There is nothing to install and no repository to clone: point any MCP client at the URL with an agent token.
Create a token on the Account page and it hands you text you can paste straight into whichever agent you use, plus the config snippet for the four common ones. The shape is always the same — one URL, one header:
Claude Code has a shorter path. The plugin carries the server, the session protocol as a skill, and one reminder at session start; it asks for the token once and keeps it in your Claude Code settings:
Everything else below still applies to it — the plugin is the same four lines,
installed rather than pasted. See plugin/README.md for
what it does and does not do.
The MCP config key and the
typevalue differ per agent, and the wrong combination is silently ignored — no error, no warning, the tool just does not show up:
Where those files live differs by platform, and VS Code is the one that is not where a Linux habit puts it:
Install it globally, not per project. Every one of these tools defaults to
the directory you are standing in — claude mcp add without a scope,
.cursor/mcp.json, .vscode/mcp.json — and a memory that only exists in one
repository is the opposite of the point. It also fails quietly: the tools
simply are not there in the next project, so the agent never mentions them.
Spell out "type": "http". A client that finds a url without one tends to
assume a local command and fails with something unhelpful.
Then tell your agent to use it
Connecting is not the same as being used, and the gap is bigger than it looks.
An MCP server's instructions are background reading; a skill or a CLAUDE.md
rule is an instruction. When they disagree, the server loses — measured, in a
fresh project, with todox connected the whole time and never once called.
So put four lines in the memory file your agent actually obeys:
Or let the installer do it:
It is off unless asked, because that file is yours rather than ours, and it is
idempotent — the block is fenced with an HTML comment, so a second run replaces
it instead of leaving two sets of instructions where the older one wins. Add
--dry-run to see the exact block first.
When the tools do not show up at all, the silent failure is usually one of the two tables above, and there is a command that reads the files the way each client does and says which:
Per client: the entry, its type, its root key, a leftover in a location the
client never reads, whether the memory file carries the habit, and whether the
server answers the token it found (masked in the output). It also names a
todox entry sitting in the current checkout's own config for what it is.
Nothing is changed; docs/mcp.md has the detail.
If you skip this and the account then connects for days without calling a
tool, the server says so at the top of its instructions on the next session —
"connected for N days and has not called a tool" — and hands the agent the
four lines and the path of your client's memory file, telling it to append
them and to tell you it did. Measured from tool_usage, so it is said only
while it is true and stops the moment a tool is called. That is how an account
whose client changed, or whose memory file was never written, comes back
without anybody having to ask.
The user-level file, not the project one. This is the same trap as the config above, one directory over:
A repository's own AGENTS.md, and the per-project rules files the editors also
read, apply inside that checkout only. A cross-project memory installed into one
project is the thing this whole section exists to avoid.
The longer version, as a skill. The four lines are the habit; the whole
session protocol — the same text the server sends at initialize — can also
sit in the client's user-level skills directory, where every one of these
clients loads a SKILL.md by its description when the moment matches, and
spends nothing on it otherwise:
The file is wholly todox's — a directory of its own, nothing of yours inside — so a second run after an upgrade replaces it. It is generated from the same text as the server instructions rather than written twice, which is what keeps the two from disagreeing.
The token stays out of that file — it lives in your MCP config. This is the habit, not the credential.
Optional: local mode
The hosted server has no filesystem — but your agent does, and that is enough:
it sends the hash when it links a file (which counts as a check, so the link
reads fresh at once) and calls report_file_hashes with what it finds
afterwards, so staleness works over HTTP like anywhere else. Either hex case is
accepted, so PowerShell's (Get-FileHash f).Hash works as it is.
The stdio server does that part itself rather than asking. Worth running if you would rather not spend an agent's attention on it, or want the hashing to happen even when the agent forgets. There is nothing to clone:
Or as an MCP config, which is the form an agent wants:
There is no npm package, and that is a decision rather than a to-do. A
GitHub Release needs no account and no token to publish or to install from, so
the tarball is the whole distribution and npx takes its URL directly. The URL
above always resolves to the newest release; every release also carries a
todox-mcp-<version>.tgz if you would rather pin and choose when to move.
It carries only what the stdio server actually loads — no Next, no React, no
Postgres driver, because it talks to the API over HTTP and never opens a
database. pnpm pack:mcp builds it, and fails the build if anything
server-side ever finds its way into the tool surface again.
From a clone, pnpm -C /path/to/todox mcp still works and is what to use when
you are changing the tools themselves.
Tools
Every write tool takes a model, and the server instructions tell the agent to
always pass it. That is what makes the per-model breakdown real rather than
guessed.
Prompts
Three, because there are three moments this is for. They show up in your client's own menu, so you can see what the server does without reading anything:
Deploying
A container and a Postgres beside it. docker-compose.yml at the root is that,
assembled — the database publishes no port at all and is reachable only over
the compose network:
The migration is a separate line on purpose; see the note at the end of this section. todox.dev itself runs the same two containers on one host.
Run pnpm db:migrate when the schema changes. It deliberately does not run at
startup: DDL racing between instances of a rolling deploy is a bad way to
discover lock contention, and the schema is idempotent precisely so the decision
can be made after a deploy rather than during one. From the host:
That is also why the image keeps its dev dependencies instead of using Next's
standalone output — pruning them removes tsx and everything under
scripts/, and a database that is deliberately unreachable from the internet
can only be migrated from something already inside the network.
Knowing it actually deployed
A merge is not a deploy, and the gap between them is silent: nothing errors, the site stays up, and the only symptom is that a fix you watched go green is not the one people are running. On 2026-09-05 this instance served code two days and fifty-six commits old, and the thing that made it visible was looking rather than anything reporting it.
The image tag is the git sha and the container name changes on every deploy, so one line answers it:
Compare that against git rev-parse origin/main. If they differ, the code you
are reading is not the code that is running.
Automatic deploys are worth wiring up, and worth checking after you do. A platform that pulls on a webhook can have the switch on and still never fire, because the switch and the webhook are two settings in two places: this instance had auto-deploy enabled for weeks while the repository had no webhook at all, so nothing was ever told to look. After wiring one, confirm from the sending side — the delivery log — rather than from the switch, because a webhook pointed at the wrong path answers cheerfully and does nothing.
Taking your data with you
The Account page has a Download my data button, and /api/export answers
the same file to a bearer token — so an agent can write the backup without the
result passing through a model. It carries every project you own with its
tasks, log, context notes and file hashes, and nothing about anybody else: no
credential, no collaborator, no share token, and no projects that were shared
with you, which belong to whoever made them.
Loading one into an instance you run:
Additive, never destructive: nothing is deleted or overwritten, and a project whose slug is taken arrives under the next free one. Task events come across too, so durations in a report on the restored copy say what they said on the original.
Security
Passwords are scrypt; sessions, agent tokens and email links are stored as hashes only. Ownership is enforced in one module, and a row belonging to someone else answers 404 rather than 403 so ids cannot be probed. Rate limits live in the database, so they hold across instances.
Details, and an honest list of what is not covered, in SECURITY.md.
Known gaps
- Search's substring half is indexed only where the database allows it. The
two halves are asked separately and merged, which is what lets either use an
index at all — measured on 110k rows, a search went from 5.7s to 0.16s on the
full-text arm alone. The
ILIKEarm that finds identifiers full-text cannot needspg_trgm;pnpm db:migratecreates the extension and its five indexes where the role may, and says so either way. Where it may not — a Postgres without contrib, a managed service that refuses extensions — that arm stays a sequential scan andpnpm smoke:searchprintsSKIPfor it rather than failing. Thepostgres:18image indocker-compose.ymlhas it. - Staleness is per-file hash; per-symbol would be the honest version. Hosted, it depends on the agent actually sending hashes — the instructions ask, and nothing can make it.
- Coverage sits around 39%, and the shape matters more than the number: the agent surface, the auth boundary and the repositories that answer "is this yours" are covered, while much of the UI is not.
- Observations see what git can tell them and which task a session set to
doing, so they answer "what changed" and "on what" — and never "why". The half that carries reasoning is a transcript, and the only hook API that exposes one belongs to a single client. - The briefing's byte budget covers log bodies, note bodies and task bodies.
One axis is still bounded only by a row count: the heads of carried
entries and tasks, fifty tasks' worth. It is far smaller than what the
budgets fixed — one project went from 143 KB to about 55 KB on the log
alone — but it is not bounded in bytes, and
pnpm bench:memoryprints it so the next reader does not have to discover it. - Observations are captured by the local process only. Watching git means
running on the machine that holds the checkout, and the hosted endpoint has
none — so connected that way, the
observationssection of every briefing stays empty and nothing anywhere fills it. The Try-it path in this README is the hosted one, so that is most people.npx todox-mcpis the transport that captures. Everything else works identically either way. - No 2FA, no per-session revocation, no audit log.
- Share links are unlisted, not access-controlled.
- No keyboard navigation beyond
/for search.
Cutting a release
That is the procedure. The workflow checks the tag against package.json,
runs the checks, builds the stdio package and attaches it to a GitHub Release —
no account and no credential involved, so npx <that tarball url> works from
the first tag.
Two names go up: todox-mcp-<version>.tgz, and the same bytes as
todox-mcp.tgz so that /releases/latest/download/todox-mcp.tgz is an address
worth writing into a config once. Nothing is published to npm, on purpose — see
the local-mode section above.
server.json pins the MCP registry entry to the same version and
server-json.test.ts holds it there, so the tag, the package and the registry
move together or the release stops.
Contributing
The rules the codebase actually follows, and how to run the checks: CONTRIBUTING.md.
MIT — see LICENSE.
来源：README.md，提交 0d771c8
工具
0版本历史
2- v0.1.4最新Sep 19, 2026
- v0.1.1Sep 16, 2026
评分
已满足适用检查项的 85%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
- 近 30 天内可连通必需25 分
- 已声明认证方式必需10 分
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分