scry

The problem

The preeminent problem in agentic coding and more broader agentic space in general is what is becoming known as the “agent context problem.”

Every point of information an agent could ever need in a future session can be captured — but what aspects of that knowledge to surface to an agent and how to surface it remain the lynchpin of the agent context problem. The scry marker specification attempts to address some of the surface of the agent context problem as it relates specifically to agentic coding.

Other attempts

The agent context problem is not new, and scry is not the first attempt at it. The approaches that came before each address a real part of it — and each leaves a different part unsolved.

Larger context windows. The simplest answer: make the budget bigger. But the corpus grows without bound while any window, however large, stays finite — and a larger window dilutes attention across more tokens, raising the cost of the irrelevant knowledge that gets admitted. A bigger budget moves the line; it does not remove it.

Retrieval-augmented generation. Embed the corpus, retrieve by vector similarity at query time. This is the closest prior art, and scry shares its instinct — surface a subset, not the whole. But similarity is not relevance: an embedding match returns what is near the query, not what answers it, and the retrieval step is itself a model call — non-deterministic and unauditable. Two identical questions can return different context.

Hand-maintained memory files. A CLAUDE.md, an AGENTS.md, a notes file the agent reads at the start of every session. These work until the corpus outgrows the file: everything is loaded every time, relevant or not, and a human must curate what stays. It is a context budget with no selection function — only an ever-growing fixed cost.

Grep. Search the codebase directly. Grep is deterministic and needs no index, but it searches text, not meaning — it finds the files that contain a string, not the files that answer a question, and it cannot rank a load-bearing design note above an incidental mention. The agent still reads, reconstructs, guesses.

Scry takes the deterministic, no-model retrieval of grep and gives it a curated, meaning-shaped index: markers authored to be found, indexed into a structured cache, queried in SQL. The selection function is explicit, the query path has no LLM in it, and the same question always returns the same answer.

The query, end to end

Below is the same marker / SQL pair as above, expanded into a shape you can copy and run. The marker lives at the top of the file; the SQL runs against the SQLite cache scry init created in your project.

# In agent/design/auth-flow.md
<!-- @scry.entry
id: design.auth-flow~9eb0fd7e
kind: design
status: active
weight: 0.9
tags: ["topic:auth", "auth", "scope:runtime"]
summary: >
  JWT auth middleware, validates bearer tokens. Also:
  JWT, bearer-token, auth-guard, refresh-flow.
applies: adding protected endpoints, modifying auth
seeded_questions:
  - "What is the JWT refresh flow?"
  - "JWT bearer token validation"
@scry.entry.end -->

# In a future session, scry_sql:
SELECT d.id, d.summary
FROM   scry__doc d
JOIN   scry__doc_tag t ON t.doc_id = d.id
WHERE  t.tag = 'topic:auth'
  AND  d.status = 'active'
ORDER BY d.weight DESC;

One row comes back, every time. No vector store. No re-rank. No LLM in the query path. The marker fields decided what would be found before any future agent went looking; the SQL is just the lookup that honors that decision.

Install

1. Install the MCP server.

   uv tool install scry-mcp
   # or:
   pip install scry-mcp

2. Add scry to your agent’s MCP config.

   {
     "mcpServers": {
       "scry": {
         "command": "scry-mcp"
       }
     }
   }

3. Initialize scry in your project.

   cd path/to/your/project
   scry init

   A project.db appears in the working directory; the watcher begins indexing markers as files are saved.

The spec

scry-spec v1.1 — the versioned Scry Marker Contract. Defines the three marker kinds (@scry.entry, @scry.anchor, @scry.bind), the required and optional fields, and the resolution rules for binding references. Versioned independently from any implementation.

SQL is scry’s answer, not the spec’s mandate — scry-spec defines the marker; scry is the implementation that makes it queryable. A different implementation could index the same marker corpus into embeddings and serve recall by similarity; RAG, in that sense, is a possible implementation of the marker contract rather than a peer alternative to it.

Read scry-spec v1.1 →