Skip to main content

SOMA

Organizational intelligence for AI agent systems.

SOMA's worker cascade turns raw agent execution traces into organizational knowledge. The pipeline — Harvester → Reconciler → Synthesizer → Cartographer — ingests traces from any framework, synthesizes cross-agent patterns via LLM, and feeds learned policies back into your agent guards. The cascade has processed 6,870+ entities from real production agents.

SOMA goes beyond aggregate statistics with decision intelligence: extracting per-step decisions from agent traces, comparing decision patterns across agents, and identifying exactly where failing agents diverge from successful ones. When Agent A succeeds 95% and Agent B fails 60% doing the same task, SOMA tells you which step diverges and what tool choice makes the difference.

SOMA is the analytical layer — it observes, synthesizes, and recommends. The operational loop where agents consult the vault before executing is provided by the AICP control plane (a separate, future layer that reads from SOMA's vault via the Policy Bridge).

For deployments that need governance depth, SOMA layers knowledge into a four-tier vault (Archive → Emerging → Canon) with evidence chains and human-in-the-loop review gates. But most teams start with just the cascade.

The Problem​

AI agent systems generate knowledge constantly. Every execution, every tool call, every decision is a data point. But that knowledge rots in flat stores:

  • No cross-agent learning. Agent A discovers a workaround. Agent B hits the same wall next week. The knowledge exists but never flows between them.
  • No audit trail. An agent changes behavior. Why? Which policy caused it? Which traces supported that policy? The answer is buried in logs nobody reads.
  • No confidence hierarchy. A machine-inferred pattern sits next to a human-verified policy. Agents treat them as equally authoritative.
  • No review gate. The Synthesizer infers "always retry 3 times." But retries cause duplicate transactions in your domain. Without human review, that insight becomes a constraint that breaks production.

SOMA solves this with a proven worker cascade, optional governance layers, and evidence chains that trace every ratified policy back to the raw execution data that produced it.

30-Second Example​

import { createVault, writeToLayer, governanceAPI } from 'soma';

// Create a four-layer knowledge vault
const vault = await createVault({ dir: '.soma/vault' });

// Write raw execution data to L1 (archive)
await writeToLayer(vault, {
  type: 'execution',
  name: 'agent-alpha run #42',
  layer: 'archive',
  source_worker: 'harvester',
  status: 'completed',
  agent_id: 'agent-alpha',
});

// Synthesizer proposes a pattern to L3 (emerging knowledge)
await writeToLayer(vault, {
  type: 'insight',
  name: 'Agents retry fetch-data 3x before fallback',
  layer: 'emerging',
  source_worker: 'synthesizer',
  confidence: 0.85,
  evidence_links: ['exec-trace-1', 'exec-trace-2', 'exec-trace-3'],
  status: 'pending',
});

// Human reviews and promotes to L4 (institutional canon)
const pending = await governanceAPI.list_pending(vault);
await governanceAPI.promote(vault, pending[0].id, 'reviewer-jane');
// Now it's ratified truth. Agents enforce it.

Key Features​

  • Four knowledge layers — L1 Archive (raw traces), L2 Working Memory (team context, 14-day expiry), L3 Emerging Knowledge (machine proposals, 90-day expiry), L4 Canon (ratified truth, never expires). Each layer has strict write permissions.
  • Zero dependencies — No external packages. Vault is Markdown files with YAML frontmatter. Works everywhere Node.js runs.
  • Framework-agnostic — Works with AgentFlow, LangChain, CrewAI, or any system that produces execution data. Drop files in the inbox and SOMA ingests them.
  • Decision extraction — Infers agent decisions (tool choices, branches, retries, delegations, failures) directly from ExecutionGraph structure. No adapter changes needed.
  • Governance gate — L3 proposals require human approval by default to become L4 canon. Opt-in auto-promotion is available for high-confidence proposals backed by 5+ agents (disabled by default, --governance-auto-promote). Every L4 entry has ratified_by, ratified_at, and a full evidence chain back to raw L1 traces.
  • Decay mechanics — L2 and L3 entries expire automatically. Reading an entry resets its timer. Decayed entries move to L1 with metadata preserved. Evidence references are updated — no broken links.
  • CLI — soma ingest, soma run, soma layers status, soma governance list/promote/reject, soma report. Full pipeline from the terminal.
  • Dashboard — Intelligence tab (per-agent health, insights with layer badges) and Governance page (approve/reject proposals, evidence drill-down, canon list).
  • 197 tests — Including property-based invariant tests (200-operation random sequences) and fault injection (crash recovery, corrupt index, dead locks).

Next Steps​