Todox

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.

How it works

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_context says 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 doing and 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_context takes 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](https://www.todox.dev) — anyone can register. Small personal deployment, no uptime promise. Self-host if the log matters to you.

Run your own

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

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:

claude plugin marketplace add beydemirfurkan/todox

claude plugin install todox@todox

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.

# 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_…" } } } }

**The MCP config key and the type value differ per agent, and the

wrong combination is silently ignored — no error, no warning, the tool

just does not show up:**

| agent | key | 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 |

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:

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.

Or let the installer do it: