Knowledge graph

Pull your workspace knowledge graph into a local replica, search it semantically, and ground the coding agent in it.

The knowledge graph is what distinguishes oxagen from a generic coding agent. Your Oxagen workspace maintains a graph of entities, code symbols, documents, executions, and the relationships between them. The CLI can replicate that graph locally and feed it to the agent as context, so it reasons about your system — not just the files open in your repo.

These commands call the platform, so you need an authenticated CLI (platform token + org + workspace).

Two graphs, one store. oxagen init builds a local code graph — a tree-sitter parse of your repo into files, symbols, and call/import edges — that the agent queries for structural context even before you authenticate. The commands below sync that up to, and pull the wider workspace knowledge graph down from, the platform (entities, documents, memories, lineage). The graph is structural context — what your system is. It's distinct from agent memory, which is experiential — what the agent learned.

Pull a local replica

oxagen graph pull downloads an incremental snapshot of your workspace graph into a fast local replica (DuckDB). It remembers a cursor, so subsequent pulls only fetch what changed:

oxagen graph pull              # incremental — only what changed since last pull
oxagen graph pull --full       # ignore the cursor and re-pull everything
oxagen graph pull --json       # machine-readable summary

Scope what you replicate:

Flag	Description
`-l, --labels <csv>`	Only pull these domain labels, e.g. `Person,SourceFile`.
`--no-system`	Exclude product-owned (system) nodes; pull only your workspace's nodes.
`--full`	Re-pull the entire graph, ignoring the saved cursor.

Once pulled, the coding agent automatically draws on the replica for context during its runs.

Check the replica's state

oxagen graph status            # node counts, last cursor, freshness
oxagen graph status --json

Search the graph

oxagen graph search runs a unified semantic (vector) similarity search across the entire graph from a natural-language query:

oxagen graph search -q "where do we enforce tenant isolation?"

Flag	Description
`-q, --query <text>`	Natural-language query (required).
`-k, --kinds <csv>`	Restrict to node kinds: `entity, file, symbol, chunk, memory, execution, document, message`.
`-l, --labels <csv>`	Restrict to domain labels, e.g. `Person,SourceFile`.
`-n, --limit <n>`	Max results, 1–50 (default 10).
`--system`	Only product-owned (system) nodes.
`--no-system`	Only your workspace's nodes (exclude system nodes).

# Top 5 source-file matches for an authentication question
oxagen graph search -q "rate limiting per org" -k file,symbol -n 5

# Search only your workspace's people and documents
oxagen graph search -q "who owns the billing service?" -l Person --no-system

Each result is tagged with its node kind and a similarity score:

Push code changes

oxagen graph push computes a git code delta and up-syncs it to the workspace knowledge graph. It is the write-path counterpart to graph pull:

oxagen graph push              # delta push — only files changed since the last cursor
oxagen graph push --full       # ignore the cursor and push all tracked source files
oxagen graph push --repo <id>  # override the repo identifier
oxagen graph push --json       # machine-readable summary

oxagen graph lineage pushes CLI session execution lineage (touched files, turn edges) into the graph:

oxagen graph lineage [--repo <id>] [--json]

A typical workflow

# 1. Authenticate once (see Account setup)
oxagen login --org acme --workspace eng

# 2. Replicate the graph
oxagen graph pull

# 3. Explore it
oxagen graph search -q "how does ingestion dual-write to Postgres and Neo4j?"

# 4. Let the agent use it
oxagen "refactor the ingestion cursor handling; keep the dual-write invariant"

Re-run oxagen graph pull whenever you want the freshest context; it's incremental, so it's cheap to run often.

Agent memory — the experiential context that sits alongside the graph.
The agent engine — how the enhance stage injects graph context into a turn.
Quickstart — grounding the agent in the graph.
Command reference — the graph command group.