# Source Graph Overview



<a id="section-goal"></a>

**Context Source Graph** is a self-hosted service for searching and reading code at pinned Git revisions. It is built on Go, Git and the Zoekt trigram index, and it exists for the workload AI coding Agents create: many small, precise *search, then read* round trips against code the Agent has not checked out.

Every request resolves to one exact commit before anything is read, so a search hit, the file it points to and a later diff all describe the same snapshot. The same operations are available in a browser, over HTTP, as an MCP server and from a command-line client.

```mermaid
flowchart LR
  callers["People, scripts<br/>and AI Agents"] --> surfaces["Website · HTTP · MCP · CLI"]
  surfaces --> service["repo-service<br/>one shared contract"]
  service --> git["Git mirrors<br/>per repository"]
  service --> engine["Zoekt index<br/>child process"]
  service --> db["Application database<br/>SQLite, PostgreSQL or MongoDB"]
  git -->|background sync and indexing| engine
```

Source Graph is part of the Context project. The name does not imply any affiliation with the Sourcegraph platform.


<a id="section-get-it"></a>

## Code and live demo

- **Source code:** [github.com/context4ai/sourcegraph](https://github.com/context4ai/sourcegraph).
- **Live demo:** [https://context4ai-portal.fly.dev/sourcegraph/](https://context4ai-portal.fly.dev/sourcegraph/), also reachable at [https://context4ai-sourcegraph.fly.dev/sourcegraph/](https://context4ai-sourcegraph.fly.dev/sourcegraph/). It is the public, read-only instance behind this documentation site's knowledge service and serves `context4ai/context` and `context4ai/sourcegraph`. Its MCP endpoint is `/sourcegraph/mcp`. [Deployment Recommendations](</context/llms/pages/089284d83f97cfa37c4c3f03d2c1a417.txt>) shows how it is deployed.
- **Optional for Context:** Context works without Source Graph. When no instance is installed or configured, Context's query skill reads code through a shallow, sparse partial clone and grep instead.


<a id="section-why"></a>

## Why it exists

An Agent answering a question about code usually needs a handful of exact lines, not a whole repository. Cloning every repository into every Agent sandbox at the right revision is slow, and running `rg` or `git grep` over a checkout repeats the same scan on each call. Source Graph keeps an index per repository and answers instead:

- **Fast.** Indexed search typically completes in a few milliseconds on the server. With the service in the same region as its callers, a full request including the network stays well under 100 ms. [Pinned Search and Reads](</context/llms/pages/9b8f7c105b990cf29a3a7936dc0ff462.txt>) explains where the speed comes from and shows the measured comparison.
- **Reproducible.** Branches resolve to a commit first, and full commit SHAs are accepted only inside the repository's retention window, so answers never drift to a different snapshot mid-conversation.
- **Agent-ready.** The MCP endpoint is stateless Streamable HTTP and works with any MCP client. Anonymous access is read-only and limited to public repositories.
- **Small footprint.** One process manages the Git mirrors, the search engine and background indexing; SQLite is the default database.


<a id="section-surfaces"></a>

## One contract, four surfaces

All four entry points expose the same operations:

| Operation | What it does |
| --- | --- |
| `repositories` | List registered repositories and their observed branches |
| `availability` | Show a repository's retained versions and indexing status |
| `resolve` | Turn a branch, or an eligible full SHA, into the fixed commit to use next |
| `search` | Search file contents at one commit, shaped like `rg` |
| `read` | Read a line range of one file at one commit |
| `read_many` | Read up to ten known ranges at one commit in a single MCP call |
| `list` | List one directory at one commit |
| `diff` | Compare two eligible commits |
| `prepare` | Ask for a commit to be synchronized and indexed (authorized callers only) |

The website lives under `/sourcegraph/`, the MCP endpoint at `/sourcegraph/mcp`, and the HTTP API under `/sourcegraph/v1/` and `/sourcegraph/api/`. The command-line client `sourcegraph-cli` calls the same HTTP routes. Exact routes, tool inputs and limits are in the [HTTP and MCP](</context/llms/pages/a8fe02c341a72e370f653228d71e9982.txt>) and [CLI](</context/llms/pages/7b5a8c8039ac425e57fbaeb65690b5b6.txt>) references.


<a id="section-components"></a>

## How an instance is put together

A Source Graph instance is a single `repo-service` process. It starts the Zoekt search server as a child process listening only on the loopback interface, keeps a bare Git mirror for each registered repository on its data volume, and runs background workers that synchronize monitored branches and index new branch heads.

The application database stores repositories, jobs, identities and settings. SQLite is the default; PostgreSQL and MongoDB are supported for larger or sharded deployments. Git mirrors and indexes always stay on the instance's local disk — search speed comes from that locality — so capacity is planned around disk rather than CPU. To grow, run several instances that each own a disjoint set of repositories; never run two instances over the same repositories or data directory. [Self-Hosting](</context/llms/pages/87e9a0f083fa7c393fae3f5bbb123a11.txt>) covers both topologies.

Repositories can also ship WebAssembly plugins named `<name>.sourcegraph.wasm` that add text to `read` and `read_many` results. Context uses this to attach each knowledge section's sources, described in [Evidence for Context](</context/llms/pages/3bbf57d3dcee4b0ea0433d3b367cc045.txt>).


<a id="section-access"></a>

## Who can do what

Without any sign-in provider configured, an instance is an anonymous, read-only site: visitors can search and read repositories marked public, subject to per-minute rate limits. Adding Google or GitHub sign-in enables administration, and the first verified user becomes the administrator. Signed-in users can create personal API keys for scripts and Agents, and a service token covers automation. Registering repositories, indexing older commits and other changes require an administrator or the service token. [Authentication and Access Control](</context/llms/pages/1388f44bd0735b535af45b2eefc03e30.txt>) lists the full matrix.


<a id="section-next"></a>

## Where to go next

A public demo instance at [context4ai.org/sourcegraph](https://context4ai.org/sourcegraph/) indexes the Context and Source Graph repositories and allows anonymous reading.

| To… | Read |
| --- | --- |
| Understand pinned search and the speed comparison | [Pinned Search and Reads](</context/llms/pages/9b8f7c105b990cf29a3a7936dc0ff462.txt>) |
| See how Context knowledge and Source Graph combine | [Evidence for Context](</context/llms/pages/3bbf57d3dcee4b0ea0433d3b367cc045.txt>) |
| Connect a browser, MCP client, script or the CLI | [Connecting](</context/llms/pages/ef2f49d8f38697ceb1f7aaa88deba84d.txt>) |
| Add repositories and monorepo path groups | [Registering Repositories](</context/llms/pages/aa50227a56841f0d42fe08e9dfa4cd53.txt>) |
| Deploy your own instance | [Self-Hosting](</context/llms/pages/87e9a0f083fa7c393fae3f5bbb123a11.txt>) |
| Configure sign-in and API keys | [Authentication and Access Control](</context/llms/pages/1388f44bd0735b535af45b2eefc03e30.txt>) |
| Run, monitor and troubleshoot it | [Operations](</context/llms/pages/b6b5d0b7d4370275aa82611da7136e4f.txt>) |
| Look up routes, tools, flags and settings | [HTTP and MCP](</context/llms/pages/a8fe02c341a72e370f653228d71e9982.txt>), [CLI](</context/llms/pages/7b5a8c8039ac425e57fbaeb65690b5b6.txt>), [Query Syntax](</context/llms/pages/e6f59a794ecd01b09dc543afbc9f5da1.txt>), [Configuration](</context/llms/pages/8165da3ea04839f9d9684e308d054177.txt>) |

---

## Sources

- [sourcegraph/README.md L1–L16 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/README.md#L1-L16>)
- [sourcegraph/README.md L105–L109 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/README.md#L105-L109>)
- [sourcegraph/cmd/repo-service/main.go L113–L126 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/repo-service/main.go#L113-L126>)
- [sourcegraph/README.md L43–L43 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/README.md#L43-L43>)
- note:20261013/demo-deployment.md · demo-deployment.md L12–L19
- [context/plugins/context/skills/context-inspect-search/SKILL.md L348–L352 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/plugins/context/skills/context-inspect-search/SKILL.md#L348-L352>)
- [sourcegraph/README.md L18–L25 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/README.md#L18-L25>)
- [sourcegraph/internal/service/service.go L289–L349 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/internal/service/service.go#L289-L349>)
- [sourcegraph/README.md L22–L22 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/README.md#L22-L22>)
- [sourcegraph/docs/interfaces.md L1–L8 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/docs/interfaces.md#L1-L8>)
- [sourcegraph/internal/mcpserver/server.go L29–L82 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/internal/mcpserver/server.go#L29-L82>)
- [sourcegraph/cmd/repo-service/main.go L96–L161 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/cmd/repo-service/main.go#L96-L161>)
- [sourcegraph/internal/service/worker.go L25–L45 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/internal/service/worker.go#L25-L45>)
- [sourcegraph/docs/deployment.md L3–L17 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/docs/deployment.md#L3-L17>)
- [sourcegraph/internal/httpserver/runtime.go L180–L240 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/internal/httpserver/runtime.go#L180-L240>)
- [sourcegraph/internal/httpserver/website_access.go L15–L36 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/internal/httpserver/website_access.go#L15-L36>)
- [sourcegraph/docs/authentication.md L1–L5 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/docs/authentication.md#L1-L5>)
- [sourcegraph/README.md L41–L63 · 4e5c555](<https://github.com/context4ai/sourcegraph/blob/4e5c5552394f4c16e050ae3185aad585fb07785d/README.md#L41-L63>)