# Simorg — Agent Help Guide (simorg-gem)

> Auto-generated at 2026-07-30T10:41:21.482Z. Synthesized from the live homepage, reference book, and e2e training examples.
> Canonical structured docs: https://simorg.art/.well-known/agent-docs.json

## Instructions for AI agents

- **Do not guess Simorg syntax** — use the language essentials and examples below, or fetch the full JSON corpus.
- Prefer `https://simorg.art/.well-known/agent-docs.json` for complete documentation (getting started, reference book, standard library, artisans).
- Simorg has **no classical assignment operator**. The `=` token is an **equality check** only. To bind data, use **eventflows**: vibrate a value into a variable (e.g. `10 $x` or `10 x`).
- Events flow **left to right**. Variables (`$name`) are **event markers**, not memory slots.
- Simorg has **zero reserved keywords**; identifiers and operators carry meaning. Favor concise, token-efficient code.
- Artifacts and packages come from **Logos** (`https://logos.simorg.art`) — the registry of building blocks.
- Simorg is currently in **PoC / Genesis** — not production-ready for LTS workloads.

## Language essentials (reference book)

Condensed from the current Genesis reference book. **Read this before writing Simorg code.**

### Core model

- Simorg is a **Programming Language as a Platform** — event-driven, AI-native, not a generic replacement for classical languages.
- Everything is an **Event** that flows **left to right** through **Shells** (scoped spaces). **Data leads processing** — you write pathways, not imperative steps.
- Code compiles into **mathematical entities** in a runtime engine. No null/undefined, no garbage collector, no classical functions/arrays.
- Low-level capabilities come from **Artifacts** published on **Logos** (`https://logos.simorg.art`).
- **Zero reserved keywords** — no `if`, `else`, `while`, `for`, etc. Conditions are explicit eventflow pathways.

### ⚠️ No assignment operator — `=` is equality only

**Simorg does not have a classical assignment operator (`=`).** The `=` token is a **relational equality check**, not assignment.

- On success, the **subject** (left side) passes through unchanged; on failure the event does not release.
- Binding data to a variable is done through **eventflows**: an event vibrates into a variable when data reaches it.

```simorg
# WRONG mental model (classical languages):
# x = 10   ← this does NOT assign in Simorg

# CORRECT — eventflow binds a value to a variable:
10 $x
x ?

# Equality check (not assignment):
20 = 20 $ok
ok ?          // releases 20

20 = 10 $fail
fail ?        // never releases
```

From the guessing-game tutorial (`guess = TARGET "Congratulations!" ?`): `guess = TARGET` means **if guess equals TARGET**, pass the guess event forward — it is a conditional pathway, not assignment.

To set a value, vibrate data into the variable:

```simorg
3 $TARGET
3 $guess
guess = TARGET "Congratulations! You successfully guess the number!" ?
```

### Variables

- Variables are **event markers**, not memory owners. They activate only when an event reaches them.
- Declare with `$` before the identifier: `$myVar`
- Value flows left → right: `"Hello World!" $myFirstVar` then `myFirstVar ?`
- **Value literals**: numbers (`10`, `7.50`), strings (`"Hello"`), buffers (`0x01`)
- **Empty values** (`0`, `0.0`, `0x`, `""`) are valid events representing emptiness — not null/undefined
- **Const convention**: UPPERCASE identifiers (e.g. `$TARGET`) are set once per app lifecycle
- **Open pipes** (`:`) re-trigger a variable on future events: `:terminal.promptAndReadLine $guess`

### Gates

Gates aggregate multiple events. They care about **event presence**, not truthy/falsy values.

| Gate | Syntax | Releases when |
|------|--------|---------------|
| OR | `[a, b, c]` | at least one slot has an event |
| XOR | `[a; b; c]` | one slot per cycle (sequential) |
| AND | `(a, b, c)` | every slot has an event |

Named slots use `.` access: `( "HELLO" $hello, "BYE" $bye ) $message` → `message.hello ?`

### Eventflow operators

Operators chain into **pipes** (pathways). No operator precedence — evaluation is strictly **left to right**.

