The Personal Agent Ontology: Every Entity Explained
A complete walkthrough of all 115 classes, 173 properties, and 75 named individuals across 9 modules — the formal domain model behind every personal AI agent
📺 Watch the Full Deep Dive Video
17-minute narrated walkthrough of every PAO module with entity relationship diagrams.
🎬 Watch Video (17 min)🎧 Listen to this article
This is the companion reference for our deep-dive video on the Personal Agent Ontology (PAO). While our introductory post covered what the PAO is and why it matters, this guide walks through every class in every module — a complete entity-by-entity reference for agent architects and ontology engineers.
The PAO is a formal OWL 2 DL ontology aligned to BFO 2020 that maps the converging domain model of personal AI agents. It was created by analyzing implementations like OpenClaw, Claude Code, Letta, and the Model Context Protocol.
PAO at a Glance
115
Classes
138
Object Properties
35
Data Properties
75
Named Individuals
60
SHACL Shapes
128
Competency Questions
Module 1: Agent — Who Participates
The Agent module defines who acts in agent systems. Every entity that can participate in conversations, invoke tools, or hold beliefs descends from Agent.
| Class | Description | Key Relationships |
|---|---|---|
Agent | Base class for all participants | hasRole, belongsTo, holdsDesire, heldBelief |
AIAgent | An agent powered by a foundation model | usesModel → FoundationModel, hasPersona → Persona |
HumanUser | A human person interacting with AI systems | Aligned to foaf:Person, prov:Person |
SubAgent | An AI agent spawned by another agent for delegated work | spawnedBy → AIAgent, delegatedTask → Task |
AgentRole | A role an agent plays (researcher, coder, reviewer) | Aligned to BFO Role, prov:Role |
Organization | A formal body or group of people | hasMember → Agent |
Persona | Configured identity, behavior, and system prompt | Referenced by hasPersona from AIAgent |
💡 Real-World Example
In OpenClaw, the main agent (Yaneth) is an AIAgent with a Persona defined in SOUL.md. When she spawns Karibe for research, that's a SubAgent with spawnedBy pointing to Yaneth and delegatedTask pointing to the research task.
Module 2: Session — The Conversation Stack
The Session module models conversation as a five-layer stack, each with distinct architectural concerns.
Core Conversation Classes
| Class | Description | Key Properties |
|---|---|---|
Conversation | Coherent dialogue thread spanning multiple sessions | hasConversationId |
Session | Bounded period of interaction | hasContextWindow, partOfConversation |
Turn | Single speaker contribution within a session | hasMessage, inSession, hasDialogAct |
Message | Textual/structured content of a turn | hasContentBlock, sentViaChannel |
ContentBlock | Typed segment of a message (text, code, image, tool call) | hasContentBlockType, blockSequenceIndex |
Context Management
| Class | Description |
|---|---|
ContextWindow | Finite attention resource with hasTokenCapacity and hasTokensUsed |
CompactionEvent | Context window compressed by summarizing prior turns |
CompactionDisposition | Records fate of individual items during compaction |
Channels
| Class | Description |
|---|---|
CommunicationChannel | Configured endpoint for agent-user dialogue |
ChannelType | CLI, Messaging, WebChat, APIChannel, VoiceChannel, EmailChannel |
Dialog Pragmatics (DIT++ Theory)
| Class | Description |
|---|---|
DialogAct | Pragmatic classification of a turn's communicative intent |
CommunicativeFunction | Purpose: requesting, confirming, topic change |
CommonGround | Accumulated shared knowledge between participants |
GroundingAct | Contributing evidence to the common ground |
AcceptanceEvidence | Proof that a participant acknowledged a proposition |
ClarificationRequest | Request for additional info to resolve ambiguity |
Status Classes
| Class | Description |
|---|---|
SessionStatus | Active, Suspended, Completed, Error |
SessionStatusTransition | Records session state changes |
ContentBlockType | Text, Code, Image, ToolCall, ToolResult |
ItemFate | Retained, Summarized, Dropped (during compaction) |
Module 3: Memory — Cognitive Architecture
Drawing from Letta's MemGPT, the CoALA framework, and LangMem's cognitive science framing, the Memory module defines four tiers and six operations.
Memory Tiers
| Tier | Description | Analogy |
|---|---|---|
WorkingMemory | Active context window contents, volatile | RAM |
EpisodicMemory | Time-situated experiences and interaction histories | Diary |
SemanticMemory | Generalized facts, knowledge, beliefs | Encyclopedia |
ProceduralMemory | Learned action policies, skills, patterns | Muscle memory |
Memory Items
| Class | Description | Stored In |
|---|---|---|
MemoryItem | Base class for stored information | Any MemoryTier |
Episode | Temporally bounded cluster of related events | EpisodicMemory only |
Claim | Proposition with confidence + evidence + provenance | SemanticMemory |
MemoryBlock | Structured key-value data (Letta pattern) | WorkingMemory |
Memory Operations
| Operation | Description |
|---|---|
Encoding | Write new information into a memory tier |
Retrieval | Read information from a memory tier |
Consolidation | Transform episodic memories into semantic knowledge |
Forgetting | Remove or decay items by policy or request |
Rehearsal | Strengthen items via repeated access |
Memory Governance & Multi-Agent
| Class | Description |
|---|---|
MemoryScope | Private, Shared, Global visibility |
MemorySource | Where a memory item originates |
SensitivityLevel | Privacy classification |
RetentionPolicy | How long items are kept (retentionPeriodDays) |
ErasureEvent | Privacy-compliant deletion of memory items |
SharedMemoryArtifact | Memory accessible to multiple agents (min 2) |
MemoryWriteConflict | Concurrent write conflict on shared memory |
Module 4: Tool — The Action Layer
| Class | Description | Key Properties |
|---|---|---|
Action | Intentionally caused event (subclass of Event) | performedBy → Agent |
ToolInvocation | Actual call to a tool (subclass of Action) | producedToolResult, partOfInvocationGroup |
ToolResult | Typed output artifact from a tool call | — |
ToolInvocationGroup | Groups parallel tool calls within a turn | groupedInTurn → Turn |
ExternalService | External system exposing capabilities | — |
ServiceCapability | Base for discoverable capabilities | — |
ServiceToolCapability | Provides a tool for invocation | — |
ServiceResourceCapability | Provides a data resource | — |
ServicePromptCapability | Provides a prompt template | — |
CapabilityDiscoveryEvent | Agent discovers service capabilities | discoveredCapability, discoveryAgainstService |
ServiceConnection | Runtime connection to a service | connectsToService, hasConnectionStatus |
Integration | Configured connection | hasIntegrationStatus |
Hook | Interceptor that can modify/block tool calls | hookTriggeredExecution |
HookExecution | Event when a hook fires | interceptsInvocation → ToolInvocation |
Module 5: Permission — Governance as Architecture
| Class | Description |
|---|---|
PermissionPolicy | Governs tool access (ODRL-aligned) |
PermissionMode | Enforcement level: strict ↔ permissive |
SafetyConstraint | Non-negotiable behavioral limits (appliesTo → Agent) |
SandboxPolicy | Filesystem and network restrictions |
ConsentRecord | Data subject's consent (consentPurpose, consentSubject) |
AuditLog | Container for audit entries |
AuditEntry | Authorization decision record with rationale |
AuthorizationDecision | Allowed, Denied, Escalated |
ComplianceStatus | Did invocation comply with policies? |
Checkpoint | Decision point requiring human approval |
CheckpointDecision | Approved, Rejected, Deferred |
Module 6: Interaction — BDI Cognitive Architecture
Drawing from the Belief-Desire-Intention model in philosophy of mind, this module gives agents a vocabulary for why they act.
BDI Core
| Class | Description | Key Properties |
|---|---|---|
Belief | Proposition held to be true | heldBelief, considersBelief |
Desire | Desired state or outcome | holdsDesire, considersDesire |
Intention | Committed goal the agent will pursue | justifiesIntention |
Deliberation | Reasoning process: beliefs + desires → intentions | considersBelief, considersDesire, producesIntention |
Justification | Evidence supporting an intention | justifiesIntention → Intention |
Goals, Plans & Tasks
| Class | Description |
|---|---|
Goal | High-level objective |
Plan | Ordered sequence of actions to achieve a goal (achievesGoal) |
Task | Individual unit of work within a plan |
TaskStatus | Pending, InProgress, Blocked, Done, Failed |
TaskStatusTransition | Records task state changes |
Events
| Class | Description |
|---|---|
Event | Base class for all occurrences |
Observation | Agent receives environmental feedback (inSession) |
StatusTransition | Base for state changes |
Module 7: Identity — Model Provenance
| Class | Description | Key Properties |
|---|---|---|
FoundationModel | Model family (e.g., Claude 4, GPT-4o) | hasModelId, hasModelVersion, hasProvider, deployedAs |
ModelProvider | Organization serving models (Anthropic, OpenAI) | — |
ModelDeployment | Running model endpoint configuration | — |
ModelInvocation | Event: model produces output for a turn | invokedOnDeployment, modelInvocationForTurn, hasGenerationConfig |
GenerationConfiguration | Temperature, top_p, max_tokens | — |
Module 8: Deployment — Scheduling & Automation
| Class | Description | Key Properties |
|---|---|---|
Schedule | Binds a recurrence to an action | schedulesAction, hasRecurrencePattern, activatedBy |
RecurrencePattern | When to fire: cron, interval, or calendar | hasCronExpression, hasIntervalSeconds |
Trigger | Base activation condition | — |
CronTrigger | Activates on cron schedule | — |
IntervalTrigger | Activates at fixed intervals | — |
EventTrigger | Activates on external event/webhook | — |
ScheduledExecution | Individual run of a schedule | executionOf, hasExecutionOutcome, initiatedSession |
ScheduleStatus | Active, Paused, Completed | — |
ExecutionOutcome | Success, Failure, Skipped | — |
ConcurrencyPolicy | Skip, Queue, Replace on overlap | — |
Module 9: Provenance — Error Recovery & Observability
Error Recovery
| Class | Description |
|---|---|
ErrorRecoveryEvent | Failure occurrence with hasFailureType |
FailureType | Timeout, AuthError, RateLimit, ParseError, NetworkError |
RetryAttempt | Retry of a failed operation |
ReplanEvent | Generate new plan after failure |
RollbackEvent | Revert changes from failed operation |
ReliabilityIncident | Broader failure/degradation event |
Observability
| Class | Description |
|---|---|
OperationalMetric | Named metric type (hasMetricName) |
MetricObservation | Recorded data point (observesMetric, hasMetricValue, observedOnEntity) |
75 Named Individuals
The PAO uses owl:oneOf closed enumerations for status classes. Key enumeration values include:
- SessionStatus: Active, Suspended, Completed, Error
- TaskStatus: Pending, InProgress, Blocked, Done, Failed
- ChannelType: CLI, Messaging, WebChat, APIChannel, VoiceChannel, EmailChannel
- AuthorizationDecision: Allowed, Denied, Escalated
- MemoryScope: Private, Shared, Global
- FailureType: Timeout, AuthError, RateLimit, ParseError, NetworkError
- CommunicativeFunction: Request, Inform, Confirm, Reject, TopicChange
- ItemFate: Retained, Summarized, Dropped
- ComplianceStatus: Compliant, NonCompliant, Unknown
- ConnectionStatus: Connected, Disconnected, Error
- PermissionMode: Strict, Permissive, Ask
- ExecutionOutcome: Success, Failure, Skipped
- ConcurrencyPolicy: Skip, Queue, Replace
- SensitivityLevel: Public, Internal, Sensitive, Restricted
The Unified Picture
All nine modules connect through the Agent class at the center:
- Agent → Session: Agents participate in sessions, which contain turns and messages
- Session → Memory: WorkingMemory maps to ContextWindow; Episodes derive from turns; Claims consolidate from episodes
- Turn → Tool: Turns trigger ToolInvocations that produce ToolResults
- Tool → Permission: Every invocation passes through PermissionPolicy to generate AuditEntries
- Agent → Interaction: Beliefs, Desires, and Intentions inform deliberation and goal pursuit
- Turn → Identity: ModelInvocation tracks which model/deployment produced each turn
- Schedule → Session: ScheduledExecution can initiate new sessions automatically
- Any Event → Provenance: ErrorRecoveryEvent connects to failures in tools, models, or schedules
✅ Formal Guarantees
12 AllDisjointClasses groups • 4 DisjointUnion axioms • 0 unsatisfiable classes • 1,332 test assertions passing • Every class aligned to BFO 2020
Real-World Mappings
Letta (MemGPT)
- Core Memory Blocks →
MemoryBlockinWorkingMemory - Message Buffer (FIFO) →
EpisodicMemory+CompactionEvent - Recall Memory →
EpisodicMemory(full searchable history) - Archival Memory →
SemanticMemory - memory_insert tool →
Encodingoperation - Self-editing agent →
Deliberation→Encoding
Claude Code / OpenClaw
- Main agent session →
Session+AIAgent - Sub-agent spawning →
SubAgent(spawnedBy, delegatedTask) - AGENTS.md / SOUL.md →
Persona - Tool calls (read, write, exec) →
ToolInvocation→ToolResult - Permission ask modes →
PermissionPolicy+PermissionMode - [compacted] messages →
CompactionEvent+CompactionDisposition - Telegram / CLI channels →
CommunicationChannel+ChannelType - Cron-triggered tasks →
Schedule+CronTrigger
Model Context Protocol (MCP)
- Discovery →
CapabilityDiscoveryEvent - Authentication →
ServiceConnection - Invocation →
ToolInvocation - Disconnect →
ConnectionStatus= Disconnected
References
- PAO Full Documentation — Browsable HTML with all 115 classes
- PAO Blog Post — Original announcement
- PAO Persistent URL — OWL 2 DL in Turtle/JSON-LD/OWL-XML
- BFO 2020 — Basic Formal Ontology (ISO 21838-2)
- MemGPT Paper — Virtual context management for LLMs
- CoALA Framework — Cognitive architectures for language agents
- Letta — Stateful agents with tiered memory
- OpenClaw — Open-source personal AI agent platform
- Claude Code — Anthropic's agentic coding tool
- Model Context Protocol — Standard for LLM-tool integration
- PROV-O — W3C provenance ontology
- ODRL — W3C permissions vocabulary