research-git

A new Git tool for ambitious researchers and developers in the agentic era.
Works with Claude Code, Codex, Gemini CLI, and opencode.

Git remembers commits. research-git remembers ideas.

research-git turns experiments and features into reusable Feature Capsules so coding agents can reapply, adapt, or remove them safely as your code evolves.

Not a rollback. Not hard deletion. Bring back the idea, not the old branch.

How it works

One loop: capture each idea into a graph, then regenerate it onto today's code. The engine (blue) is free and deterministic; intelligence happens at exactly two points (green) — subagents dispatched onto your existing subscription, never a paid API.

flowchart LR
    A["edit code /<br/>rgit run -- ..."] -->|"free, deterministic"| B["raw proposal<br/>(diff staged)"]
    B -->|"/rgit-capture"| C{{"capsule-<br/>segmenter"}}
    C --> D[("Feature Capsule<br/>graph (.rgit/)")]
    D -->|"/rgit-recall «query»"| E["compose brief vs<br/>today's code"]
    E --> F{{"capsule-<br/>regenerator"}}
    F --> G["reviewable diff<br/>on today's code"]
    G -.->|"rgit run — freeze + link variant"| D

    classDef engine fill:#eef2ff,stroke:#5b6cff,color:#1e2a78;
    classDef agent fill:#eafff0,stroke:#36a85f,color:#0f5132;
    class A,B,D,E,G engine;
    class C,F agent;

The Feature Capsule

Every idea you keep becomes one capsule — a self-contained unit a future agent can read and bring back:

Capsules live in a small graph beside your repo (.rgit/), on top of normal git. Every run you launch through research-git also freezes a byte-exact, content-addressed snapshot of the code that ran — so "the code behind this result" is always a perfect replay, never at the mercy of an agent.

🚀 Quick Start

1. Install

pip install research-git
rgit install        # wires research-git into every agent client on this machine
cd your-project
rgit init           # creates the .rgit/ store in your repo

That's the whole setup. Start a new agent session afterwards so it picks everything up.

Adopting rgit on a repo that already has history? rgit init offers to digest that history into capsules — pick a mode in the prompt, then let your agent run the rgit-digest skill so recall has something to find from day one.

2. Working with an agent? Just talk to it

After install your agent does the remembering. Work as usual — it saves each meaningful idea as a Feature Capsule (asking you before anything is kept). Weeks later, when the code has moved on, just ask:

"bring back the re-ranking retrieval step"

The agent finds the capsule and re-implements the idea onto today's code, leaving you a reviewable diff. No commands to memorize — but if you like being explicit, /rgit-capture saves recent work and /rgit-recall <what you want back> brings an idea home.

3. Working in the terminal? Three commands

rgit run -- python eval_agent.py --retrieval rerank   # run an experiment; freezes a byte-exact snapshot + metrics
rgit review                                           # see what's been captured, approve what's worth keeping
rgit compare rerank                                   # which variant won?

rgit capture saves the current changes (or the last commit) when you're not using rgit run. Bringing an idea back needs an agent session — that's where the intelligence lives; from the terminal you can always browse the memory with rgit features and rgit graph.

More commands as your store grows: More commands.

Updating

rgit update

Upgrades the package (via whichever of uv/pipx/pip installed it) and refreshes every installed platform surface: the Claude Code plugin copy, MCP config, and the managed guidance blocks. Guidance blocks you have customized or removed are left alone — the command tells you how to restore them instead.

rgit checks PyPI for a newer release at most once a day (in the background, terminal sessions only). Once one is found, it prints a one-line upgrade notice after every qualifying command until you upgrade or turn the notice off — the check is throttled, the reminder is not. Silence it for good with rgit update --off, or per-environment with RGIT_UPDATE_CHECK=0.

🧩 Where it fits

Anywhere you try many variations of one thing and later want a single one back — cleanly, on top of how the code looks now.

• 🤖 Agent / Prompt engineering — you tried four prompt structures, two tool-splitting schemes, and a different retrieval step. Last week's version scored better; bring that idea back onto the agent you've since rewritten.
• ⚙️ Backend / Systems — three caching strategies, two rate-limiters, a reworked query plan. Which won? Pull the winning variant forward without reverting everything built since.
• 🎨 Frontend — competing interaction flows and layout variants, half commented out. Resurrect the one that tested best onto the current component tree.

Also at home in ML research — different loss terms, attention blocks, augmentations. Same shape: the experiment is the idea, the metrics are the result, and you want one variant back on today's code.

🤝 Share the memory with your team

The graph is served over MCP read-only (recall / compose / get, plus the query commands compare / ablation / provenance). Point a teammate's client at your rgit mcp server and they get the same Feature Capsules and the same answers — then their session regenerates an idea onto their code, on their subscription. The memory is shared; the intelligence is local.

🔧 Under the Hood

Build the memory, borrow the agent

The engine owns the durable, deterministic parts — the graph, content-addressed object store, git diffing, and the byte-exact run freeze. The agentic parts are delegated to subagents the host already provides. We don't reimplement an agent loop, and we never call a paid API.

Two-phase capture

A free, deterministic Phase 1 (libcst maps diff hunks to the functions/classes they touch) produces a rough candidate for every change. Phase 2 is a dispatched capsule-segmenter subagent that clusters the diff into coherent features, drops infrastructure noise, and writes the real intent, knobs, assumptions, and resurrection guide. Once a capsule is approved, the engine deterministically links same-region edges and over-produces depends_on candidates from name overlap, which an edge-judge subagent confirms or rejects.

Ranked, edge-aware recall

Recall scores every approved capsule against your query in plain Python — no embeddings, no SQL LIKE traps — and boosts a hit when a connected capsule also matches, so related work surfaces together. Each result carries its related subgraph.

Two planes

• MCP — shared memory (query-only). Returns graph snippets; safe to expose so a team shares one memory. Carries no intelligence.
• Plugin — local intelligence. Three subagents (capsule-segmenter, capsule-regenerator, edge-judge) and two skills (rgit-capture, rgit-recall) define how a session acts on those snippets, natively, on its own subscription.

Reproducibility contract

The agent helps you author; it is never in the replay path. rgit run freezes the exact bytes that ran, content-addressed and immutable. "The code behind run X" is a byte-identical re-materialization of a stored blob.

More commands

The five-step loop above is the core. These show up as your store grows — run rgit <command> --help for any of them:

License

MIT © Stepzero Lab
_{Core contributors: Yuxiang Lin · Fengrong Wan · Jiajun Sun}