Redthread: Portable, Git-Backed Memory for AI Coding Agents

Most coding agents keep their memory in a local folder, for example .claude/, .cursor/ or .agent/. When you move to a different machine, the agent does not have that memory. The context about your project stays on the first machine.

Redthread is a small tool that solves this problem. It keeps agent memory in a git repo, not in a local folder. It makes the memory available over MCP. Each machine that clones the store gets the same memory. This post shows how to install Redthread, connect it to an agent and use it.

Install¶

pip install redthread          # or: uv tool install redthread

The procedures in this post need redthread 0.6 or newer. Version 0.6 changed the agent tools, and some tool signatures are different.

Create a store¶

A store is a git repo with a phase pipeline. The pipeline is an ordered list of phase names. You can use the names that apply to your project, for example build,test,present or train,eval,present:

redthread init my-project --phases build,test,present --store ./my-store

Connect your agent¶

For Claude Code, use this command:

claude mcp add redthread -- uvx redthread mcp-serve --store ./my-store

uvx downloads Redthread from PyPI the first time that it starts. Thus, this command works without the install step. If Redthread is already installed, remove uvx:

claude mcp add redthread -- redthread mcp-serve --store ./my-store

To make sure that the connection is correct, do these steps:

1. In Claude Code, type /mcp.
2. Make sure that redthread shows as connected with 17 tools.
3. Tell the agent to call context_bootstrap.

NOTE: Claude Code reads MCP servers only when a session starts. If you add the server during a session, restart Claude Code.

Cursor uses an install deeplink, not a CLI command. VS Code uses code --add-mcp. The per-client reference gives the procedures for Cursor, VS Code, Windsurf, Claude Desktop, Codex CLI, Gemini CLI and the Claude Agent SDK.

Make the agent use the memory¶

This step is important, and it is easy to forget. When you register the MCP server, the agent can use the memory. But no instruction tells the agent to use the memory tools. In tests, agents frequently did not use them for a full session.

Redthread solves this problem in two ways.

1. One tool that gives all the context. An agent that starts without context must find the runs, the memory namespaces and their contents. This needs many tool calls, and agents frequently stop before they get useful data. Thus, one tool gives all of this data at the same time:

redthread bootstrap --store ./my-store

This command shows the same data that the agent gets from context_bootstrap:

• The phase pipeline.
• The recent runs and their status.
• The published handoffs.
• An index of all memory entries, with a one-line description for each.

The response also has a _next field. This field tells the agent what to do next. For example, it tells the agent to read some entries, to start a run or to write a session summary before it stops. After one call, the agent knows the condition of the store.

2. A note in AGENTS.md or CLAUDE.md. Most agents read this file first. Redthread can write the note. Tell the agent to call agents_md_bootstrap. This tool adds a short usage policy to the file in your project. The tool is idempotent, thus you can call it in each session.

CAUTION: Subagents do not get the instructions of the main agent, and they do not read AGENTS.md. A subagent does not use the memory and does not tell you. Thus, the tool descriptions and the tool responses also have the usage instructions. This is the only channel that gets to all agents in all clients. If you give a subagent a task with important results, tell it to call context_bootstrap.

Make the store portable¶

The store is now a local git repo. To use it on other machines, add a remote and sync:

git -C ./my-store remote add origin git@github.com:you/my-store.git
redthread sync --store ./my-store

sync does a commit, a pull --rebase and a push in one operation. Each machine that clones the store gets the same memory. To do the commits automatically, use the auto-commit daemon (redthread daemon run).

You can also keep the store in a repo that you already have. Redthread puts the store on an orphan branch of that repo, as a git worktree. It does not change the checked-out branch of the repo:

redthread init my-project --phases build,test,present \
  --store ./my-store --worktree-repo .

This command writes a small .redthread.yaml file in the host repo. Commit this file. On the next machine, clone your code repo and register the same MCP command. You do not need flags, and you do not need to clone the store manually.

Use the CLI¶

The store also records multi-phase runs. This is also useful without an agent, for example in a pipeline where the results of one phase go to the next phase. This is a full example:

# a run is one attempt through your declared phases
run_id=$(redthread run start --store ./my-store)

# append immutable context entries as a phase works
redthread log "$run_id" build note '{"msg": "kicked off build"}' --store ./my-store

# publish the build phase's curated handoff for the next phase
echo '{"headline": "build ok", "key_results": {"warnings": 0}}' > handoff.json
redthread handoff publish "$run_id" build handoff.json --store ./my-store

# the test phase reads only the handoff — never build's raw log
redthread handoff get "$run_id" build --store ./my-store

# full raw history, one JSON entry per line
redthread read "$run_id" --store ./my-store

The handoffs and the raw log are different on purpose. You can only add entries to the log, and you cannot change them. Thus, the raw log becomes larger at each step. The next phase reads the short handoff, not the full log. Thus, the context window does not fill with unnecessary data from the previous phase.

On the MCP side, run_id is optional for all tools that use a run. If you do not give it, the tool uses the newest active run in the store. The response shows the run id that the tool used. Thus, an agent cannot write to the incorrect run without a record. If many runs are active on different machines, give the run_id.

Long-term memory¶

Long-term memory is separate from runs, because most important data does not apply to only one run. Each entry has a one-line description in YAML frontmatter:

redthread memory write notes toolchain.md ./note.md \
  --description "Why this project uses uv, not conda" \
  --tags toolchain --store ./my-store

redthread memory list --store ./my-store

The list shows the descriptions, not only the filenames. Thus, an agent can find the important entries before it opens them. If an entry has no description, the list shows its first line with content. Thus, old stores also show correctly.

To find a specific entry, use search. Search looks in keys, descriptions, tags and bodies. It shows the line that matches:

redthread memory search uv --store ./my-store

The same data is also available as MCP resources, for example redthread://bootstrap, redthread://memory and redthread://handoff/{run_id}/{phase}. Some clients can attach this context directly, without a tool call.

Warning¶

WARNING: Do not write secrets to the store. The store is a git repo, and usually you push it to a shared remote. Git keeps all memory entries in its history. All persons with access to the repo can see them.

Links¶

• Repo: github.com/sina5/redthread
• Docs: sina5.github.io/redthread
• Quickstart · Full usage reference · Architecture

Redthread has an MIT license. It works on Windows, Linux and macOS (Python 3.11+). Issues and PRs are welcome.