SOMA

Code License: Apache-2.0 Docs License: CC BY 4.0 Rust 1.88+ SQLite MCP Local Dashboard CI Security Policy

SOMA is a local context, memory, and control plane for cloud LLMs.

SOMA stands for Self-Optimizing Memory Architecture: a local system that learns from your work history by moving evidence through explicit memory lifecycle states instead of treating every remembered token as truth.

Cloud LLMs are now strong enough to code, write, refactor, plan, and use tools. Their weakest point is not raw intelligence. It is continuity: the model often does not know the current task state, which project constraints matter, which older assumptions were corrected, which local events are evidence, and which cloud-generated claims are still unverified.

SOMA owns that missing layer locally.

It captures local work history, keeps it in a private SQLite store, compiles evidence-backed context, exposes that context through MCP, and prevents cloud output from becoming durable memory until it is verified by a user, tool, test, local observation, or correction.

The short version:

Cloud LLM = synthesis, execution, broad reasoning, code/prose generation
SOMA      = local memory, task state, evidence, policy, correction, trust gates

SOMA does not try to replace the cloud model. It gives the cloud model the right cognitive state.

The long-term destination is a cloud-local latent protocol: when cloud model providers expose safe interfaces for it, a cloud LLM and a local memory-learning system should be able to exchange bounded raw hidden vectors or latent states under explicit user control. SOMA would use those model-native signals to learn compact private memory locally, then return evidence-grounded memory and control signals back to the cloud model. The goal is an efficient partnership: cloud LLMs provide broad reasoning and generation, while local SOMA provides private memory learning, continuity, verification, and lifecycle control.

Today's public runtime approximates that direction with evidence-backed latent proxies and ContextEnvelopes, because mainstream cloud APIs do not yet expose a portable raw-hidden-state exchange protocol.

Inspired By

This section summarizes the research papers referenced by the private SOMA research notes under docs/research/, plus the latent-learning paper linked during public README preparation. SOMA does not implement every method below as a core backend; most of them shaped the architecture, trust boundary, or future optional context-quality modules.

Associative and Episodic Memory

  • Hopfield Networks is All You Need (Ramsauer et al., 2020): Inspired SOMA's view of retrieval as associative recall over encoded episodes, with Hopfield-style modules kept optional rather than treated as the trust source.
  • Provably Optimal Memory Capacity for Modern Hopfield Models (Hu et al., 2024): Informed the expectation that large episodic stores need capacity-aware recall and bounded retrieval cost.
  • On Computational Limits of Modern Hopfield Models (Hu et al., 2024): Reinforced SOMA's separation between memory retrieval and higher-level reasoning or verification.
  • The Capacity of Modern Hopfield Networks (Lucibello and Mezard, 2024): Strengthened the theoretical motivation for associative memory as a scalable recall primitive.
  • Modern Hopfield Networks with Continuous-Time Memories (Santos et al., 2025): Inspired future compressed temporal-memory backends for long-running work streams.
  • Sparse Hopfield Networks with Tsallis-style sparsity (2024): Inspired sparse, top-k recall so unrelated memories do not pollute a ContextEnvelope.
  • Sparse Quantized Hopfield Networks for Online-Continual Memory (Alonso and Krichmar, 2024): Motivated online memory updates while keeping interference and storage cost bounded.
  • Modern Hopfield Networks as hippocampus with VAE/neocortex-style CLS (2025): Inspired the episodic-versus-semantic split behind SOMA's memory lifecycle.
  • Hopfield Encoding Networks (Kashyap et al., 2024): Inspired storing pre-encoded task and evidence embeddings rather than raw conversational text.
  • Input-driven dynamics for robust memory retrieval in Hopfield networks (Betteti et al., 2025): Inspired current-task-conditioned recall instead of static global memory lookup.

