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 how that selection works and how it improves over time. It does not cover the scoring math, which is intentionally 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. Every entry is also held as a computed representation of what it means, your request is turned into the same kind of representation, and the two are compared directly. That is why a match can happen with no shared string at all, and it is the first of several things the layer computes rather than stores. 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 runs both and combines them, so an exact match keeps its priority and a same-idea-different-words match still surfaces.

The files next to the one you are in

Path scope and meaning both start from where the assistant is working. A third 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 only from the activity your agents log, never from reading your code, and it fades as those relationships stop happening. 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 still finds 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, and content the assistant already has is not sent again, so the assistant gets what it needs without carrying the whole knowledge base.

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 opens a record of what was sent, and the turn reports back into it: which of those entries the assistant actually consulted rather than merely received, how many tool calls the work took, how many failed and on which files. A turn that received knowledge and still ran into failures counts against the knowledge it was given, weighted by how bad the failure was.

That record is taken by the layer that did the delivering, not asked for. The assistant does not have to call a tool, remember a session id or cooperate in any way for the turn to be measured, which is what keeps the loop honest across every client, including the ones that would never volunteer anything.

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.

• Ambiguous signals are skipped, not recorded. A sarcastic reply or an unclear outcome does not teach the wrong 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 naturally loses ground instead of haunting results forever.

And it changes the choice, not the size. What an entry has proven can move it ahead of an equally relevant rival, but it cannot push an entry past the relevance bar that decides whether anything is sent at all. A workspace that has been learning for six months delivers a better few entries per turn than it did on day one, in the same amount of context. Learning here buys accuracy, not room.

Ranking happens in two layers. The base ranking that decides which candidates surface is open source and runs locally, so you can read how it chooses. The learning layer that re-ranks by real usage is the part the cloud edition adds on top. How knowledge compounds covers this loop end to end, and Suggestions and self-audit covers how stale entries are raised for review.

Computed once, the same for the whole team

The selection runs on the server, not in each person's client. Two teammates asking the same thing on the same path get the same result, and the answer does not drift across Claude Code, Codex, Grok, Kimi, Antigravity and OpenCode in Studio. Cursor, Windsurf and GitHub Copilot receive the same selection when connected through Pathrule CLI.

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. Claude should not be smarter for one person than for the team.

What retrieval never sees

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

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.