Code Graph

Why a code graph?

Grep and embedding-only retrieval treat a codebase as a bag of strings. An agent asked "who calls parseJWT?" either runs ten greps and stitches the answers together, or it gets a vector-similarity guess that misses exact callers and surfaces unrelated files that happen to mention the substring. Both modes pay tokens for context the agent then has to read to find what it actually needed.

A code graph encodes the relationships directly. Files, functions, classes, imports, calls, and tests are typed nodes; the edges between them are typed too. One traversal answers structural questions exactly, in one MCP call, with deterministic node IDs the agent can cite back.

Oxagen ingests every connected GitHub repository into the same Neo4j-backed workspace knowledge graph that holds your business ontology — so an agent doing code work and an agent doing business work read from the same store, with the same RLS scoping, over the same MCP surface.

What gets ingested

Connect a GitHub repository through the GitHub App and Oxagen runs a deterministic pipeline: clone at HEAD, walk the include / exclude globs, parse each supported file with tree-sitter, resolve cross-file references with stack-graphs, fetch repo + identity + CI + tests + security metadata through the GitHub REST + GraphQL APIs, and write typed nodes and edges into the workspace graph. The source parser ships TypeScript / JavaScript and Python; the GitHub-metadata, CI, tests, and security passes apply to repositories in any language.

Every node and edge carries an envelope of provenance: tenant_id, workspace_id, source (one of github, git, tree-sitter, lsp, derived, manual), source_id, fetched_at, observed_at, schema_version. Edges carry valid_from and a nullable valid_to so every traversal is bitemporal — the graph reflects HEAD by default and can be queried at any commit (see Time-travel queries).

Node types

The ingestion pipeline emits nodes in nine categories. Every node inherits the provenance envelope above; the tables below name only the type-specific properties.

Repository layer

Identity layer

The identity-resolution pass runs after every sync and folds code.author + github.user into a single person via deterministic strategies — exact-email match (1.0), GitHub login match (0.8), name match (0.6) — recorded as edges so the resolution is auditable.

Filesystem layer

Code semantics

Markdown / mdx documents are stored as code.file nodes with lang in {markdown, mdx} — not a separate code.doc type. Filter on lang when querying for "all docs in this repo".

diff_patch is byte-capped at 16 KB per commit. Larger diffs are truncated UTF-8-safely with a [truncated] marker so an agent can tell the diff was clipped before reasoning over it.

Documentation surfaces

GitHub metadata

CI

Tests, coverage, knowledge

Security

Memory

Edge types

The connector emits structural edges deterministically from the AST and the GitHub API. Semantic edges are LLM-inferred with a confidence score and can be turned off per-connection. Derived edges are computed by the M7 derivation jobs and refresh on every push.

Every edge carries valid_from and a nullable valid_to (the bitemporal envelope). The structural edges below are the canonical ones agents traverse — see packages/oxagen/oxagen/connectors/github/types.py:EdgeKind for the complete enum, including review / comment / project plumbing surfaces.

Code structure

Semantic (LLM-inferred, optional)

Git history and identity

GitHub metadata (PRs, issues, discussions, reviews)

CI

Tests and coverage

Security

Memory

Derived (M7)

The derivation jobs run after every push and recompute the following edges from the structural graph. They carry confidence_score and computed_at.

Agent-authored (incidents)

Why touched and not modifies for commit edges? modifies is reserved for the LLM-inferred semantic edge above (code.function → code.symbol — this function mutates this value). The structural commit→file edge would be a different relationship with the same string, which Neo4j would silently merge into a single edge type. An agent calling code.find_path { edge_types: ["modifies"] } would then get a mix of structural commit history and semantic data flow with no way to disambiguate. touched keeps the two cleanly apart.

The EdgeKind enum in packages/oxagen/oxagen/connectors/github/types.py is the source of truth for the names — every traversal tool accepts these strings as filters.

The canonical agent query

The whole graph is shaped to make the following query a one-call answer. Given a function name, return everything an agent needs to fix or refactor it: input shape, output shape, last commit, last author, diff, test coverage, and the docs that reference it.

