conxt.docs
Handbook · for anyone building on MCP

Retrieval over MCP.

Good retrieval over MCP comes from tools that each answer one kind of question, scope before they search, say what they drew from, and abstain rather than guess. The model, not your code, decides which tool to call, so the tool’s name, description and result shape are the retrieval design. Conxt’s memory server is the worked example throughout.

1

Why retrieval over MCP is different

In a normal RAG pipeline your code decides when to search, with what query, and how many results go into the prompt. Over MCP the model makes all three choices, from text you wrote months earlier. Four things follow:

  • The description is the interface. The model sees a tool’s name, its description and its parameter descriptions, and nothing else. If two tools sound alike, it picks between them at random. If a description doesn’t say when to use the tool, it gets used at the wrong time.
  • Every result costs the model’s context. Twenty raw matches of a few hundred words each can fill a turn and push the user’s own words out. The server should return the few things that answer the question, not everything that matched.
  • The server often can’t see the client. A stateless HTTP server, as Conxt’s is, gets no session, no open files and no workspace roots. Anything it needs to scope the search, such as a project, must come in as a parameter.
  • The model will use whatever comes back. Results are read as evidence. A near match, a stale fact or another project’s number is repeated as fact unless the result itself marks it as weak, old or out of scope.
2

Choosing a retrieval pattern

A question needs the person’s memory Scope it firstpass project or team on every read call If the question isuse this pattern and tool One fact or decisionResolve to one answerresolve_contextEverything we know about XBroad recall, then readsearch_memory, get_contextOne kind: rules or decisionsTyped lookupsearch_decisions, get_memoriesThe latest, or as of a dateNewest firstrecall_as_ofNothing yet: a session startsStanding contextget_pinnedWho or what wrote this?Provenancelist_agent_memories Nothing clears the floor?Say nothing is on record, and keepthe question as an open item Scope first, then let the shape of the question pick the tool
Scope comes before the choice of tool; the question’s shape then picks the pattern. The answer path abstains when nothing clears its similarity floor.
3

The eight patterns

Each pattern answers one kind of question. Give each its own tool, so the model’s choice of tool is also its choice of strategy.

PatternUse it when the question isWhat the tool doesConxt tool
1. Resolve to one answer“What did we decide about X?”Searches, checks the hits, retries wider once, and returns one answer with its source, or says nothing is on recordresolve_context
2. Broad recall“What do we know about X?”Ranked semantic search; returns several short hits with idssearch_memory, get_context
3. Typed lookup“What are our coding rules?”Filters by kind (decision, rule, open question) before rankingsearch_decisions, get_memories with memory_type
4. Standing contextStart of a session, before any questionReturns the few pinned facts every task needsget_pinned, get_context
5. Scoped recallWork inside one project or teamReads one project’s memory plus general memory, nothing elseproject on every read tool; get_team_memories
6. Newest first“What is the latest on X?” or “What was true on 1 Oct?”Filters to the topic, then sorts purely by date; can stop at a daterecall_as_of
7. Provenance“Who wrote this, and in which session?”Lists what one agent or session wrotelist_agent_memories
8. AbstainAny question nothing on record answersSays so plainly, and records the question as openbuilt into resolve_context

Two rules hold across all eight:

  • Search, then read. A search returns short hits with ids. A follow-up read fetches the one or two that matter in full. This keeps a broad search from flooding the context.
  • Similar is not the same as answering. Ranking puts the closest match first even when nothing is close. Patterns 1 and 8 exist because a ranked list can’t say “nothing answers this”; Conxt’s resolve_context treats a best match under 0.35 similarity as no answer.
4

Designing retrieval tools on the server

  1. Write the description as a routing rule. Open with the question the tool answers, then when not to use it and which tool to use instead. Conxt’s recall_as_of says it answers “what’s the MOST RECENT thing you know about X” and why get_context can’t. That one line stops the model using a ranked search for a recency question.
  2. Describe every parameter, including the trap. A filter that looks like an identity gets filled with the caller’s own id. Conxt’s search_memory says outright that agent_id is a filter and must not carry the caller’s id “out of habit”.
  3. Scope in the query, before the limit. Filter by project or team inside the database query, then take the top N. Filtering after the limit returns fewer results than asked for, or none, and the shortfall never shows.
  4. Fail closed on scope. A project name that matches nothing is refused with the names that do exist, not widened to everything. A row with no project field is dropped while a project is in scope; it never counts as general memory.
  5. Say what the answer was drawn from. Put one line at the top of every scoped result, such as Conxt’s “Answered from the Lantern project and general memory.” Then the model, and the person reading over its shoulder, can tell scope from content.
  6. Return short hits with ids and dates. Return a title or first sentence, the type, the date and an id, and offer a separate read for the full text. A date on every hit lets the model judge staleness itself.
  7. Mark conflicts; don’t hide them or pick silently. When two memories disagree, say so, and prefer the newer one only when the rule is stated. Conxt’s resolve_context re-ranks a pair flagged as conflicting by recency instead of returning both raw.
  8. Abstain in words the model will repeat. “Nothing on record answers ‘X’ yet” is quoted to the user. An empty list often isn’t; the model fills the gap from its own knowledge.
  9. Annotate honestly. Mark every read tool readOnlyHint: true, destructiveHint: false, idempotentHint: true, and set all four hints to true or false, never null. Clients use these to decide what runs without asking, and directories reject servers whose hints don’t match what the tool does.
5

Using retrieval tools from an agent

