Soma
Soma lets you change tools without losing the assistant. It keeps the durable assistant body in one filesystem-native home, then projects that body into Codex, Claude Code, Pi.dev, Cursor, and future Cortex/Myelin flows.
Source on GitHub ↗ README ↗ Architecture ↗
Why Soma exists
Coding agents are useful, but every substrate wants to own the assistant. Codex has its instruction files. Claude Code has rules, hooks, settings, and skills. Pi.dev has extensions. Cursor has rules. Each substrate can carry context, but none of them should be the permanent source of who the assistant is, what it has learned, and how it works.
Soma separates the assistant from the substrate. The durable core holds identity, telos, ISA, skills, memory, policy, and learning. Each adapter turns that core into the substrate-native shape needed for one tool. The user can switch substrates, run several at once, or add a future Cortex/Myelin daemon without rebuilding the assistant from scratch.
The short version
Change the substrate, not the assistant.
A useful assistant is not just a prompt. It is an operating context around the model: who it serves, what matters, what work is active, which skills it can use, what it has learned, which boundaries it must respect, and how it proves that work is done. Soma keeps that operating context portable.
The compartments
Soma uses a cellular metaphor. The whole system is the assistant body; the durable pieces inside it are compartments:
- Identity — who the principal is and who the assistant is.
- Telos — goals, principles, commitments, strategies, and desired state.
- ISA — ideal-state artifacts: the definition of done and the verification contract.
- Skills — portable capability folders with workflows, references, examples, and tools.
- Memory — file-backed work, state, learning, relationship, knowledge, and evidence stores.
- Policy — privacy, permission, security, and verification rules.
- Learning — explicit promotion paths from verified work into durable lessons.
These are not a stack. They are peer compartments. A projection may summarize them, cache them, or present them in a substrate-specific shape, but it does not become the source of truth.
How it is being used
Soma is already used as the shared operating context for day-to-day agent work. At session start, a substrate can load the same assistant identity, active work pointer, memory summary, skills, policy, and Algorithm guidance. During work, lifecycle events and result summaries write back through Soma's policy gates instead of disappearing into a substrate-local transcript.
The practical pattern is simple: keep the assistant core in Soma, project it into the substrate being used today, let the substrate do the work it is good at, and write durable state back only through the Soma contract.
arc install @metafactory/soma
soma init --yes
soma install codex --apply
soma install claude-code --apply
soma install pi-dev --apply
soma install cursor --applyAlgorithm and ISA
Soma's most visible working method is the Algorithm: a deterministic phase harness around non-trivial AI work. A run moves through OBSERVE, THINK, PLAN, BUILD, EXECUTE, VERIFY, LEARN, and COMPLETE. The assistant can propose content, but Soma owns the run state and phase gates.
ISA supplies the definition of done. Criteria, plan steps, verification evidence, capability choices, and learning all stay attached to the run, so a task can move from Codex to Claude Code to Pi.dev without losing what has already been decided or verified.
Memory and policy
Soma starts with plain files rather than a hidden database. Memory search, result capture, feedback capture, promotion, telemetry, and Algorithm state all work over inspectable files and append-only events. Durable learning is deliberate: verified work can be promoted; raw prompts and full transcripts are not silently stored by default.
Policy follows the same portability rule. Soma uses runtime policy inspection for prompts, tool calls, permission requests, and configuration changes. Hooks, extensions, MCP gates, and daemon dispatchers are projection mechanisms; the core policy language stays substrate-neutral.
Relationship to this stack
Soma does not replace myelin, cortex, arc, or metafactory. It sits next to them:
- myelin owns the protocol stack and envelope semantics.
- cortex owns the collaboration surface and operator visibility.
- arc owns package installation and distribution.
- metafactory owns the trusted distribution hub.
- Soma owns the portable personal assistant core.
The planned Cortex/Myelin integration is daemon-shaped: Soma can become a long-running assistant agent that consumes Myelin-owned contracts through Cortex, while preserving the same memory, policy, and writeback boundaries used by substrate sessions.
PAI and TELOS lineage
Soma is inspired by Daniel Miessler's Personal AI Infrastructure and TELOS. PAI proved that deep operating context can become active inside an assistant; TELOS gave that context a structure of missions, goals, strategies, projects, and measures. Soma keeps that lineage explicit while making the result independent, MIT-licensed, substrate-portable, and inspectable.
The trust and security caveat matters: portability is only useful if the generated files, policy gates, and writeback behavior can be inspected. Soma's public proof points are readable projections, reversible installs, policy checks, and explicit verification evidence.
Canonical docs
- README.md — purpose, quickstart, PAI migration, substrates, status.
- CONTEXT.md — canonical Soma vocabulary.
- docs/architecture.md — core compartments, adapters, modes, Meta Factory boundaries.
- docs/boundaries.md — source-of-truth boundaries across nearby systems.
- docs/substrate-adapters.md — Codex, Claude Code, Pi.dev, Cursor, and Cortex/Myelin adapter behavior.
- docs/integration-with-pai.md — PAI migration walkthrough.