Migration Guide

Migrating from Python agent frameworks

LangChain / LangGraph

The main shift is from stateless function calls to stateful reducers inside the database:

LangChain concept	Cosmictron equivalent
Chain / Graph	WASM module with #[reducer] functions
Memory / Checkpointer	#[table] with #[event] flag — persisted by default
Tool invocation	record_tool_call reducer + complete_tool_call reducer
Callback handler	Real-time subscription on agent_state
External vector DB	Coming Soon — built-in semantic memory

# LangChain pattern
memory = ConversationBufferMemory()
chain = LLMChain(llm=llm, memory=memory)
response = chain.run("Summarise the report")

// Cosmictron equivalent — state is durable by default
#[reducer]
pub fn run_agent(ctx: &ReducerContext, prompt: String) {
    // All inserts are ACID and replayed on restart
    AgentMessage::insert(AgentMessage {
        role: "user".to_string(),
        content: prompt,
        ..Default::default()
    }).unwrap();
    // ... call LLM, insert assistant response
}

CrewAI / AutoGen

Multi-agent coordination in Cosmictron is handled via cross-node orchestration and supervisor handoff hooks rather than Python class hierarchies. The event log provides the shared state that all agents read from and write to.

---

Upgrading Cosmictron versions

Breaking changes: PersistenceLayer API

Before (pre-0.8):

let persistence = PersistenceLayer::new(&config)?;

After (0.8+):

let durability_config = DurabilityConfig::default();
let persistence = PersistenceLayer::new(&config, &durability_config)?;

For a temporary rollback:

#[allow(deprecated)]
let persistence = PersistenceLayer::new_legacy(&config)?;

Environment variable renames

Old variable	New variable	Notes
COSMICTRON_ENABLE_WAL=true	COSMICTRON_FSYNC_POLICY=always
COSMICTRON_ENABLE_WAL=false	COSMICTRON_FSYNC_POLICY=never	Not recommended for production

New variables introduced alongside the rename:

COSMICTRON_FSYNC_POLICY=always        # always | periodic | never
COSMICTRON_PERFORMANCE_PROFILE=production  # development | balanced | production | maximum_safety

Performance profiles

The quickest upgrade path is to set a performance profile:

config.toml

profile = "production"

Profiles configure WAL fsync policy, sync method (fsync vs fdatasync), and memory limits automatically.

Caution

Changing COSMICTRON_FSYNC_POLICY from always to periodic or never increases write throughput but reduces durability guarantees in the event of a power failure. Do not use never in production.

---

Migrating from SpacetimeDB

Cosmictron is architecturally similar to SpacetimeDB. The key differences:

• Cosmictron adds a compliance layer (event signing, hash chain, RFC 3161 timestamps)
• Cosmictron supports V8 (JavaScript) modules in addition to WASM
• The CLI and SDK macro names differ slightly

SpacetimeDB	Cosmictron
#[spacetimedb::table]	#[table(name = "...")]
#[spacetimedb::reducer]	#[reducer]
spacetime publish	cosmictron-cli deploy
spacetime logs	cosmictron-cli logs

Data migration: export from SpacetimeDB using its CSV dump tool, then replay via Cosmictron’s bulk_insert REST endpoint.