io.github.argon-lab/argon

Argon — Git for MongoDB

Branch, time-travel, merge and undo your MongoDB. Any driver, real mongod, versioned history underneath. Built for AI agents.

Three ideas, thirty seconds:

1. A branch is a pointer, not a copy — created with a metadata write. Checkout separately materializes the data.
2. checkout turns a branch into a real MongoDB database — pymongo, mongoose, mongosh, indexes, aggregation, transactions: all real, and supported document writes become history while capture is healthy.
3. Review and recover changes — diff, merge, undo and pin states within the configured retention and capture guarantees.

Install

For npm, use Node.js 24 LTS with npm 11.16 or newer. The package-scoped approval allows the installer to download Argon's binary on npm 12.

brew install argon-lab/tap/argonctl      # macOS
npm install -g argonctl --allow-scripts=argonctl # cross-platform

# MongoDB must run as a replica set (one-node is fine):
docker run -d --name argon-mongo -p 127.0.0.1:27017:27017 mongo:7 --replSet rs0
docker exec argon-mongo mongosh --quiet --eval 'rs.initiate({_id:"rs0",members:[{_id:0,host:"localhost:27017"}]})'
argon doctor

Use a current supported MongoDB patch release in production. Source builds use Go 1.26.9 or newer, as declared in go.mod. Use a patched toolchain: Go 1.27.0–1.27.1 also contain the October 2026 standard-library vulnerabilities.

The flow

main ──branch──▶ experiment ──checkout──▶ mongodb://…  ← any driver
                                              │
                     ┌── argon diff ──────────┤  document history
                     ▼                        ▼
        merge (a data PR)          or   undo / discard / rewind

# 0 · Stop source writers and DDL for the import — or: argon projects create myapp
argon import database --uri mongodb://localhost:27017 --database myapp --project myapp --source-quiesced

# 1 · Branch — instant, no copy
argon branches create experiment -p myapp

# 2 · In terminal A, capture writes with a branch actor label
argon checkout -p myapp -b experiment      # prints a connection string
argon watch    -p myapp -b experiment --actor agent:experiment

# In terminal B, write through the printed URI. Then:

# 3 · Review and merge back — a data pull request
argon diff          -p myapp -b experiment
argon merge preview -p myapp -b experiment
argon merge apply <plan-id>

# …or rewind instead of merging
argon restore reset -p myapp -b main --time 2026-07-07T09:00:00Z --backup pre-incident

Prefer clicking? argon console serves a local web console (UI + REST API), supervises capture, reaps expired sandboxes every minute, and opens your browser. The console's MIT-licensed source is in web/; see the rebuild instructions. For a complete managed workflow, run the two-agent pinned dataset example.

What you get

Data history covers document inserts, updates, replacements and deletes. Collection drop/rename produces degraded capture; indexes and collection options are not versioned. Native writes are asynchronous; control operations drain capture. Stop writers before release. Existing pins protect their referenced states, while GC can expire audit and undo history. See operations for recovery and credentials.

Storage retention uses snapshots + retention-window GC to keep state plus a window of history, not every write forever. Details and the consistency model, stated honestly: ARCHITECTURE.md.

For AI agents

claude mcp add argon -- argon mcp        # 13 tools: sandbox, diff, merge, undo, pins
# Install the published Python SDK and LangGraph adapter.
python3 -m pip install 'argon-agents[langgraph]==0.2.0'

Start argon console --no-browser in another terminal, then:

from argon_agents import ArgonClient, ArgonCheckpointSaver

argon = ArgonClient("http://127.0.0.1:1818")
argon.get_or_create_project("myapp")
saver = ArgonCheckpointSaver.from_sandbox(argon, "myapp")
# Compile and run your LangGraph graph with checkpointer=saver, then review:
plan = argon.merge_preview("myapp", saver.sandbox.branch)
print(plan)
# After reviewing this exact plan, apply it explicitly:
# argon.merge_apply(plan["id"])
# Or reject the run: saver.discard()

argon.create_pin("myapp", "eval-v1")                        # pin the dataset once
run = argon.sandbox_from_pin("myapp", "eval-v1")            # identical state, every eval run

saver.merge() is a convenience call that previews and applies immediately; use the separate calls above when approval is required. Pins protect captured document state while they exist; keep independent backups.

The full agent workflow: docs/AGENTS.md.

Documentation

Community

Issues · Discussions · Contributing · argonlabs.tech · Blog

Give your MongoDB a time machine. Branch without fear. ⭐