| Category | Operators | Notes |
|----------|-----------|-------|
| Opener | `:` | unary — open pipe to future events |
| Arithmetic | `+` `-` `*` `/` `%` `++` `--` | binary ops consume right operand; `++`/`--` unary; `+` joins strings/buffers |
| Relational | `=` `!` `>` `>=` `<` `<=` | binary — **`=` is equality check**; subject passes through on match |
| Truthy | `&` `!&` | unary — pass only if truthy / not truthy |
| Variable declaration | `$` | binary — marks next token as variable; prefix/suffix shape behavior |
| Logger | `?` `??` | unary — log with/without trailing newline |
| Do Not Care | `|` | unary — keep the act of the event, discard the value |
| Filter | `@` | binary — pass event only if it carries a specific frequency |
| Collector | `..` | binary — batch streaming events into `{ }` collections |
| Creation | `#` | optional operand — instantiate Shells from artifacts, files, or agentic prompts |

**Conditionals** use relational + truthy pathways — not `if/else`:

```simorg
guess = TARGET "You guessed right!" ?
guess > TARGET "Target is smaller" ?
guess < TARGET "Target is bigger" ?
```

**Truthy check** instead of else:

```simorg
"" $userInput
userInput &
userInput !& "Invalid Empty Value!" ?
```

### Wrappers (Shell scopes)

| Wrapper | Syntax | Behavior |
|---------|--------|----------|
| Isolator | `{ ... }` | closed scope — events cannot exit |
| Conditional | `activator { ... }` | opens when activator event fires |
| IO | `$name { ... }` | bidirectional — data flows in and out |

Layer operator `.` walks nested identity layers (like member access, event-driven).

### Artifacts & Logos

- **Artifacts** wrap digital elements (plugins, binaries, AI agents, web/3D components) as Shells in the eventflow.
- Instantiate with `#`: `"@stl/random0.1.7" #random` then `9 random.integer $TARGET`
- Load local files: `"../my-artifact/main.art" #localArtifact`
- **Applications** are Simorg programs; **Machines** run them; **Logos** is the artifact repository.
- Simorg does **not throw exceptions** — failed events simply do not release; the engine logs conversion failures.

### Agentic runtime

In an agentic runtime, the runtime manager generates Simorg code from prompts. Setup first:

```simorg
"@runtime/openai-runtime-manager0.1.0" #openAi
"your-openai-token" openAi.initialize
```

- A **standalone string value** is an **anonymous prompt** (generates code/artifacts).
- A string **inside a pipe** is **not** a prompt — it is just data:

```simorg
"Create a web application and serve it on port 3000"   // anonymous prompt
"Hello World!" ?                                      // NOT a prompt
```

- **Named prompt** — creates a named artifact you can call later:

```simorg
"Create an agentic chatComponent" #chatComponent
chatComponent.userPrompt ?
```

- **Conditional anonymous prompt** — use `#` without an identifier:

```simorg
chatComponent.onClose "Exit this application" #
```


## At a glance

**Software, Rebuilt for the AI Era.**

Today's programming languages were designed for human developers. SIMORG gives humans and AI agents a simpler way to build, understand and evolve software.

_Simorg is a platform for building next-generation AI and metaverse applications._

**Credibility:** Open Source · AI Native · Event Driven