MATCH (f:Node {type: 'code.function', name: $fn_name})
OPTIONAL MATCH (c:Node {type: 'code.commit'})-[:touched]->(f)
OPTIONAL MATCH (c)-[:authored_by]->(a:Node {type: 'code.author'})
OPTIONAL MATCH (f)<-[:is_tested_by]-(t:Node {type: 'code.function'})
OPTIONAL MATCH (doc:Node {type: 'code.file'})-[:references]->(f)
WHERE doc.properties.lang IN ['markdown', 'mdx']
OPTIONAL MATCH (c)-[ct:touched]->(f)
RETURN
  f.properties.params         AS input_shape,
  f.properties.return_type    AS output_shape,
  f.properties.signature      AS signature,
  c.properties.message        AS last_commit_message,
  c.properties.diff_patch     AS last_diff,
  ct.action                   AS last_change_kind,  -- added | modified | removed
  a.properties.name           AS last_author,
  collect(DISTINCT t.name)    AS test_coverage,
  collect(DISTINCT doc.name)  AS referencing_docs
ORDER BY c.properties.authored_at DESC
LIMIT 1

What the OPTIONAL MATCH clauses do, one at a time:

1. The first MATCH anchors on the function. name is a property; the type filter restricts to code.function so a class or symbol of the same name does not collide.
2. c-[:touched]->(f) walks back to every commit whose diff touched this function. The touched edge from a commit to a function is best-effort — emitted when the diff hunk header includes a function marker — but touched from commit to file is exhaustive, which is why code.commit is queryable as a sibling and not the only handle.
3. c-[:authored_by]->(a) resolves the commit's author node. Authors are deduplicated on email across the repo, so an agent can ask "who else has touched this code?" with one more hop.
4. f<-[:is_tested_by]-(t) returns the test functions that exercise the target. The connector also emits the inverse tests edge from the test function to the subject — pick the direction that fits the query.
5. doc-[:references]->(f) returns markdown / mdx documents that name the function or its file. Design docs, changelogs, and incident write-ups all link back to the symbols they describe. Markdown / mdx files are stored as code.file nodes with lang in {markdown, mdx} — the WHERE clause above filters to those.

A vanilla file-search agent reproduces this with: git log --follow, git blame for the author, grep -r 'def parseJWT' to find the implementation, two more greps to locate tests, a final pass to find docs that mention the symbol — every step a separate tool call, every hop paying for tokens. The graph collapses it to one MCP call and returns typed records the agent does not have to re-parse.

Impact analysis across class members

The member_of edge makes the "if I change a method, what else in the class might break?" query a single hop. Expand the canonical query above to walk class siblings + their tests:

MATCH (m:Node {type: 'code.function', name: $method_name})
MATCH (m)-[:member_of]->(cls:Node {type: 'code.class'})
MATCH (cls)-[:defines]->(sibling:Node {type: 'code.function'})
WHERE sibling.id <> m.id
OPTIONAL MATCH (sibling)<-[:is_tested_by]-(t:Node {type: 'code.function'})
RETURN
  cls.name                       AS containing_class,
  sibling.name                   AS sibling_method,
  sibling.properties.signature   AS sibling_signature,
  EXISTS { MATCH (sibling)-[:calls]->(m) } AS calls_changed_method,
  collect(DISTINCT t.name)       AS sibling_tests

What this answers in one MCP call: which methods sit beside the one the agent is about to change, which of them call into it, and the tests that exercise each of those siblings. The agent does not need to grep, git blame, or re-parse — every relationship is already typed in the graph.

You do not write Cypher directly — ontology.explain_function, ontology.symbol_context, ontology.traverse, and ontology.ask compile to this shape. ontology.symbol_context is the closest direct wrapper: pass a name (or node_id) and it returns the target node, its containing class, sibling methods, tests, callers, callees, semantic returns, and the most-recent commits with action labels and resolved authors — every collection independently capped so a hub function can't blow up the response. See How agents query the graph below for the MCP tool surface.

// laser-context bundle for a single symbol — one MCP call, no Cypher
{
  "tool": "ontology.symbol_context",
  "args": { "name": "processOrder" }
}
// →
{
  "target": {
    "id": "…", "name": "processOrder", "kind": "function",
    "signature": "async function processOrder(input)",
    "file": "services/api/lib/orders.ts",
    "is_exported": true, "is_async": true
  },
  "containing_class": { "id": "…", "name": "OrderService" },
  "siblings":         [ { "id": "…", "name": "cancelOrder" } ],
  "tests":            [ { "id": "…", "name": "processOrder_handles_decline" } ],
  "callers":          [ { "id": "…", "name": "checkoutHandler" } ],
  "callees":          [ { "id": "…", "name": "chargeStripe" } ],
  "semantic_returns": [ { "id": "…", "name": "OrderResult" } ],
  "recent_commits": [
    {
      "commit": {
        "id": "…", "name": "9a4c1f10",
        "sha": "9a4c1f10abcdef…", "short_sha": "9a4c1f10",
        "message": "fix(api): retry chargeStripe on transient 5xx",
        "authored_at": "2026-04-22T14:03:12Z",
        "files_changed": 3, "insertions": 41, "deletions": 12
      },
      "action": "modified",
      "author": { "id": "…", "name": "Alex Rivera", "email": "alex@example.com" },
      "diff_excerpt": "@@ -1,3 +1,5 @@\n  retry()"
    }
  ]
}