Working Memory and Long Context

  • xLSTM: Extended Long Short-Term Memory (Beck et al., 2024): Inspired SOMA's L1 working-memory idea as a bounded state that compresses the active session.
  • xLSTM 7B (Beck et al., 2025): Informed future expectations for scaling matrix-memory backends beyond toy cognitive modules.
  • Tiled Flash Linear Attention for xLSTM/mLSTM kernels (2025): Inspired the practical constraint that optional learned memory backends must have realistic latency.
  • RWKV-7 Goose (Peng et al., 2025): Inspired constant-memory recurrent state as another candidate backend for local continuity.
  • Mamba-3 (Gu, Dao et al., 2026): Informed the broader state-space-model design space for bounded state tracking.
  • MemMamba (2025): Inspired the idea that recurrent sequence models can be augmented with explicit memory paths.
  • Jamba (AI21, 2024/2025): Inspired hybrid attention-plus-SSM designs for long-context work where pure recurrence is not enough.
  • Hymba (NVIDIA, 2024): Inspired hybrid memory/attention routing with explicit meta-token-style state.
  • NVIDIA Mamba-2-Hybrid empirical study (2024): Informed SOMA's preference for deterministic baselines plus optional learned modules rather than one model family as the whole architecture.

Predictive Coding, Latents, and Salience

  • Learn from your own latents and not from tokens: A sample-complexity theory (Korchinski, Favero, and Wyart, 2026): Inspired SOMA's latent-learning direction: learn from model-native representations rather than token text; today's runtime uses evidence-backed latent proxies until a safe raw-hidden-vector exchange protocol exists.
  • Incremental Predictive Coding (Salvatori et al., 2024): Inspired surprise and anomaly detection as L2 candidate signals, while SOMA still requires evidence before promotion.
  • Deep Bidirectional Predictive Coding (2025): Inspired future bidirectional error signals for review-only semantic candidates.
  • PCX predictive-coding benchmarking (2024): Informed the decision to keep predictive-coding work on compact evidence embeddings rather than raw high-dimensional inputs.
  • Introduction to Predictive Coding Networks for ML (Stenlund, 2025): Inspired implementation guardrails for any future PCN-based optional module.
  • Active Predictive Coding (Rao et al., 2024): Inspired the idea of local prediction error as a control signal for what needs attention.
  • FEP-based neuromimetic perception (Bazargani, Friston et al., 2025): Inspired uncertainty-aware local diagnostics without allowing hidden latents to become durable facts.
  • The Free-Energy Principle (Friston, 2010): Inspired the salience framing, but SOMA turns salience into review candidates rather than truth.
  • Self-modeling as regularization (Premakumar, Graziano et al., 2024): Inspired SOMA's self-review direction: learn from observed behavior, not from unverified cloud prose.

Continual Learning and Adaptation

  • O-LoRA (2023): Inspired orthogonal adaptation spaces as a future way to avoid overwriting prior behavior.
  • InfLoRA (2024): Inspired feature-subspace separation for continual learning without replay-heavy pipelines.
  • S-LoRA for Class-Incremental Learning (2025): Inspired magnitude/direction separation as a possible adaptation guardrail.
  • Online-LoRA (2025): Inspired task-free online adaptation as a future local-learning direction.
  • PEARL (2025): Inspired dynamic rank allocation for adapting only where new evidence justifies extra capacity.
  • OLieRA (2025): Inspired geometry-aware LoRA constraints for stable specialization.
  • OPLoRA (2025): Inspired orthogonal projection as another route for reducing interference between learned skills.
  • CLoRA (2025): Inspired lightweight continual-learning adapters for long-lived personalized systems.
  • TreeLoRA (2025): Inspired hierarchical adapter organization that could map naturally to persona and project provenance.
  • CL-LoRA (2025): Inspired class/task-incremental adapter management for future semantic-learning experiments.
  • DoRA (2024): Inspired separating magnitude and direction when adapting model behavior.
  • LoRA+ (2024): Inspired practical optimizer choices for any future adapter training path.
  • rsLoRA (2023): Inspired stable scaling rules for higher-rank adapter experiments.
  • LoRA Learns Less and Forgets Less (Biderman et al., 2024): Motivated skepticism toward naive LoRA as a complete memory or learning system.
  • LoRA Without Regret (Schulman, 2025): Inspired the view that small-rank adaptation can be useful when carefully tuned, but still belongs outside SOMA's core trust boundary.

