How retrieval finds the right knowledge

A workspace can hold thousands of memories, rules and skills. The job of retrieval is to put the few that matter into the assistant's context before it starts, and to leave the rest out. This page describes what that selection does and how it improves over time. How the ranking is computed is part of Pathrule's proprietary engine and is not published.

Path scope comes first

The first filter is location. Every memory, rule and skill lives at a node path. When the assistant works in /apps/api/payments, Pathrule starts from what is pinned to that path and what it inherits from the paths above it. A UI tweak in /apps/web/dashboard does not pull in the rules about database migrations.

This is the same path scope described in Core concepts, applied as the first cut. By the time anything more expensive runs, the candidate set is already small.

Meaning and keywords, together

Once the path narrows the field, Pathrule matches your intent against the candidates two ways at once.

• Keyword matching catches exact hits: a file name, a function name, a literal phrase from a memory title.
• Meaning-based matching catches the rest: a question phrased differently from how the memory was written, a synonym, a paraphrase, a concept that shares no words with the entry.

The second one is not a text search with extra steps. Each entry and your request are compared by what they mean rather than by the words they share, which is why a match can happen with no shared string at all. See what Pathrule computes.

Neither alone is enough. Keyword search misses a memory that says the same thing in other words. Meaning-based search can blur an exact file-name match. Pathrule combines them, so an exact match keeps its priority and a same-idea-different-words match still surfaces.

On a Cloud workspace, the prompt hook sends the start of your prompt (roughly the first 1,000 characters) to Pathrule Cloud so knowledge can be ranked by meaning. If that call is slow or fails, the hook falls back to this machine's cached index of the same workspace for that prompt. In local mode, with no account, matching leans on path scope and keywords.

The files next to the one you are in

Path scope and meaning both start from where the assistant is working. A further signal widens that slightly: Pathrule learns which files your team habitually changes in the same piece of work, and lets knowledge attached to those neighbours surface too.

It means a decision recorded once, on the file where it was made, still reaches the sessions that need it, even when the prompt never mentions that file. The signal is built from file paths, not file contents: the paths your agents' logged work touched and, on a Cloud workspace, a one-time seed from the file paths of recent git history, so it helps before your team has logged much work. It fades as those relationships stop happening. On a Cloud workspace, when one neighbour moves with the file in front of the assistant especially often, the context an agent asks for also carries a one-line heads-up naming it. See files that change together.

It works across languages

The meaning-based match is not tied to one language. A prompt in Turkish can surface a memory written in English, and a mixed-language prompt can still find the right entry.

This is the case plain keyword search cannot handle. When the prompt and the memory share an idea but no words, matching has to work on meaning rather than spelling.

The best matches arrive ready to use

Retrieval delivers in two tiers. The entries that clearly fit the prompt come through as full content, so the assistant works straight from your team's knowledge instead of going to read it. Only the most relevant few are sent each turn, within a per-prompt budget, and content the assistant already has is not sent again, so the assistant gets what it needs without carrying the whole knowledge base.

Everything else that qualifies arrives as a name, an id and one line, enough for the assistant to recognise it and pull the body when it turns out to matter, so a relevant entry that does not fit is still listed rather than dropped. Skills are offered by name, because a procedure should be asked for rather than pushed. A prompt that asks two separate things is matched part by part, so both parts get knowledge. What arrives in full, and what arrives as a name covers all three.

Candidates are evidence, not answers

When retrieval is not certain, it does not pretend to be. Pathrule surfaces likely entries as candidates and tells the assistant to read the full body before acting on one. A candidate is a pointer worth checking, not a fact to repeat.

This follows Pathrule's standing rule that wrong context is worse than no context. In an ambiguous case Pathrule shows a candidate rather than asserting an answer.

It learns from how knowledge is actually used

Retrieval is not frozen at the moment a memory is written. Over time Pathrule observes which entries actually helped on which kinds of work, and lets that move future results. An entry that keeps proving useful for a kind of task is more likely to surface for similar work later.

The observation is concrete rather than a rating anyone gives. Each delivery is recorded along with how the turn went: which of the delivered entries the assistant actually consulted rather than merely received, how many tool calls the work took, and how many failed and on which files. A turn that received knowledge and still ran into failures counts against the knowledge it was given.

That record is taken by the layer that did the delivering, not asked for. The assistant does not have to call a tool or cooperate in any way for the turn to be measured, which keeps the loop consistent across clients.

Because the record is kept per kind of work, the result is not one score per entry. The same memory can rank high for a migration and low for a UI tweak. A single importance field, maintained by hand, cannot express that difference.

The learning is conservative by design.

• Unclear outcomes do not teach. A turn whose outcome is ambiguous is not used as a lesson.
• A clear miss reduces, it does not erase. A single clear miss lowers an entry's standing for that kind of work rather than wiping out its history.
• Influence fades with time. An entry that stops matching the current code loses ground instead of haunting results.

And it changes the choice, not the size. What an entry has proven can move it ahead of an equally relevant rival, but it does not push an entry past the relevance bar that decides whether anything is sent at all. Over time a workspace delivers a better few entries per turn in the same amount of context. Learning here buys accuracy, not room.

How knowledge compounds covers this loop end to end, and Suggestions and self-audit covers how stale entries are raised for review.

The same for the whole team

On a Cloud workspace, ranking draws on the workspace's shared data in Pathrule Cloud rather than on a separate copy in each person's client. Two teammates asking the same thing on the same path get consistent results, whichever coding agent they use. Claude Code and Codex receive the prompt-ranked selection through their prompt-submit hook. Cursor, GitHub Copilot and Windsurf have no Pathrule hooks; they get a ranked selection when they ask the MCP server for context with pathrule_get_context, as any client can.

It also means the learning is shared. When an entry proves useful, it surfaces better for everyone on the team, not just the person who triggered it.

What retrieval does not see

Retrieval operates on your team-written memories, rules and skills, plus the path you are working in, the words of your request and the record of how past work went. It does not read, index or upload the contents of your source files. The match runs over knowledge your team chose to write down, not over the repo itself.

From a checkout, a Cloud workspace takes file paths: the first time an agent asks for deep context, Pathrule reads the file paths of recent git history to seed which files change together, and the file names near the top of the folder tree to recognise the technologies in use. What Pathrule computes lists what is read and what is kept.

Where this fits

• Core concepts defines path scope, the first filter retrieval uses.
• How hooks work describes how the selected slice reaches the assistant before its first tool call.
• How knowledge compounds places retrieval inside the deliver, capture, score loop.