Skip to content

api_reference.md

Latest commit

 

History

History
98 lines (77 loc) · 2.22 KB

api_reference.md

File metadata and controls

98 lines (77 loc) · 2.22 KB

API Reference

The primary interface for CausalOS is the CausalMemory class.

CausalMemory

from causal_memory import CausalMemory

Constructor

memory = CausalMemory(
    db_path="causal.db", 
    agent_id=None,
    pool_id=None,
    shared=False,
    fail_safe=True
)
  • db_path: Path to the SQLite database file.
  • agent_id: Unique identifier for this agent. Defaults to hostname:script_name.
  • pool_id: Optional identifier for a shared causal pool.
  • shared: If True, the instance will recall records from all agents in the same pool_id.
  • fail_safe: If True (default), errors in recording/recalling are logged but won't crash your agent.

Methods

record()

Save a new causal event.

record(
    action_type: ActionType,
    action_detail: str,
    outcome: str,
    intent: Optional[str] = None,
    severity: Severity = Severity.NONE,
    context: Optional[Dict[str, Any]] = None,
    tags: Optional[List[str]] = None,
    metadata: Optional[Dict[str, Any]] = None
) -> CausalRecord

recall()

Search for similar past events using vector similarity.

recall(
    action_detail: str,
    top_k: int = 5,
    threshold: float = 0.6
) -> List[CausalRecord]
  • action_detail: The query string to find similar actions.
  • top_k: Maximum number of records to return.
  • threshold: Cosine similarity threshold (0.0 to 1.0).

append_downstream()

Add an observed effect to an existing record.

append_downstream(
    record_id: str, 
    description: str, 
    severity: Severity
)

graph()

Fetch a sequence of records, optionally filtered by session.

graph(
    session_id: Optional[str] = None, 
    limit: int = 100
) -> List[CausalRecord]

Models

CausalRecord

The data model representing a single memory.

  • id: Unique identifier (UUID).
  • timestamp: Time of creation.
  • agent_id, pool_id, session_id.
  • action_type, action_detail, intent, outcome, severity.
  • downstream: List of DownstreamEffect objects.

Severity Enum

Values: NONE, LOW, MEDIUM, HIGH, CRITICAL.

ActionType Enum

Values: DB_WRITE, DB_DELETE, FILE_OP, API_CALL, SHELL, NETWORK, OTHER.