Skip to content

stevedores-org/aivcs

BranchesTags

Repository files navigation

AIVCS - AI Agent Version Control System

A Rust-based version control system for AI agents, implementing AgentGit 2.0 concepts for state rollback, branching, and semantic merging.

Overview

AIVCS brings Git-like version control to AI agent workflows:

  • State Commits: Save agent state snapshots with full rollback capability
  • Branching: Create parallel exploration paths for different strategies
  • Semantic Merging: LLM-assisted conflict resolution for agent memories
  • Time-Travel Debugging: Trace agent reasoning through commit history

Architecture

┌─────────────────────────────────────────────────────┐
│                   AIVCS-Core (CLI)                  │
│          aivcs init | snapshot | restore            │
└─────────────────────┬───────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
        ▼             ▼             ▼
┌───────────────┐ ┌───────────┐ ┌──────────────────┐
│ Oxidized-State│ │ Nix-Env   │ │ Semantic-RAG     │
│ (SurrealDB)   │ │ Manager   │ │ Merge            │
│               │ │           │ │                  │
│ • Commits     │ │ • Flake   │ │ • Memory diff    │
│ • Snapshots   │ │   hashing │ │ • LLM arbiter    │
│ • Graph edges │ │ • Attic   │ │ • Vector merge   │
└───────────────┘ └───────────┘ └──────────────────┘

Quick Start

# Build
cargo build --release

# Initialize repository
./target/release/aivcs init

# Create agent state snapshot
echo '{"step": 1, "memory": "learned X"}' > state.json
./target/release/aivcs snapshot --state state.json --message "Initial state"

# View history
./target/release/aivcs log

# Create a branch
./target/release/aivcs branch create experiment-1

# Restore previous state
./target/release/aivcs restore <commit-id> --output restored.json

Commands

Command Description
init Initialize a new AIVCS repository
snapshot Create a versioned checkpoint of agent state
restore Restore agent to a previous state
branch Manage branches (list, create, delete)
log Show commit history
merge Merge two branches with semantic resolution
diff Show differences between commits/branches
env Environment management (Nix/Attic integration)
fork Fork multiple parallel branches for exploration
trace Time-travel debugging - show reasoning trace
replay Replay a recorded run artifact by run ID
diff-runs Diff the tool-call sequences of two runs
pr open Open a GitHub Pull Request and request review from the Librarian Agent

Environment Commands (Phase 2)

# Show environment hash for a Nix Flake
aivcs env hash /path/to/flake

# Show logic hash (Rust source code)
aivcs env logic-hash src/

# Check Attic cache status
aivcs env cache-info

# Check if environment is cached
aivcs env is-cached <hash>

# Show system info (Nix/Attic availability)
aivcs env info

Parallel Simulation Commands (Phase 4)

# Fork 5 parallel branches from main for exploration
aivcs fork main --count 5 --prefix experiment

# Fork 3 branches from a specific commit
aivcs fork abc123 -c 3 -p strategy

# Show reasoning trace (time-travel debugging)
aivcs trace main

# Show trace with more depth
aivcs trace experiment-0 --depth 50

A2A CODE_COMMITTED Events

aivcs snapshot and aivcs merge can notify an A2A JSON-RPC transport after an AIVCS commit is durably stored. Emission is opt-in and best-effort: transport failures are logged and retried with bounded exponential backoff, but they do not fail the local commit operation.

export AIVCS_A2A_JSONRPC_URL="https://a2a.example.com/jsonrpc"
export AIVCS_AGENT_ID="builder-agent"
export AIVCS_JOB_ID="agent-job-123"
aivcs snapshot --state state.json --message "Update state" --branch develop

Optional settings:

Variable Description
AIVCS_A2A_JSONRPC_URL Enables JSON-RPC event emission when set
AIVCS_A2A_JSONRPC_METHOD Overrides the default method, a2a.events.publish
AIVCS_AGENT_ID Authoring agent ID; falls back to the snapshot author
AIVCS_JOB_ID Ephemeral job ID included in the event payload
GITHUB_REPOSITORY Repository in owner/name form; otherwise detected from origin

