# Your Coding Agent Can Read the Code. Give It the History with Relate by Neo4j

> Source: <https://neo4j.com/blog/developer/your-coding-agent-can-read-the-code-give-it-the-history-with-relate-by-neo4j/>
> Published: 2026-11-18 21:00:00+00:00

**Recommendation:** Load git history into a graph and expose it read-only over MCP so coding agents can follow co-change edges; raise --max-content-bytes above 64 KB or large files like FastAPI's 260 KB routing.py lose their text.
More in the playbook "Working with AI coding agents": <https://wpnews.pro/playbooks/coding-agents>

# Your Coding Agent Can Read the Code. Give It the History with Relate by Neo4j

Senior Product Manager

13 min read

Load a repository’s git history into a graph with Relate’s git-to-graph extension, serve it read-only, and see what a coding agent finds with it that it cannot find in the source tree.

In a popular open source codebase, `security/api_key.py` has been changed in 28 commits. In 18 of them `oauth2.py` changed too. `http.py` changed in 17, and `open_id_connect_url.py` in 16. None of those four modules imports another so nothing obvious in`api_key.py` points you at the other three files.

The history is clear about why. Each time someone added a behavior to one security scheme, they added it to all of them: `auto_error` in #134, `description` in #1757, the 401 status code in #13786, WebSocket support in #10147.

We asked three coding agents what else they would need to change before adding a constructor argument to `APIKeyHeader`. With only the source tree to read, none of them named those three modules. With the repository’s history loaded into a graph, all three did.