These go in the agent’s instructions or a skill file, because the model won’t infer them from the tools alone.

  • Retrieve before answering, not after. Anything that depends on the person’s own decisions, rules or projects is looked up first. An answer written first and checked second rarely gets corrected.
  • Pass the scope every time. If the work is in one project, send project on each call. A missing scope reads every project, and that is how one client’s price ends up in another’s answer.
  • Ask the question, not keywords. Semantic search ranks better on “what payment processor do we use for Lantern” than on “payments”. Very short queries work for names: Conxt matches a short query against titles as text as well.
  • Pick the tool by the question’s shape. One fact means pattern 1. “What do we know” means pattern 2. “Latest” or “as of” means pattern 6. A tool chosen by habit gives the wrong ranking for the question.
  • Stop after two calls on one question. If two retrievals find nothing, say nothing is on record. More calls with reworded queries usually end in a weak match taken as an answer.
  • Quote the scope line and the source. Tell the person which project the answer came from and when it was recorded. They can then catch a wrong-scope or stale answer.
  • Write back what was settled. When the conversation settles something, save it as a decision in the same project. The next retrieval then finds it, and pattern 8 stops recording the question as open.
6

Query techniques

The query text decides most of what comes back, so write it for the search behind the tool, not for a person. Semantic search matches meaning, so a full question beats keywords. Name matching matches words, so a short name beats a sentence.

Weak queryBetter queryWhy it works
paymentswhat payment processor does Lantern useNames the thing and the attribute; one word matches every memory that mentions money
please find what we decided about the database, thankswhich database did we choose for the APIFiller words dilute the embedding; keep only the question
Lantern pricing with no scopewhat does a clinic pay per month, plus project: "Lantern"Scope belongs in the parameter, so the query can spend its words on the question
what is the latest deploy ruledeploy rule, sent to recall_as_of“Latest” in the text doesn’t change ranking; a tool that sorts by date does
not Stripewhich payment processor did we switch toEmbeddings ignore “not”; the negated word pulls Stripe memories to the top
pricing, region and owner for Harborlinethree queries: Harborline pricing, Harborline hosting region, Harborline ownerOne query per fact; a mixed query ranks memories that touch a bit of each
money back policy? (no match)refund policy, then money backTry the person’s own words, then the common synonym; stop after the second try

Five habits behind the table:

  1. Ask for one fact per query. Split a question with several parts, run each, and combine the answers yourself.
  2. Put the subject and the attribute in the words. “Lantern” plus “payment processor” finds the one memory. Either alone finds dozens.
  3. Phrase it the way the memory was written. Memories are statements such as “We use Stripe for rider payments”. A query shaped like the expected statement (“we use … for payments”) often ranks the right memory first; this is the HyDE technique, short for hypothetical document embeddings.
  4. Use short queries for names and ids. In Conxt, a query of three content words or fewer is also matched as text against titles and bodies, so Pedalway deploys finds memories that a semantic score would put below the floor. A long query skips that text match.
  5. Move filters out of the text. Project, team, type and date belong in parameters. Words like “latest”, “our rules” or “for Lantern” in the query only blur what the search is ranking.
7

Failure modes we have seen

Five of these shipped, or nearly shipped, in Conxt in October and November 2026. The stale-note row comes from a developer’s public report about another memory server.

FailureWhat the user sawFix
Another project’s facts in the answerIn a 16-question eval, 5 answers gave another project’s price, region, payment processor or ownerProject bins: every read takes project, filters inside the query, and fails closed on an unknown name
Scope filter applied after the limitA project’s own memories missing from the top results, with no sign anything was cutFilter in the query, before the limit, in search and in duplicate checks alike
An open question returned as the answer“What did we decide?” answered with the memory that recorded it as undecidedSkip open questions as answers; below 0.35 similarity, say nothing is on record
An old, often-repeated fact beating a newer oneA superseded decision ranked first because it had been reinforced many timesrecall_as_of sorts by date alone; conflicting pairs are re-ranked by recency
A stale note in one tool overriding a newer decision from anotherReported by a developer using a shared memory server across three tools, for two weeksRecord supersession with provenance: which tool decided what, and what replaced it
A near-duplicate saved across projectsOne project’s memory merged into another’s as a “duplicate”Duplicate checks look only within the memory’s own project and general memory
8

Measuring retrieval

You can’t tune retrieval you don’t measure, and “it found something” is not a measure. Keep a fixed question set in the repository and run it on every change to ranking, scoping or descriptions.

  1. Write 15 to 30 real questions with the answer you expect, taken from how people actually ask. Include questions that should have no answer.
  2. Seed a test account with overlapping projects that share vocabulary: two clients that both have “payments”, “pricing” and “owner”. Cross-scope leaks only show up when the projects look alike.
  3. Score four numbers per run: right answer, from the right scope; wrong scope, an answer taken from another project or team; false answer, something returned where nothing was on record; and missed, nothing returned where an answer existed.
  4. Run it through a real client, not just the server’s functions. A model choosing the wrong tool is a retrieval failure the unit tests never see.
  5. Commit the harness and the results. A number nobody can rerun can’t be defended. Conxt’s matcher was tuned against 16 real questions in a harness that lived in a scratch folder, and the headline number couldn’t be reproduced later.

A wrong-scope answer is worse than a miss: the person trusts it. Track it as its own number and treat any rise as a regression.

9

Checklist before you ship a retrieval tool

  • The description opens with the question the tool answers, and names the tool to use instead for nearby questions.
  • Every parameter is described, including what not to pass.
  • Scope (project, team, owner) is a parameter, applied inside the query before any limit.
  • An unknown scope is refused with the valid choices, never widened.
  • Scoped results start with a line saying what they were drawn from.
  • Hits are short, with an id, type and date; full text comes from a separate read.
  • Below a stated similarity floor, the tool says nothing is on record instead of returning the closest match.
  • Conflicting memories are flagged, and any preference for the newer one is stated.
  • All four annotation hints are set to true or false, and match what the tool does.
  • The tool is in the committed question set, scored on right, wrong scope, false answer and missed.