Caps are configurable: siblings_limit, tests_limit, callers_limit, callees_limit, returns_limit, and commits_limit default to 50 / 50 / 50 / 50 / 25 / 10 respectively. Identity comes from the bearer token — workspace_id is never read from input.

How agents query the graph

Every entry in the catalogue below is a real MCP tool exposed by mcp.oxagen.ai. Tool names and input field names match the running server — see MCP Server for installation. The catalogue follows the SPEC §7 grouping so it stays one-to-one with the spec doc.

Discovery and structure

Traversal and impact

SPEC §7.2 aliases dual-register at the same credit cost: code.callers_of → code.find_callers, code.dependency_path → code.find_path, code.affected_by → ontology.impact_of. Both names roll up to the canonical in usage analytics.

History and ownership

Tests and CI

Dependencies and security

Issues, PRs, discussions

Search

Memory

Maintenance

Identity (workspace_id, user_id) is derived from the verified bearer token — never passed as input. Cross-workspace queries return empty results.

Response envelope

Every code-graph tool returns the same canonical envelope so the agent parses one shape regardless of which tool emitted it.

{
  "results": [...],
  "evidence": [
    {"node_id": "…", "kind": "code.function", "url": "https://github.com/…"}
  ],
  "tokens_used_estimate": 142,
  "counterfactual_estimate_tokens": 8400,
  "counterfactual_method": "grep_plus_read_n_files",
  "cursor": null,
  "tenant_scoped_at": {
    "tenant_id": "…",
    "workspace_id": "…",
    "project_id": null
  }
}

• results — the typed records the tool was asked for.
• evidence — node IDs the agent can cite back. Every record in results is reachable from at least one evidence entry.
• tokens_used_estimate — tokens spent on this tool's reply, computed from the assembled payload (Anthropic SDK token-count API → tiktoken cl100k_base approximation → deterministic fallback). Note: the tiktoken fallback uses GPT-4 tokenisation, so estimates may differ slightly from Anthropic-billed token counts.
• counterfactual_estimate_tokens — what the same answer would have cost a vanilla file-search agent, computed by a per-tool estimator. This is the receipt for the "fewer LLM calls, smaller models, lower bills" claim.
• counterfactual_method — stable method-id naming the estimator (e.g. grep_plus_read_n_files, lockfile_transitive_parse_plus_manifests).
• cursor — opaque pagination token, or null for unpaginated results.
• tenant_scoped_at — the workspace the tool resolved to. Always populated.

The envelope is enforced — malformed responses are rejected before they reach the agent.

Time-travel queries (at_commit)

Every relationship in the graph carries valid_from and a nullable valid_to, so a query can ask the graph as it stood at any commit. Tools that traverse the graph accept an optional at_commit parameter; the Cypher rewriter ANDs r.valid_from <= $at AND coalesce(r.valid_to, '9999-…') > $at into the first MATCH for every named relationship variable. Bare patterns are left alone.

// callers of parseJWT as of commit 9a4c1f2
{
  "tool": "code.find_callers",
  "args": {
    "name": "parseJWT",
    "at_commit": "9a4c1f2"
  }
}

The same shape works on ontology.explain_function, code.find_path, code.references_to, memory.recall, and any other tool that traverses bitemporal edges. The response envelope's tenant_scoped_at records the workspace; evidence records the node IDs at that commit.

A vanilla file-search agent reproduces this with git checkout <sha>, repeats every grep, parses every file again, and discards the working tree. The graph keeps the historical state queryable without checking anything out.

How agents share state through the graph

Two agents that never run in the same process can still share state through the workspace graph. The first writes a node — a finding, a pattern, a code.commit — and the next agent's first MCP call sees it.

A concrete shape:

