# Memory
> How CGraph persists the graph, keeps it warm, and serves context to agents.
[Source](https://open.nxtsoft.io/docs/cgraph/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 explicit `update` operations.

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](/docs/cgraph/graph-model) — what is stored.
- [Retrieval](/docs/cgraph/retrieval) and [Context Packing](/docs/cgraph/context-packing) — the gather and packing algorithms in depth.