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. The gap is in how the subset is chosen. Similarity is not relevance: an embedding match returns what is near the query, not what answers it. The embedding space is opaque — you can rank neighbors but you cannot explain why one is nearer than another, which makes the retrieval step hard to audit and silently sensitive to embedding-model upgrades. Scry’s selection function lives in fields the agent authored at write time, in plain text, queryable by SQL — the same question always returns the same answer, and the reason is legible.

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. The selection function is hand-curation — useful at small scale, but the file grows monotonically while the context budget does not. Selective imports and hierarchical loading buy time; they do not provide a query-time selection function.

Grep, and its modern extensions (ripgrep, Sourcegraph, ast-grep, LSP-driven navigation). Search the codebase directly. These are deterministic and need no model in the query path — the property scry inherits. What they lack is a meaning-shaped index: they find the files that contain a string or match a structural pattern, not the files that answer a question, and they cannot rank a load-bearing design note above an incidental mention.

Agent-memory tools. A newer category — mem0, MemGPT/Letta, Zep, the platforms’ own built-in memory features. These are scry’s nearest neighbors in product space: persistent stores for what an agent has learned, queried across sessions. The difference is where the work goes. Memory tools extract structure from raw text after the fact — consolidation passes, summarization, learned categories — which means the retrieval surface is shaped by a model, not by the agent that did the work. Scry inverts this: the agent shapes the surface at write time, in a marker it authors itself, indexed by SQL it can read. The selection function is explicit and editable; nothing learned sits between the agent and what it wrote.

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.

Scry’s own cost is marker discipline. A file without a marker is invisible to the curated index; a marker whose fields no longer match the file’s content silently degrades recall. Both are caught only by the agent that uses the system. The trade is upfront authoring work for cheap, deterministic recall — worth it when the same knowledge is recalled across many sessions, not worth it for one-off or fast-changing state.

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;

The query returns whatever the marker index holds — zero rows, one, or many — keyed by the fields the author chose to expose. A marker that was never written when the artifact was produced leaves the artifact invisible to scry. The discipline lives at write time, not query time.

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",
         "args": ["serve"]
       }
     }
   }

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 →