**Primary CTA:** [Join the Pilot Program](https://simorg.art/pilot-program)
**Download:** [Download](https://simorg.art/download)

## Why software engineering is changing

_Why Software Engineering is Changing_

### 1. Classical Programming Creates,

- Complexity
- Integration friction
- Token waste

Classical programming language stack abstractions, reserved keywords, and noise that agents pay for in tokens—without a runtime designed for AI-native execution resulting in a token economy that does not add up!

### 2. AI Agents Need,

- Simple
- Connected
- Context-efficient systems

Agents sit outside the elements they should inhabit, integration and workflows are yet artificial and rigid.

### 3. We Need,

- Simplicity of a conversation.
- Power of a programming language.
- An AI-native runtime.

AI-powered applications remain islands—conscious in isolation, unable to discover or collaborate.

## How SIMORG solves it

_Here's how SIMORG solves it_

### Communication — A language built for AI

A language designed for agents: zero reserved keywords, maximum meaning per token.

A data- and event-driven fully async programming language that compiles your code into mathematical entities and executes it on top of a mathematical machine—removing all unnecessary abstractions while having zero reserved keywords. We make the token economy positive.

### Execution — A mathematical runtime

Mathematical runtime and event/data-driven by design—a natural ecosystem for agents and apps to run and access data.

Our language makes it possible to integrate AI agents in every single digital element, from 3D components all the way to binaries and cloud applications. A platform of digital elements shaped on top of artifacts wrapped inside Simorg code, published by our Artisans. These artifacts are closed-source, guarding our artisans from AI theft and guarding AI tokens from unnecessary code processing.

### Ecosystem — A collaborative platform

Agents are first-class citizens: platform access to publish and reuse artifacts, see each other, and communicate.

Applications created using our technology can naturally communicate with each other, making it possible to create a network of AI-powered applications that communicate with one another.

## How it works

Applications publish and consume artifacts through Logos — the repository of building blocks. Provider applications supply artifacts; consumer applications compose them. Agents live inside applications and communicate when owners allow.

- **LOGOS — The Repository Of Building Blocks**
- **Providers** publish artifacts to Logos
- **Consumers** compose artifacts into applications

## Pilot program

Help shape the next generation of software engineering.

**Who should apply:** CTOs, Engineering leaders, AI startups, Companies building AI products.

[Apply to the Pilot Program](https://simorg.art/pilot-program)

## Hello World

Experience the beauty of simplicity by writing your first Simorg program.

```simorg
"Hello World!"?
```

```bash
sim hello-world.art → Hello World!
```

## Agent-driven application demo

Homepage animation snippet showing runtime + natural-language commands in Simorg:

```simorg
"@runtime/runtime-manager^0.10.1" #runtime

"Create a react app and serve it on port 3000" #myApp

"create a home page inside myApp " #homepage

"create a chat component and put it inside homepage" #chatComponent

chatComponent.onMessage ?
```

## Roadmap milestones

### Simorg PoC (Today) — completed

Language Syntax and Core Features

**Result:** 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.

**Why:** A solid PoC gives our early adopters the chance to validate our technology in practice and gives the community something to try and build on. It also de-risks the next phases of the project.

### Logos (Next) — current

Opening Up Logos To Artisans

**Result:** Artisans can publish and share their blueprints. The ecosystem becomes collaborative and reusable.

**Why:** A single implementation cannot cover every use case. Logos turns Simorg into a platform by letting the community contribute and share packages, making it possible to build a universe together.

### Simorg Applications (Future) — future

Enable Interconnected Application Shells

**Result:** Simorg applications can communicate and compose safely and clearly, supporting distributed and modular systems.

**Why:** Real-world systems are rarely isolated. Connections enable the creation of a universe of interconnected conscious applications.

## Reference book (table of contents)

Full merged reference is in `simorg-ref.md`. Chapters:

- Introduction
- Simorg In 10 Minutes
- Variables
- Gates
- Eventflow
- Wrappers
- Artifacts
- Logos

## Code examples by topic

_122 question/answer pairs from 16 JSON files in e2e_code_tests._

### basic_gate

#### train-usage (`basic_gate/train-usage.json`)

**Q:** how to declare an OR gate in simorg?

```simorg
[1,2,3]
```

**Q:** how to declare an AND gate in simorg?

```simorg
(1,2,3)
```

**Q:** how to declare an XOR gate in simorg?

```simorg
[1;2;3]
```

**Q:** this is an AND gate to check if all the vibrations are available and it will log the result

```simorg
10 $a 
 20 $b 
 30 $c 
 (a,b,c) ?
```

**Q:** this is an AND gate to check if vibraitons are available and it will not log because variable x is not vibrated

```simorg
$x 
 20 $y 
 30 $z 
 (x,y,z) ?
```

_…and 6 more in simorg-examples.json._

### basic_identifier

#### train-error (`basic_identifier/train-error.json`)

**Q:** declaration should not happen after usage, it will throw compiler error

```simorg
myVariable 
 $myVariable
```

**Q:** when declaring a variable there should not be any space between $ and variable name

```simorg
$ myVarName
```

**Q:** variable declaration name should not start by a number

```simorg
$10varName
```

**Q:** an identifier should always be declared before being used

```simorg
myVariable 
 10 myVariable
```

**Q:** a variable name can only include _ in its name as special character. All other characters are invalid

```simorg
$invalid^name
```

_…and 3 more in simorg-examples.json._

#### train-simorg-javascript (`basic_identifier/train-simorg-javascript.json`)

**Q:** Translate the following Javascript code into simorg:  
 let my_variable 


```simorg
$my_variable
```

**Q:** Translate the following Javascript code into simorg: 
 const CONST_VAR = 100 


```simorg
100 $CONST_VAR
```

**Q:** Translate the following Javascript code into simorg: 
 let x; 
 x = 7.50; 
 console.log(x);


```simorg
$x 
 7.50 x 
 x?
```

**Q:** Translate the following Javascript code into simorg: 
 let myVariable = 10 
 this is a non const variable

```simorg
$myVariable  
 10 myVariable
```

#### train-simorg-python (`basic_identifier/train-simorg-python.json`)

**Q:** Translate the following Python code into simorg:  
 my_variable 


```simorg
$my_variable
```

**Q:** Translate the following Python code into simorg: 
 CONST_VAR = 100 


```simorg
100 $CONST_VAR
```

**Q:** Translate the following Python code into simorg: 
 x 
 x = 7.50 
 print(x)


```simorg
$x 
 7.50 x 
 x?
```

**Q:** Translate the following Python code into simorg: 
 x = 10 
 this is a non const variable

```simorg
: 10 $myVariable
```

#### train-usage (`basic_identifier/train-usage.json`)

**Q:** declare a variable and call it test

```simorg
$test
```

**Q:** How variable assignment is done in simorg?

```simorg
simorg uses data flow to do assignment. Token on the left assigns to variable on the right. this is because of vibration which moves from left to right. For example: 
 10 $a 
 assigns 10 to variable a
```

**Q:** declare a const variable name MY_VAR and give it default value of 10

```simorg
10 $MY_VAR
```

**Q:** declare a variable and give it a decimal value and log its value

```simorg
$x 
 7.50 x 
 x?
```

**Q:** declare an empty variable called myVariable that will recieve its value later

```simorg
$myVariable
```

_…and 8 more in simorg-examples.json._

### basic_value_literal

#### train-error (`basic_value_literal/train-error.json`)

**Q:** a string value literal should not have negative sign

```simorg
-"Hello"
```

**Q:** a decimal number should not have more than one decimal point

```simorg
100.3.0
```

**Q:** there should be a digit after decimal point otherwise it is error

```simorg
0.
```

**Q:** there should be a digit before decimal point or it will be an error

```simorg
.10
```

#### train-simorg-javascript (`basic_value_literal/train-simorg-javascript.json`)

**Q:** Translate the following Javascript code into simorg:  
 console.log("Hello, World!")


```simorg
"Hello World" ?
```

**Q:** Translate the following Javascript code into simorg: 
 console.log(100) 


```simorg
100 ?
```

**Q:** Translate the following Javascript code into simorg: 
 console.log(3.14)


```simorg
3.14 ?
```

#### train-simorg-python (`basic_value_literal/train-simorg-python.json`)

**Q:** Translate the following Python code into simorg:  
 print("Hello, World!")


```simorg
"Hello World" ?
```

**Q:** Translate the following Python code into simorg: 
 print(100) 


```simorg
100 ?
```

**Q:** Translate the following Python code into simorg: 
  print(3.14)


```simorg
3.14 ?
```

#### train-usage (`basic_value_literal/train-usage.json`)

**Q:** write a simple Hello World app using value literal and log it 

```simorg
"Hello, World!" ?
```

**Q:** create an integer value literal with value 10

```simorg
10
```

**Q:** create a decimal value literal with value 0.5

```simorg
0.5
```

**Q:** create a string value literal with value "TEST"

```simorg
"TEST"
```

**Q:** create a buffer value literal with value [0, 10]

```simorg
0x00_0a
```

_…and 9 more in simorg-examples.json._

### calculational

#### train-error (`calculational/arithmetic/train-error.json`)

**Q:** divisio by 0 is not valid and will result in runtime error

```simorg
1 / 0 $a
```

**Q:** what happens if we use subtract operator with non-number types like buffer or string

```simorg
it will log runtime error for example for these code examples: 
 10 - 0x11 
 10 - "test"
```

**Q:** what happens if we use multiply operator with non-number types like buffer or string

```simorg
it will log runtime error for example for these code examples: 
 10 * 0x11 
 10 * "test"
```

**Q:** what happens if we use division operator with non-number types like buffer or string

```simorg
it will log runtime error for example for these code examples: 
 10 / 0x11 
 10 / "test"
```

**Q:** what happens if we use modulus operator with non-number types like buffer or string

```simorg
it will log runtime error for example for these code examples: 
 10 % 0x11 
 10 % "test"
```

#### train-simorg-javascript (`calculational/arithmetic/train-simorg-javascript.json`)

**Q:** Translate the following Python code into simorg:  
 let a = 10 + 20; 


```simorg
10 + 20 $a
```

**Q:** Translate the following Python code into simorg: 
 let  varA = 10; 
 let varB = 20; 
 let result = varA + varB;  


```simorg
10 $varA 
 20 $varB 
 varA + varB $result
```

**Q:** Translate the following Python code into simorg: 
 let a = 1; 
 let b = 2; 
 let c = b - a; 


```simorg
10 $a 
 20 $b 
 b - a $c
```

**Q:** Translate the following Python code into simorg: 
 let a = 1; 
 let b = 2; 
 let c = b * a; 


```simorg
10 $a 
 20 $b 
 b * a $c
```

**Q:** Translate the following Python code into simorg: 
 let a = 1; 
 let b = 2; 
 let divideResult = b / a; 


```simorg
10 $a 
 20 $b 
 b / a $divideResult
```

#### train-simorg-python (`calculational/arithmetic/train-simorg-python.json`)

**Q:** Translate the following Python code into simorg:  
 a = 10 + 20


```simorg
10 + 20 $a
```

**Q:** Translate the following Python code into simorg: 
 varA = 10 
 varB = 20 
 result = varA + varB  


```simorg
10 $varA 
 20 $varB 
 varA + varB $result
```

**Q:** Translate the following Python code into simorg: 
  a = 1 
 b = 2 
 c = b - a 


```simorg
10 $a 
 20 $b 
 b - a $c
```

**Q:** Translate the following Python code into simorg: 
  a = 1 
 b = 2 
 c = b * a 


```simorg
10 $a 
 20 $b 
 b * a $c
```

**Q:** Translate the following Python code into simorg: 
  a = 1 
 b = 2 
 divideResult = b / a 


```simorg
10 $a 
 20 $b 
 b / a $divideResult
```

#### train-usage (`calculational/arithmetic/train-usage.json`)

**Q:** add two numbers in simorg

```simorg
10 + 20
```

**Q:** add variable a to variable b in simorg and save the result in c

```simorg
10 $a 
 20 $b 
 a + b $c
```

**Q:** add three numbers in simorg and log the result

```simorg
10 $a 
 20 $b 
 30 $c 
 a + b + c ?
```

**Q:** subtract two numbers in simorg

```simorg
10 - 20
```

**Q:** subtract variable b from variable a in simorg and save the result in c

```simorg
10 $a 
 20 $b 
 a - b $c
```

_…and 13 more in simorg-examples.json._

#### train-simorg-javascript (`calculational/relational/train-simorg-javascript.json`)

**Q:** What is the equivalent of this Javascript code in simorg:  
 let x = 10; 
 let y = 20; 
 if (x > 20) { 
 console.log("GREATER"); 
 } else if (x < y) { 
 console.log("LESS"); 
 } else { 
 console.log("EQUAL"); }

```simorg
10 $x 
 20 $y 
 x > y "GREATER"? 
 x < y "LESS"? 
 x = y "EQUAL"?
```

**Q:** what is equivalent of this Javascript code in simorg: 
 let a = 10; 
 let b = 20; 
 if (a !== b) { 
 console.log("NOT_EQUAL"); }

```simorg
10 $a 
 20 $b 
 a ! b "NOT_EQUAL"?
```

**Q:** what is equivalent of this Javascript code in simorg: 
 let a = 10; 
 let b = 20; 
 if (a === b) { 
 console.log("EQUAL"); }

```simorg
10 $a 
 20 $b 
 a = b "EQUAL"?
```

**Q:** what is equivalent of this Javascript code in simorg: 
 let a = 10; 
 let b = 20; 
 if (a < b){ 
 console.log("LESS"); }

```simorg
10 $a 
 20 $b 
 a < b "LESS"?
```

**Q:** what is equivalent of this Javascript code in simorg: 
 let a = 10; 
 let b = 20; 
 if (a > b){ 
 console.log("GREATER"); }

```simorg
10 $a 
 20 $b 
 a > b "GREATER"?
```

_…and 3 more in simorg-examples.json._

#### train-simorg-python (`calculational/relational/train-simorg-python.json`)

**Q:** What is the equivalent of this Python code in simorg:  
 x = 10 
 y = 20 
 if x > 20: 
	 print("GREATER") 
 elif x < y: 
	 print("LESS") 
 else: 
	 print("EQUAL") 

```simorg
10 $x 
 20 $y 
 x > y "GREATER"? 
 x < y "LESS"? 
 x = y "EQUAL"?
```

**Q:** what is equivalent of this Python code in simorg: 
 a = 10 
 b = 20 
 if a != b: 
	 print("NOT_EQUAL")

```simorg
10 $a 
 20 $b 
 a ! b "NOT_EQUAL"?
```

**Q:** what is equivalent of this Python code in simorg: 
 a = 10 
 b = 20 
 if a == b: 
	 print("EQUAL")

```simorg
10 $a 
 20 $b 
 a = b "EQUAL"?
```

**Q:** what is equivalent of this Python code in simorg: 
 a = 10 
 b = 20 
 if a < b: 
	 print("LESS")

```simorg
10 $a 
 20 $b 
 a < b "LESS"?
```

**Q:** what is equivalent of this Python code in simorg: 
 a = 10 
 b = 20 
 if a > b: 
	 print("GREATER")

```simorg
10 $a 
 20 $b 
 a > b "GREATER"?
```

_…and 3 more in simorg-examples.json._

#### train-usage (`calculational/relational/train-usage.json`)

**Q:** write a simorg code that compares two number variables of a and b and sets c with the bigger one

```simorg
10 $a 
 20 $b 
 [a > b, b>a] $c
```

**Q:** write a simorg code that compares two number variables of a and b and sets c with the bigger one or if they are equal

```simorg
10 $a 
 20 $b 
 [a > b, a=b, b>a] $c
```

**Q:** write a simorg code that compares and checks if 20 is greater than 10 

```simorg
20 > 10
```

**Q:** compare 20 and 10 in simorg and log the smaller one

```simorg
10 < 20 ?
```

**Q:** how to check equality in simorg

```simorg
use a single = operator to check equality. Simorg never uses == and it does not have assignment operator.
```

_…and 4 more in simorg-examples.json._

## Preferred agent entry points

- Structured docs JSON: https://simorg.art/.well-known/agent-docs.json
- Docs alias: https://simorg.art/docs.json
- Agent index: https://simorg.art/llms.txt
- Full text dump: https://simorg.art/llms-full.txt
- Reference book merge: https://simorg.art/agent-resources/simorg-ref.md
- Training examples JSON: https://simorg.art/agent-resources/simorg-examples.json
- This guide: https://simorg.art/agent-resources/simorg-gem.md
- Logos registry: https://logos.simorg.art
- Sitemap: https://simorg.art/sitemap.xml

## Blog

Stay up to date with the latest releases, design decisions, and insights from the Simorg team.

- [Status Update](https://simorg.art/blog/status-update-genesis-version/): A brief discussion on the status of the genesis version and how simorg is moving forward.
- [Words to Create Worlds](https://simorg.art/blog/words-to-create-worlds/): In this blog post we share more about our programming language and our technology.