1. The idea, in two lines

Ask Metnos with a request like this example: “Find the PDF files modified today.” If you repeat the request, Metnos may reuse the plan that already succeeded; you do not select or enable the fastpath manually.

Before calling the planner, Metnos tries to recognise the request. If a reusable plan exists and is still valid, it runs that sequence of executors. If the context or catalogue has changed, it treats the entry as invalid and returns to normal planning.

2. Why a fast-path is necessary

Planning is needed when a request is new or requires a new composition of capabilities. Repeating it when the system already holds a valid plan adds work and variability without improving the result. For example, a request already solved with get_urls and describe_entries can reuse that sequence, provided its arguments are derived from the current request.

What remains is to recognise a known request — and to judge when one that is merely similar sits close enough to be handled the same way. Two reuse layers handle this distinction. They recognise different degrees of similarity, but share one purpose: run a known plan without asking the planner to build it again.

3. The two layers and their boundary

The two layers differ in how much of the path they recognise. L0 recognises all of it, arguments included: the same request as before, with the same concrete values. L1 recognises the path alone — the skeleton of the solution, stripped of its arguments — and so it holds for a whole family of related requests.

The order is fixed: L0 first; if it finds nothing, L1. If both miss, the request reaches the planner (the engine), as always.

The planner does not disappear: L0 and L1 are controlled shortcuts. A new or ambiguous request, a turn with attachments, or a request without a valid match continues through the normal engine.

4. L0 — runtime-produced cache (fastpath.py)

The first layer lives in runtime/engine/fastpath.py and keeps the plans it has already run in a SQLite database (fastpaths.sqlite). The entries appear on their own: whenever a turn succeeds — a fresh plan from the engine, the reuse of an L1, a promotion from cosine 0b — Metnos notes down the canonical query, its hash, the embedding produced by the configured model, the whole plan (the skeleton, or framework) and the intent: the verb and the object of the request. No approval involved: the chains are built from executors already vetted and tested.

Two ways to find a match

The search runs in two phases:

• 0a — hash match. The query, reduced to a normal form, becomes a fingerprint (a deterministic hash) and is looked up for an exact match, with no language model and no new embedding. It is the only route allowed for plans tied to a single request: the ones with literal arguments lifted from the question — a proper name used as a search key, say — which, replayed on a similar but different request, would return the wrong data.
• 0b — semantic cosine. If the fingerprint finds nothing, the query becomes a vector and is compared, by cosine, against the entries above the configured threshold. This is what brings the variants of one request under the same answer (“what time is it?” and “tell me the time”). Cosine serves only the general plans, the ones not tied to a single request: that way one question's arguments don't stray onto another that is close in meaning but distinct.

An L0 entry removed because it aged, became invalid, or received negative feedback can be recreated by the next successful turn. Removing it does not remove the underlying capability.

Safety valves

• Negative rating: a user “✗” deletes the fastpath for that query — which comes back if the request returns and succeeds (the last word always wins).
• Administration: in the web chat, open Settings > Memory > Praxis to inspect L0 shortcuts and delete one. If you ask for directions from Telegram, this path still refers to the web chat; the page does not open inside Telegram.
• Tools that cannot be stored: undo_last_turn, get_inputs, get_approval, and authenticated browsing tools produce no fastpath, because their meaning or session identifier depends on the current turn.
• Absolute dates: a plan with explicit ISO dates (say since_iso="2026-06-11") is not recorded: replaying it on another day would open a time window already frozen in the past. Relative dates (time_window="today") are kept, because each replay works them out afresh.

5. L1 — reuse across a request family (autopath.py)

The second layer lives in runtime/engine/autopath.py. It does not look for the same wording. It finds a semantic family, checks that the intent object matches, and reuses only plans without literal arguments tied to the original request. Variable arguments are derived again from the current request before execution.

An autopath can arise in two ways. Positive feedback promotes a successful plan once it reaches the configured threshold, which is one confirmation by default. Alternatively, two successful runs of the same intent can seed a shadow autopath when the latest plan contains at least four steps. A shadow is usable but remains distinct from a confirmed plan; the first positive rating confirms it. This second path reduces the cost of recurring requests without presenting a non-human signal as human approval.

Feedback and plan selection

• Anti-autopath: after a repeated negative rating (three failures or more), Metnos records an anti-autopath that bans that plan, for that group, for thirty days. The same symmetry holds: a positive rating lifts the ban.
• User-requested repeat: the repeat verdict excludes the plan for one hour, allowing recovery to seek a different one.
• Several available plans: ordering is deterministic: first the composite score, then positive confirmations, uses, and finally the identifier.

