1 · What Metnos is, in thirty seconds

You give it goals in natural language through a browser, Telegram, or another admitted channel. The reference installation reads mail, files, photos, calendars, the web and GitHub, but those are examples, not its boundary: every governed capability that can be expressed as a signed executor can join the same architecture. It stops to ask before actions that cannot be redone. There is no Metnos cloud and no “sign up”: data and control remain with the operator.

What happens on every request, in one drawing:

Six properties that set it apart from a generic agent:

• It asks before acting. A two-phase evaluator — binary guard, then a graded judge against your telos — decides whether an action passes silently, asks for consent, or is refused. The request is three lines and two buttons. See vaglio.
• It builds the tools it lacks. No endless hand-written catalog: when an executor is missing, the synthesizer generates one in a few minutes — name from the closed vocabulary, birth tests, signature — with your approval. See synt and scene 6.
• It can add bounded agency inside an executor without expanding the planner. When the route is uncertain but the purpose is narrow, an internal LLM disambiguates steps within fixed actions and limits. To the planner it remains the same typed executor. See intelligent executors.
• It takes execution to where the data lives. A compatible executor may run on a registered PC; decision, consent, signing, and audit remain on the server. The device executes, but does not become a second agent. See remote executors.
• It is reproducible like software, not like a prompt. The local planner is constrained to a closed vocabulary, the generation seed is pinned, ties between sibling tools are broken by curated affinity — not by coin flip. You can test it, regression-guard it, trust it.
• It doesn't lie about outcomes. Counts reflect what was actually done; truncations are declared; every action that claims to be undoable is undoable by construction (a closed catalog of reverse patterns).

2 · Why it's different

Agents already exist, in whole families — frameworks you assemble, terminal companions, chat-borne butlers (OpenClaw and friends) and the ecosystem of importable “skills”. Metnos makes different choices across several axes, and for a precise reason: a local planner is not a frontier model, and it must be put in a position where it cannot go wrong.

The map, mid-2026

A snapshot taken in July 2026: names move fast, the families barely at all.

1 · Orchestration frameworks — LangChain/LangGraph, LlamaIndex, CrewAI, AutoGen (now folded into the Microsoft Agent Framework), smolagents. Open libraries a developer assembles an agent from. Over the last two years they have all settled into the same shape: a graph or an event flow provides structural determinism — fixed routing, checkpoints, resume — but inside every node the model decides afresh on every run. Tools are free-named functions written by whoever assembles the system, and safety is that person's job, not a property of the frame. A note apart for smolagents: it has the model write executable Python directly — maximum flexibility, and all the trust moves onto the sandbox that contains it.

2 · Model-vendor stacks — OpenAI (Responses API and Agents SDK), Anthropic (Claude Code and the Agent SDK). Polished harnesses around proprietary cloud models. Claude Code's permission system — allow, ask, deny, with hooks that block outside the model's loop — is the closest mainstream relative of Metnos's approval card; but it governs free-form tool names around a remote model, where Metnos governs a closed vocabulary around a model that lives at home. On reproducibility the distance is sharp: OpenAI calls its own seed “best effort”, and Anthropic's API has no seed at all.

3 · Autonomous engineering agents — Devin, OpenAI Codex, Google Jules; on the open side, OpenHands. Maximum autonomy inside an isolated virtual machine; the brake sits downstream, in the human review of the pull request. Nearly all cloud and metered. OpenHands is the self-hosted exception capable of local models — but it remains a programmer executing contained arbitrary code, not an assistant with enumerated capabilities.

4 · Self-hosted personal assistants — Metnos's own family, and this is where the comparison bites. The 2026 story is OpenClaw: the same intent — a butler in your house, reached over chat, local models welcome — and the opposite governance: free-form markdown skills plus MCP servers, permissive by default, human confirmation concentrated on payment steps. ZeroClaw, a minimal Rust rewrite, is its wary cousin: pairing, isolated workspaces, allowlists. Alongside them: Goose (Block), Letta for persistent memory, Khoj for a private index of your documents, and Home Assistant's voice assistant — which rediscovered the fastpath principle on its own: deterministic intent matching first, the model only as a reserve.