Memory Architecture and Consolidation

  • Titans (Behrouz et al., 2025): Inspired the four-stage memory lifecycle: short-term candidates, durable episodic memory, forgetting, and semantic consolidation.
  • Hope / Nested Learning (Google Research, 2026): Inspired future work on nested local control loops, while current SOMA keeps learning explicit and evidence-gated.
  • HippoRAG (2024): Inspired graph-indexed, multi-hop recall across projects, policies, corrections, and durable episodes.
  • Latent ODEs (Rubanova et al., 2019): Inspired smooth latent-state tracking between discrete user/tool events.
  • DreamerV3 (2023): Inspired world-model-style latent state as a possible evaluation surface, not as cloud-facing hidden-state transfer.
  • Sleep Replay Consolidation (2022): Inspired review and consolidation cycles that happen after evidence is captured.
  • NeuroDream (Tutuncuoglu, 2024): Inspired sleep-like rehearsal from latent or embedding evidence while keeping outputs review-only.
  • MemoryBank (2024): Inspired decay, forgetting, and access-weighted memory policies.

Meta-Learning and Control Signals

  • ANIL (Raghu et al., 2020): Inspired treating fast adaptation as feature reuse and control-plane routing, not as a memory layer by itself.
  • learn2learn (Arnold et al., 2020): Provided the practical meta-learning reference point behind optional future experiments.
  • HyperMAML (2024): Inspired one-shot hypernetwork adaptation as a possible alternative to gradient-heavy inner loops.
  • In-Context In-Context Learning Neural Processes (2024): Inspired set-conditioned adaptation as a future route for project/persona-sensitive behavior.

Current Status

This repository is the public runtime source set:

  • single Rust crate: crates/soma
  • one binary: soma
  • local SQLite storage under ~/.soma by default
  • MCP server entry point: soma mcp-serve
  • public adapter/reference scripts under tools/
  • public contribution, security, PR, and repository governance policy