The boundary is deliberate: L0 favours repetition of the same request; L1 generalises to an intent group and may derive either from explicit feedback or from the shadow seeding described above. L0 comes first in the cascade, but both layers must pass the same validity, argument-grounding, and safety checks before execution.

6. Validity, aging, and usage transfer

Operational-world signature

Every stored plan carries two signatures: one for the executors it uses and one for the candidate family available for that intent. The signature also incorporates the version of routing and presentation rules. Metnos recomputes them before reuse: a changed or removed executor, a new competing capability, or a routing change turns the entry into a miss. The system replans instead of executing a decision made in a different operational context.

These signatures are user-agnostic and contain no profiles, affinities, or personal preferences. L1 therefore remains a shared cache of plan decisions with deterministic keys. Effects authorised for the user and final presentation — language, tone, length, and format — are applied outside the plan key.

The candidate family comes from the canonical vocabulary, including the relationships between specialised content and filesystem carriers. For example, a new files capability may change a plan operating on images or texts. Query words and manifest affinities do not enter the signature: invalidation follows catalogue semantics without making L1 specific to a user or to one phrasing.

L0 fastpaths are retained or retired by fixed rules, with no model in the loop. Each night the task_state_reaper process applies three aging rules and four retirement conditions.

Aging

Retirement (only with a complete catalogue)

Usage-count transfer

When a fastpath is retired because an executor superseded it (the C2 conditions), its usage count (n_uses) passes to that executor through the lifecycle statistics store. Previously observed usage is therefore not reset.

Pruning removes a stored route, not its executors. If the same request returns and succeeds, L0 can record the updated plan again.

7. The arguments extractor

Recognising the request is half the work. The other half is drawing out its concrete values: which paths, which URLs, which date, which threshold. A rule-based extractor (args_extractor.py) handles this, again with no model:

• Closed rules. Regular expressions for the known types: URL (https://...), path (~/... or /..., with the “home” shortcut becoming ~/), email, numbers, file extensions (“PDF file” → *.pdf), dates (today, yesterday, tomorrow, the day after — in Italian and English — turned into ISO format), and time windows (“this week”, “last 24 hours”, “last 7 days”).
• Arguments that depend on the request. Some values — the mail account, the time window — change with the question: at execution (and at recording) they are worked out afresh on the current query, not inherited from the stored plan.

8. Configuration

Fastpath and autopath thresholds are read from the Metnos process environment; when a variable is absent, the module default applies. The former [fast_path] and [multi_tool_fast_path] sections in ~/.config/metnos/runtime.toml have been retired and are ignored. The Praxis page can inspect and flush the caches, but it does not edit these thresholds. A persistent override therefore belongs in the service configuration; constants read at import time require a process restart.

Layer 0 (fastpath)

Layer 1 (autopath)

Promotion to executor

9. Promotion to a synthesised executor

When several recurring L0 fastpaths share the same plan structure (the skeleton hash) and the same intent, each night the task_fastpath_promotion process weighs them as candidates to become a synthetic executor in their own right. What it weighs is the group, never the single instance: at least three distinct fastpaths, fifteen uses in all, and thirty days of age. And only multi-step shapes are promoted: single-step ones already have an executor, and there the fastpath only saves the LLM call, not the plan.

Why from L0 and not from L1. The analysis looks at the L0 fastpaths, not the L1 autopaths, because evidence of concrete requests lives in L0: how many distinct requests recur, how often, and for how long (the three numbers above). L1 is already general and arises from user feedback or shadow seeding, but it does not retain that count of distinct requests. Generalisation therefore happens here by grouping L0 fastpaths with the same plan shape and intent.

Two modes of promotion

• Mode 1 (default, active). The candidate becomes a proposal awaiting a person's approval in Settings > Lifecycle > Changes in the web chat. If the intent family is absent from the catalogue, approval queues the full synthesis: five stages, birth test, signing, and installation. If the plan already composes an executor from that family, a person must first choose a qualifier; approval alone does not start synthesis. Telegram can explain the procedure, but the path always leads to the web chat.
• Mode 2 (optional, off). Past a much higher threshold, Metnos may automatically synthesise only a candidate whose family is still free. It requires at least five fastpaths, fifty uses, thirty days, and three nightly observations of the same proposal; a previous human decision blocks automation. The candidate still traverses the complete synthesis pipeline. Only one attempt is allowed per night, whether it succeeds or fails.

Where an executor comes from

For candidates whose family is free, Metnos records the source fastpath identifiers and fingerprints in the promotions table. Once the new executor enters the catalogue, the nightly process uses that link to retire exactly the entries that produced it. Composition candidates do not receive this automatic provenance because their final name depends on the human-selected qualifier; their L0 entries remain manageable under Settings > Memory > Praxis.

© 2026 Roberto Brunialti · Metnos documentation