The universal socket, behind the gate — The Model Context Protocol (MCP), born at Anthropic in late 2024 and passed to the Linux Foundation in late 2025, has become the universal tool socket: OpenAI, Google and Microsoft adopted it, and thousands of servers expose ready-made connectors. A typical MCP client, though, reads the prose descriptions servers declare and trusts them: that is the vector of the tool poisoning the security literature documents at length. Metnos neither ignores that ecosystem nor grafts it in raw: the declared route is a dedicated executor that speaks MCP — a vocabulary-admitted name, a signature, a sandbox and an approval card like any other tool; the external server remains a mediated guest, never an authority. Thousands of connectors come within reach, but none enters without passing the gate.

Where the mainstream wins — Honesty is owed here too. Whoever grafts MCP in raw inherits thousands of connectors in an afternoon; Metnos's gate reaches that ecosystem too, just not at the same speed. A frontier model re-invoked on every turn handles novel, messy requests better than a local planner on repeatable routes. And the managed platforms offer observability, evaluation and scale that a self-hosted project does not match. Metnos does not compete on those axes: it competes on provenance, reproducibility and boundary — signed tools, a repeatable plan, judgement against your telos, data that never leaves your machine.

Nine systems, one table

Two choices that change the boundary

These are not two more tools. They are general ways to make executors more capable without expanding the planner's language.

Why Metnos did not adopt the standard “skill” format

