Metadata-Version: 2.4
Name: causal-os
Version: 0.1.1
Summary: Causal memory for AI agents
Author-email: Palguna <palguna@causalos.xyz>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: networkx>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: ksuid>=0.0.0
Requires-Dist: onnxruntime>=1.15.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: typing-extensions>=4.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2; extra == "langchain"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.1; extra == "langgraph"
Provides-Extra: crewai
Requires-Dist: crewai>=0.1; extra == "crewai"
Provides-Extra: all
Requires-Dist: langchain-core>=0.2; extra == "all"
Requires-Dist: langgraph>=0.1; extra == "all"
Requires-Dist: crewai>=0.1; extra == "all"
Dynamic: license-file

# 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.

[![](https://img.shields.io/pypi/v/causal-os.svg)](https://pypi.org/project/causal-os/)
[![](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

```bash
pip install causal-os
```

## 🧱 Quick Start

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

```python
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.

```bash
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
