s0ma
Your AI doesn't know what you know about your code: why each part exists, what it promises, and what it must never do. So you explain it again every session, or it guesses.
s0ma is an open-source language for building software that explains itself to you and your AI. It moves that knowledge into the code, where the build holds it true, so you, your coding agent, and the AI running your application all read the same account. s0ma contains no AI model and needs none.
What you get
- Context that can't rot. A notes file for your agent goes stale without anyone noticing. Here the description compiles with the code, so an undescribed part fails the build and a drifted description fails the release gate.
- One answer for every reader.
s0ma inspect, the studi0 visual environment, a Python API, and an MCP server all answer from the same declarations: what exists, what it promises, what it depends on, and what a change would break. - Agents that start informed. A coding agent reads what each part is for instead of reconstructing it from source.
- Ordinary Python, adopted gradually. The build emits plain
.pyfiles you can read, type-check, and ship, and an existing codebase can convert one module at a time.
How it works
You write .s0ma files. Each part opens with a declaration of what it is for, what it expects, what it guarantees, and what it must never do, followed by a line of three hyphens and then ordinary Python:
nerve greet :: DOMAIN
kind: FUNCTION
visibility: PUBLIC
intent: "Return a greeting for the name it is given."
expects: "A name, as text."
guarantees: "Returns a greeting that contains the name."
forbids: none
...
---
def greet(name: str) -> str:
"""Return a greeting for the name it is given."""
return f"Hello, {name}!"
The ... stands for twelve more lines, nearly all of them none, so that an unanswered question never looks like an answer of nothing. Your first project has the whole file, and the quick reference has every line a declaration can carry.
s0ma build turns the source into plain Python and writes beside it a machine-readable record of everything declared, which we call the self-model. Because a part has to be declared to exist, that record can't drift from the code without something refusing to build. The vocabulary comes from the nervous system, since s0ma connects a brain, such as a language model, to the body of software it acts on.
| Word | What it is |
|---|---|
nerve |
A working part: a function, a class, or a service. |
cell |
Where data lives. |
ganglion |
A part that watches and responds. |
axon |
A declared dependency between two parts. |
How agents meet it
An agent building a s0ma application works through the s0ma command line or the authoring MCP server, and the guardrails refuse an undeclared or drifted change before a person sees it. When the application runs, it loads the self-context every build emits and hands it to the agent operating it, as quoted project data rather than instructions.
Is it for you?
It probably fits if:
- an AI works on your system or runs it, and you want its answers to come from the project rather than a guess
- you keep answering "what does this do, and what breaks if I change it?" by reading code
- you build agents, AI-enabled applications, or autonomous systems whose operator needs to ask the system what it is
It probably doesn't if:
- the work is a throwaway script, or has no Python in it
- the codebase can't accept generated Python beside your sources
- your team won't let a release fail on a part's purpose and boundaries
The last of these is the whole mechanism, and without it s0ma is overhead.
s0ma doesn't replace your tests or your production monitoring. It tells you what the system is, but not whether it is working.
Get it
The code is in the public repository at github.com/kn0w-thyself/s0ma, with the install steps kept in one place in its README. Getting started takes you through a first project, and if you already have a working application, retrofitting an existing codebase converts it a module at a time with the code working at every step.
Questions and bug reports are welcome in the repository's issues and discussions, or by email at hello@kn0wthyself.ai.