Coding agents that retrieve the relevant file, not the similar one

1. 01 · Ingest

   Scope what you ingest

   Every document lands with a groupName: the sets it belongs to. Those sets are what retrieval intersects later, so the structure you choose here is the precision you get there.

   context.add

   import AlchemystAI from "@alchemystai/sdk";const client = new AlchemystAI(); // reads ALCHEMYST_AI_API_KEYawait client.v1.context.add({  context_type: "resource",  scope: "internal",  source: "github",  documents: [{    content: "withSession() wraps every authenticated route. Token refresh happens here, not in auth/refresh.ts.",  }],  metadata: {    fileName: "services/api/middleware/session.ts",    groupName: ["codebase", "api", "middleware"],   // the sets this belongs to  },});

2. 02 · Write

   Store the decision next to the code

   The reason code looks strange is usually in a PR thread. Store it in the same scope as the file it explains, so the agent reads the why before it changes the what.

   context.add

   await client.v1.context.add({  context_type: "resource",  scope: "internal",  source: "github-prs",  documents: [{    content: "PR #1184: retry refresh once, with jitter. Immediate retry caused a thundering herd on token expiry. Do not remove the delay.",  }],  metadata: {    fileName: "pr-1184-session-retry.md",    groupName: ["codebase", "api", "middleware"],    lastModified: "2026-07-22T00:00:00Z",  },});

3. 03 · Search

   Search before editing

   Search intersects the scopes, subtracts superseded and duplicate content, and ranks what survives. Only that reaches the model, and the whole decision is recorded as a Context Trace.

   context.search

   const { contexts } = await client.v1.context.search({  query: "Users are logged out after token refresh",  scope: "internal",  similarity_threshold: 0.8,  minimum_similarity_threshold: 0.5,  metadata: { groupName: ["codebase", "api", "middleware"] },   // ∩ narrow scope});// − superseded, deduplicated → ranked → into the window// Every search is recorded as a Context Trace.const reply = await llm.respond(message, { context: contexts });

npm install @alchemystai/sdk or pip install alchemystai, both ship the same client. Full reference in the docs.