Skip to main content
Gecko is a control plane, not a data plane. It holds the API’s surface, the generated tool defs, and correctness metadata — never the data flowing through. That single invariant is what makes the rest of the design coherent. Below: the same system in three views. Each has a static diagram and an interactive version you can pan, filter, and click through.

​
View 1 — Context engineering (the memory substrate)

Gecko context engineering — semantic memory (comprehended surfaces plus a lexical catalog), procedural memory (question-shaped tool defs and typed executable plans), episodic memory (a categorical corpus and an N-confirmed drift series), and a working-memory projection that feeds the host agent over MCP.

Gecko as a memory substrate: semantic, procedural, episodic, and working memory — under someone else's agent, not replacing it.

Gecko is not the agent — it is the memory-and-context substrate under other people’s agents. Every block of the canonical agent-memory architecture exists here, and three of them are deliberately different from the textbook. Retrieval quality is fed by a misrank-aware evaluation: a golden set plus a closed miss-cause vocabulary, so the lexical-vs-semantic gate gets data instead of a guess.
The diagram above is a render. The interactive version — pan, zoom, guided views, PNG/SVG export — ships in the repo as a single self-contained file: docs/assets/architecture-context.html. Download it and open it locally; it needs no server and no network.

​
View 2 — The full pipeline (sources → knowledge → action)

Gecko full architecture — OpenAPI, docs, Anchor IDLs, program source and a project catalog enter through sanitize/quarantine/Skill Guard, are comprehended into normalized operations, recovered PDA seed recipes and generated configs with measured overlays, form surface and program knowledge graphs with provenance on every edge, are projected over MCP and CLI, and reach action only via plan → external build → simulate → receipt → fail-closed signing gate → external signer.

Untrusted sources pass an anti-poison gate into comprehension, become provenance-tagged graphs, project as MCP tools, and reach action only through simulate → receipt → signing gate.

1

Sources — all untrusted

OpenAPI, human docs, llms.txt, Anchor IDLs, raw program source (Steel and native too), and a 4,500-project on-chain catalog. Everything ingested is treated as hostile input.
2

Anti-poison gate

Spec sanitizer, per-tool quarantine, image Skill Guard (rendered-pixel payloads and encoded-content rescan), SSRF netguard, out-of-band auth-host anchoring. Fail-closed.
3

Comprehension

Ingest to normalized Operation / Param; PDA seed recovery from IDL and source (source rescues what the IDL structurally drops); auto-comprehend on pick, which emits a generated config plus a measured overlay of what could not be derived from any public surface.
4

Knowledge — provenance on every edge

Surface graph: EXTRACTED > DECLARED > INFERRED > CLAIMED → VERIFIED / REFUTED. Program graph: EXTRACTED / RECOVERED / FLAGGED. Cross-API correlations join on declared value domains first.
5

Projection

MCP (hosted, stdio, npx/uvx), the CLI, the Scorecard, and the Playground. Auth headers never appear in a tool def.
6

Action — verify, never execute

plan_* returns the full account set plus state-read args and landing preludes → an external builder builds → Gecko simulates → a Receipt → a fail-closed signing gate → an external signer (wallet / TEE / human).
7

Learn

A categorical outcome (never a payload) can be recorded on explicit opt-in, feeding the drift series, which feeds back into the graph.
The hard boundaries: Gecko never signs, never broadcasts, never proxies the data plane. Building and signing belong to compose partners — that is the design, not a gap.
The diagram above is a render. The interactive version — pan, zoom, guided views, PNG/SVG export — ships in the repo as a single self-contained file: docs/assets/architecture.html. Download it and open it locally; it needs no server and no network.

​
View 3 — The on-chain action path (the proven loop)

The proven on-chain loop — the agent states intent, Gecko derives the full account set including IDL-hidden and source-recovered accounts, reads control-plane state for sane arguments, an external builder builds the instruction, Gecko assembles unsigned preludes and simulates the transaction, and returns a receipt; only a passing receipt reaches an external signer.

Intent → derive the full account set → state reads → external build → unsigned prelude assembly → simulate on a $0 fork → Receipt → only a passing receipt reaches the signer.

  1. Intent — “buy this token”, “swap SOL for USDC on this pool”.
  2. Derive the full account set — including accounts the IDL hides (bonding_curve_v2) and seeds recovered from source (base_factor).
  3. State reads (control plane) for sane arguments — e.g. curve reserves → max_sol_cost.
  4. External build — the plan goes to the builder; the builder returns the instruction.
  5. Unsigned prelude assembly, for simulation only — idempotent ATA creation, wSOL wrap/unwrap, compute budget.
  6. Simulate — simulateTransaction with sigVerify:false on a $0 mainnet fork.
  7. Receipt — status, categorical revert class, compute units. → The Receipt
  8. Signing gate — fail-closed. Only a passing verdict reaches an external signer.
Gecko never signs and never broadcasts. Unsigned assembly for simulation is the one documented carve-out, and it is enforced at the sign/send boundary by an AST check that proves the landing layer contains no signing or sending path.
The diagram above is a render. The interactive version — pan, zoom, guided views, PNG/SVG export — ships in the repo as a single self-contained file: docs/assets/architecture-onchain.html. Download it and open it locally; it needs no server and no network.

​
Invariants

Control plane, never data plane

Stores the API surface, tool defs, and correctness metadata only — never response payloads, user data, or secrets.

The engine is API-agnostic

Everything API-specific reduces to data (the spec) plus one adapter seam, Session.auth_headers(). Adding an API doesn’t touch ingest/catalog/tools/caller.

One code path, two modes

recorded and live differ only at the transport edge. The free offline simulation comes first; live smoke is the final check.

Auth is invisible to the agent

Tool defs never expose auth headers. The agent describes intent; Gecko injects credentials at call time from your OS keychain.

Never sign, never broadcast

Simulation only. No keypair, no sendTransaction. AST-enforced at the boundary.

Never fabricate

Unknown facts are FLAGGED, not invented. Below the retrieval floor the answer is an honest no-start.

​
Module map

The comprehension logic is the product and lives in the package; the MCP server, the client, and the scripts are thin transport.

​
The one seam that matters

Adding a new API should not require touching ingest, catalog, tools, or the caller. The only API-specific code is, at most, an auth adapter — an object that implements:
A public API uses the built-in no-auth adapter (returns {}); a paywalled API supplies a session that returns its tokens. See Access & auth.

​
Security posture

  • Ingested spec, doc, IDL, and source content is treated as untrusted input.
  • URLs are validated before fetching (no SSRF — private/loopback/link-local ranges and non-http schemes blocked).
  • Secrets resolve from the OS keychain at call time and are never logged or persisted; errors redact tokens before they’re raised.
  • Seven fail-closed security layers: spec sanitizer · per-tool quarantine · image Skill Guard · SSRF netguard · out-of-band auth anchoring · verdict signing gate · the AST-enforced never-sign boundary.
The agent-readable version of this page is architecture.llms.txt in the engine repo — the same three views plus the honest works / not-built split. See also Status.