getting_started.md

Getting Started with CausalOS

CausalOS provides a stateful causal context layer for AI agents, allowing them to learn from past actions and outcomes to avoid recurring failures.

Installation

Install the core library via pip:

pip install causal-os

Optional Dependencies

CausalOS includes built-in integrations for popular agent frameworks:

# For LangChain integration
pip install "causal-os[langchain]"

# For FastAPI server support
pip install "causal-os[serve]"

# Install everything
pip install "causal-os[all]"

Your First Causal Memory

To start recording causal history, initialize a CausalMemory instance. This creates a local SQLite database to store agent interactions.

from causal_memory import CausalMemory
from causal_memory.models import ActionType, Severity

# Initialize memory
memory = CausalMemory(db_path="causal.db", agent_id="my-first-agent")

# Record an action and its outcome
memory.record(
    action_type=ActionType.SHELL,
    action_detail="rm -rf /tmp/cache",
    intent="Clear temporary files",
    outcome="SUCCESS: Cache cleared, 500MB freed.",
    severity=Severity.NONE
)

print("Action recorded successfully!")

Recalling the Past

Once you've recorded some actions, you can recall them when your agent is about to perform something similar.

# Search for similar past actions
past_incidents = memory.recall("rm -rf old_logs", top_k=3)

for record in past_incidents:
    print(f"[{record.severity.upper()}] Action: {record.action_detail}")
    print(f"Outcome: {record.outcome}")

Next Steps

• Explore Core Concepts to understand how CausalOS models the world.
• Learn how to protect your infrastructure with the Causal Guard.
• Check the API Reference for detailed method documentation.