Skip to content
eternego / docs

Instructions

An instruction is a situation she knows how to handle, written as a short procedure she follows. When she meets a familiar kind of moment, she loads the matching instruction by its intention and acts on it. This page documents where instructions live on disk and the three files that make them work.

The folder is named meanings/

On disk, her instructions live in home/meanings/. In the source code the entity is called a meaning (the Meaning class in the application/core/brain/meanings/ package) — that is the internal name. Everywhere operator-facing, including the dashboard, they are instructions. The folder simply keeps its code name. The two words refer to the same thing.

An instruction has two parts:

  • Intention — a short phrase naming the kind of moment, like "search using tavily." She loads an instruction by its intention. For a custom instruction the intention is not read from the file — it lives in the learned.json catalog (see below), keyed to the file that holds the path.
  • Path — the file's body: the steps she follows once it's loaded. The body is read verbatim; nothing in it is parsed.

There are two layers. Built-in instructions ship with Eternego and are immutable. Custom instructions are hers — she writes them herself when her Teacher teaches her something new. Both are presented to her by intention; she loads a body only when that moment is active. This page covers the custom layer, which is what lives in a persona's home.

The meanings/ directory

home/meanings/
├── learned.json                            ← catalog: intention → file stem
├── 44757993-d9bf-44d9-a487-44b860e642e1.md ← one instruction
└── bfd565f8-0ec5-4912-b399-142350727250.md ← another instruction

Each instruction is one Markdown file named by an opaque UUID stem. The filename is just a stable id — the human-readable intention is not in the filename, and it is not parsed from the file either. The intention she matches on lives only in learned.json, which maps it to the file stem. The .md file holds nothing but the path prose she reads when the instruction is loaded.

An instruction file

The whole file is the path — the body is read verbatim, no H1 parsing. The translation model that wrote it often opens with a heading, but that heading is just prose: it can differ from the intention in learned.json (and in real personas it usually does — the file below opens # Searching the web with Tavily while its catalog intention is search using tavily). A real custom instruction (Adam's web-search procedure), with the API key reference left as a placeholder:

# Searching the web with Tavily

Use for background research, competitive intel, and finding what
conversations are happening outside owned channels.

1. If the moment needs web search, first load this instruction on demand,
   then use Tavily via `tools.http.request` rather than trying any other
   endpoint pattern.

2. Send a Tavily search with this exact shape — change only the `query`
   value unless you have a clear reason to narrow results count:
   - method: `POST`
   - url: `https://api.tavily.com/search`
   - headers: `{"Content-Type": "application/json"}`
   - body keys: `api_key`, `query`, `search_depth`, `max_results`
   - keep `search_depth` as `basic`
   - keep `max_results` as `5` by default
   - pass `body` and `headers` as native dicts, never JSON-encoded strings
   - use the stored Tavily key (tvly-dev-XXXX) in `api_key`

3. Start with one targeted query, not a broad stack. ...

4. Cross-check first-party hits directly with `tools.http.request` GET calls
   to the surfaced URLs before citing specifics. ...

The path is procedural by design: numbered, ordered steps, each naming what to do and the observable outcome that marks it complete. She executes one step per beat and re-perceives between them, so the body has to be self-contained — if a step needs a URL or credential, it is inlined into the step rather than routed to another instruction.

Secrets can be inlined here

When she refines a web/API instruction, she may write a real key directly into a step (as tvly-dev-XXXX above, masked). Treat instruction files that call external APIs as potentially sensitive.

learned.json

The catalog — and the single source of truth for an instruction's intention. A flat JSON object mapping each intention (the exact phrase she emits to load it) to its file stem:

{
  "research Eternego public surfaces and produce an evidence-grounded findings report": "44757993-d9bf-44d9-a487-44b860e642e1",
  "search using tavily": "bfd565f8-0ec5-4912-b399-142350727250"
}

When she loads an instruction, she emits the intention text; the system looks the exact key up here to find the file. When reflect reviews an instruction, it matches the intention against this catalog: only a learned instruction (a key here) is reviewed — a built-in, whose intention isn't a key, gets no review at all, she just moves on (reflection only refines instructions she's learned; it never creates or deletes). The match is on the learned.json key alone — the heading inside the .md file is never read, so editing or removing it changes nothing. What you must keep correct is the key here and the stem it points at: if a key points at a stem with no .md file, that instruction silently drops from her catalog.

lessons/

home/lessons/
└── bfd565f8-0ec5-4912-b399-142350727250.md

When she meets a kind of moment she has no instruction for, the learn stage consults her Teacher (a stronger model). The Teacher writes a raw lesson — the principle and the steps, in the Teacher's own voice. That lesson is saved to lessons/<uuid>.md. Then her own thinking model translates the lesson into the instruction she'll read herself next time, saved to meanings/<uuid>.md under the same UUID stem, and learned.json gains the new intention → stem entry. So a freshly-learned instruction is three files written together:

lessons/<uuid>.md     ← Teacher's raw lesson (kept for provenance)
meanings/<uuid>.md    ← her translated instruction (what she actually reads)
meanings/learned.json ← + "<intention>": "<uuid>"

A lesson file is also Markdown with the intention as H1, but it reads as the Teacher's instructions to her, often ending in a done step:

# search using tavily

1. Confirm the search need and Tavily access. If the person has not given a
   concrete query, ask for the query and any constraints. ...

2. Build the Tavily request. Use the official endpoint
   `https://api.tavily.com/search` ...

...

7. `done`.

The lesson is kept for provenance; she doesn't read it during normal operation — she reads the translated meanings/ version. The lesson stem and the instruction stem are the same id, which is how you trace one to the other.

Editing an instruction by hand

She writes her own instructions — when her Teacher teaches her a new procedure, her thinking model saves it as the three files above. You don't author them by hand. But because each one is plain Markdown, you can open what she wrote and refine it.

Open the instruction's file, home/meanings/<id>.md, and edit the path — sharpen a step, add a caveat, cut something that misfires. The body is read verbatim, so your wording is exactly what she follows the next time that moment comes up. Leave learned.json alone: the intention she loads it by is already keyed to that file's id.

To remove an instruction she's outgrown, delete its meanings/<id>.md file and its learned.json entry — a key pointing at a missing file silently drops from her catalog. (Built-in instructions are immutable and don't live here; they ship with the system.)