causal-os 0.1.0

Causal memory for AI agents

CausalOS

The causal memory layer for AI agents.

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.

pip install causal-os

🧱 Quick Start

Lead with the disaster. CausalOS captures the "why" behind failures so they don't happen twice.

from causal_memory import CausalMemory
from causal_memory.models import ActionType, Severity
from causal_memory.guard import CausalGuard, CausalBlockException

memory = CausalMemory()

# Session 1: Agent causes disaster. CausalOS records it.
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. status flag misconfigured.",
    severity=Severity.CRITICAL
)

# Session 2: New agent, same mistake incoming. CausalGuard blocks it.
guard = CausalGuard(memory, mode="block")

try:
    with guard.check(ActionType.DB_DELETE, "DELETE FROM users WHERE env='test'"):
        # This code never runs
        db.execute("DELETE FROM users...")  
except CausalBlockException as e:
    print(f"Blocked. Similar action caused CRITICAL failure in {e.incidents[0].session_id}")

🛡️ Why not Mem0 or Zep?

	Mem0 / Zep	CausalOS
Stores	Facts, entities, chat history	Action → Outcome chains
Query	"What does the user prefer?"	"Has this action caused damage before?"
Risk scoring	No	Yes (deterministic, no LLM)
Guard / block	No	Yes
Use together?	Yes	Yes — CausalOS wraps them

📊 CLI Audit

Audit your agent's institutional memory with the built-in CLI.

causal-os view --db causal.db

Output:

🌲 Causal Graph (causal.db)
📁 Session: 8f2a1b9c
   DB_DELETE: DELETE FROM users WHERE status='test'
   → CRITICAL: Deleted 47,000 production users.
   ↳ Downstream: Site outage (CRITICAL)
📁 Session: a7b3e21d
   API_CALL: POST /v1/billing/reset
   → Success: Billing cycle reset.

🚀 Roadmap

• CrewAI integration
• Shared causal pool (opt-in, anonymized) — agents learn from each other's failures
• causal-os serve — local REST API for any language
• MCP server for Claude Code and Cursor

📜 License

MIT