1. 2026-04-22, 14:03 UTC. Agent A (Claude Code in a developer's editor) merges PR #517 to main. The push webhook triggers an incremental sync. code.commit { sha: "9a4c1f…" }, code.author { email: "alex@…" }, and the code.commit-[:touched]->code.function { name: "parseJWT" } edge land in the workspace graph within ~30 seconds.
2. 2026-04-25, 08:11 UTC. Agent B (a triage agent invoked by an on-call engineer) receives a stack trace mentioning parseJWT. Its first MCP call is ontology.explain_function { name: "parseJWT" }. The response contains every commit since 04-22, author Alex, the diff for #517, and the tests that exercise the function — without Agent B running git log or cloning the repo.

The agents never coordinated. The graph did. Multi-agent coordination is structural, not bolt-on: the second agent reads the first agent's output the same way it reads any other graph node.

Memory and the graph are the same store

The agent memory layer (Agent Memory) writes _mem:action, _mem:sequence, and _mem:pattern nodes into the same Neo4j workspace graph as your code.* nodes. A pattern that applies to a specific function is structurally connected to it, so retrieving the pattern pulls the symbol with it.

When the evaluator promotes a pattern keyed on a code symbol — for example, "ontology mutations on parseJWT fail with NodeNotFoundError 83% of the time" — it writes:

{
  "type": "_mem:pattern",
  "name": "ontology_mutation:code.function:NodeNotFoundError",
  "properties": {
    "confidence_score": 0.83,
    "applies_to": {
      "type": "code.function",
      "name": "parseJWT"
    },
    "recommendation": "Validate the node exists and is accessible before proceeding."
  }
}

The applies_to shape is matched by the pre-execution context hook, which traverses from the pattern node to the referenced code node in one hop. An agent calling memory.context for parseJWT receives the pattern, the function node, its commits, and its tests in the same payload — one MCP call, no follow-up.

{
  "patterns": [
    {
      "id": "5c7c…",
      "name": "ontology_mutation:code.function:NodeNotFoundError",
      "confidence_score": 0.83,
      "recommendation": "Validate the node exists and is accessible before proceeding."
    }
  ],
  "code_context": {
    "function": {
      "id": "a3f2…",
      "name": "parseJWT",
      "signature": "function parseJWT(token: string): JWTClaims",
      "file": "services/api/lib/auth.ts",
      "is_exported": true
    },
    "tests": [
      { "id": "b8c1…", "name": "parseJWT_handles_expired_token" }
    ],
    "recent_commits": []
  }
}

The shape is deterministic. The agent does not need to interpret free-form text — it reads the typed record and decides.

Per-repo configuration

Every GitHub connection ships with the manifest fields below. They are read on the first sync and editable from Connections → Settings (or via the API on the connection record).

Existing connections inherit the documented defaults on the first sync after a settings update — the manifest defines the schema, the API merges new keys non-destructively, and the worker honours the merged blob on the next run.

Sync lifecycle

A repo connection moves through four states, defined by the ConnectionStatus enum:

Five things drive a sync:

• Initial backfill. Triggered automatically on connect. Reads commit_depth commits, walks include / exclude globs, parses every supported file, resolves edges, writes nodes.
• Push webhook. GitHub pushes to the default branch trigger an incremental sync that re-parses changed files and adds new code.commit nodes since last_synced_sha.
• Schedule. sync_schedule runs a defensive re-sync daily or weekly to recover from missed webhooks. manual opts out — only push webhooks and explicit ontology.refresh_repo calls trigger a sync.
• Reconciliation cadence. Even if a webhook is dropped or rate-limited, the graph self-heals on a known schedule: an hourly drift sweep refreshes issues / PRs / discussions, a nightly metadata pass refreshes repository / branch / label / milestone / CODEOWNERS / branch-protection state, a nightly security pass refreshes Dependabot / code-scanning / secret-scanning alerts, and a Sunday-night full reparse re-derives every code.symbol from source. State per (workspace, surface) is tracked in a watermark table so each sweep resumes from where the last one left off.
• Manual. Force a re-sync from the connection card or from any agent with ontology.refresh_repo { connection_id, paths? }. Pass paths to limit the re-ingest to a subset of the repo — useful after a targeted edit when you do not want to wait for the next webhook.

Where to go next

• Cookbook: Index your codebase and query it with Claude — first-sync walkthrough.
• Agentic coding cookbook — three end-to-end agent threads with real MCP payloads.
• MCP Server — install the server in Claude Code, Cursor, VS Code, Windsurf, or Codex.
• Agent Memory — how patterns and sequences attach to code nodes.
• Cheaper models with Oxagen — the cost argument with eval methodology.

Get started free · Read the docs