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 → binding → 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 → binding.

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 sign

plan_* returns the full account set plus state-read args and landing preludes → an external builder builds → Gecko simulates the exact bytes → a Receipt with a binding over those bytes → an external signer (wallet / TEE / human) signs → verify_signed_transaction proves the signed bytes are the checked ones → submit_transaction relays them, and refuses anything that does not verify.
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 holds a key, never proxies the data plane. Building and signing belong to compose partners. That is the design, not a gap. The one send path it ships relays only signed bytes that verify against its own binding.
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 with a binding; an external signer signs, and only bytes that verify against the binding are relayed.

Intent → derive the full account set → state reads → external build → unsigned prelude assembly → simulate → Receipt + binding → external signer → verify → submit.

  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. On the money paths, a fresh blockhash is patched in at the offset the layout dictates, so the simulated bytes are the bytes handed back.
  6. Simulate: simulateTransaction with sigVerify:false, on a fork or against a public mainnet RPC.
  7. Receipt + binding: status, categorical revert class, compute units, and a hash over the exact message bytes at exact strength. → The Receipt
  8. External signer signs. Then verify_signed_transaction checks the signed bytes against the binding, and submit_transaction relays them only if that check passes.
Gecko never signs. Unsigned assembly for simulation is the one documented carve-out, and it is enforced at the landing layer by an AST check that proves that layer contains no signing or sending path. The one sending path, submit_transaction, lives outside it and is structurally unable to relay bytes without a binding.
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 hold a key

No keypair on any path. The landing layer has no sign or send path, AST-enforced. submit_transaction relays only signed bytes that verify against a Gecko binding.

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). A caller-supplied rpc_url goes through the same guard.
  • 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 · the signing gate that checks signed bytes against the receipt’s binding · the AST-enforced no-sign boundary on the landing layer.
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.