Quick Start
Full SOMA workflow in 7 steps: ingest agent traces, run the pipeline, review proposals, promote to canon.
This assumes you have completed installation and have an LLM provider configured.
Step 1: Ingest Traces
Drop trace files (JSON, JSONL, or Markdown) into the inbox directory, then run ingest:
# Copy some agent execution traces into the inbox
cp ~/agentflow-output/traces/*.json .soma/inbox/
# Ingest all traces
npx soma ingest --traces .soma/inbox
Expected output:
Harvester: scanning .soma/inbox
Found 24 trace files
Created 24 execution entities
Created 4 agent profiles (agent-alpha, agent-beta, curator, distiller)
Extracted 37 decisions from execution graphs
Skipped 0 duplicates
Ingestion complete. 65 entities written to L1.
The Harvester writes everything to L1 (Archive). It extracts decisions (tool choices, branches, retries, delegations, failures) directly from the ExecutionGraph structure of each trace. Agent profiles are created or updated automatically.
Duplicate detection uses trace_id for executions and graph_id-node_id for decisions — re-running ingest on the same files is safe and idempotent.
Step 2: Run the Pipeline
The pipeline runs all SOMA workers in sequence: Harvester → Reconciler → Synthesizer → Cartographer → Decay Processor.
npx soma run --provider openrouter --model anthropic/claude-sonnet-4
Expected output:
Pipeline started
Reconciler: scanned 65 entities
Fixed 2 structural issues (missing status field)
Merged 1 near-duplicate pair
0 orphan entities found
Synthesizer: analyzed 61 L1 candidates
Generated 8 L3 proposals (confidence range: 0.42 — 0.91)
3 cross-agent patterns detected
5 single-agent patterns detected
Cartographer: embedded 65 entities
Discovered 3 archetypes
Proposed 4 relationships
Detected 1 contradiction
Decay Processor: 0 entries expired
Pipeline complete. 8 proposals pending review.
The Synthesizer only processes entities that are not tagged synthesized (no self-processing loops). Cross-agent patterns (5+ agents corroborating) score >= 0.8 confidence. Single-agent patterns are capped at 0.5.
Step 3: Check Layer Status
npx soma layers status
Expected output:
Layer Status
────────────────────────────
L4 Canon: 0
L3 Emerging: 8
L2 Working Memory: 0
L1 Archive: 68
────────────────────────────
Total: 76
L3 has 8 entries — these are the Synthesizer's proposals waiting for human review. L1 grew from 65 to 68 because the Reconciler created 2 merge entities and the Cartographer wrote 1 contradiction entity.
Step 4: Review Proposals
List all pending L3 proposals, sorted by confidence (highest first):
npx soma governance list
Expected output:
Pending L3 Proposals (8)
─────────────────────────────────────────────────────────────────────
ID Confidence Type Name
pattern-retry-fetch-5agent 0.91 insight Agents retry fetch-data 3x before fallback
pattern-timeout-escalation 0.87 insight Timeout triggers escalation in 4/5 agents
archetype-data-pipeline 0.78 archetype Data pipeline execution cluster
pattern-auth-refresh 0.65 insight Auth token refresh before API calls
contradiction-retry-vs-failfast 0.62 contradiction Retry policy conflicts with fail-fast policy
pattern-beta-logging 0.48 insight agent-beta excessive logging pattern
pattern-curator-delegation 0.45 insight curator delegates to distiller for summaries
relationship-alpha-beta-shared 0.42 synthesis agent-alpha and agent-beta share tool set
Inspect a specific proposal and its evidence chain:
npx soma governance show --id pattern-retry-fetch-5agent
Expected output:
L3 Proposal: pattern-retry-fetch-5agent
─────────────────────────────────────────────────────────────────────
Name: Agents retry fetch-data 3x before fallback
Type: insight
Confidence: 0.91
Status: pending
Created: 2026-03-21T01:00:00.000Z
Evidence Chain (5 L1 entries):
exec-agent-alpha-run-12 agent-alpha tool_choice: fetch-data (retry 3x)
exec-agent-beta-run-7 agent-beta tool_choice: fetch-data (retry 3x)
exec-curator-run-31 curator tool_choice: fetch-data (retry 2x, fallback)
exec-distiller-run-15 distiller tool_choice: fetch-data (retry 3x)
exec-agent-gamma-run-4 agent-gamma tool_choice: fetch-data (retry 3x)
Body:
Five agents independently developed a retry pattern for the fetch-data tool:
retry up to 3 times, then fall back to cached data. This pattern emerged
across 12 executions over 5 days.
Step 5: Promote or Reject
Promote a high-confidence proposal to L4 (institutional canon):
npx soma governance promote --id pattern-retry-fetch-5agent
Expected output:
Promoted: pattern-retry-fetch-5agent → L4 Canon
Ratified by: cli-user
Ratified at: 2026-03-21T14:30:00.000Z
New L4 entry: canon-retry-fetch-5agent
Original L3 status updated to: promoted
Reject a proposal that does not apply:
npx soma governance reject --id pattern-beta-logging --reason "Logging volume is by design for debug mode"
Expected output:
Rejected: pattern-beta-logging
Rejected by: cli-user
Reason: Logging volume is by design for debug mode
L3 status updated to: rejected
Entry will not decay (promoted/rejected entries are preserved).
Promoted and rejected entries never decay. They stay in the vault as a permanent record of governance decisions.
Step 6: Query Knowledge by Intent
The Policy Bridge routes queries to the appropriate layer based on intent:
# Get mandatory constraints (L4 canon only)
npx soma layers query --intent enforce
# Get advisory guidance (L3 emerging knowledge)
npx soma layers query --intent advise
# Get team context (L2, requires team_id)
npx soma layers query --intent brief --team platform-team
# Get historical reference (L1 archive)
npx soma layers query --intent route
# Get stratified results from all layers
npx soma layers query --intent all
Expected output for --intent enforce:
L4 Canon (enforce) — 1 entry
─────────────────────────────────────────────────────────────────────
canon-retry-fetch-5agent
Agents retry fetch-data 3x before fallback
Semantic weight: mandatory
Ratified by: cli-user (2026-03-21T14:30:00.000Z)
Every result includes source_layer and semantic_weight metadata so agents know how to treat the knowledge: mandatory (L4), advisory (L3), contextual (L2), or historical (L1).
Step 7: Generate Report
npx soma report --threshold 0.3
Expected output:
SOMA Intelligence Report
─────────────────────────────────────────────────────────────────────
Vault: .soma/vault
Entities: 76
Layers: L1=68 L2=0 L3=7 L4=1
Agents (4):
agent-alpha 12 runs 1 failure 8.3% failure rate active
agent-beta 8 runs 0 failures 0.0% failure rate active
curator 6 runs 2 failures 33.3% failure rate degraded
distiller 5 runs 0 failures 0.0% failure rate active
Top Insights (confidence >= 0.3):
[L4] Agents retry fetch-data 3x before fallback (0.91) ✓ ratified
[L3] Timeout triggers escalation in 4/5 agents (0.87) pending
[L3] Data pipeline execution cluster (0.78) pending
[L3] Auth token refresh before API calls (0.65) pending
[L3] Retry policy conflicts with fail-fast policy (0.62) pending
[L3] curator delegates to distiller for summaries (0.45) pending
[L3] agent-alpha and agent-beta share tool set (0.42) pending
Contradictions (1):
contradiction-retry-vs-failfast
Retry policy (L3, 0.91) vs fail-fast policy (L4 from legacy)
Action: review and resolve
Report written to soma-report.json
The report is consumed by the AgentFlow Dashboard for the Intelligence and Governance pages.