Typed knowledge graph + causal inference engine for structured agent memory and composable skills. Enhanced with causal reasoning, root cause analysis (5 Whys), and success attribution. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", "why did this fail", "what caused success", entity CRUD, or cross-skill data access.
A typed vocabulary + constraint system for representing knowledge as a verifiable graph, enhanced with causal inference engine.
Everything is an entity with a type, properties, and relations to other entities. Every mutation is validated against type constraints before committing.
Entity: { id, type, properties, relations, created, updated }
Relation: { from_id, relation_type, to_id, properties }
Automatically trace failure reasons with 5 Whys method:
from ontocausal import CausalAnalyzer
analyzer = CausalAnalyzer()
# Log failed task
analyzer.add_event(
id="task_001",
type="Task",
outcome="failure",
context={"error": "Build failed", "logs": "..."}
)
# Get root cause chain (5 Whys)
chain = analyzer.root_cause_analysis("task_001")
for step in chain:
print(f"Level {step.level}: {step.why}")
print(f"Evidence: {step.evidence}")
Extract key factors from successful outcomes:
# Log successful task
analyzer.add_event(
id="task_002",
type="Task",
outcome="success",
context={"actions": ["step1", "step2", "step3"]}
)
# Get success attribution
attribution = analyzer.success_attribution("task_002")
print(f"Key factors: {attribution.key_factors}")
print(f"Recommendations: {attribution.recommendations}")
Simulate decisions and predict outcomes:
simulation = analyzer.simulate_decision(
scenario={"project": "claw-mesh", "resources": "limited"},
decision={"action": "deploy_now", "risk": "high"}
)
print(f"Predicted outcome: {simulation.predicted_outcome}")
print(f"Confidence: {simulation.confidence}")
print(f"Risks: {simulation.risks}")
| Trigger | Action |
|---|---|
| "Remember that..." | Create/update entity |
| "What do I know about X?" | Query graph |
| "Link X to Y" | Create relation |
| "Show all tasks for project Z" | Graph traversal |
| "What depends on X?" | Dependency query |
| "Why did this fail?" | Root cause analysis (5 Whys) |
| "What caused this success?" | Success attribution |
| "What if we do X?" | Decision simulation |
| Planning multi-step work | Model as graph transformations |
| Skill needs shared state | Read/write ontology objects |
# Agents & People
Person: { name, email?, phone?, notes? }
Organization: { name, type?, members[] }
# Work
Project: { name, status, goals[], owner? }
Task: { title, status, due?, priority?, assignee?, blockers[] }
Goal: { description, target_date?, metrics[] }
# Time & Place
Event: { title, start, end?, location?, attendees[], recurrence? }
Location: { name, address?, coordinates? }
# Information
Document: { title, path?, url?, summary? }
Message: { content, sender, recipients[], thread? }
Thread: { subject, participants[], messages[] }
Note: { content, tags[], refs[] }
# Resources
Account: { service, username, credential_ref? }
Device: { name, type, identifiers[] }
Credential: { service, secret_ref } # Never store secrets directly
# Meta
Action: { type, target, timestamp, outcome? }
Policy: { scope, rule, enforcement }
Default: memory/ontocausal/graph.jsonl and memory/ontocausal/causal.jsonl
{"op":"create","entity":{"id":"p_001","type":"Person","properties":{"name":"Alice"}}}
{"op":"create","entity":{"id":"proj_001","type":"Project","properties":{"name":"Website Redesign","status":"active"}}}
{"op":"relate","from":"proj_001","rel":"has_owner","to":"p_001"}
Query via scripts or direct file ops. For complex graphs, migrate to SQLite.
When working with existing ontology data or schema, append/merge changes instead of overwriting files. This preserves history and avoids clobbering prior definitions.
python3 scripts/ontocausal.py create --type Person --props '{"name":"Alice","email":"[email protected]"}'
python3 scripts/ontocausal.py query --type Task --where '{"status":"open"}'
python3 scripts/ontocausal.py get --id task_001
python3 scripts/ontocausal.py related --id proj_001 --rel has_task
python3 scripts/ontocausal.py relate --from proj_001 --rel has_task --to task_001
python3 scripts/ontocausal.py validate # Check all constraints
# Root cause analysis for failed task
python3 scripts/ontocausal.py causal --analysis root_cause --id task_001
# Success attribution for successful task
python3 scripts/ontocausal.py causal --analysis success_attribution --id task_002
# Decision simulation
python3 scripts/ontocausal.py causal --analysis simulate --scenario '{"project":"test"}' --decision '{"action":"deploy"}'
Define in memory/ontocausal/schema.yaml: