1. What Metnos is

Metnos is a self-hosted architecture for a governed agent. Its core does not define an application domain: it plans, applies policy, remembers, synthesizes, isolates and audits. The admitted executor set defines what a concrete instance can actually do. Executors are small signed programs, generated or imported only inside a closed vocabulary and orchestrated by a local-first LLM planner. Frontier models are optional consults, not the residence of the system.

The name comes from mētis (cunning intelligence) + noûs (mind). It lives on a machine under your physical and legal control. The reference instance is reached through Telegram and the browser (port 8770), and its current executor catalog covers files, mail, photos, calendars, the web, GitHub and host operations. Those are uses of that catalog, not limits of Metnos. Change the admitted executors and enabled skills/backends, and the operational domain changes without changing the governing architecture.

The identity card

2. The three bets

The whole project rests on three architectural bets. They are deliberate positions, not optimizations: each one reverses a widespread habit of agent frameworks.

The comparison, with no discounts

3. The key concepts, in seven cards

Seven words carry the whole document. Defining them now saves you half an hour of confusion thirty lines from here; each one has its implementation contract in the component atlas below.

The anatomy of a name

The closed vocabulary is the project's most fertile idea: it makes names composable (the planner can predict what a capability it has never seen is called), filterable (the prefilter reasons over verb and object) and synthesizable (synt cannot name anything outside the grammar).

4. The layered architecture

Metnos is an onion: the outside talks to the world, the inside executes. Each layer trusts only the one beneath it, and privileges shrink as you move toward the core. A request — whether from a user or from a scheduled task — crosses all of them, in order.

• Channels — a channel is an adapter: it converts an external interface (Telegram, browser) into messages and replies. Adding one does not touch the core (ch. 11).
• Turn runtime — the shell that measures and orchestrates: per-phase telemetry (intent_ms, prefilter_ms, vaglio_ms, exec_ms), safety caps, logs.
• The Mētis engine — plans once, executes deterministically, recovers with judgment, and when there is no way out, says so (ch. 5).
• Guards — no bare subprocess, ever: every effect passes through policy, vaglio and sandbox (ch. 12).
• Executors and backends — who acts and against what: the skill↔backend separation keeps the provider out of the planner's head; placement then decides whether the executor stays on the server or runs on a registered device (ch. 3 and 6).
• Tissues — what survives between turns: associative memory, learned shortcuts, undo history, audit.

5. Anatomy of a multitool turn

If you read only one chapter, read this one. We follow a real request — «find the spam mails and move them to the trash» — from entry to answer: four tools chained together, a single call to the model, every step measured and annotated.

5.1 The cascade, step by step

The ground rule: the model is the last resort, not the first. Memory is tried first (zero LLM, milliseconds); if the request is new, the model is asked once, for the whole plan; the execution that follows is pure deterministic mechanics.

1. Literal shortcuts. A closed table recognizes the most common phrases («what time is it») in microseconds. Here: no match.
2. Intent. One call to the fast tier (reasoning off, ~0.4 s) extracts the canonical verb, the object and keywords. Compound requests become an ordered list of clauses, each with its own pool.
3. Plan memory. Fastpath (shortcuts you approved with the ★ button) and Autopath (plans learned on their own) answer without the model if they recognize the request. Here: miss, it's the first time.
4. Prefilter. The catalog shrinks to the relevant pool for the clause: verb+object match, qualifier bonus, and — to break ties among siblings — the curated affinity bonus (cap +3). All deterministic: same query, same pool, same order.
5. Mētis Proposer. ONE call to the wise tier produces the whole plan: steps, links, final message. It generates up to N candidates (adaptive, with early-stop), each physically constrained by the pool's GBNF grammar; a teleological ranking picks the best.
6. Validator. A typecheck of the plan before running it: existing tools, well-formed args, real references. A trivial error costs one re-proposal, not one wrong execution.
7. Execution. Pure mechanics: for every step the runtime resolves the placeholders, passes through the vaglio, invokes in the sandbox, accumulates the observation. Caps: 12 steps per turn, same executor max 3 times in a row.
8. Closing. The final message is a template filled with the real results. If the turn succeeds, Autopath records it: next time we jump straight to point 3.

5.2 The plan: what the model actually proposes

The Proposer does not produce prose: it produces a structured object — steps, slots to fill (fillers), final message. This is the real plan for our request:

{
  "steps": [
    {"tool": "find_messages",
     "args": {"folder": "INBOX", "query": "is:unread"}},
    {"tool": "classify_entries",
     "args": {"from_step": 1, "dimension": "spam"}},
    {"tool": "filter_entries",
     "args": {"from_step": 2, "where_field": "spam", "where_value": "spam"}},
    {"tool": "move_messages",
     "args": {"from_step": 3, "dst_folder": "${FILLER:trash_folder}"}}
  ],
  "fillers": {
    "trash_folder": {
      "prompt": "What is the trash folder called for this account?",
      "default": "Trash",
      "tier": "fast"
    }
  },
  "final_message": "Moved ${step4.ok_count} mails to the trash."
}

Worth noting: the model does not know the account's trash folder name — and does not make one up. It declares a slot (${FILLER:trash_folder}) that the runtime will fill at the right moment with a cheap micro-call (cached) or with the default.

5.3 Data piping: how the steps talk to each other

6. Executors: vectorized by construction

Every executor accepts a list and returns a list — even when the list has zero or one element. There is no *_batch anywhere: the batch version is the executor. It is the decision that keeps plans short and results composable.

Three conventions follow from the contract, and you will see them everywhere:

• entries vs results — whatever enriches or reads a list returns entries (the record schema is preserved, the pipeline can continue); whatever transforms (move, write, delete) returns results (the schema changes: outcomes, not records).
• Robustness at the natural-language boundary — 0 as a placeholder means «no limit»; comparisons are case-insensitive by default; on open text domains values with */? are globs, on closed domains (ids, slugs, scopes) matching is strict and exact. LLM biases never turn into silent failures.
• Honest counting — ok_count counts the elements that were actually processed. Never declare an outcome that does not match reality.

The manifest: the tool's prompt

Every executor carries a TOML manifest. It is not courtesy documentation: it is what the planner reads when it decides whether and how to use the tool — written for a mid-size local LLM, not for a frontier model. Short sentences, literal examples, defaults spelled out; the description follows four prescriptive chapters:

The same manifest also declares where the executor may run. The platforms and [placement] fields prevent sending to Windows a tool written only for Linux, or running on a PC an executor that has not been audited for the device. When the chat names a paired PC, the runtime uses those declarations to choose server or device execution; if the target is not reachable, the outcome is honest, not a silent fallback.

[description]
en = "SCOPE: search files by pattern in directory.
      PATTERN: find_files(base_path=\"/\", patterns=[\"*.jpg\"]).
      NOT: list_dirs+filter_entries; get_files (ID lookup).
      OUT: entries=[{path,name,type,mime,kind,size,mtime}]."

One execution policy

Every executor call, local or remote, crosses the same execution engine. In one place the runtime applies metrics, backpressure, per-resource limits and a cap derived from the hardware. The default deliberately remains serial and the cross-executor pool is off: adopting the infrastructure does not change the order, inputs, outputs or capabilities of existing executors.

[execution]
effect = "unknown"
parallelism_class = 0
resource_class = "default"
concurrency_key = "none"
equivalence_gate = "unverified"

The class measures only a budget: it grants no authority and does not mean read-only. A future executor that creates or mutates objects may run concurrently, but it must declare an isolation key, provide the resource identity, and pass equivalence, collision, idempotency and postcondition tests. If any evidence is missing, the loader reduces it to class 0.

All three executor-generation paths — Synt proposals, reactive synthesis and skill generation — also consume one central contract. The local model may design a rich implementation, but it cannot rewrite identity, lifecycle, I/O or the initial execution policy. When it parallelizes independent entries, the worker count comes from the engine and results must return in input order.

Remote authority: declared once, consumed three times

A provider name in an argument is data, not permission. For a conforming executor, remote access exists only when the manifest declares an effective provider:access capability. A closed when condition can make that capability active only for the selected backend. Invalid or non-matching conditions grant nothing.

Execution on the server or on a registered PC

The normal shape remains simple: the plan selects an executor, the runtime sends it through policy and vaglio, then invokes it in the server sandbox. Remote executors add one controlled detour: for selected executors declared portable, the execution point may be a registered PC in the same LAN or overlay network.

This is not a new channel and not a generic backend. The channel is still Telegram or web; the backend is still files, mail, calendar or another service. The remote executor is the place where the small signed program runs. Metnos keeps on the server the executor choice, policy checks, device registry, payload signing, timeout and audit.

The choice does not depend on the browser IP address. In the web UI, the machine opening the page may be the server, another PC on the network, or a browser behind a proxy; from Telegram there is no local browser at all. Metnos therefore uses the name of the paired device and anchors it in the request language: “on the laptop” is a target, “the laptop” alone is not.

The remote client does not receive general freedom. It polls the server instead of exposing ports; verifies the server signature before execution; downloads only signed and compatible executors; writes the result to a local spool before delivery. If the server is not reachable, it retries delivery without rerunning the work already done.

The remote client is contained by construction: on Windows the Job Object bounds duration, memory and process trees; on Linux the sandbox uses bwrap when present. On this foundation remote executors are no longer read-only: since C7 (ADR 0183) mutating ones — file write, move and delete — run on the device too, made safe by the policy they long required: idempotency, audit, and device-aware reversibility (deterministic reverse patterns and blob backups queued to the same device for undo; the known gap being that blob-restore is not remotable). Executors whose dependencies cannot be resolved on the device stay server-only.

The operational details — PC pairing, UI installation, heartbeat, signed queue, per-OS sandboxing and current limits — live in the remote executors component contract.

7. Synt: the tool factory

When the pool cannot do something, the planner does not improvise code in the middle of the turn: it hands over to synt, the process that brings into existence what is missing. It first tries to compose existing executors; only as a documented exception does it generate a new one — in five stages, each with its own contract.

Two triggers, one cascade

In both cases the same rule holds: synt proposes, the human approves. No self-modification without a filter; every proposal comes with its rationale, and is reversible.

The 7-layer gate

The same funnel applies to synthesized code and to skills imported from outside: no package runs on trust.

8. Four tiers, one deterministic routing

Tiers are abstract roles, not pinned models: fast / middle / wise are assignments you bind to whatever endpoint you have, and frontier is the optional cloud role. Several tiers may share one endpoint or use separate endpoints: the planner always sees the role.

The three locks of determinism

An LLM at temperature zero is not enough to make routing reproducible: the local server stays non-deterministic because of speculative decoding with a random seed. Metnos closes the door with three locks, one per noise source:

9. The memory that speeds things up

Metnos trains no models: no fine-tuning, no RLHF. Everything it learns is inspectable data — plans, traces, shortcuts — and anything learned can be read, corrected, deleted. The practical effect: the more you use it, the less it calls the model.

10. The senses: the image pipeline

To search your photos, Metnos ships nothing to anyone: three in-process extractors turn every image into three signals — what is seen, who is there, where and when — fused into one unified index queried through the ordinary vocabulary.

A search arrives from the channel like any other request: the planner composes find_images_indices with the criteria extracted from the sentence, and the channel shows inline previews. Building the index is a background job, incremental and restartable, started with a sentence («index the photos in…»).

11. The channels: Telegram and web

A channel is an adapter: it converts an external interface into messages and replies, plus one optional capability — rendering buttons for confirmations and choices. Two channels come with the install; adding more does not touch the core.

The Tutor: explaining without executing

Explicit questions about how to use Metnos are intercepted at the shared HTTP/Telegram boundary, before the planner and without consuming a pending dialog. A conservative detector recognizes only the request class; the relevant card is selected neither by synonyms nor exact phrases, but by local BGE-M3 embeddings compared with vectors held in the signed SQLite catalog.

After retrieval, the authenticated principal filters the content. Administrative procedures remain deterministic; for informational guides the local model composes the answer using only the retrieved card and the admitted instance inventory. It receives no tools and crosses the central llm slot in the serial class: it can explain, not act. An invalid catalog, a weak match, or insufficient context produces an explicit outcome, never an invented capability.

12. Safety and reversibility

Safety is not a module: it is a chain of independent guards, and an action must pass all of them. And since even the best guard makes mistakes, the last defense is being able to go back: honest undo, by construction.

13. Component atlas

The architecture above says what the system promises. This atlas shows which component owns each promise and where its exact contract lives.

13.1 From overview to component contracts

Metnos architecture has two levels of zoom. The upper level describes the system as a whole: its layers, organs, laws and ends. It is the path you have just followed from chapter 1.

The lower level is the set of component deep dives linked below: one HTML document per component, with the detail needed 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.

13.2 Four nouns, now as implementation contracts

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. Product membership, origin, and transport remain separate axes. GitHub executors maintained by Metnos are builtin with handcrafted origin, not imports; the generated catalog is the single source for the source-tree domain breakdown.

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 LLM, wise tier) and leans on the other components for the hard calls (Vaglio for safety, Synt for missing capabilities, Telos for ends).

13.3 The component map

The documented components are organized by role. The diagram below groups the main nodes 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.

13.4 A second worked request

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.

13.5 Canonical component deep dives

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

13.6 Vocabulary and primitives

The closed vocabulary stands at 26 actions (read, write, move, delete, create, find, list, filter, sort, group, classify, get, set, send, describe, render, extract, compress, compute, compare, change, order, share, open, login, act) and 26 objects (files, dirs, packages, messages, events, contacts, places, processes, urls, numbers, images, signatures, texts, proposals, persons, tasks, inputs, approval, credentials, issues, pulls, calendars, entries, lists, skills, sites). 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.

The planner currently exposes nine consumers for lists of entries. The five structural or numeric operators are filter_entries, filter_lists, sort_entries, group_entries, and compute_entries. The four in-process semantic helpers are classify_entries, compare_entries, extract_entries, and describe_entries. The first group filters one list, combines two lists, sorts, merges/deduplicates, or computes an aggregate; the second classifies, compares semantically, extracts structured records, or summarizes. The list is checked against the runtime registry and signed manifests. 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 verified live inventory contains 115 standard, signed executors: 82 handcrafted executors in the main tree, 16 builtin GitHub executors with handcrafted origin, and 17 runtime builtins using in-process transport. The Composer sees the same contract for all of them and does not select by transport. Five orthogonal producer verbs (find for patterns, get for ids/state, read for blobs from a source, list for containers, filter for reduction).

13.7 Contract-writing conventions

Every component-contract file follows the same template as this handbook's architectural overview:

• navy / sage / bronze palette; CSS inline, no external dependencies;
• every list presented as exhaustive names its source of truth and is either generated from it or covered by an element-for-element equality test;
• 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).

14. The principles, in eight cards

If you remember only eight sentences from this document, make it these. Everything else — code, prompts, conventions — follows from here.

15. What Metnos is NOT

Half of the design lives in the no's. Every temptation to add an item from this list must be resisted.

• Not a permissionless plug-in framework. The core is domain-independent, but every concrete instance has a bounded, admitted executor set and explicit policies. A new domain is expressed through governed executors and skills, not by letting arbitrary packages inherit the agent's privileges.
• It does not run third-party skills as-is. Drop-in formats are execution of someone else's code with your privileges. Here every package passes the 7-layer gate, or it does not run (ch. 7).
• It trains no models. No fine-tuning, no RLHF. Growth is inspectable memory + synthesis behind the human filter (ch. 7 and 9).
• Not a cloud agent. It runs at home; the frontier is an explicit consult, never the residence. No opening you did not choose.
• Not an IDE nor a dev assistant. It does not write code in other projects on your behalf; at most it analyzes with read-only executors.
• Not a home-automation replacement. It can ask a home-automation system; it does not duplicate it.
• Not multi-channel at all costs. Two channels done well; the others when truly needed.

16. Where to go next

You now have both levels: the system from above and the map of its component contracts. Use the atlas for implementation detail, or continue with the tour, glossary and design dialogues.

Metnos — Architecture Handbook (July 2026).
mētis + noûs: cunning intelligence in the service of the mind — on your own hardware.
Bilingual IT+EN documentation at metnos.com; code at github.com/brunialti/metnos.