# Inside the Unblocked context engine: how we decide what your agent needs to know


URL: https://getunblocked.com/blog/inside-the-unblocked-context-engine/
Published: 2026-08-05T12:00:00.000Z
Author: Dennis Pilarinos
Categories: Context Engine, Engineering Insights

How Unblocked decides what your agent needs to know: scoped retrieval, an expert graph for conflicting sources, and source-level permissions at 100,000+ repo scale.

---
When engineering teams evaluate Unblocked, the conversation converges on the same handful of questions. An architect at a large financial institution asked something we hear from almost all our customers: our applications have tens of thousands of historical issues, tickets, and years of commit history. That's an enormous amount of context you could surface on every change. How do you decide what's relevant? An engineering leader at another company asked about the “AI version” of that problem: writing a doc now costs nothing, so we're drowning in documents of wildly uneven importance, much of it AI slop. How do you retrieve well in that world?

This article is the written version of what we walk through in those calls: how the context engine actually works.

## What we mean by context

The context that both people and agents need is the combination of your source code with all the systems of record you use to build software: pull requests, issues, design docs, incident channels, and the conversations where decisions are made. Unblocked connects to those systems (GitHub, GitLab, Jira, Linear, Confluence, Notion, Google Drive, Slack, Teams, Sentry, Datadog, and [many more](https://docs.getunblocked.com/configuring-data-sources)), continuously indexes them, and synthesizes them into a living model of how your organization builds software.

On top of that layer sit interfaces. Humans reach it through a web app, a desktop app, Slack and Teams, and our code review product. Agents reach it through a single MCP server, a CLI, and an API. Each is a client of the same engine, so the answer a developer gets in Slack and the context a coding agent pulls mid-task come from the same place.

Naturally, these systems of record data are not static and are shifting constantly. Code changes, document edits, new decisions, and architectural revisions all need to be reflected in real time. A decision made in a Slack thread can override documentation overnight, and the convention you’re about to follow may have changed two PRs ago. So ingestion is event-driven (webhooks update the graph's nodes and edges as new information arrives), and every answer is computed against the current state of your code, conversations, and documents at the moment you ask.

## How retrieval gets scoped

Back to the architect's question. You have hundreds of thousands of repositories and years of history. Some prior history is still relevant, and some history is obsolete. Historical code, documents and conversations may conflict with each other and with the current state of the system. Some information may not even be relevant to the engineer asking the question. Surfacing all of it would be useless, and surfacing the wrong slice would be worse. The scoping happens in stages.

It starts with intent and identity. Every request to Unblocked arrives authenticated, so we know who is asking, and the agent (or person) expresses what it's trying to do. Identity matters more than people expect. An engineer's contribution history, the repos they're active in, and the people they work with all narrow the search before any retrieval runs. If you've been stacking a series of pull requests on a feature and you ask for help with "the next widget," that phrase is meaningless in isolation. Against your recent PR history, it's specific.

Then retrieval runs across several stores at once. Some of the data is vectorized for semantic search. Some lives in a knowledge graph, where we traverse relationships: time-based correlations, shared identifiers, the thread that mentions the ticket that links the PR. Some are answered through relational queries against structured data, like "open PRs by this person in this repo." The results get ranked and related using recency, authority, the expert graph (more on that below), and proximity to the asker's own work.

The last stage is the one that makes the output usable by an agent: selection and compression. Too much context dilutes the signal and overflows the model's window, so we cut the result down to the most salient information for the task, and we leave citations that work as breadcrumbs. If the agent needs to go deeper on any source, it jumps off from those references back into the engine rather than starting over.

## Who do you trust when sources disagree?

Every organization past a certain size contains contradictions. The Confluence page disagrees with a Slack thread from last week, and the code does something else entirely. A search index returns all three and leaves the reader, or worse the agent, to guess. Most of the job is deciding which one to believe, and that’s where the expert graph earns its keep.

We build the expert graph primarily from pull request activity and commit history. Authorship counts, but review activity counts too: what someone frequently reviews is expertise, even if they have zero commits there. Both signals decay over time, so the person who owned a service three years ago doesn't outrank the person who has owned it for the last six months. Contributions cluster into topic areas, so expertise attaches to concepts, not just file paths. And because it's derived from real human interactions rather than raw commit volume, it's resistant to the distortions that fool naive contribution counting, like infrastructure accounts that generate enormous numbers of commits that aren't really code.

That graph then feeds conflict resolution. The heuristics are roughly what an experienced engineer would apply. Code is the strongest ground truth for how the system behaves right now. Recency matters, especially for stream-of-consciousness sources like Slack. And the voice matters: a recent statement from the person the graph identifies as the domain expert can override an older document, while a confident proposal from someone brand new to the area gets weighed accordingly.

A real example from our own team. Someone asked Unblocked about picking up a piece of work. Two conversations existed in Slack: a proposal from a recent joiner, and a different direction from the engineer the graph identified as the expert in that area. Unblocked surfaced both, said so explicitly, and framed which one carried more weight and why, with citations into each thread. We decided early on not to silently discard the losing source when a conflict can’t be cleanly resolved. We present it, contextualized, and let the person or agent make the call. Once someone resolves the ambiguity, the resolution is remembered.

We open-sourced a deliberately simplified version of the expert graph, built only on git and pull request data, if you want to see the shape of the idea and run it on your own repos: [engineering-social-graph](https://github.com/unblocked/engineering-social-graph). The production system layers a lot more on top, but the core intuition is visible there.

## What about AI-generated documents?

This is the newest version of the trust question. Writing a document now costs nothing, so document volume is exploding while average document authority falls. Any retrieval system that treats every doc as equally important is going to get noisier every quarter.

Our answer follows from the machinery above. A document is one signal among several, cross-referenced against the rest. Source code represents the ground truth of the system at any point in time. Documents often describe a future state, which is legitimate, but it has to be contextualized as intent rather than fact. If a document says one thing and a very recent conversation from the domain expert contradicts it, the expertise and recency signals boost the conversation, and the answer reflects that the decision has moved. If the signals genuinely conflict, the engine says so rather than picking a side and hiding the disagreement.

The same philosophy applies to team conventions. Unblocked learns best practices by mining pull request review comments: recurring feedback becomes a candidate rule, and a rule is only promoted once enough independent evidence supports it, weighted by who backed it. Those learned practices are deliberately scoped per repository. That's partly an access control matter, and partly because two teams can work on similar-looking systems with genuinely different views of the world. A convention learned in one repo should not leak into another unless you choose to make it organization-wide through documentation.

## The bias that breaks agent search

There's a failure mode we talk about constantly, borrowed from radiology: satisfaction of search. A radiologist who finds one lesion on an X-ray is at risk of stopping there and missing the more serious finding, so radiologists are trained to keep looking after the first hit. Agents badly suffer from this bias. Give an agent a pile of MCP connectors and a search task, and the first plausible result it finds becomes the truth it acts on. That's why agents rush to implement, and why you end up steering: "no, that's not quite right, you missed the constraint discussed in the other channel."

You can't prompt your way out of it reliably, and prompting an agent to be exhaustive just burns tokens on an unguided crawl. The context engine sidesteps the bias structurally: the exhaustive traversal across sources happens inside the engine, in parallel, with reconciliation and ranking applied before anything reaches the agent. The agent receives the reconciled result, compact enough to fit its context window, with breadcrumbs to pull more. In practice the agent keeps unblocking itself, asking the engine follow-up questions instead of asking the human, which is where the reduction in correction loops comes from.

This is also why the context layer matters more as teams move from local, babysat agent sessions toward remote and overnight agents. A human at the terminal can catch a wrong turn in real time. An agent running for hours unattended can’t be course-corrected, so the quality of the context it starts from, and can return to mid-task, sets the ceiling on what comes back.

## Permissions, and the identity problem underneath

The question every security-conscious team asks: how do you stop someone from seeing, through Unblocked, what they couldn't see in the underlying systems?

The approach is to flow access controls from the source. You've already configured permissions in GitHub, Jira, Confluence, Slack, and the rest. Unblocked maps those permissions and enforces them at query time, filtering retrieval down to what the asking identity is authorized to see. For some sources this means continuously synced access rules; for others, like Jira, it includes real-time access checks at answer time. The feature is called [Data Shield](https://docs.getunblocked.com/team-settings/data-shield), and the practical consequence is easy to demo: ask a question that draws on a protected document, get an answer; revoke access to that document at the source; ask again, and the answer no longer contains it. When someone moves between parts of the organization, their access in Unblocked moves when their access in the source systems moves, because the source systems stay the authority.

The permission model is an identity problem. You aren't one person to your tools; you're a GitHub login, a Slack member, a Jira account, and an SSO identity, often with different usernames and emails. Unblocked reconciles those into a single person, and that mapping does double duty. It's what makes permission enforcement trustworthy, and it's also what makes retrieval good, because personalizing scope by "your" work only functions if we know which activity across five systems is actually yours.

One related question we get from teams with a history of reorgs: what happens when repositories get renamed or moved? The graph traces continuity through git history, so as long as the commit history survives the move, the accumulated context follows the code.

## How we prove it works

We don't ask teams to take any of this on faith. The evaluation we run during a proof of concept is an A/B comparison: the same tasks in the same harness, one session with the context engine and one without, measuring time and token consumption, with a blind LLM-as-judge review of both transcripts to score output quality. The differences show up quickly enough that most engineers feel them in the first week: the agent's first attempt lands close to right, and the loop of "not quite, try again" mostly disappears.

Scale, for the teams that need the number: the largest organizations on Unblocked run well over 100,000 repositories with tens of thousands of engineers.

If you want to go deeper, the [documentation](https://docs.getunblocked.com/) covers the product surface, the [open-source expert graph](https://github.com/unblocked/engineering-social-graph) shows a simplified version of the expertise model, and our [security white paper](https://getunblocked.com/security/) covers the deployment and data-handling story. Or do what the teams above did and [ask us the hard questions directly](https://getunblocked.com/demo/). It's our favorite part of the job.