Refs

Every search hit in Echo carries a ref — an opaque string that uniquely identifies the entity the hit refers to. Refs are the currency of the system: you receive them from search, pass them to fetch, and store them when you need to come back.

Ref grammar

A ref encodes the source, the provider, the repository or connection, the branch or version, and the path to the entity. But from the consumer's perspective, it is an opaque string. Do not parse it, build it, or assume its internal structure — the grammar may change between versions.

Example refs (for illustration only — treat them as opaque):

  code:github:acme/api:main:src/auth/verify.ts:verifySession
  work_items:jira:PROJ-1234
  database:postgresql:analytics:public.orders
  graph:acme/api:main:Module:src/auth
  commits:github:acme/api:abc1234

What you can do with a ref

• Fetch — pass it to the fetch endpoint to get the full content object, its type, and its relations.
• Store — refs are stable across searches within the same sync state. You can store a ref and resolve it later, as long as the entity still exists.
• Cite — every fact Echo returns keeps its ref, so the consumer can trace the claim back to the source.

Ref resolution and staleness

A ref becomes stale when the underlying entity no longer exists — a file was deleted, a ticket was closed and archived, a table was dropped. Fetching a stale ref returns a 404 with a body indicating the ref was valid but the entity is gone. This is different from an invalid ref (malformed or from another project), which returns a 400.

Resource URIs

In addition to refs, Echo exposes stable ontology:// URIs for entities in the graph. These are used in cross-references and MCP resource declarations. Like refs, they are opaque to the consumer.

Next: The faceted contract.