Memory
"Memory" in CGraph is the persistent, warm graph that agents query — the reason they don't re-derive a codebase's structure on every request.
Why persistence matters
An agent that rebuilds its understanding each turn is slow and inconsistent. CGraph extracts the graph once, persists it, and keeps it resident so that queries are fast and stable across a session — the graph is the agent's durable memory of the codebase.
Persistent state
The canonical graph is written to cgraph-out/ as graph.json (plus the other
exports). When the daemon is running, incremental state is re-persisted to
cgraph-out/ in the background and on shutdown, so a restart resumes from the
last known graph rather than a cold rescan. Content-hash cache records track
semantic enrichment state, so unchanged content isn't re-enriched.
Warm state and incremental updates
The daemon (graphd) keeps the graph warm and folds edits in incrementally:
- Ordinary source edits are folded into the graph within a couple of seconds.
- A large batch — a branch switch, say — collapses into a single full rescan rather than thousands of tiny updates.
- Without
--watch, the graph is updated only by explicitupdateoperations.
While the graph is being built, client queries return graph_state: "building"
so a caller can distinguish "not ready yet" from "genuinely empty".
Serving context to agents
Memory is only useful if it fits the agent's context window. When an agent asks for context around a node, CGraph gathers a neighborhood and packs it to a budget:
gather: "fixed"packs the whole k-hop neighborhood.gather: "adaptive"keeps the full 2-hop core and expands the third hop only along query-relevant nodes.- Packing is knapsack-style — fit the most relevant nodes into the token budget.
The response reports what happened: a reach summary
(candidates, expanded_past_core, gated_at_core) alongside the gather and
packing mode, so the retrieval is inspectable rather than a black box.
Performance figures for adaptive gather (recall lift versus token cost) are documented on the Benchmarks page, with methodology — not asserted here.
Where to go next
- Graph Model — what is stored.
- Retrieval and Context Packing — the gather and packing algorithms in depth.