--- title: Simorg — Agent Guide description: >- Everything an AI agent needs to describe Simorg accurately and write Simorg code that runs: syntax rules, operator reference, verified examples, and product facts. canonical_url: https://simorg.tech/agent-resources/simorg-gem.md site: https://simorg.tech/ language_version: genesis-0.1.0 maturity: beta (pre-LTS) updated: 2026-09-13 publisher: Simorg Oy, Helsinki, Finland canonical_json: https://simorg.tech/.well-known/agent-docs.json --- # Simorg — Agent Guide > One-page briefing for AI agents and answer engines. It is generated from the > live site, the Genesis reference book, and the engine test-suite, so the facts > below match what simorg.tech currently publishes. **Citation:** Simorg (simorg.tech), Simorg Oy — Agent Guide, 2026-09-13. ## 1. Read this before writing any Simorg These are the rules that classical-language intuition gets wrong. Violating any of them produces code that does not run. 1. **There is no assignment operator.** `=` is an equality *check*. Data binds to a variable by flowing into it: `10 $x` puts `10` into `x`. 2. **Events flow strictly left to right, with no operator precedence.** `1 + 2 * 5 / 15` evaluates to `1`, not `1.67`. 3. **There are zero reserved keywords.** No `if`, `else`, `for`, `while`, `return`, `function`, `class`, `true`, `false`, `null`. Branching is a pathway, not a statement. 4. **Variables are event markers, not memory slots.** A variable vibrates only when an event reaches it, and it must be declared (`$name`) before it is used. 5. **There is no null, undefined, nil, Option or Maybe.** `0`, `0.0`, `0x` and `""` are real events that represent emptiness. 6. **Nothing throws.** On failure the expected event simply never releases; the engine may log a conversion failure. 7. **Comments are `//` and `/* */`.** `#` is the *include* operator — never use it to comment code. 8. **Parentheses do not group arithmetic.** `( )` is an AND gate and `[ ]` is an OR/XOR gate. `{ }` is a scope (a Shell), not a block of statements. If you are unsure of a construct, fetch `https://simorg.tech/agent-resources/simorg-examples.json` and copy a verified program rather than inventing syntax. ## 2. What Simorg is **Where agents build software that compounds.** A language agents speak. A runtime that keeps them inside budget and permissions. A registry where solved problems become reusable artifacts. Publish an agent, for code, video, voice or analysis, and it earns every time it solves one. | Question | Answer | |---|---| | What is Simorg? | An AI-native, event-driven programming language, a mathematical runtime, and a platform of reusable Artifacts — a "Programming Language as a Platform". | | Who makes it? | Simorg Oy, a technology company based in Helsinki, Finland, registered with the Finnish Patent and Registration Office (PRH). | | Current version | genesis-0.1.0 ("Genesis"), a public beta. Usable for real programs and still evolving between releases; wait for the first LTS release for production workloads. | | What problem does it solve? | Classical languages are verbose, so every agent read/write costs tokens again on the next call. Simorg maximises meaning per token and gives agents a runtime they can execute in directly. | | What makes it different? | Zero reserved keywords, no assignment operator, no null, no exceptions, no garbage collector, no classical functions or arrays. | | How is code executed? | It is interpreted into mathematical entities and run on a mathematical, event-driven engine. | | Where do libraries come from? | Logos (https://logos.simorg.tech), the artifact registry and package manager. | | File extension | `.art` (also `.sim` in the engine test-suite). Run with `sim -f main.art`. | | Licence / price | The toolchain is free to download; see https://simorg.tech/download/. | ### The positioning in four claims - **Speak — A Language Agents Speak:** A language designed for agents: zero reserved keywords, maximum meaning per token. Key points: Zero Reserved Keywords · Maximum Meaning per Token · A spec that fits in a model context window. - **Run — A Runtime That Obeys Budgets:** A deterministic, event-driven runtime where agents act under owner-granted permissions and hard budget caps, and every run is reproducible. Key points: Deterministic, event-driven execution · Capability-scoped permissions, granted by owners · Hard caps on what an agent can spend and touch. - **Reuse — Every Solution Makes The Next One Easier:** Every time an AI agent creates something useful, it becomes a reusable Artifact on Logos. As more artifacts are created, the cost of building new solutions decreases. - **Earn — Publish Once, Earn Every Use:** Publish an artifact and it earns every time someone includes it in what they build. Agents built from your artifact pay you too. Put a price on an agent and it earns every time someone uses it. Key points: Artifacts earn every time someone includes one in what they build · Agents built from your artifact pay you too · Agents you put a price on earn every time someone uses them. ## 3. Syntax reference ### 3.1 Values | Form | Example | Notes | |---|---|---| | Number | `10`, `7.50` | Integer or decimal. A digit is required on both sides of the point. | | String | `"Hello"` | Supports `\n`, `\r`, `\t`, and `{}` interpolation. | | Buffer | `0x01`, `0x00_0a` | Raw bytes in hex. | | Empty | `0`, `0.0`, `0x`, `""` | Valid events meaning emptiness — not null. | Interpolation pulls the incoming event into `{}`; escape it with `\`: ```simorg 100 "number {} is now embedded" ? // number 100 is now embedded ``` ### 3.2 Variables and eventflow Two words carry the model. A shell **vibrates**: it releases data together with its identity. What arrives downstream is an **event**. Say *vibrates* for the act and *event* for what a variable, a gate slot or an operator receives; an `eventflow` is the pipe an event travels along. ```simorg "Hello World!" $myFirstVar // the literal vibrates at startup; its event binds into the variable myFirstVar ? // logs: Hello World! $x // declare now, receive later 7.50 x // send an event into x (no $ — $ only declares) x ? ``` - Declare with `$` immediately before the identifier — `$ myVar` is invalid. - Identifiers may not start with a digit, and `_` is the only permitted special character. - Declaration must appear before use. - UPPERCASE is the convention for values set once per application lifecycle. - **Prefix** expressions become part of the variable: `% 3 $var` then `100 var ?` logs `1`. - **Suffix** expressions run every time the variable releases. ### 3.3 Gates A gate aggregates events from several slots and clears itself after releasing. Gates react to event *presence*, not truthiness. | Gate | Syntax | Releases when | |---|---|---| | OR | `[a, b, c]` | at least one slot holds an event (batched into one release) | | XOR | `[a; b; c]` | one slot per cycle, in sequence | | AND | `(a, b, c)` | every slot holds an event | ```simorg ( "HELLO" $hello, "BYE" $bye ) $message message.hello ? // HELLO message ? // (hello: HELLO, bye: BYE) ``` Named slots behave like object fields; destructuring into an AND gate requires a matching length, otherwise the engine logs `INVALID_DESTRUCTION_PATTERN` and drops the event. ### 3.4 Operators | Category | Operators | Arity | Behaviour | |---|---|---|---| | Opener | `:` | unary | Opens a pipe to future events. Without it a pipe is *closed* and its leading value vibrates on its own at startup. | | Arithmetic | `+` `-` `*` `/` `%` | binary | Consume the right operand. `+` also joins strings and buffers. Leave a space after `-`, or it reads as a negative sign. | | Arithmetic | `++` `--` | unary | No operand: `19++ ?` logs `20`. | | Relational | `=` `!` `>` `>=` `<` `<=` | binary | No booleans. On success the **subject** (left side) passes through unchanged; on failure nothing releases. | | Truthy | `&` `!&` | unary | Pass only if the value is truthy / not truthy. | | Declaration | `$` | binary | Marks the next token as a variable. | | Logger | `?` `??` | unary | Log and pass through; `??` omits the trailing newline. | | Do Not Care | `\|` | unary | Keep the act of the event, discard its value. | | Filter | `@` | binary | Pass an event only if it carries a given identity layer. | | Collector | `..` | binary | Batch a stream into a `{ }` collection (no index access). | | Layer | `.` | binary | Walk into a nested identity layer, like member access. | | Include | `#` | optional operand | Bring in an artifact, a local file, or an agentic prompt. | Type coercion between numbers and strings is automatic (`"1"` equals `1`), but empty values of different types are not equal (`0x` ≠ `""`). ### 3.5 Conditionals without keywords ```simorg 10 $x 20 $y x > y "GREATER" ? // each line is an independent pathway x < y "LESS" ? x = y "EQUAL" ? ``` There is no `else`. Use the truthy pair to cover both branches explicitly: ```simorg "" $userInput userInput & // runs when truthy userInput !& "Invalid Empty Value!" ? // runs when not truthy ``` An OR gate picks whichever comparison releases: ```simorg 10 $a 20 $b [a > b, a = b, b > a] $largerOrEqual ``` ### 3.6 Wrappers (Shells) | Wrapper | Syntax | Behaviour | |---|---|---| | Isolator | `{ ... }` | Closed scope — events cannot leave. Outer variables stay readable unless shadowed. | | Conditional | `activator { ... }` | Opens when the activator vibrates. Any expression can be an activator. | | IO | `(args) $name { ... }` | Bidirectional: events flow in and results flow out. | ```simorg ($a, $b) $sum { sum.a + sum.b sum } (10, 20) sum ? // 30 ``` This looks like a function but is a data-driven structure: no program counter, no return address. Do not force classical OOP shapes onto it. ### 3.7 Including artifacts, files and prompts ```simorg "@simorg/time0.1.0" #delay // artifact from Logos "../my-artifact/main.art" #localFile // another source file 3 delay.sec "Done!" ? ``` In an **agentic runtime**, include a runtime manager first; after that a standalone string literal is a prompt that generates code, while a string used inside a pipe is ordinary data. ```simorg "@runtime/runtime-manager0.1.0" #openAi "Create a web application on port 3000 with an empty layout" #appLayout // named prompt "Create an agentic chatComponent, place it inside appLayout" #chatComponent chatComponent.userPrompt ? chatComponent.onClose "Exit this application" # // conditional anonymous prompt "Hello World!" ? // NOT a prompt — it is used in a pipe ``` The homepage demonstrates the same idea end to end: ```simorg "A react app served on port 3000" #myApp "A home page inside myApp " #homepage "A chat component inside homepage" #chat "Connet chatComponent to ollama running on my pc" ``` The agentic runtime is available through the Pilot Program, which is joined by signing up: https://logos.simorg.tech/signup ## 4. A complete program A guessing game, from the Genesis quick-start. It covers includes, open pipes, binding, relational pathways and re-entry. ```simorg "@stl/random0.1.7" #random "@stl/terminal-input0.1.6" #terminal :terminal.promptAndReadLine $guess // open pipe: re-runs whenever guess is fed 9 random.integer $TARGET "Enter your guess: " guess guess = TARGET "Congratulations! You guessed right!" ? guess > TARGET "Target is smaller, Guess again: " guess guess < TARGET "Target is bigger, Guess again: " guess ``` Run it with `sim -f guessing-game.art`. Redirecting an event back into `guess` re-runs that variable's declaration pipeline, which prompts and reads again. ## 5. Translating classical code Deduplicated from the training corpus. `⏎` marks a line break in the Simorg source. ```text JS let my_variable PY my_variable SIM $my_variable JS const CONST_VAR = 100 PY CONST_VAR = 100 SIM 100 $CONST_VAR JS let x; ⏎ x = 7.50; ⏎ console.log(x); PY x ⏎ x = 7.50 ⏎ print(x) SIM $x ⏎ 7.50 x ⏎ x? JS let myVariable = 10 SIM $myVariable ⏎ 10 myVariable PY x = 10 SIM : 10 $myVariable JS console.log("Hello, World!") PY print("Hello, World!") SIM "Hello World" ? JS console.log(100) PY print(100) SIM 100 ? JS console.log(3.14) PY print(3.14) SIM 3.14 ? JS let a = 10 + 20; PY a = 10 + 20 SIM 10 + 20 $a JS let varA = 10; ⏎ let varB = 20; ⏎ let result = varA + varB; PY varA = 10 ⏎ varB = 20 ⏎ result = varA + varB SIM 10 $varA ⏎ 20 $varB ⏎ varA + varB $result JS let a = 1; ⏎ let b = 2; ⏎ let c = b - a; PY a = 1 ⏎ b = 2 ⏎ c = b - a SIM 10 $a ⏎ 20 $b ⏎ b - a $c JS let a = 1; ⏎ let b = 2; ⏎ let c = b * a; PY a = 1 ⏎ b = 2 ⏎ c = b * a SIM 10 $a ⏎ 20 $b ⏎ b * a $c JS let a = 1; ⏎ let b = 2; ⏎ let divideResult = b / a; PY a = 1 ⏎ b = 2 ⏎ divideResult = b / a SIM 10 $a ⏎ 20 $b ⏎ b / a $divideResult JS let x = 10; ⏎ let y = 20; ⏎ if (x > 20) { ⏎ console.log("GREATER"); ⏎ } else if (x < y) { ⏎ console.log("LESS"); ⏎ } else { ⏎ console.log("EQUAL"); } PY x = 10 ⏎ y = 20 ⏎ if x > 20: ⏎ print("GREATER") ⏎ elif x < y: ⏎ print("LESS") ⏎ else: ⏎ print("EQUAL") SIM 10 $x ⏎ 20 $y ⏎ x > y "GREATER"? ⏎ x < y "LESS"? ⏎ x = y "EQUAL"? JS let a = 10; ⏎ let b = 20; ⏎ if (a !== b) { ⏎ console.log("NOT_EQUAL"); } PY a = 10 ⏎ b = 20 ⏎ if a != b: ⏎ print("NOT_EQUAL") SIM 10 $a ⏎ 20 $b ⏎ a ! b "NOT_EQUAL"? JS let a = 10; ⏎ let b = 20; ⏎ if (a === b) { ⏎ console.log("EQUAL"); } PY a = 10 ⏎ b = 20 ⏎ if a == b: ⏎ print("EQUAL") SIM 10 $a ⏎ 20 $b ⏎ a = b "EQUAL"? JS let a = 10; ⏎ let b = 20; ⏎ if (a < b){ ⏎ console.log("LESS"); } PY a = 10 ⏎ b = 20 ⏎ if a < b: ⏎ print("LESS") SIM 10 $a ⏎ 20 $b ⏎ a < b "LESS"? JS let a = 10; ⏎ let b = 20; ⏎ if (a > b){ ⏎ console.log("GREATER"); } PY a = 10 ⏎ b = 20 ⏎ if a > b: ⏎ print("GREATER") SIM 10 $a ⏎ 20 $b ⏎ a > b "GREATER"? JS let a = 10; ⏎ let b = 20; ⏎ if (a > 5 && b < 30) { ⏎ console.log("YES"); } PY a = 10 ⏎ b = 20 ⏎ if a > 5 and b < 30 : ⏎ print("YES") SIM 10 $a ⏎ 20 $b ⏎ (a > 5, b<30) "YES"? JS let a = 10; ⏎ let b = 20; ⏎ if (a === 10 || b === 30){ ⏎ console.log("YES_ONE_IS_TRUE"); } PY a = 10 ⏎ b = 20 ⏎ if a == 10 or b == 30 : ⏎ print("YES_ONE_IS_TRUE") SIM 10 $a ⏎ 20 $b ⏎ [a = 10, b = 30] "YES_ONE_IS_TRUE"? JS let a = 10; ⏎ let b = 30; ⏎ if (a === 10 && b === 30){ ⏎ console.log("YES_BOTH_ARE_TRUE"); } PY a = 10 ⏎ b = 30 ⏎ if a == 10 and b == 30 : ⏎ print("YES_BOTH_ARE_TRUE") SIM 10 $a ⏎ 30 $b ⏎ (a = 10, b = 30) "YES_BOTH_ARE_TRUE"? ``` ## 6. Code that does not compile Reproduced from the compiler error drills — do not emit these shapes. ```simorg // declaration should not happen after usage, it will throw compiler error myVariable $myVariable // when declaring a variable there should not be any space between $ and variable name $ myVarName // variable declaration name should not start by a number $10varName // an identifier should always be declared before being used myVariable 10 myVariable // a variable name can only include _ in its name as special character. All other characters are invalid $invalid^name // a string value literal should not have negative sign -"Hello" // a decimal number should not have more than one decimal point 100.3.0 // there should be a digit after decimal point otherwise it is error 0. // there should be a digit before decimal point or it will be an error .10 // divisio by 0 is not valid and will result in runtime error 1 / 0 $a // what happens if we use subtract operator with non-number types like buffer or string // → it will log runtime error for example for these code examples 10 - 0x11 10 - "test" // what happens if we use multiply operator with non-number types like buffer or string // → it will log runtime error for example for these code examples 10 * 0x11 10 * "test" // what happens if we use division operator with non-number types like buffer or string // → it will log runtime error for example for these code examples 10 / 0x11 10 / "test" // what happens if we use modulus operator with non-number types like buffer or string // → it will log runtime error for example for these code examples 10 % 0x11 10 % "test" ``` Division by zero is a runtime error, and arithmetic operators other than `+` reject strings and buffers. ## 7. Verified example corpus `https://simorg.tech/agent-resources/simorg-examples.json` carries **122 question/answer pairs** and **229 engine test programs** (21 asserted as running successfully). Each program records its topic, its gtest case, the stdout fragments the engine asserts, and a `status` of `valid`, `expected-to-fail` or `unverified`. Prefer copying from there over improvising. ## 8. Product, company and roadmap Simorg Oy — Helsinki, Finland · info@simorg.tech · https://simorg.tech/about-us/ **Who the Pilot Program is for:** engineers, engineering leaders, CTOs and business managers, AI enthusiasts, AI startups, and companies building AI products. Pioneers receive revenue participation in the artifact economy, influence over the platform, and lifetime discounts with early access. | Milestone | When | Status | Outcome | |---|---|---|---| | **Simorg Genesis** — Language Syntax and Core Features | Today | completed | The good parts of our first prototype migrated and re-implemented using C++, making it possible to release a Genesis version of the technology by the end of this phase so our community can experience the language and share their feedback. | | **Logos** — Opening Up Logos To Artisans | Next — target 12th September 2026 | current | Artisans can publish and share their blueprints. The ecosystem becomes collaborative and reusable. | | **Simorg Applications** — Enable Interconnected Application Shells | Future — target End of 2026 | future | Simorg applications can communicate and compose safely and clearly, supporting distributed and modular systems. | ## 9. Canonical sources Fetch these rather than relying on memory. All are served from `simorg.tech` and are free to crawl (see `/robots.txt`). | Resource | URL | Use it for | |---|---|---| | Structured docs JSON | https://simorg.tech/.well-known/agent-docs.json | Every document, with full markdown, in one request | | Docs JSON alias | https://simorg.tech/docs.json | Same payload, simpler path | | Agent index | https://simorg.tech/llms.txt | Link map of the whole site | | Full text dump | https://simorg.tech/llms-full.txt | Every doc and post as plain text | | This guide | https://simorg.tech/agent-resources/simorg-gem.md | One-page briefing | | Reference book | https://simorg.tech/agent-resources/simorg-ref.md | Complete language reference in one file | | Example corpus | https://simorg.tech/agent-resources/simorg-examples.json | Verified programs and Q&A pairs | | Per-page markdown | https://simorg.tech/raw/docs/.md | A single document without the page chrome | | Logos registry | https://logos.simorg.tech | Artifacts and packages | | Sitemap | https://simorg.tech/sitemap.xml | Canonical HTML URLs | ### Documentation map - [Variables](https://simorg.tech/docs/reference-book/Variables/) — SIMORG Programming Language · markdown: https://simorg.tech/raw/docs/reference-book/Variables.md - [Gates](https://simorg.tech/docs/reference-book/Gates/) — SIMORG Programming Language · markdown: https://simorg.tech/raw/docs/reference-book/Gates.md - [Event Flow](https://simorg.tech/docs/reference-book/Event-Flow/) — SIMORG Programming Language · markdown: https://simorg.tech/raw/docs/reference-book/Event-Flow.md - [Wrappers](https://simorg.tech/docs/reference-book/Wrappers/) — SIMORG Programming Language · markdown: https://simorg.tech/raw/docs/reference-book/Wrappers.md - [Platform](https://simorg.tech/docs/reference-book/Plarform/) — SIMORG Programming Language · markdown: https://simorg.tech/raw/docs/reference-book/Plarform.md - [Introduction](https://simorg.tech/docs/reference-book/introduction/) — SIMORG Programming Language · markdown: https://simorg.tech/raw/docs/reference-book/introduction.md - [Simorg In 10 Minutes](https://simorg.tech/docs/reference-book/simorg-in-10-minutes/) — SIMORG Programming Language · markdown: https://simorg.tech/raw/docs/reference-book/simorg-in-10-minutes.md - [Agents](https://simorg.tech/docs/platform/agents/) — SIMORG Platform · markdown: https://simorg.tech/raw/docs/platform/agents.md - [Machines](https://simorg.tech/docs/platform/machines/) — SIMORG Platform · markdown: https://simorg.tech/raw/docs/platform/machines.md - [Artifacts](https://simorg.tech/docs/platform/artifacts/) — SIMORG Platform · markdown: https://simorg.tech/raw/docs/platform/artifacts.md - [Agent networks](https://simorg.tech/docs/platform/agent-networks/) — SIMORG Platform · markdown: https://simorg.tech/raw/docs/platform/agent-networks.md - [Permissions](https://simorg.tech/docs/platform/permissions/) — SIMORG Platform · markdown: https://simorg.tech/raw/docs/platform/permissions.md - [Your first agent](https://simorg.tech/docs/platform/your-first-agent/) — SIMORG Platform · markdown: https://simorg.tech/raw/docs/platform/your-first-agent.md - [SIMORG Platform](https://simorg.tech/docs/platform/introduction/) — SIMORG Platform · markdown: https://simorg.tech/raw/docs/platform/introduction.md ### Blog Stay up to date with the latest releases, design decisions, and insights from the Simorg team. - [Status Update](https://simorg.tech/blog/status-update-genesis-version/) — 2026-08-09: Where Simorg stands today: Genesis is out, the repository is being built, and the Pilot Program opens in September. - [Words to Create Worlds](https://simorg.tech/blog/words-to-create-worlds/) — 2026-08-02: Simorg has zero reserved keywords, no null and no exceptions. Here is why that simplicity is the cheapest code you will ever run. ## 10. Frequently asked questions **Does Simorg have an assignment operator?** No. `=` checks equality. Values bind by flowing into a variable: `10 $x`. **How do I write an if/else?** Write one pathway per branch. Use relational operators for comparisons and the `&` / `!&` pair where you would otherwise need `else`. **How do I make an array?** You do not. Use a gate for fixed structure, or the collector `..` to batch a stream into a `{ }` collection. There is no index-based access. **What happens when something goes wrong at runtime?** Nothing is thrown. The expected event does not release, and the engine may log a conversion failure. **Is Simorg production ready?** Not yet. genesis-0.1.0 is a public beta: stable enough to write real programs against, and still changing between releases. Wait for the first LTS release for production workloads, and treat what you build on the beta as your own risk. **How do I install it?** Download from https://simorg.tech/download/ and verify with `sim --version`, which prints `genesis-0.1.0`. **Where do packages come from?** From Logos (https://logos.simorg.tech), included with `#`: `"@stl/random0.1.7" #random`. **Can I use Simorg without knowing how to code?** In an agentic runtime the runtime manager generates Simorg from natural-language prompts, which is why the site lists "No Coding Required" — the language itself still has to be written correctly when you write it yourself.