The public repo intentionally excludes the private development history, throw-away spikes, legacy multi-process prototypes, internal planning docs, and large private dogfood artifacts. It keeps only the small docs/evals/*.json snapshots that are compiled into the runtime hardening report. Important architecture concepts from the private prose docs are summarized here instead.

Repository policy:

Installation Guide

Prerequisites:

Requirement Notes
Rust Minimum supported Rust version is 1.88.0. The repo includes rust-toolchain.toml.
SQLite No separate install or server is needed. SOMA uses bundled SQLite through rusqlite.
Network Required only for fetching Rust crates, or for optional embedding/model downloads.

Clone and build:

git clone https://github.com/wnsdy95/SOMA-Public.git
cd SOMA-Public
cargo build -p soma
target/debug/soma --help

Install the default CLI:

cargo install --path crates/soma --locked
soma --version
soma --help

Install with the local dashboard:

cargo install --path crates/soma --locked --features dashboard
soma serve --gui --open

Install with optional semantic embeddings:

cargo install --path crates/soma --locked --features embed-onnx

Install with dashboard plus optional context-quality modules:

cargo install --path crates/soma --locked --features "dashboard,cognitive"

The heavier optional features are off by default:

Feature When to enable
dashboard You want the local web transparency UI.
embed-onnx You want ONNX semantic embeddings through fastembed.
cognitive You want optional context-quality diagnostics/modules.
cognitive-train You are experimenting with trainable optional modules.
pty-capture You want advanced PTY terminal capture.
llm-summary You need the legacy Anthropic narrative-summary diagnostic.

Set up shell completions:

mkdir -p ~/.zsh/completions
soma completions zsh > ~/.zsh/completions/_soma

mkdir -p ~/.config/fish/completions
soma completions fish > ~/.config/fish/completions/soma.fish

soma completions bash > soma.bash

Storage is automatic:

  • SOMA creates and migrates its SQLite database on first use.
  • Default DB path: ~/.soma/soma.db.
  • Override with SOMA_DB=/path/to/soma.db.
  • Named personas use isolated DBs under ~/.soma/personas/<name>/soma.db.
  • The DB file is local; no Postgres, Redis, server process, or cloud account is required.

Start, stop, or inspect the resident runtime when you want always-on local operation:

soma start
soma status
soma stop

On macOS, install the LaunchAgent for resident operation:

soma install
soma status
soma uninstall

Verify the installed CLI:

soma diagnose
soma config
soma list

Update or remove the installed binary:

cargo install --path crates/soma --locked
cargo uninstall soma

Removing the binary does not delete local memory. Delete ~/.soma only when you intentionally want to remove local databases, persona stores, logs, models, and adapter spool files.

Usage Guide

The normal SOMA workflow is:

1. Choose or create a persona
2. Activate that persona in a terminal
3. Start a project/session scope
4. Capture local evidence
5. Render or serve ContextEnvelope to a cloud client
6. Capture cloud output as draft claims
7. Verify claims with user/tool/test/local evidence
8. Review learning proposals and promote only verified memory

Create and activate a persona:

soma create research
soma list
eval "$(soma call research --client terminal --project SOMA)"

Check active scope:

soma session status --json
soma projects --brief
soma clients --brief

Capture local evidence:

soma ingest \
  --source terminal \
  --project SOMA \
  --session "$SOMA_SESSION_ID" \
  --command "cargo test" \
  --exit-code 0

Recall and render context:

soma recall --query "what did we decide about ContextEnvelope?"
soma context render --project SOMA --format xml
soma context why --query "ContextEnvelope" --project SOMA

Create a TaskFrame before a cloud call:

soma context task-frame \
  --query "refactor the MCP bridge" \
  --project SOMA

Render a cloud-facing prompt artifact:

soma context prompt \
  --query "refactor the MCP bridge" \
  --project SOMA

Connect an MCP client:

soma mcp-config --client codex-cli
soma mcp-config --client cursor --check --brief
soma mcp-serve

Run the dashboard when installed with dashboard:

soma serve --gui --open

Capture cloud output as draft claims:

soma adapter-cloud-output --json payload.json

Review and verify claims:

soma context review-queue --format json
soma context review-actions --format json
soma context verify-claim \
  --claim-id 1 \
  --verifier user \
  --result confirmed \
  --evidence-kind user \
  --evidence-id "manual-confirmation"

Inspect trust, learning, and hardening:

soma learning --brief
soma context trust-audit
soma context audit --project SOMA
soma context hardening-report --json

Manage memory lifecycle:

soma context l2-promote --project SOMA
soma context l2-promote --project SOMA --apply
soma context l3-decay --dry-run
soma forget --help

l2-promote previews candidates by default. Add --apply only when you want to mutate lifecycle state.

Persona, project, and session rules:

Scope Meaning How to use
Persona Isolated learning state and SQLite DB. soma create <name>, then eval "$(soma call <name>)".
Project Provenance inside the persona store. Pass --project <name> or activate with soma call --project.
Session Terminal/client continuity marker. soma session start, soma session attach, or soma call --client.

Common troubleshooting:

Symptom Check
soma serve is missing Reinstall with --features dashboard.
Dashboard port is busy Use soma serve --gui --port 8766 --open.
Empty dashboard panels Capture/recall some local evidence first; fresh stores are allowed to be empty.
Wrong persona data appears Run soma list and soma session status --json; reactivate with eval "$(soma call <name>)".
MCP client sees no context Run soma mcp-config --client <client> --check --brief and soma clients --brief.
A cloud claim should become memory Use soma context verify-claim; cloud drafts do not promote by themselves.

Why SOMA Exists

Every serious LLM workflow eventually has the same failure mode:

  1. The user explains the project.
  2. The model helps.
  3. The session ends or context is compressed.
  4. The next session forgets subtle constraints.
  5. The user re-explains corrections, preferences, decisions, and local state.

SOMA makes those pieces first-class local state:

  • recent work and active task continuity
  • project and session provenance
  • user corrections
  • unresolved decisions
  • policy-like preferences
  • cited episodic evidence
  • cloud drafts that still need verification
  • durable semantic facts only after evidence gates pass

The goal is not "more prompt text". The goal is better context selection, evidence, and trust boundaries.

Design Principles

  • Local first. The durable memory store is local. Cloud clients receive only generated projections, not the raw database.
  • Evidence before memory. Durable memory must cite local evidence or trusted verification. Cloud output alone is a draft.
  • Deterministic baseline first. Every learning layer has a rule-based path. Neural or learned backends are optional context-quality modules, not the core product promise.
  • MCP as the bridge. Cloud/editor clients read ContextEnvelope resources and call explicit tools through soma mcp-serve.
  • Personas own storage. Projects are provenance. A named persona/profile has its own local DB and adapter spool. Project names describe where experience came from inside that persona.
  • Review beats silent mutation. Promotion, verification, semantic learning, and client-binding proof are visible operator workflows.

High-Level Architecture

flowchart TB
  subgraph local["Local machine"]
    CLI["soma CLI"]
    MCP["soma mcp-serve\nJSON-RPC over stdio"]
    DB[("SQLite WAL\n~/.soma/soma.db")]
    CAP["Capture adapters\nterminal / editor / cloud output"]
    COMP["ContextEnvelope compiler"]
    CRITIC["Trust + learning critic"]
    REVIEW["Review / verification queue"]
  end

  subgraph clients["Cloud LLM clients"]
    CODEX["Codex CLI / app"]
    CLAUDE["Claude Code"]
    CURSOR["Cursor"]
    CONTINUE["Continue"]
    OTHER["Any MCP-aware client"]
  end

  CAP --> DB
  CLI --> DB
  DB --> COMP
  DB --> CRITIC
  CRITIC --> REVIEW
  REVIEW --> DB
  COMP --> MCP
  MCP <--> CODEX
  MCP <--> CLAUDE
  MCP <--> CURSOR
  MCP <--> CONTINUE
  MCP <--> OTHER

The binary is deliberately boring: one Rust executable dispatches the CLI, resident runtime, capture adapters, and MCP server. There is no required remote service.

The Cloud/Local Loop

SOMA is designed for an iterative loop:

SOMA: infer task state, relevant evidence, policy, and open decisions
Cloud: generate a plan, patch, explanation, or draft
SOMA: capture the output as draft claims and critique it against local evidence
User/tool/test/local observation: verify or reject claims
SOMA: promote, correct, decay, or forget memory with cited lifecycle evidence

Cloud LLMs remain the high-capacity synthesis engine. SOMA is the local continuity and evidence engine.

ContextEnvelope

The primary product artifact is the ContextEnvelope: a cited, scoped, cloud-facing projection of local memory.

It is available through CLI and MCP:

soma context render --project SOMA --format json
soma context render --project SOMA --format xml
soma mcp-serve

Canonical envelope sections include:

Section Purpose
thread_state current task continuity and active working set
short_term_candidates recent L2 candidates, anomalies, conflicts, and latent proxy evidence
project_experience projects the active persona has learned from, with provenance
relevant_memory cited episodic evidence selected for the query/scope
stable_facts verified semantic facts and durable abstractions
user_policy evidence-backed user or project preferences
open_decisions unresolved conflicts, decisions, and review candidates
corrections user/tool/local corrections that suppress stale assumptions
evidence top-level evidence references used by cloud-facing sections

Example shape:

Four-Stage Learning Hierarchy

SOMA's core memory architecture is a four-stage learning hierarchy. The stages are not marketing labels; they are lifecycle contracts.

stateDiagram-v2
  [*] --> captured
  captured --> working: active session or thread
  working --> short_term_candidate: episode closes or leaves active budget
  short_term_candidate --> long_term_memory: promoted by evidence policy
  short_term_candidate --> decayed: stale, low salience, or low utility
  short_term_candidate --> forgotten: explicit forget or privacy expiry
  long_term_memory --> semantic_fact: repeated, corrected, or resolved pattern
  long_term_memory --> decayed: low access, low salience, or superseded
  long_term_memory --> forgotten: explicit forget or invalidation
  semantic_fact --> corrected: user correction or stronger evidence
  semantic_fact --> decayed: contradicted or no longer useful
  corrected --> semantic_fact: replacement claim accepted
  corrected --> forgotten: invalidated claim removed from recall
  decayed --> long_term_memory: recalled and re-promoted
  decayed --> forgotten: expiry threshold reached

Every layer must define:

  • storage contract
  • promotion rule
  • decay/forgetting rule
  • evidence rule
  • ContextEnvelope projection
Layer Role Transition Basis ContextEnvelope Projection
L1 Working Memory active thread/task working set active session, continuity, budget thread_state
L2 Short-term Episodic Cache recent candidate memory, novelty, anomaly, conflict recency, salience, anomaly, conflict, candidate expiry short_term_candidates, unresolved open_decisions
L3 Long-term Episodic Store durable retrievable evidence pin, recall frequency, correction/policy/belief reference, anomaly value relevant_memory
L4 Semantic Memory abstracted facts, rules, policies, corrections repeated verified pattern, correction, resolved conflict, policy extraction stable_facts, user_policy, corrections, durable decisions

The 4-stage hierarchy is core. Optional neural or learned backends may assist a layer only when they improve cited ContextEnvelope output. They never replace the deterministic baseline or evidence gate.

Optional Context Quality Modules

The source tree contains optional cognitive modules:

Module Current role
mLSTM candidate working-memory selector/compressor for thread_state
iPC / predictive coding anomaly or novelty signal for L2 candidates
Hopfield optional retrieval/ranking backend for L3 evidence
ANIL-like scope signal control-plane selector for scope/budget/routing, not a memory layer

These are implementation candidates. The product proof is whether the ContextEnvelope becomes more accurate, compact, cited, scoped, and correctable.

Trust Boundary

SOMA treats sources differently:

Trust class Meaning
cloud_draft generated by a cloud model; useful as a candidate but not evidence
user_confirmed explicitly confirmed by the user
tool_verified verified by a tool result or structured local command
test_verified verified by a test/eval result
local_observed observed from local runtime/editor/terminal evidence
correction explicit correction that changes or invalidates prior memory

Cloud output can be captured:

soma adapter-cloud-output --json payload.json

But it is stored as draft claims. It cannot promote to L3/L4 memory until verification exists. This prevents the system from laundering hallucinations into durable memory.

Useful inspection commands:

soma learning --brief
soma context review-queue --format json
soma context verify-claim --help
soma context trust-audit
soma context hardening-report --json

TaskFrame

A TaskFrame is SOMA's local pre-call understanding of a task:

  • what the task is
  • which project/session/persona scope applies
  • what evidence is relevant
  • which local-private fields are safe to project to a cloud model
  • which constraints and open decisions should shape the request

SOMA persists both a local full form and a cloud-redacted projection policy. Secret-like or blocked fields fail closed before cloud projection.

soma context task-frame --query "refactor the MCP bridge" --project SOMA

Personas, Projects, and Sessions

Named personas isolate local SOMA learning state:

soma create research
soma list
eval "$(soma call research --client codex-cli --project SOMA)"

The persona/profile owns:

  • SQLite DB path
  • adapter spool paths
  • local policy/corrections/memory

The project is provenance inside that persona store. This mirrors how a person learns from multiple projects without pretending each project is a separate mind.

Useful commands:

soma projects --brief
soma session status --json
soma clients --brief

Local Dashboard

The dashboard is optional and feature-gated. Default builds do not expose soma serve, so build or install SOMA with the dashboard feature first.

Build and run from the repository:

cargo run -p soma --features dashboard -- serve --gui --open

Or build once, then run the binary:

cargo build -p soma --features dashboard
target/debug/soma serve --gui --open

Install a dashboard-enabled binary:

cargo install --path crates/soma --features dashboard
soma serve --gui --open

What starts:

  • soma serve --gui starts the local web server and blocks until Ctrl-C.
  • The browser opens automatically when --open is passed.
  • Default address: http://127.0.0.1:8765.
  • Use --port when the default port is busy.
  • Use --bind only when you understand the security boundary. The default is localhost. Binding to 0.0.0.0 exposes the dashboard to the local network, and v1.x has no authentication layer.

Examples:

soma serve --gui
soma serve --gui --open
soma serve --gui --port 8766 --open
soma serve --gui --bind 127.0.0.1 --port 9000

There is no separate backend to start. The dashboard command itself starts the Rust/Axum backend and serves both the HTML UI and the JSON API routes. The resident runtime is also not required just to view the dashboard, although running clients or adapters may separately use the resident runtime.

SQLite is automatic:

  • SOMA uses local SQLite; no Postgres, Redis, or external DB service is needed.
  • Dashboard DB resolution follows the active SOMA environment: SOMA_DB when set, otherwise ~/.soma/soma.db.
  • soma call <persona> sets SOMA_DB, so a dashboard launched from that shell reads that persona's isolated store.
  • On first use, SOMA creates the parent directory, creates the SQLite file, applies pragmas, and runs migrations.

Persona-scoped dashboard example:

soma create research
eval "$(soma call research --client terminal --project SOMA)"
soma serve --gui --open

The dashboard tabs are:

Tab What it shows
Operations Client binding readiness, current project/persona scope, dogfood status, and semantic learning review state.
Quality Optional module diagnostics mirrored from soma inspect weights. Empty rows are acceptable on fresh installs.
Recall Recent recall traces from local recall activity. Empty state is normal before recall has run.
Memory Memory state, policy/correction candidates, corroborations, contradictions, and note-pin timeline.
Architecture Interactive diagram of the ContextEnvelope bridge and local memory path.

Dashboard API routes:

Route Purpose
/health Liveness check.
/api/operations/status Read-only operations/readiness snapshot.
/api/quality/weights Read-only quality/weight diagnostics.
/api/training/weights Historical alias for quality diagnostics.
/api/recall/recent Recent recall trace snapshot.
/api/memory/state Memory state snapshot.
/api/memory/timeline Recent note-pin timeline.

Useful fallbacks when the dashboard cannot bind a port:

soma clients --brief
soma projects --brief
soma learning --brief
soma inspect weights

MCP Resources and Tools

Run the MCP server:

soma mcp-serve

Common resources:

  • soma://context/current
  • soma://context/by-query?q=<text>
  • soma://context/project/<name>
  • soma://context/session/<session_id>
  • soma://context/thread/<thread_key>

Common MCP tools include:

  • soma_recall
  • soma_capture_turn
  • soma_capture_cloud_output
  • soma_verify_claim
  • soma_review_queue
  • soma_review_actions
  • soma_review_report
  • soma_review_render
  • soma_review_action
  • soma_context_why
  • soma_context_audit
  • soma_trust_boundary_audit
  • soma_product_hardening_report

MCP reads and explicit writes are the bridge. Prompt-prefix injection is not the primary acceptance path.

Client Integration Model

SOMA supports conservative integration with:

  • Claude Code
  • Codex CLI
  • Codex app
  • Cursor
  • Continue
  • generic MCP clients

The important distinction:

  • MCP registration proves a client can read/query/inspect SOMA.
  • Explicit capture proves a client or wrapper submitted a turn.
  • Private app readiness requires stronger proof: app hook, in-client render, and review-action evidence must replay cleanly.

SOMA does not claim that a private editor integration works just because a config file exists.

soma mcp-config --client codex-cli
soma mcp-config --client cursor --check --brief
soma clients --brief
soma adapter-binding-proof --client cursor --proof-session --brief

Reference adapter assets live in tools/:

  • tools/client-bindings/*.json.example
  • tools/soma-adapter-*.sh
  • tools/soma-codex-*.sh
  • tools/soma-client-*.sh
  • tools/soma-review-*.sh
  • tools/soma-continue-devdata-*.py

Common Recipes

Fresh local setup:

cargo install --path crates/soma --locked
soma create default
eval "$(soma call default --client terminal --project my-project)"
soma diagnose

Dashboard setup:

cargo install --path crates/soma --locked --features dashboard
eval "$(soma call default --client terminal --project my-project)"
soma serve --gui --open

Cloud-client setup:

soma mcp-config --client codex-cli
soma mcp-config --client cursor --check --brief
soma clients --brief

Daily context loop:

soma ingest --source terminal --project my-project --session "$SOMA_SESSION_ID" \
  --command "cargo test" --exit-code 0
soma context render --project my-project --format xml
soma context review-queue --format json
soma context trust-audit

Command Reference

soma --help is the source of truth for exact flags. This section lists the public command surface and explains what each command is for.

Global flags:

Flag Meaning
--color <auto,always,never> Control diagnostic color output. auto respects NO_COLOR and TTY detection.
-v, -vv, -vvv Increase logging verbosity from info to debug to trace. RUST_LOG still wins.
-q, --quiet Lower base logging to warnings.
-h, --help Print help for the selected command.
-V, --version Print the SOMA version.

Top-level commands:

Command Purpose
soma list List named local personas and their isolated stores. The active persona is marked in human output.
soma create <name> Create a named persona under ~/.soma/personas/<name>/ with its own private soma.db.
soma call <name> Print shell exports that activate a persona for the current terminal. Alias: soma activate <name>.
soma start Start the resident runtime in the foreground.
soma stop Ask the resident runtime to shut down.
soma status Report resident runtime and feature status.
soma session ... Manage shell-visible session scope for multi-terminal work.
soma install Install the LaunchAgent for always-on resident operation.
soma uninstall Remove the LaunchAgent.
soma ingest Record an AI interaction or terminal episode into the active store.
soma adapter-capture Record one normalized editor or CLI adapter turn through the ingest pipeline.
soma adapter-cloud-output Capture cloud output as untrusted draft claims tied to a TaskFrame. It does not promote claims without later verification.
soma adapter-lifecycle Normalize one raw editor lifecycle event into SOMA's adapter spool contract.
soma adapter-spool Drain a checkpointed JSONL spool of normalized adapter events.
soma adapter-spool-append Append one normalized event to an adapter JSONL spool without directly ingesting it.
soma adapter-binding-proof Record observed proof for a client binding, render proof, or review-action proof.
soma clients Read-only readiness report for Claude Code, Codex CLI, Codex app, Cursor, and Continue.
soma learning Read-only semantic learning and L4 review readiness report.
soma projects Show project provenance accumulated inside the active persona store.
soma recall Recall ranked local episodes for inspection.
soma context ... Render, audit, verify, and operate on ContextEnvelope, TaskFrame, review, and learning surfaces.
soma config Print resolved local configuration.
soma inspect Inspect local context store diagnostics.
soma forget Delete stored context episodes through the audited forgetting path.
soma mcp-serve Serve MCP resources over stdio for Claude Code, Codex CLI, Codex app, Cursor, and Continue.
soma mcp-config Generate or check dry-run MCP registration JSON for supported clients.
soma diagnose Print one support/debug JSON object with version, features, liveness, DB stats, envelope disposition, and failures.
soma backfill Backfill primary embedder vectors after an embedder or index change.
soma logs tail Print the last lines of SOMA's rolling local log file.
soma completions <shell> Emit shell completion scripts for bash, zsh, fish, elvish, or PowerShell.
soma help [command] Print command help.

Session commands:

Command Purpose
soma session start Start a SOMA-managed shell session and print eval-able exports.
soma session attach Attach the current shell to an existing SOMA session id.
soma session status Show SOMA session variables visible to the current process.
soma session clear Print commands that clear SOMA session variables from the shell.

Context commands:

Command Purpose
soma context render Render a scoped ContextEnvelope for inspection or tooling.
soma context prompt Render a cloud-facing artifact containing a TaskFrame plus ContextEnvelope.
soma context task-frame Build and persist a deterministic TaskFrame for inspection.
soma context task-frames retention Report or apply retention for old unreferenced TaskFrames.
soma context task-frames outcomes List evidence-backed TaskFrame outcome records.
soma context task-frame-outcome Record an evidence-backed outcome for a persisted TaskFrame.
soma context l3-decay Inspect or apply stale, low-access L3 proxy decay policy.
soma context l2-promote Promote eligible L2 latent proxies to L3 through explicit lifecycle policy.
soma context latent-predict Predict active evidence-backed latent proxies for a query without mutating memory.
soma context latent-packet Render an inspectable latent interface packet for future cloud latent channels.
soma context latent-eval Score latent predictor hits against J