The JSON-RPC params contain the AIVCS commit hash. Snapshot events include the state file path in changed_paths; merge events may emit an empty list because they merge persisted AIVCS state rather than filesystem paths.

{
  "event": {
    "kind": "CODE_COMMITTED",
    "payload": {
      "repo": "stevedores-org/aivcs",
      "branch": "develop",
      "commit_sha": "<aivcs-commit-hash>",
      "changed_paths": ["state.json"],
      "authoring_agent_id": "builder-agent",
      "job_id": "agent-job-123",
      "timestamp": "2026-05-27T00:00:00Z"
    }
  }
}

GitHub Integration (pr open)

aivcs pr open creates a Pull Request via the GitHub API and, by default, requests review from the Librarian Agent so it can audit changes before downstream OCI builds. This is the canonical PR-creation path used by autonomous builder agents running in ephemeral ADK Jobs.

export GITHUB_TOKEN="<github-app-installation-token-or-pat>"
export RELIC_LIBRARIAN_USERNAME="librarian-bot"
aivcs pr open \
  --owner stevedores-org \
  --repo aivcs \
  --head feature/my-change \
  --base main \
  --title "feat: my change" \
  --body  "Summary of what changed."

Required environment:

Variable Description
GITHUB_TOKEN Bearer token for the GitHub API. Accepts a GitHub App installation token (preferred for autonomous Jobs) or a personal access token.
RELIC_LIBRARIAN_USERNAME GitHub username of the Librarian Agent. Required when --librarian is enabled (the default). Missing or whitespace-only values are rejected eagerly so the failure surfaces before the API call rather than mid-pipeline.

The --librarian flag defaults to true; pass --librarian=false to skip the review request in development or test contexts where the Librarian is not deployed.

Documentation

Contributing

Crate Structure

  • aivcs-core: Main CLI and orchestration logic
  • oxidized-state: SurrealDB backend for state persistence
  • nix-env-manager: Nix Flakes and Attic integration for reproducible environments
  • semantic-rag-merge: RAG-based semantic merging with LLM conflict resolution

Development

# Run tests
cargo test --all

# Run specific test
cargo test test_snapshot_is_atomic

# Build with verbose output
cargo build --release -v

Database Configuration

AIVCS supports both in-memory (local development) and SurrealDB Cloud (production) backends.

Local Development (Default)

No configuration needed - uses in-memory SurrealDB automatically.

SurrealDB Cloud

  1. Create an account at SurrealDB Cloud
  2. Create a database user with Editor/Owner role at Authentication > Database Users
  3. Copy .env.example to .env and configure:
cp .env.example .env
SURREALDB_ENDPOINT=wss://YOUR_INSTANCE.aws-use1.surrealdb.cloud
SURREALDB_USERNAME=your_username
SURREALDB_PASSWORD=your_password
SURREALDB_NAMESPACE=aivcs
SURREALDB_DATABASE=main

The library automatically detects cloud credentials:

  • If SURREALDB_ENDPOINT is set, connects to cloud
  • Otherwise, falls back to in-memory database

Tech Stack

  • Rust - Core implementation
  • SurrealDB - Graph + Document database for commits and state (local or cloud)
  • Nix/Attic - Hermetic environment versioning (Phase 2)
  • Tokio - Async runtime for parallel exploration

Phase Roadmap

Phase Status Features
1 - Snapshot Core ✅ Complete commit, restore, branch, log
2 - Environment Lock ✅ Complete Nix Flake hashing, Attic cache, logic hashing
3 - Semantic Merge ✅ Complete Memory diff, conflict arbiter, memory synthesis
4 - Parallel Simulation ✅ Complete Concurrent fork, branch pruning, time-travel trace

References

License

Apache-2.0

About

aivcs AI Agent Version Control System. State commits, branching, and semantic merging for agent workflows.

Topics

rust version-control ai-agents

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages