Microdesign

This page is the entry guide to Metnos microdesign. It does not describe the system from above — that is the job of Architecture — Introduction — but it shows you the parts: how they are named, what they do, how they talk to each other. We move from the general to the particular, fixing each term before we use it.

1. What «microdesign» means here

Metnos architecture lives on two tiers. The upper tier — Level 1 — describes the system as a whole: the four layers, the organs, the laws, the ends. You find it in Metnos_Architecture_Intro_v1.html.

This folder is the lower tier, Level 2: one HTML document per component, with the level of detail you need to write the code without guessing. Decisions here are not opinions — they are contracts: data schemas, function signatures, sandbox flags, error conditions. When the code and the document drift apart, the document wins and the code is adjusted; or the document is corrected on the spot — never «later».

The rule of life is short: a component is not implemented until its HTML exists, has been approved, and speaks the same language as the code already in place.

2. The four words to learn first

Everything in Metnos revolves around four nouns. Defining them now saves half an hour of confusion thirty lines down.

executor

An executable capability: a small program that does one thing well (read files, send mail, compute a hash, OCR a PDF, discover fresh URLs on a site). Every executor takes lists in and returns lists out; it has a manifest that describes it, an Ed25519 signature that authenticates it, and a sandbox profile that confines it. The current pool counts 79 executors across hand-crafted ones in /opt/metnos/executors/ and synthesised ones under ~/.local/share/metnos/executors/, plus those imported from external skills.

mnest

The thread that links two executors when the planner has fired them together. It is not a code pointer, it is a trace: born from context, reinforced by repetition, decayed when unused.

mnestome

The emergent graph of all mnests. It is the system’s associative memory: it lives on SQLite, is curated by a nightly process (the ager), and gives the planner the intuition for «which executor usually follows which». The Italian counterpart of the term is mnestoma.

agent runtime

The engine that orchestrates everything: it receives the user request, breaks it into steps, picks executors, runs them in a sandbox, gathers observations, decides the next step. It implements the ReAct loop with native tool-use (local Qwen 3.6 35B-A3B LLM) and leans on the other components for the hard calls (Vaglio for safety, Synt for missing capabilities, Telos for ends).

3. A map of the components

There are twenty-one documented components. The diagram below groups them by role: thick black border for the central engine, green shapes for the «services» the engine consults, blue shapes for the «tissues» that hold state, bronze shapes for the peripheral organs facing the user and the environment. Arrows show who calls whom.

Three observations to read the diagram well.

1. Telos sits above everything: it is not a service one calls, it is an orientation. The runtime weighs alternatives in light of the ends declared in the homonymous workspace file.
2. Vaglio always runs before execution, never after. Once an executor has fired, going back is not free: undo exists, but it costs history and backup blobs.
3. The executor pool is open: synt can compose new executors out of existing ones, or — if that is not enough — generate one from scratch, with signing and automatic install.

4. How a user request flows through the system

To pin the map down, let’s follow a simple request from inbox to reply: «move to ~/Archive/2026 the invoice PDFs that arrived this week».

1. Channel. Telegram receives the user message. The daemon checks that the sender is paired with sufficient authorisation; otherwise the message is silently dropped. Pairing means «channel + sender ID recognised»: it is obtained by replying to a signed Ed25519 code with a TTL.
2. Agent runtime — planning. The runtime extracts the intent (canonical verb: move; object: files; criterion: invoice-attached PDFs in the «last week» window), asks the prefilter to narrow the catalog to relevant executors, and prepares the first step of the ReAct loop.
3. Vaglio — guard + judge. Before the executor fires, Vaglio checks two things: that the path is not forbidden, that the shell command is not unrecoverable (rm -rf and friends). For grey-zone operations, the rule-based judge assigns a score and, above threshold, asks the user for confirmation via the three-line card (what / where / why).
4. Sandbox + executor. The runtime invokes read_messages inside bwrap with the flags derived from the manifest. The output comes back as a list of entries; each entry is a dict with the PDF path and metadata.
5. Pipe. The next step is move_files; it takes the previous step’s list via from_step: N. Ground truth lives in the scratchpad: the planner sees not the whole list, but a synthetic view large enough to decide.
6. Mnest + mnestome. The pair read_messages → move_files reinforces an existing trace in the graph; if absent, it creates one. The nightly ager will do upkeep: decay, merges, drops.
7. Reply. The runtime answers the user via Telegram with the number of files moved and the first reason for skipping if any have been left out. The final_answer includes a truncation marker if the input list had been capped.

5. The twenty-one canonical documents

Below, the twenty-one documents grouped by role. All have an Italian counterpart at /it/architecture/.

6. Vocabulary and primitives

The closed vocabulary stands at 23 actions (read, write, move, delete, create, find, list, filter, sort, group, classify, get, set, send, describe, render, extract, compress, compute, compare, change, order, share) and 22 objects (files, dirs, packages, messages, events, calendars, contacts, places, processes, urls, numbers, images, signatures, texts, proposals, inputs, credentials, entries, persons, tasks, issues, pulls). Qualifiers come in four families: format/encoding, modality, safety policy, and provider (for specific non-default backends like _google_workspace). Centralised in runtime/vocab.py.

Three pipeline primitives work on the turn's lists of entries: filter_entries reduces one list (predicates on a field: where_starts_with, where_contains, where_glob, where_regex), filter_lists combines two lists (set ops: intersect, union, difference, symdiff, temporal overlap), compute_entries produces a scalar from one list (sum, avg, min, max, count). Concrete user example: «Is there an HLT appointment that overlaps with an MNM one in the next 3 months?» → the planner builds in six steps read_events → filter HLT → filter MNM → filter_lists(op=overlap) → final_answer.

The executor pool stands at 79 units across hand-crafted and synthesised, plus executors imported from external skills (Google Workspace, etc.). Five orthogonal producer verbs (find for patterns, get for ids/state, read for blobs from a source, list for containers, filter for reduction).

7. Writing conventions

Every microdesign file follows the same template as Architecture — Introduction:

• navy / sage / bronze palette; CSS inline, no external dependencies;
• title page, numbered table of contents, chapters with stable id;
• at least one inline SVG figure (never a PNG: diagrams must remain searchable and PDF-printable);
• a Contract section (Protocol + error conditions), an Implementations one, a Conformance tests one;
• a sticky breadcrumb navigation at the top;
• prescriptive rules to LLMs follow the MUST / MUST NOT / OK / ERROR pattern, four lines max;
• option labels as (a)/(b)/(c), never as Greek letters;
• no third-party real names: only «Roberto» or generic terms (guest, invited family member).

Read on