1. The idea, in two lines

For example, you can ask Metnos: “Find the PDF files modified today.” If you later repeat the same request, Metnos may reuse the plan that already worked. There is nothing to enable: the check happens automatically.

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

Both layers reuse plans that have already run, but at different levels of generality. L0 starts from one request: an exact match may reuse a plan that contains request-specific values. Only plans known to be generalisable are eligible for L0's semantic match against differently worded but equivalent requests. L1 instead starts from the complete intent and a group of related requests; before execution, values that depend on the question are derived again from the current text.

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 stores previously executed plans in a SQLite database (fastpaths.sqlite). An entry is created after a successful turn produced by the engine, L1, or an L0 semantic match. Metnos records the normalised request, its fingerprint, an embedding when available, the complete plan, and the intent expressed as a verb and object. No separate approval is needed: the plan consists of admitted executors and has just completed a real execution successfully.

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 associated with that request. If the engine later resolves it successfully, it may create a new one.
• 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 a family of requests and may derive either from explicit feedback or from the shadow seeding described above. L0 comes first in the cascade. Before execution, both layers validate their signatures, realign arguments with the current request, and pass through the same preparation and safety checks used for a new plan.

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. How arguments are refreshed

Recognising a plan is not enough: it must also be bound to the values in the current request, such as paths, URLs, accounts, dates, or quantities. Before every execution, Metnos applies one shared sequence of deterministic transformations. Each transformation operates only on fields declared by the executor schema; when there is no reliable signal, it does not invent a value.

• Values recognisable in text. args_extractor.py identifies known types, including URLs, Linux and Windows paths, email addresses, explicit quantities, file extensions (“PDF files” becomes *.pdf), dates, and time windows in Italian and English.
• Specialised resolvers. Mail accounts, time windows, and other instance-governed fields are recalculated from the request and the context available at execution time.
• Compound requests. When a sentence contains several actions, values are associated with the relevant clause, so that a date or path belonging to one action does not leak into the next.

This preparation also applies to plans retrieved from L0 and L1. A plan with literal values that cannot be generalised remains eligible only for the exact request; some plans, including those with embedded numeric identifiers or authenticated sessions, are not stored at all.

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 complete synthesis procedure, including deterministic checks, birth tests, 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 same 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