Entity Types
SOMA stores knowledge as typed entities in Markdown files with YAML frontmatter, organized into type subdirectories under .soma/vault/. This page documents every field and every entity type.
Common Fields
Every entity in the vault has these base fields regardless of type.
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Entity type (see types below). Determines the subdirectory and valid statuses. |
id | string | Yes | Unique identifier. Auto-generated if not provided. Stable across re-ingestion for decision entities (derived from graph_id-node_id). |
name | string | Yes | Human-readable name. Used in search results and wikilink resolution. |
status | string | Yes | Lifecycle status. Valid values depend on the entity type (see per-type tables below). |
created | string (ISO 8601) | Yes | Timestamp of entity creation. Set automatically on vault.create(). |
updated | string (ISO 8601) | Yes | Timestamp of last modification. Updated automatically on vault.update(). |
tags | string[] | No | Freeform tags for filtering and search. Workers add tags like synthesized, cartographer, graph-inferred to track provenance. |
related | string[] | No | Wikilink-style references to other entities by ID. Used by Reconciler for orphan detection and by Cartographer for relationship mapping. |
body | string | No | Markdown body content below the YAML frontmatter. Contains the human-readable narrative of the entity. |
Layer Fields
These fields are added to entities participating in the four-layer knowledge model. The layer and source_worker fields are present on all layered entities. Other fields are required only for specific layers.
| Field | Type | L1 Archive | L2 Working | L3 Emerging | L4 Canon | Description |
|---|---|---|---|---|---|---|
layer | KnowledgeLayer | Required | Required | Required | Required | One of 'archive', 'working', 'emerging', 'canon'. Stored in the index for fast filtering. |
source_worker | WorkerName | Required | Required | Required | Required | The worker that created this entity (e.g. 'harvester', 'synthesizer', 'governance'). |
team_id | string | — | Required | — | — | Team scope for working memory entries. Must be non-empty. Used by Policy Bridge brief intent to filter by team. |
agent_id | string | Optional | Optional | Optional | Optional | The agent that produced the source data. Present on executions, decisions, and agent-scoped insights. |
trace_id | string | Optional | — | — | — | Unique trace identifier for deduplication. Harvester checks this before creating duplicates. |
decay_at | string (ISO 8601) | Forbidden | Required | Required | Forbidden | Expiry timestamp. L2 defaults to 14 days, L3 to 90 days. Reset on read (activity-based extension). Promoted/rejected L3 entries are exempt. |
confidence_score | number (0-1) | — | — | Required | — | Machine confidence in the proposal. Cross-agent patterns (5+ agents) score >= 0.8; single-agent capped at 0.5. |
evidence_links | string[] | — | — | Required | — | IDs of L1 entities supporting this proposal. Updated by decay processor when referenced entries decay. |
ratified_by | string | — | — | — | Required | Reviewer ID who promoted the entry from L3. |
ratified_at | string (ISO 8601) | — | — | — | Required | Timestamp of promotion from L3 to L4. |
origin_l3_id | string | — | — | — | Required | ID of the original L3 entry this was promoted from. Provides full traceability back through the evidence chain. |
decayed_from | KnowledgeLayer | Optional | — | — | — | Set on L1 entries that arrived via decay. Value is 'working' or 'emerging', indicating the original layer. |
Entity Type: agent
Directory: .soma/vault/agent/
Agent profile entities represent individual AI agents known to the system.
| Field | Type | Description |
|---|---|---|
type | 'agent' | Fixed value |
name | string | Agent identifier (e.g. agent-alpha) |
status | string | One of: active, inactive, deprecated, proposed |
Agents are created or updated by the Harvester during trace ingestion. The Harvester builds agent profiles from execution events, tracking run counts, failure rates, and last-seen timestamps.
Entity Type: execution
Directory: .soma/vault/execution/
Execution records capture individual agent runs.
| Field | Type | Description |
|---|---|---|
type | 'execution' | Fixed value |
name | string | Descriptive name of the execution |
status | string | One of: completed, failed, running, pending |
agent_id | string | Agent that performed the execution |
trace_id | string | Unique trace ID for deduplication |
graph_id | string | Associated ExecutionGraph ID (if ingested via ingestGraph()) |
Executions are written to L1 by the Harvester. They serve as the primary evidence base for L3 synthesis.
Entity Type: decision
Directory: .soma/vault/decision/
Decision entities are inferred from ExecutionGraph structure by the decision extractor.
| Field | Type | Description |
|---|---|---|
type | 'decision' | Fixed value |
name | string | Pattern: "{decision_type}: {choice} ({agent_id})" |
status | string | One of: active, superseded, reversed, flagged |
decision_type | string | One of: tool_choice, branch, retry, delegation, failure |
choice | string | The selected option (tool name, branch name, subagent name, or error message) |
outcome | string | Result of the decision (e.g. completed, failed) |
agent_id | string | Agent that made the decision |
graph_id | string | Source execution graph ID |
trace_id | string | Stable ID: "decision-{graph_id}-{node_id}" for idempotent re-ingestion |
confidence | string | One of: high, medium, low |
alternatives | string[] | Sibling branches or available tools not chosen (for branch type) |
retry_count | number | Number of retries (for retry type) |
parent_agent | string | Delegating agent (for delegation type) |
failure_path | string[] | Node path from root to failure (for failure type) |
Graph-inferred fields: decision_type, choice, outcome, alternatives, retry_count, parent_agent, and failure_path are all extracted automatically from graph structure. Decisions always carry the tag graph-inferred plus their decision_type value.
Entity Type: insight
Directory: .soma/vault/insight/
Observations extracted by the Synthesizer from execution patterns.
| Field | Type | Description |
|---|---|---|
type | 'insight' | Fixed value |
name | string | Descriptive insight title |
status | string | One of: active, superseded, rejected |
Insights in L3 carry confidence_score and evidence_links. When promoted to L4, they become organizational knowledge that agents can query via the Policy Bridge.
Entity Type: policy
Directory: .soma/vault/policy/
Guard policies that constrain agent behavior.
| Field | Type | Description |
|---|---|---|
type | 'policy' | Fixed value |
name | string | Policy name |
status | string | One of: active, draft, deprecated, enforcing |
Policies in L4 with status enforcing are returned by the Policy Bridge for enforce intent queries. The semantic_weight is mandatory, meaning agents must comply.
Entity Type: archetype
Directory: .soma/vault/archetype/
Cross-agent behavioral patterns discovered by the Cartographer via BFS community detection and embedding clustering.
| Field | Type | Description |
|---|---|---|
type | 'archetype' | Fixed value |
name | string | Archetype name |
status | string | One of: active, inactive, deprecated, proposed |
Archetypes group agents exhibiting similar behavior patterns. They exist in L3 as proposals until promoted by governance review.
Entity Type: assumption
Directory: .soma/vault/assumption/
System beliefs inferred from execution patterns.
| Field | Type | Description |
|---|---|---|
type | 'assumption' | Fixed value |
name | string | Assumption description |
status | string | One of: active, validated, invalidated |
Assumptions represent beliefs the system holds about agent behavior or environmental conditions. They can be validated or invalidated as new evidence arrives.
Entity Type: constraint
Directory: .soma/vault/constraint/
Identified limitations on agent capabilities or system behavior.
| Field | Type | Description |
|---|---|---|
type | 'constraint' | Fixed value |
name | string | Constraint description |
status | string | One of: active, resolved, deprecated |
Constraints track known limitations. When a constraint is resolved (e.g., a capability is added), it transitions to resolved status.
Entity Type: contradiction
Directory: .soma/vault/contradiction/
Conflicting positions detected by the Cartographer between L3 proposals and L4 canon.
| Field | Type | Description |
|---|---|---|
type | 'contradiction' | Fixed value |
name | string | Description of the conflict |
status | string | One of: active, resolved |
Contradictions are surfaced when a new L3 proposal conflicts with existing L4 canon. They require human attention to resolve — either the proposal is wrong, or the canon needs updating.
Entity Type: synthesis
Directory: .soma/vault/synthesis/
Cross-cluster patterns generated by the Synthesizer from L1 content similarity analysis.
| Field | Type | Description |
|---|---|---|
type | 'synthesis' | Fixed value |
name | string | Pattern description |
status | string | One of: active, superseded |
Synthesis entities capture patterns that span multiple clusters of related entities. They are produced by synthesizeL3() and synthesizeDecisions() and written to L3 with confidence scores.
File Format
Entities are stored as Markdown files with YAML frontmatter:
---
type: decision
id: tool-choice-fetch-data-agent-alpha
name: "tool_choice: fetch-data (agent-alpha)"
status: active
layer: archive
source_worker: harvester
decision_type: tool_choice
choice: fetch-data
outcome: completed
agent_id: agent-alpha
graph_id: exec-123
trace_id: decision-exec-123-t1
confidence: medium
tags: ["graph-inferred", "tool_choice"]
created: "2026-03-21T01:00:00.000Z"
updated: "2026-03-21T01:00:00.000Z"
---
## tool_choice: fetch-data
Agent **agent-alpha** made a tool_choice decision.
- **Choice:** fetch-data
- **Outcome:** completed
Nested objects and arrays of objects are serialized as inline JSON in YAML frontmatter (e.g., metadata: {"author":"alice","version":2}). Simple values use standard YAML syntax. This preserves round-trip integrity without a YAML library dependency.