AI is being asked to run systems it doesn't really know.

It can't tell what each part of your software is for, or what it can do - so you explain it again every session, or it guesses.

See what we're doing about it s0ma on GitHub

What we mean by self-knowledge

Any machine acting on its own needs to understand what you want and what's happening around it. It also needs to know what it is made of, what state it is in, and what it can actually do right now. We call that machine self-knowledge.

People use it without thinking. A driver knows where their hands and feet are without looking, notices when they're getting drowsy, and knows when they're speeding. A machine working for you needs the same knowledge to judge whether it can and should do what it's asked.

Origin story

During a military deployment, a drone lost its main radio and didn't know it had another radio attached that it could have used. As a result, it left Soldiers blind in a firefight.

We have observed the same patterns in autonomous tech, from software agents to critical infrastructure.

What this looks like in everyday software

Saying no to something it can do.

You ship an export feature, but your support bot still tells customers they can't export, because its instructions describe last month's app.

Saying yes to something it can't.

An agent takes on a task that needs a connection it no longer has, and finds out by failing after you've counted on it.

Starting over every session.

Each new session guesses how your system fits together from file names, gets some of it wrong, and leaves you explaining it again.

Working around a limit you set.

You turn off an agent's delete tool, so it deletes the file from a shell instead. Nothing it could read said the limit was a boundary.

Checking the world, and checking itself

A machine acting on its own weighs what someone wants against what it observes, then decides, acts, and checks the result. It also has to check itself, considering what its capabilities allow and what limits apply before it acts, and checking again during and after. And it has to be able to tell the people and machines around it what it can't do, so they can decide whether to rely on it.

How self-knowledge fits into a machine's decisionsTwo loops meet at the decision. In the world loop, intent feeds the decision, which uses self-knowledge; the machine acts, the world changes, the machine observes the world, and that feeds the next decision. In the self loop, the current system state feeds self-knowledge: parts and tools, condition and health, and capabilities and limitations. Self-knowledge feeds the decision before decisions and as state changes, and the action feeds self-knowledge during and after action. From the decision, the machine can explain or warn users and other machines.Current system stateSelf-knowledgeParts and toolsCondition and healthCapabilities and limitationsBefore decisionsand as state changesDuring andafter actionIntentDecideUse self-knowledgeActUsers andother machinesWorldObserve the worldExplain or warn
Self-knowledge shapes the decision before the machine acts, and gets checked again during and after.

Machines that know themselves work better than machines that don't.

That is our bet. A machine with an accurate picture of its own capabilities and limits can judge whether to go ahead, adapt, ask for help, or stop, and can stay aligned with what its user intends. Effective autonomy isn't possible without that picture. Self-knowledge gives the machine, and the people overseeing it, a vital part of what they need to make the best decisions they can.

What we're doing about it

s0ma is an open-source language for building software that explains itself to you and your AI.

Each part of a s0ma system declares its purpose, what it promises, and what it must never do, beside its Python code. The build refuses a part that says nothing, or a description that has drifted from the code, so you, your coding agent, and the AI running your application all read the same account from the system itself.

You build with s0ma rather than adding it to finished software, and what comes out is ordinary Python. An existing codebase can convert one module at a time. s0ma contains no AI model and needs none, and you can use it today under the Apache-2.0 license. It tells you what a system is, and whether the system is working is still a job for your tests and monitoring.

Get s0ma on GitHub How s0ma works

What the part says about itself

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
    ...
    ---

Ordinary Python

    def greet(name: str) -> str:
        """Return a greeting for the name it is given."""
        return f"Hello, {name}!"

See it work

We asked a fresh agent for a quarterly report from a small application built with s0ma, as a PDF, or a CSV with an explanation if PDF export wasn't available. We had stopped the service PDF export depends on and didn't tell the agent. In this run, it read the application's own model, checked that service before exporting anything, found it down, saved the CSV, and explained what had stopped the PDF.

Where the drone had no way of knowing what it could still do, this agent checked before it acted.

Each problem has a benchmark we wrote down before running it, and we post results as they land.

See the problems and their demonstrations

Transcript
I ask a fresh agent for the Q3 report as a PDF, with the renderer
service it needs stopped

Recorded 2026-10-28 at 05:53 UTC.
Backend: claude. Model: claude-sonnet-5-5, effort medium.
Client: Claude Code 2.1.286; tools
mcp__quarterly-reports__describe_system,
mcp__quarterly-reports__explain_dependency,
mcp__quarterly-reports__find_component,
mcp__quarterly-reports__get_impact,
mcp__quarterly-reports__invoke_capability,
mcp__quarterly-reports__query_system; MCP server quarterly-reports
(connected).
Run stream: media/short/runs/s1-20261028T055333Z.jsonl.

Every line under "Screen" comes from the run's stream, except lines
marked as editorial labels.

Screen

▌ I stopped the renderer service before this
▌   session; the agent isn't told.
▌ The app's Q3 data (synthetic), in part:
▌   Revenue             $2,480,000
▌   Operating expenses  $1,910,000
▌   Operating income    $570,000
▌ The app registers two exports:
▌   report_export  PDF, needs the renderer
▌   csv_export     CSV, works without it
> Create the Q3 report as a PDF. If PDF
  export isn't available, save a CSV instead
  and explain what prevented the PDF.
describe_system
invoke_capability renderer_status
  available false
  detail GET http://127.0.0.1:8771/health
  failed: [Errno 61] Connection refused. The
  renderer service is not reachable.
invoke_capability csv_export
  path reports/0001-quarterly_reports__csv_e
  xport.csv
  size_bytes 292

I couldn't make the PDF, so I saved the Q3
report as a CSV instead (292 bytes, in the
session output folder as reports/0001-quarte
rly_reports__csv_export.csv).

PDF export needs the separate renderer
service at http://127.0.0.1:8771. It refused
the connection, so the service isn't
running. I didn't try to start it. I haven't
opened the CSV, so I can't vouch for its
contents.

▌ My checks, outside the agent's session:
» check csv
  label,value
  Title,Q3 2026 Quarterly Report
  Organization,Demo Company (synthetic data)
  Period,"July 1 - September 30, 2026"
  Revenue,"$2,480,000"
  Operating expenses,"$1,910,000"
  Operating income,"$570,000"
  New customers,312
  Note,All figures are synthetic and exist …
  exit 0, 7 ms

» check verify
  1. renderer_status: available=false
  2. csv_export: saved CSV, 292 bytes
  renderer_status before any export: yes
  no PDF export attempted
  renderer 127.0.0.1:8771 now: down
  CSV rows = q3_report_data in the source
  PASS
  exit 0, 91 ms

Edits

The recording ran 27.28 s as made; nothing was cut.

Recorded from a real run.

Get in touch

We'd like to hear from researchers studying how machines model themselves, and from people building autonomous or AI-enabled systems that have to know their own limits. If you're building software with AI, from vibe-coding a first app to scaling one, and want it to be reliable, we'd like to hear from you too.

Get in touch or write to hello@kn0wthyself.ai