This post shows how to build that graph with [Relate’s](http://relatedb.ai/) [git-to-graph](https://relatedb.ai/docs/guides/extensions/git-to-graph/)[extension](https://relatedb.ai/docs/guides/extensions/git-to-graph/), what to ask it, and what changed when Codex, OpenCode and Pi could query it.

## Relate: The agent native database

[Relate](https://neo4j.com/blog/news/meet-relate-by-neo4j-an-embedded-database-for-ai-agents/) is an open-source graph database built for AI agents to use directly. It is embedded: one binary, no server to deploy and no signup, and a whole database is a single `.rl` file on your machine that your agent queries in Cypher.

“Agent-native” means the pieces an agent needs come with it. `relate skill install` gives a coding agent a skill that documents the CLI, its Cypher dialect and includes a catalog of ready-made queries. `relate serve — mcp` exposes any database as MCP tools, and `--read-only` makes it refuse every write.

Relate extensions can be used to load outside data into the graph. This post uses two of them, [git-to-graph](https://relatedb.ai/docs/guides/extensions/git-to-graph/)[for a repository’s history](https://relatedb.ai/docs/guides/extensions/git-to-graph/) and [fs-to-graph](https://relatedb.ai/docs/guides/extensions/fs-to-graph/)[for its working tree](https://relatedb.ai/docs/guides/extensions/fs-to-graph/).

## Build the graph: two commands, about 20 seconds

`git-to-graph` reads a checkout’s commit history. `fs-to-graph` reads its working tree. Both write into the same Relate store, so one graph holds what the code is and how it got there.

```
relate extension install git-to-graphrelate extension install fs-to-graphgit clone https://github.com/fastapi/fastapi.gitrelate run git-to-graph fastapi -d fastapi.rlrelate run fs-to-graph fastapi --max-content-bytes 400000 -d fastapi.rl
imported 8102 commits, 914 people, 5733 files (34551 TOUCHED, 48322 CO_CHANGED edges) into the storeimported 429 folders, 3229 files (3657 CONTAINS edges) into the store
```

On FastAPI (8,102 commits from December 2018 to November 2026) the history import took 4.6 seconds and the file import 14 seconds. The store is one 30 MB file; the clone it came from is 101 MB. Running the history import again is safe: it merges, so a second run left the same 48,322 co-change edges.

Two details matter later:

- **Paths include the directory you imported.** We ran the importers from the parent directory, so the package file is`fastapi/fastapi/routing.py` .
- **Raise the content cap for large files.**`fs-to-graph` stores file text up to 64 KB by default. FastAPI’s`routing.py` is 260 KB and`applications.py` is 185 KB, so the default left the two most-edited files without text. The`--max-content-bytes 400000` flag above covers every Python file in the repository.

## Three questions before an edit

A `CO_CHANGED` relationship joins two files that appeared in the same commit, and its `count` is the number of commits where this pattern occured. That one relationship answers the first question an agent should ask before it edits a file.

## What else will I need to touch?

```
MATCH (:File {path: $path})-[r:CO_CHANGED]-(other:File)RETURN other.path AS coupled, r.count AS timesORDER BY times DESC, coupledLIMIT 5
```

For `fastapi/fastapi/security/api_key.py`:

```
+---------------------------------------------------+-------+| coupled                                           | times |+---------------------------------------------------+-------+| "fastapi/fastapi/security/oauth2.py"              | 18    || "fastapi/fastapi/security/http.py"                | 17    || "fastapi/fastapi/security/open_id_connect_url.py" | 16    || "fastapi/fastapi/applications.py"                 | 12    || "fastapi/fastapi/routing.py"                      | 12    |+---------------------------------------------------+-------+
```

For `fastapi/fastapi/routing.py`, a 6,552-line file with 193 commits, the top of the list is `applications.py` (58), `dependencies/utils.py` (47) and `openapi/utils.py` (39). A third of all commits to `routing.py` also changed `applications.py`.

## Has someone made this kind of change before?

Counts say which files move together. Earlier commits say what a change of this kind looked like. This query finds commits on a file whose subject matches a term, and lists what else each one touched:

``` php
MATCH (c:Commit)-[:TOUCHED]->(:File {path: $path})WHERE toLower(c.subject) CONTAINS $term AND c.files_changed <= 50MATCH (c)-[:TOUCHED]->(o:File)WHERE o.path <> $pathWITH c, collect(o.path) AS othersRETURN substring(c.sha, 0, 8) AS sha,       substring(toString(c.authored_at), 0, 10) AS day,       substring(c.subject, 0, 60) AS subject,       [p IN others WHERE p STARTS WITH $prefix | replace(p, $prefix, '')] AS source,       size([p IN others WHERE p STARTS WITH $tests]) AS testsORDER BY c.authored_at DESCLIMIT 6
```

With `$path` set to `api_key.py` and `$term` to `security`, four of the five rows touched exactly the same three source files:

- `1884325c` (2026-10-18) — Add WebSocket support to security dependencies (#10147). Source files:`open_id_connect_url.py` ,`oauth2.py` ,`http.py` . Tests: 3.
- `51ad909f` (2025-11-24) — Use`401` status code in security classes when credentials… Source files:`open_id_connect_url.py` ,`oauth2.py` ,`http.py` . Tests: 23.
- `3b2e8919` (2021-07-29) — Add`description` parameter to all the security scheme classes… Source files:`open_id_connect_url.py` ,`oauth2.py` ,`http.py` . Tests: 11.
- `fad3a9e1` (2019-04-03) — Add auto_error to security utils (#134). Source files:`open_id_connect_url.py` ,`oauth2.py` ,`http.py` . Tests: 10.

That is a template for the change: the `description` commit is an earlier constructor argument, and it shows which files and how many tests came with it.

## Who should review it?

``` php
MATCH (p:Person)-[:AUTHORED]->(c:Commit)-[:TOUCHED]->(f:File)WHERE f.path IN $paths  AND NOT (p.name ENDS WITH '[bot]' OR p.name = 'github-actions')WITH p, count(DISTINCT c) AS commits, max(c.authored_at) AS last_touchRETURN p.name AS reviewer, commits, substring(toString(last_touch), 0, 10) AS last_touchORDER BY commits DESC, reviewerLIMIT 6
```

For `routing.py` and `applications.py`:

```
+-----------------------+---------+--------------+| reviewer              | commits | last_touch   |+-----------------------+---------+--------------+| "Sebastián Ramírez"   | 135     | "2026-10-22" || "David Montague"      | 8       | "2019-11-27" || "Marcelo Trylesinski" | 7       | "2025-10-11" || "Mohammed"            | 7       | "2019-03-23" || "Yurii Motov"         | 5       | "2026-07-28" || "Yurii Karabas"       | 3       | "2023-01-07" |+-----------------------+---------+--------------+
```

The `last_touch` column earns its place. Ranked by commits alone, the second reviewer is someone whose last change to these files was in 2019. Two people lower in the list touched them within the last year or so.

## What reading the code does not show

The security modules are not a one-off. Because `fs-to-graph` puts each file’s text on the same node as its history, one query can ask for files that change together although neither one’s text names the other:

``` php
MATCH (a:File)-[r:CO_CHANGED]->(b:File)WHERE r.count >= 5  AND a.path STARTS WITH $prefix AND b.path STARTS WITH $prefix  AND a.content IS NOT NULL AND b.content IS NOT NULL  AND NOT (a.content CONTAINS replace(b.name, '.py', ''))  AND NOT (b.content CONTAINS replace(a.name, '.py', ''))RETURN a.path AS file, b.path AS partner, r.count AS togetherORDER BY together DESC, file, partnerLIMIT 6
```

Inside the `fastapi/` package, 126 pairs of files have changed together five or more times. For 42 of them, a third, this query finds no reference in either direction. The check is a name match on file text, not an import graph, so treat the number as approximate. It is still a list no amount of following imports would produce.

## Hand it to an agent

Relate can serve a store over MCP, in read-only mode:

```
relate serve --mcp stdio --database fastapi.rl --read-only
```

The server exposes two tools, `read_cypher` and `get_schema`. Sending `MATCH (n:Person) DETACH DELETE n` to `read_cypher` comes back as a tool error and leaves the store unchanged:

```
Only MATCH queries are allowed for read-query
```

For Codex, add the server to `~/.codex/config.toml`:

```
[mcp_servers.fastapi_history]command = "relate"args = ["serve", "--mcp", "stdio", "--database", "/workspace/fastapi.rl", "--read-only"]
```

For OpenCode, add it to `~/.config/opencode/opencode.json`:

```
{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "servers": {      "fastapi_history": {        "type": "local",        "command": ["relate", "serve", "--mcp", "stdio",                    "--database", "/workspace/fastapi.rl", "--read-only"]      }    }  }}
```

Pi reached the same store through the `relate` command line, also read-only:

```
relate --database ./fastapi.rl --read-only --mode table "<cypher>"
```

For all three, `relate skill install --agent <name>` adds a skill that includes a catalog of ready-made history queries, so the agent does not start from an empty page.

Here is one of the `read_cypher` calls Codex made on the security task. The prompt told it to use the graph but did not supply any queries. The engine answered in 0.3 ms:

```
{  "statement": "MATCH (a:File {path: $path})-[r:CO_CHANGED]-(b:File) RETURN b.path AS coupled, r.count AS times ORDER BY times DESC, coupled LIMIT 25",  "parameters": { "path": "fastapi/fastapi/security/api_key.py", "term": "APIKeyHeader" }}
```

## The comparison

We gave Codex 0.167.1, OpenCode 2.2.7 and Pi 1.5.2 the same two tasks, all on the same model (`gpt-6.1-sol`, medium reasoning). Each agent ran in a fresh container.

- **Tasks.** Add an optional constructor argument to`APIKeyHeader` , and add a keyword argument to`APIRouter.add_api_route` . In both cases the agent was told not to edit anything and to brief us first: which other files will change, which tests to run, and who should review.
- **Code only.** The agent has the FastAPI checkout with its`.git` directory removed, and its usual search and read tools.
- **With the graph.** The same checkout, also without`.git` , plus the graph. Its only source of history is Relate.

Here is what each briefing contained across the 12 sessions:

Three things stand out:

**Code is enough for tests, and for files an import makes visible.** Every agent in both arms named the same core tests; the code-only agents got there by reading the test files. Every agent found `applications.py`, which imports `routing`.

**Code is not enough for files that leaves no reference.** No code-only briefing mentions any of the three sibling security modules. The graph-backed agents did, and qualified it sensibly. OpenCode wrote that the three modules “co-changed with `api_key.py` 17, 18, and 16 times respectively” and should be inspected for API consistency, “not automatic edits”. Codex added: “Both previous additions of `description` and `auto_error` changed all four modules.”

**Code cannot say who has worked on a file.** The code-only agents found the project’s maintainer in `docs/en/docs/management.md` and stopped there, and they said so. Codex: “I cannot identify a routing specialist or recent contributor to these methods from this checkout alone.” Pi: “Without history or explicit component ownership, I cannot identify recent maintainers of this particular code.” With the graph, all three named people by what they had changed, such as the author of the earlier `description` argument.

## How it works

`git-to-graph` makes one `git log` call for the whole history, builds the plan in memory, and writes it in six batched `MERGE` phases: people, commits, files, then the three relationship types. It creates the range indexes before writing and the full-text index on commit subjects after.

The extension itself is small because it does not own the database. It is a child process that talks to the Relate host over MCP; the host owns the store, the transaction batching and the limits. If you want an importer for a source Relate does not cover, `relate extension init <name>` scaffolds one in shell, Python, TypeScript or Rust.

Two flags control the window. `--since` reads everything after a date, and `--until` closes the range, so an older era imports the same way every time:

```
relate run git-to-graph fastapi --since 2024-01-01 --until 2025-01-01 -d fastapi-2024.rl
```

## Try it on your codebase

Everything in this post runs on your own repository in four steps: install

relate, load the history, start a read-only server, and tell your agent about

it.

Install the binary and the two extensions:

```
curl -sSfL https://relatedb.ai/install.sh | bashrelate extension install git-to-graphrelate extension install fs-to-graph
```

Run the importers from the directory above your checkout, so that paths in

the graph start with the repository’s name. The first reads the commit

history and the second adds the working tree, both into one file:

```
relate run git-to-graph my-repo -d my-repo.rlrelate run fs-to-graph my-repo -d my-repo.rl
```

Then give the graph to your agent. Install the skill, which carries the

catalog of history queries, and register the store as a read-only MCP server.

Any agent that speaks MCP over stdio can launch this command:

```
relate skill installrelate serve - mcp stdio - database /path/to/my-repo.rl - read-only
```

Now ask the question from the top of this post about a file you know well:

- *What else changes when this file changes?*
- *Has anyone made this kind of change before?*
- *Who has worked on it?*

## Resources

**Relate**

- [Relate by Neo4j](https://relatedb.ai/) home page
- [Install relate](https://relatedb.ai/docs/get-started/install/) : the CLI on macOS, Linux or Windows
- [Documentation](https://relatedb.ai/docs/)
- [Source on GitHub](https://github.com/relatedb/relate)

**The extensions in this post**

- [Import git history with git-to-graph](https://relatedb.ai/docs/guides/extensions/git-to-graph/) : the graph it builds, its flags and its limits
- [Import a directory tree with fs-to-graph](https://relatedb.ai/docs/guides/extensions/fs-to-graph/) : file text, the content cap and the full-text index
- [Install and run an extension](https://relatedb.ai/docs/guides/extensions/install-and-run/)
- [Write an extension](https://relatedb.ai/docs/guides/extensions/write-an-extension/) : scaffold an importer for a source relate does not cover

**Giving the graph to an agent**

- [Connect your agent to relate](https://relatedb.ai/docs/get-started/agent-quickstart/) : the agent quickstart
- [Connect over MCP](https://relatedb.ai/docs/guides/agents/connect-over-mcp/) : config blocks for Claude Code, Cursor, Codex, OpenCode and others
- [Install the agent skill](https://relatedb.ai/docs/guides/agents/install-the-skill/)
- [Keep an agent safe](https://relatedb.ai/docs/guides/agents/agent-safety/) : read-only opens, limits and backups
- [Agent-native by design](https://relatedb.ai/docs/concepts/agent-native/) : why the CLI and server behave the way they do

**Going further**

- [Answer codebase questions text search can’t](https://relatedb.ai/cookbook/codebase-context-graph/) : a cookbook recipe that builds on the same graph
- [The relate cookbook](https://relatedb.ai/cookbook/)
- [Model Context Protocol](https://modelcontextprotocol.io/)

**The repositories and tools used here**