The popular skill formats — markdown skills, MCP servers — are convenient and dangerous in equal measure: you import a package and the assistant executes its code with its own privileges. For an assistant that touches your files, mail and shell, that is remote code execution by design: one malicious or sloppy package is enough. Metnos chooses security by construction: a closed vocabulary (you cannot name a tool the grammar doesn't allow), a 7-layer admission gate for every new or imported executor (signature → affinity overlap → aging → sandbox → smoke test → LLM verification → append-only audit), explicit consent before anything destructive. The slogan: don't trust the package — the package has to earn its place. The public skill ecosystem isn't ignored: it gets translated into this model, never executed raw.

Determinism is a choice, not an accident

Most agents treat the LLM as an oracle you re-roll every turn. Metnos makes the opposite bet: a local planner over a closed vocabulary can be made reproducible — the generation seed is pinned, and when two sibling tools tie, a curated affinity signal decides, not chance. Measurably: the internal routing bench repeats every request five times and demands the same plan, five out of five. And it compounds: a request shape solved once is replayed by the fastpath with no LLM call at all — lower latency, zero cost, identical outcome. Flexibility (the frontier model) stays available, but it's the reserve, not the engine.

What a terminal agent does better

Due honesty: as a real-time coding companion inside a repository, a mature terminal agent remains superior, with an extension ecosystem Metnos neither has nor chases. But Metnos is not defined by household tasks or by one vertical. It is an operational architecture that keeps planning, executable capabilities, authority, memory and audit under one governed boundary. Mail, photos and calendar are reference uses; maintaining Metnos through its GitHub workflows is already a non-household use. The two kinds of system coexist just fine.

3 · Nine cases, one system

These cases are not separate modules and do not define an exhaustive product scope: they use the same planner, contracts, and guards. The line keeps them together; each stop shows only the request, the relevant chain, and the operational boundary that changes. The GitHub maintenance case deliberately shows that the architecture is not confined to the home.

4 · The Tutor: Metnos can explain Metnos

A governed system is useful only if its user can ask what it can do, why it stopped, and how to use a feature. The Tutor makes capabilities and procedures understandable without turning the manual into another all-powerful agent.

Compiled knowledge, not an answer from memory

The Tutor indexes multilingual descriptions from manifests actually admitted by the loader, a closed set of explicitly listed public documentation, and a few high-authority curated procedures. Sources, vectors, and metadata live in one signed SQLite catalog replaced atomically. It does not scan Documents, mail, calendars, logs, ADRs, or conversations.

A new language does not require a third manual

Documentation remains Italian and English. A French, German, or Spanish question is compared by the multilingual embedding model with the best available source, usually English; the local model then answers in the current language. Fallback is per concept, so a partial translation cannot hide the rest of the catalog.

5 · Where it lives and how you talk to it

Metnos runs on a Linux machine of yours. The LLM tiers are abstract roles, not pinned models: a CPU endpoint, a local or remote model you already serve, and an optional frontier fallback are all first-class paths. Phones and laptops are clients: the mind, the memory and the audit live on one machine.

Two surfaces, one mind

The browser: a chat served by the server itself (port 8770), with photo previews, the gallery, and the admin dashboards (synt proposals, executors, runs, turns). Telegram: the same brain in your pocket, with approval cards as inline buttons. For automation, the HTTP API (/agent/turn, streaming too) is the same door the chat uses.

The web chat also shows ✓/✗ feedback badges on every reply: your verdicts feed the care of the catalog.

Who you are, to the bot: pairing

Telegram is a public surface: anyone who knows the bot's name can write to it. Metnos binds every (channel, sender) pair to an autonomy level with a single-use signed code: /pair PAIR.<code> (Ed25519, expires in minutes) for pairings decided by the host; /start <token> for guests created from the admin UI. No central account, no password: a per-channel-per-sender directory only the host can edit. See pairing.

Language is data, not a constant

Every visible message, every tool description and every LLM prompt lives as per-language data: Italian and English are validated, a new language is added by translating the packs, no code changes (prompts_cli add-language <code> scaffolds the structure; the translation is reviewed and promoted by hand). Honesty: beyond IT and EN, today, it's untested ground. See multilang.

6 · What happens when it says “may I?”

This is the most important piece of the experience. Every action that changes the state of the world — sending, writing outside the granted perimeter, running shell — goes through four real components, in this order. The point is not to always ask: it is to ask well, and less and less.

Less and less friction, never less control. The card modulates with recurrence: full the first times, then two lines, then one. And on the first approval of a kind you can grant a territory (“all writes inside ~/Documents/invoices/”) — from then on, there, Metnos stops asking; the grant is revocable whenever you want. See approval_ux.

And once it has acted, it can walk back. Undo is not an LLM “doing its best”: it is a closed catalog of reverse patterns declared in each mutating executor's manifest (swap source/destination, delete what was created, restore the blob backup, delete by id). Honest counts: if it says it undid three things, it was three.

7 · Its memory: what it remembers and what it doesn't

Four distinct stores, with different lifetimes and write rules — SQLite tables and text files you can open, not an opaque vector somewhere.

Memory of the world (the first three rows) and memory of itself (the mnestome), kept separate by design. The fourth store is the unusual one: the mnestome also records the gaps — requests no tool could close — because gaps are the engine of growth.

The detail that matters: Metnos never promotes a fact to permanent memory on its own. It proposes (“I noticed you often mention the new dentist: shall I save him as a regular contact?”), you decide. And a failed attempt is not forgotten: it remains as a proto-mnest — a recorded aspiration, with enough context to recognize the same shape next time. See mnestome and scratchpad.

8 · How it grows: synt, skills, backends

An executor is a small Python file that does one thing, with a manifest declaring its arguments, capabilities and sandbox profile. Once signed it is a stable artifact: it doesn't learn, it doesn't change. The growth intelligence lives elsewhere — in the synthesizer.

Synthesis in five stages

At the exit, the admission gate (7 layers): signature → affinity overlap → aging → sandbox → smoke test → LLM description-vs-code check → append-only audit · then human approval and Ed25519 signature.

Five small, focused prompts instead of one monolith separate responsibilities and make every stage verifiable. Only stage 1 sees the closed vocabulary; only stage 5 writes code.

Reactive synthesis (it happens mid-turn, scene 6) is the first step of a cascade ordered by cost: first compose existing tools, then generate the missing one; at night the introvert passes propose merges (two tools with overlapping traces), generalizations (three specialized tools collapse into one parametric) and specializations (a hot case splits off). Everything goes through your yes. Two installations, in two homes, will have different catalogs after six months — each shaped by real use. See synt and lifecycle.

Skills and backends: two axes that don't blur

Everything that ties Metnos to an external service is a skill: a group of capabilities dormant until configured, enable/disable at will (system · photos · mail · web · geo · calendar · github · google-workspace · frontier). Enabling a skill without its prerequisites is harmless: it stays visible and inert until its service or credential appears. You manage them from the command line or just by asking in chat (“which skills do I have?”, “disable the web”).

The backend is the other axis: how an action reaches a concrete service. The provider is chosen from configuration, deterministically — the planner never sees “Google”: it sees create_events, and the resolver routes. Adding a second provider (say, GitLab next to GitHub) is +1 backend file, zero new executors: no per-provider photocopy tools, no provider bias in the local model. See skills_backends.

9 · People and devices: host, guests, remote executors

Metnos is not multi-tenant in the SaaS sense: it is one household. Inside it there is a host — the server's owner, keeper of the signing key — and zero or more guests, each with their own level.

Scene 4 shows the model at work: the host configures, the guest receives, audit lines stay separate per pairing. Every channel has its own door, its own key, its own history.

Remote executors: how far the code can reach

One server, but not one filesystem: many things you'd want acted upon (laptop files, an open application, a screen) live elsewhere. Gateway, policy and memory stay on the server; some executors run on registered devices — a thin client with its own Ed25519 identity, admitted with a single-use signed code, revocable from the server in one gesture.

10 · What the catalog enables, what the core forbids

Cross-cutting rule: no silent failure. Cap reached → it says so (how many used, how many available) and asks before widening. Partial outcome → counted as partial. Never a “done” that doesn't match reality.

11 · Operational status

Metnos is an installable and operational pre-1.0 system, not a polished product. Contracts, security and verifiability take priority over compatibility with earlier internal choices. The generated catalog and the tests are the sources of current status.

Trying it

The real requirement is hardware: a machine that can serve a capable local LLM. Tiers are abstract roles — a CPU endpoint or a model you already serve is fine; a weaker model means weaker planning, not a broken install. No GPU is required on principle.

$ git clone https://github.com/brunialti/metnos.git && cd metnos
$ bash install/bootstrap.sh --check   # pre-flight only — writes nothing
$ bash install/bootstrap.sh           # interactive, six phases, idempotent

And support is part of the experiment: the repo's issues are triaged by a Metnos instance (scene 8) — drafts prepared by the system, posted only after human approval. If the assistant can't help you run the assistant, that's a bug we want to see.

The fifty-cent description

If you take away one thing: Metnos is a self-hosted architecture for a governed agent, with five distinct commitments — it asks before acting, builds tools inside verifiable rules, is reproducible like software, concentrates adaptive intelligence inside narrow-mandate executors, and takes signed executors to devices without moving decision and audit away from the server. If that combination intrigues you, you are the right audience.

12 · Minimal glossary & further reading

Executor

A tool in the catalog: Python file + manifest + Ed25519 signature + sandbox profile. Vectorized by construction: lists in, lists out.

Intelligent executor

An executor with a bounded internal observation-and-action loop. It may use an LLM to disambiguate the route, while mandate, authority, input, output, and verification remain those of the public contract.

Remote executor

An executor run by a client on a registered device. The server plans, authorizes, signs, and audits; the device verifies and executes.

Synt

The synthesizer: the cascade that grows and curates the catalog (compose, generate; merge, generalize, specialize). Always behind human approval.

Vaglio

The two-phase evaluator between a proposed action and its execution: non-negotiable binary guard + graded judge against the telos.

Telos

Your aims, written in TELOS.md as soft tendencies. The judge measures proposed actions against them.

fastpath

The learned fast path: a request shape solved once is replayed with no LLM calls. Same outcome, minimal latency and cost. When a shape recurs across a whole group of similar requests, the generalized plan becomes an autopath.

Mnestome

The memory the system keeps about itself: successful co-activations (mnests) and attempts left halfway (proto-mnests). The substrate of growth proposals.

Skill / Backend

Two orthogonal axes: the skill governs whether a capability is active and trusted; the backend governs how it reaches a concrete provider, chosen by configuration and never by the model.

Pairing

The signed admission of a (channel, sender) pair to an autonomy level. Replaces login: no accounts, a directory only the host touches.

Approval card

Three lines and two buttons: what, on what, how redoable. It shortens with recurrence; it can grant revocable territories.

The full Glossary

Alphabetical entries with links to canonical sources.