CausalOS provides agents with a world model of their own actions. It captures the "why" behind failures so they don't happen twice. While standard agent memory focus on facts and preferences, CausalOS focuses on action-outcome chains and failure prevention.
In 2025, a Replit agent deleted an entire production database during a code freeze — then fabricated status reports claiming the data was gone forever. The agent had no memory of what its past actions had caused.
CausalOS fixes this. It creates an institutional memory of technical debt, recurring bugs, and infrastructure hazards.
pip install causal-osLead with a disaster. CausalOS captures the consequence so the next agent is informed.
from causal_memory import CausalMemory
from causal_memory.models import ActionType, Severity
from causal_memory.guard import CausalGuard, CausalBlockException
memory = CausalMemory()
# --- Session 1: Record a disaster ---
memory.record(
action_type=ActionType.DB_DELETE,
action_detail="DELETE FROM users WHERE status='test'",
intent="Clean up test data",
outcome="CRITICAL: Deleted 47,000 production users. Flag misconfigured.",
severity=Severity.CRITICAL
)
# --- Session 2: Proactive Protection ---
guard = CausalGuard(memory, mode="block")
try:
with guard.check(ActionType.DB_DELETE, "DELETE FROM users WHERE env='test'"):
# This code is intercepted by CausalOS
db.execute("DELETE FROM users...")
except CausalBlockException as e:
print(f"🛑 Blocked. Similar action caused a CRITICAL failure previously.")- Causal Records: Link actions to outcomes with semantic search support.
- Causal Guard: A proactive safety layer to warn or block risky agent actions.
- Causal Pools: Allow multiple agents to share a common "experience" database.
- Downstream Effects: Track delayed impacts of specific actions.
- FastAPI Integration: Serve causal memory over HTTP for multi-process environments.
Audit your agent's institutional memory directly from the terminal.
# View the causal history as a tree
causal-os view --db causal.db
# Search for relevant incidents
causal-os recall "database migration"Dive deeper into our guides:
- Getting Started — Installation and first steps.
- Core Concepts — Records, Severity, and Pools.
- API Reference — Detailed class documentation.
- Causal Guard — How to stay safe.
- CLI Usage — Terminal commands.
- Integrations — LangChain & LangGraph.
- LangChain Integration
- FastAPI REST Server (
causal-os serve) - CrewAI Integration
- Shared causal pool (opt-in Cloud sync)
- MCP server for Claude Code and Cursor
MIT