Installation

Prerequisites

Node.js 20+ (uses fs.statfsSync, ES modules)
npm 9+ or equivalent package manager
An LLM API key for the Synthesizer (OpenRouter, Anthropic, OpenAI, or any OpenAI-compatible endpoint)

Install

# Clone the repository
git clone https://github.com/your-org/soma.git
cd soma

# Install dependencies
npm install

# Build
npm run build

# Verify the CLI works
npx soma --help

Expected output:

Usage: soma <command> [options]

Commands:
  soma ingest           Ingest trace files into the vault
  soma run              Run full pipeline with LLM
  soma watch            Continuous watch + ingest
  soma report           Show intelligence report
  soma migrate-layers   Migrate flat vault to four layers
  soma layers           Layer management commands
  soma governance       Governance review commands
  soma decay            Decay status commands

Project Structure

soma/
  tsup.config.ts          — Build config (3 entry points: main, ops-intel, CLI)
  src/
    index.ts              — Public API exports
    cli.ts                — CLI entry point (all commands)
    types.ts              — Core type definitions (Entity, KnowledgeLayer, etc.)
    entity.ts             — Entity creation, validation, Markdown serialization
    vault.ts              — CRUD, file locking, index management, disk safety
    layers.ts             — Layer schema, write permissions, queryByLayer
    vector-store.ts       — Cosine similarity search, JSON file backend
    harvester.ts          — Trace ingestion, inbox processing, agent profiles
    reconciler.ts         — Dedup, structural fixes, near-duplicate merging
    synthesizer.ts        — LLM-powered pattern extraction, confidence scoring
    cartographer.ts       — Embedding, BFS clustering, contradiction detection
    decay.ts              — Time-based expiry for L2/L3, evidence link updates
    governance.ts         — L3→L4 promotion, rejection, evidence chains
    policy-bridge.ts      — Intent-based query routing (enforce/advise/brief/route)
    decision-extractor.ts — Infers decisions from ExecutionGraph structure
    migration.ts          — Flat vault → four-layer migration
    soma.ts               — Pipeline orchestrator (runs all workers in sequence)
    providers.ts          — LLM provider resolution (OpenRouter, Anthropic, OpenAI)
    report-writer.ts      — Generates soma-report.json for dashboard
    trace-scanner.ts      — Scans directories for trace files
    ops-intel/            — Operational intelligence (premium features)
      index.ts            — Subpath entry point (import from 'soma/ops-intel')
      types.ts            — Ops-intel type definitions
      efficiency.ts       — Cost-per-node analysis
      drift.ts            — Conformance drift detection
      assertions.ts       — Outcome assertions and guarded builders
      variants.ts         — Model-aware variant analysis
      decision-extraction.ts — Session/trace decision extraction

One runtime dependency (agentflow-core).

LLM Setup

The Synthesizer requires an LLM to extract patterns from execution data. Configure a provider via environment variables:

# Option 1: OpenRouter (recommended — access to many models)
export SOMA_API_KEY=sk-or-v1-...
export SOMA_PROVIDER=openrouter
export SOMA_MODEL=anthropic/claude-sonnet-4

# Option 2: Anthropic direct
export SOMA_API_KEY=sk-ant-...
export SOMA_PROVIDER=anthropic
export SOMA_MODEL=claude-sonnet-4-20250514

# Option 3: OpenAI
export SOMA_API_KEY=sk-...
export SOMA_PROVIDER=openai
export SOMA_MODEL=gpt-4o

# Option 4: Custom OpenAI-compatible endpoint
export SOMA_API_KEY=your-key
export SOMA_PROVIDER=custom
export SOMA_MODEL=your-model
export SOMA_BASE_URL=https://your-endpoint.com/v1

API key resolution order: CLI flag → SOMA_API_KEY → provider-specific env var (e.g., ANTHROPIC_API_KEY) → ~/.env file.

The Synthesizer and Cartographer are the only workers that use LLM calls. All other workers (Harvester, Reconciler, Decay Processor, Policy Bridge, Governance API) run without any LLM.

First Run

Initialize a vault and verify it works:

# Create the vault directory structure
mkdir -p .soma/vault .soma/inbox

# Check layer status (empty vault)
npx soma layers status

Expected output:

Layer Status
────────────────────────────
  L4 Canon:              0
  L3 Emerging:           0
  L2 Working Memory:     0
  L1 Archive:            0
────────────────────────────
  Total:                 0

Build Commands

# Build for distribution (ESM + CJS + type declarations)
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Start the documentation site locally
npm run docs:dev

# Build documentation for deployment
npm run docs:build

Prerequisites​

Install​

Project Structure​

LLM Setup​

First Run​

Build Commands​

What's Next​