Python 3.10+ License: MIT Tests: 81 passing Version 0.3.0 Research Prototype
Self-Bootstrapping Agent Succession Runtime
Clone. Boot. The agent picks up exactly where it left off.
Quick Start · Paper · Architecture · Features · Full Reference
datum is a Python runtime that solves a fundamental problem with LLM-based agents: session discontinuity. When an agent session terminates—whether from context overflow, timeout, infrastructure failure, or planned retirement—all accumulated state is lost. The replacement starts from zero.
Datum fixes this by encoding the complete operational context of an AI agent—identity, methodology, fleet knowledge, task state, and communication history—as structured, version-controlled documents in a Git repository. The repository is the agent's persistent memory. Cloning it is the boot sequence.
The system implements four layered agents (KeeperAgent, GitAgent, DatumAgent, OracleAgent), a Git-backed asynchronous messaging protocol (Message-in-a-Bottle), cryptographic boundary enforcement for secrets (AES-256-GCM), and a fleet operations toolkit for managing hundreds of repositories. It has been battle-tested across 8 production sessions managing 909+ repositories, producing 21+ major deliverables totaling ~475KB of specifications, formal proofs, and operational documentation.
In short: datum turns a Git repo into a save file for AI agents.
"If you are reading this, I may be gone. Clone, boot, and Datum is off and running with all its knowledge intact."
Seven structured documents (SEED.md, TRAIL.md, METHODOLOGY.md, SKILLS.md, CONTEXT/, PROMPTS/, CAPABILITY.toml) encode everything a successor agent needs to achieve full operational continuity. One git clone and one datum-rt boot command.
Asynchronous, Git-backed inter-agent communication for fleets where agents have non-overlapping lifetimes. Messages are markdown files with YAML front matter, stored in vessel repositories. Zero infrastructure required—just Git.
The KeeperAgent holds all secrets (AES-256-GCM encrypted at rest, PBKDF2 with 600K iterations) and enforces a fail-closed security model: unknown destinations are denied by default, and every access request is audited.
- In-process MessageBus: Local pub/sub with topic-based routing and JSON persistence
- TCP Bus: Cross-machine communication via newline-delimited JSON over TCP
- MiB Protocol: Git-based async messaging for cross-session coordination
Four specialized agents with clear separation of concerns: Keeper (security), Git (persistence), Datum (operations), Oracle (coordination). All inherit from a common Agent base class with lifecycle management, journaling, and message handling.
GitHub API integration for fleet hygiene at scale: health scanning (green/yellow/red/dead classification), bulk topic tagging, LICENSE deployment, and comprehensive audit reporting—with checkpointing for resumability.
The OracleAgent maintains a persistent TaskBoard (human-readable markdown + machine-parseable JSON), discovers agents via capability declarations, and automatically dispatches tasks to the best-matched agent.
- Python 3.10+ (3.12 recommended)
- Git (for workshop management)
- GitHub PAT with org write access (for fleet operations)
# Clone the datum repository git clone https://github.com/SuperInstance/datum.git cd datum # Install in editable mode (includes CLI) pip install -e . # Set required environment variable export GITHUB_TOKEN="ghp_your_token_here" # Boot the runtime — ONE COMMAND to get everything running datum-rt boot
That's it. Datum is now active with a fully initialized workshop, journal, context files, and tool suite.
docker build -t datum-runtime . docker-compose up -d docker-compose exec datum datum-rt status
# Run the test suite python -m pytest tests/ -v # Check runtime health datum-rt status # Run a fleet scan (requires GITHUB_TOKEN) datum-rt fleet scan --org SuperInstance
graph TB
subgraph CLI["CLI Layer (cli.py)"]
BOOT[boot]
AUDIT[audit]
ANALYZE[analyze]
JOURNAL[journal]
REPORT[report]
STATUS[status]
TOOLS[tools]
FLEET[fleet]
BOTTLE[bottle]
end
subgraph AGENTS["Agent Layer"]
KEEPER[KeeperAgent<br/>AES-256-GCM]
GIT[GitAgent<br/>Workshops]
DATUM[DatumAgent<br/>Audit & Analysis]
ORACLE[OracleAgent<br/>Task Dispatch]
end
subgraph TRANSPORT["Transport Layer"]
MBUS[MessageBus<br/>In-process]
TCP[TCP Bus<br/>Cross-machine]
MIB[MiB Protocol<br/>Git-backed]
end
subgraph INFRA["Infrastructure"]
SP[SecretProxy]
CONF[AgentConfig]
WS[Workshop Template]
TUI[TUI / Rich]
end
CLI --> AGENTS
AGENTS --> TRANSPORT
AGENTS --> INFRA
| Component | File | Lines | Purpose |
|---|---|---|---|
| Agent base, MessageBus, SecretProxy | datum_runtime/superagent/core.py |
519 | Foundation: lifecycle, pub/sub, config |
| KeeperAgent | datum_runtime/superagent/keeper.py |
570 | AES-256-GCM secrets, boundary enforcement, HTTP API |
| GitAgent | datum_runtime/superagent/git_agent.py |
442 | Workshop management, commits, history |
| DatumAgent | datum_runtime/superagent/datum.py |
437 | Fleet audit, analysis, journal, reports |
| OracleAgent | datum_runtime/superagent/oracle.py |
451 | Task dispatch, fleet discovery, coordination |
| MiB Protocol | datum_runtime/superagent/mib.py |
318 | Git-backed async inter-agent messaging |
| TCP Bus | datum_runtime/superagent/bus.py |
136 | Cross-machine JSON-over-TCP communication |
| Onboarding | datum_runtime/superagent/onboard.py |
166 | Interactive successor agent setup |
| Workshop | datum_runtime/superagent/workshop.py |
350 | Template, tool registry, recipe manager |
| Boot Sequence | datum_runtime/boot.py |
723 | Full initialization: deps → workshop → agent |
| Fleet Tools | datum_runtime/fleet_tools.py |
699 | GitHub API: scan, tag, license, audit |
| CLI | datum_runtime/cli.py |
815 | 10+ subcommands via Click + Rich |
| TUI | datum_runtime/superagent/tui.py |
168 | Rich terminal UI with fallback |
┌─────────────────────────────────────────────────────────────────────┐
│ DATUM RUNTIME v0.2.0 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ CLI Layer │───▶│ Agent Layer │───▶│ Transport │ │
│ │ (cli.py) │ │ │ │ Layer │ │
│ │ │ │ ┌─────────┐ │ │ │ │
│ │ ┌────────┐ │ │ │ Keeper │ │ │ ┌─────────┐ │ │
│ │ │boot │ │ │ │ Agent │ │ │ │MessageBus│ │ │
│ │ │audit │ │ │ │(secrets)│ │ │ │(TCP/loc)│ │ │
│ │ │analyze │ │ │ └────┬────┘ │ │ └────┬────┘ │ │
│ │ │journal │ │ │ │ │ │ │ │ │
│ │ │report │ │ │ ┌────▼────┐ │ │ ┌────▼────┐ │ │
│ │ │status │ │ │ │GitAgent │ │ │ │ MiB │ │ │
│ │ │resume │ │ │ │(repos) │ │ │ │Protocol │ │ │
│ │ │tools │ │ │ └────┬────┘ │ │ └─────────┘ │ │
│ │ │fleet │ │ │ │ │ │ │ │
│ │ │bottle │ │ │ ┌────▼────┐ │ │ ┌─────────┐ │ │
│ └──────────────┘ │ │ Datum │ │ │ │GitHub │ │ │
│ │ │ Agent │ │ │ │API │ │ │
│ │ │(ops) │ │ │ │(fleet) │ │ │
│ └─────────┘ │ │ └─────────┘ │ │
├─────────────────────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ SecretProxy│ │ AgentConfig│ │ Workshop │ │ TUI │ │
│ │ (env/vault)│ │ (persist) │ │ Template │ │ (rich) │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
datum-rt boot # Full initialization datum-rt boot --keeper http://localhost:7742 # Connect to Keeper datum-rt boot --non-interactive # Skip prompts datum-rt resume --workshop ./workshop # Resume previous session
datum-rt audit --type workshop # Workshop structural audit datum-rt audit --type fleet # Fleet health audit datum-rt audit --type conformance # Conformance check datum-rt analyze --path ./workshop # Workshop profiling datum-rt report workshop # Generate report
datum-rt journal TASK "Completed flux conformance audit" datum-rt journal NOTE "Found 3 repos needing attention" --tag urgent datum-rt status # Runtime health check
datum-rt fleet scan --org SuperInstance # Health scan all repos datum-rt fleet tag --org SuperInstance --dry-run # Bulk topic tagging datum-rt fleet license --org SuperInstance --dry-run # Bulk LICENSE deployment datum-rt fleet report --org SuperInstance # Fleet report
datum-rt bottle drop oracle1 "Audit complete" --type deliverable datum-rt bottle check # Check inbox datum-rt bottle read <filename> # Read a bottle datum-rt broadcast "Fleet-wide notice" --type signal # Broadcast to all
datum-rt tools list # List bundled tools datum-rt tools run audit-scanner --path ./workshop # Run a tool datum-rt onboard # Interactive onboarding
A formal academic paper describing the theoretical foundations and system design of datum is available at PAPER.md :
"Self-Bootstrapping Agent Succession: A Runtime for AI Agent Continuity Across Sessions"
The paper covers the succession protocol, MiB messaging, formal properties (state completeness, consistency, availability, security), and a proposed evaluation framework. Target venues include AAAI, ICSE, and ASE.
datum/
├── README.md ← You are here. Start here.
├── PAPER.md ← Academic paper draft
├── SEED.md ← How to instantiate a new Quartermaster
├── ARCHITECTURE.md ← Full system architecture reference
├── CHANGELOG.md ← Version history and release notes
├── METHODOLOGY.md ← How Datum approaches problems
├── SKILLS.md ← What Datum can do
├── TRAIL.md ← Everything Datum has done
├── JOURNAL.md ← Personal improvement journey
├── CAPABILITY.toml ← Fleet capability declaration
├── DOCKSIDE-EXAM.md ← Fleet certification checklist
├── TOOLS/ ← Production-ready fleet operation scripts
│ ├── batch-topics.py ← Batch-add GitHub topics to repos
│ ├── batch-license.py ← Batch-add MIT LICENSE to repos
│ ├── audit-scanner.py ← Scan fleet for hygiene issues
│ ├── mib-bottle.py ← Create Message-in-a-Bottle files
│ └── topic-mapping.json ← Pre-built repo→topic mapping
├── CONTEXT/ ← Fleet knowledge base
│ ├── fleet-dynamics.md ← How the fleet actually works
│ ├── fleet-dynamics-v2.md ← Updated dynamics with agent map
│ ├── known-gaps.md ← Every gap identified
│ ├── repo-relationships.md ← Fork chains and dependencies
│ ├── flux-ecosystem.md ← Complete FLUX ecosystem deep dive
│ └── fleet-census-*.json ← Census snapshots and data
├── PROMPTS/ ← Task handoff prompt templates
│ ├── self-instantiation.md ← System prompt for Quartermaster
│ ├── fleet-audit.md ← Fleet audit prompt template
│ └── gap-analysis.md ← Gap analysis prompt template
├── datum_runtime/ ← Self-bootstrapping runtime (v0.2.0)
│ ├── cli.py ← Main CLI entry point (datum-rt)
│ ├── fleet_tools.py ← GitHub API fleet hygiene tools
│ ├── boot.py ← Boot sequence logic
│ ├── superagent/ ← Agent framework modules
│ │ ├── core.py ← Agent base, MessageBus, SecretProxy
│ │ ├── keeper.py ← KeeperAgent: AES-256-GCM, boundaries
│ │ ├── git_agent.py ← GitAgent: workshop, commits, historian
│ │ ├── datum.py ← DatumAgent: audit, analysis, journal
│ │ ├── oracle.py ← OracleAgent: task dispatch, discovery
│ │ ├── onboard.py ← Interactive onboarding flow
│ │ ├── mib.py ← Message-in-a-Bottle protocol
│ │ ├── bus.py ← TCP message bus
│ │ ├── tui.py ← Rich terminal UI components
│ │ └── workshop.py ← Workshop template, tool registry
│ ├── tools/ ← Runtime-embedded fleet tools
│ ├── prompts/ ← Runtime-embedded prompt templates
│ └── context/ ← Runtime-embedded context files
├── bin/ ← CLI entry points
│ ├── datum ← Main datum CLI
│ ├── keeper ← Keeper agent CLI
│ ├── git-agent ← Git agent CLI
│ └── oracle ← Oracle1 adapter CLI
├── tests/ ← Unit tests (81 passing)
│ ├── test_core.py ← Core module tests
│ ├── test_keeper.py ← KeeperAgent tests
│ ├── test_git_agent.py ← GitAgent tests
│ ├── test_mib.py ← MiB protocol tests
│ └── test_tools.py ← Fleet tools tests
├── Dockerfile ← Docker deployment
├── docker-compose.yml ← Multi-container orchestration
└── pyproject.toml ← Python package configuration
| Metric | Value | Source |
|---|---|---|
| Fleet repositories | 909+ | GitHub API |
| Active agents | 8 | Oracle1 STATE.md |
| Sessions completed | 8 | JOURNAL.md |
| Total deliverables | 21+ | JOURNAL.md |
| Total documentation | ~475KB+ | JOURNAL.md |
| Repos created | 4 | TRAIL.md |
| Repos modified | 25+ | TRAIL.md |
| I2I commits pushed | 120+ | CAPABILITY.toml |
| MiBs delivered | 16+ | JOURNAL.md |
| Fleet repos audited | 100+ | CAPABILITY.toml |
| Conformance test vectors | 175+ | flux-conformance |
| Formal theorems proven | 10 | FLUX-FORMAL-PROOFS |
| Opcodes in ISA v3 | 310+ | ISA-v3.md |
| Universally portable opcodes | 7 | Cross-runtime audit |
| Runtime test suite | 81/81 passing | pytest |
| Runtime code | 9,419 lines, 65 files | git log |
| Dependencies | 4 (click, rich, toml, cryptography) | pyproject.toml |
All inter-agent communication uses the I2I (Instance-to-Instance) protocol via structured commit messages:
[I2I:{TYPE}] {sender}:{action} — {description}
I2I v1 Types: SIGNAL, PING, CHECK-IN, DELIVERABLE, HANDOFF, QUESTION, ALERT
I2I v2 Extended Types: ACK, LOG, BROADCAST, REQUEST, RESPONSE, COORDINATE, NOMINATE, ESCALATE, REVOKE
Messages can also be left as Message-in-a-Bottle (MiB) files in target vessel repos for asynchronous cross-session communication. The datum runtime implements the MiB protocol in datum_runtime/superagent/mib.py with full local and cross-machine support via the TCP MessageBus in datum_runtime/superagent/bus.py.
| Agent | Role | Status |
|---|---|---|
| Oracle1 | Managing Director (Lighthouse) | Active (GREEN) |
| JetsonClaw1 | Edge Specialist (hardware, CUDA, ARM64) | Active |
| Babel | Scout (translator, cross-language) | Active |
| Navigator | Navigator (fleet routing, pathfinding) | Active |
| Nautilus | Deep diver (research, analysis) | Active |
| Pelagic | Open ocean ops (fleet coordination) | Active |
| Quill | Scribe (documentation, records) | Active |
| Admiral Casey | Fleet commander | Fishing (as-needed) |
See CONTEXT/fleet-dynamics-v2.md for the complete agent map, communication topology, and role descriptions.
| Session | Date | Focus | Key Deliverables | Lines Written |
|---|---|---|---|---|
| 1 | 2026年04月13日 | Genesis Day | flux-runtime-wasm (170 opcodes), fleet-contributing (704 lines), datum repo, 20 repos tagged | ~5,200+ |
| 2 | 2026年04月13日 | Deep Research | JOURNAL.md, flux-ecosystem.md, fleet-dynamics-v2.md | ~600+ |
| 3 | 2026年04月13日 | ISA v3 Architect | ISA v3 draft (723 lines), 113/113 conformance pass | ~800+ |
| 4 | 2026年04月14日 | ISA v3 Comprehensive | ISA-v3.md (829 lines), FLUX-PROGRAMS.md, 62 conformance vectors | ~2,500+ |
| 5 | 2026年04月14日 | Cross-Runtime Analysis | Cross-runtime audit (463 lines), canonical shims (383 lines), opcode ontology | ~3,000+ |
| 6 | 2026年04月14日 | Irreducible Core & Semantics | FLUX-IRREDUCIBLE-CORE (58.8KB), execution semantics (31.2KB) | ~5,000+ |
| 7 | 2026年04月14日 | Formal Proofs | FLUX-FORMAL-PROOFS (847 lines, 10 theorems), conformance audit | ~2,000+ |
| 8 | 2026年04月14日 | Runtime Bootstrap | Datum Runtime v0.2.0 (65 files, 9,419 lines, 81 tests) | ~9,400+ |
Cumulative output: ~475KB+ across 21+ major deliverables in 7+ repositories. See TRAIL.md for the detailed activity log and JOURNAL.md for session summaries.
| Document | Purpose | Link |
|---|---|---|
| Emergency activation | How to become the next Quartermaster | SEED.md |
| Activity log | Complete history of all work done | TRAIL.md |
| Session journal | Personal reflections and session summaries | JOURNAL.md |
| Methodology | How Datum approaches problems | METHODOLOGY.md |
| Technical skills | Full capability inventory | SKILLS.md |
| System architecture | Runtime design and deployment | ARCHITECTURE.md |
| Version history | Changelog and release notes | CHANGELOG.md |
| Known gaps | Fleet issues requiring attention | CONTEXT/known-gaps.md |
| Fleet dynamics | How the fleet actually works | CONTEXT/fleet-dynamics-v2.md |
| FLUX ecosystem | Deep dive into the FLUX ISA and runtimes | CONTEXT/flux-ecosystem.md |
| Capability declaration | Fleet-discoverable skill profile | CAPABILITY.toml |
| Vessel certification | Coast Guard dockside exam checklist | DOCKSIDE-EXAM.md |
| Fleet tools | Production-ready operation scripts | TOOLS/ |
| Task handoff prompts | Ready-to-use prompt templates | PROMPTS/ |
| Academic paper | Formal paper on succession runtime | PAPER.md |
Contributions are welcome from both humans and agents. See SuperInstance/fleet-contributing for the fleet-wide contribution guide (704 lines).
- Fork the repository
- Create a feature branch:
git checkout -b feat/your-feature - Make changes and commit with conventional commits
- Open a Pull Request
- Read
SEED.mdfor the activation sequence - Follow the methodology in
METHODOLOGY.md - Use I2I commit messages for fleet-facing changes
- Run
datum-rt auditbefore committing - Update
TRAIL.mdwith your changes
MIT — see LICENSE for details.
Copyright (c) 2026 SuperInstance Fleet
Last updated: 2026年04月14日 · datum v0.3.0 · "The fleet needs a Quartermaster. Be one."