# Knowledge Graph

Specs and code both grow into webs of relationships you can't hold in your head — which requirement touches which module, which constitution principle a contract answers to, which files a feature actually spans. Forge turns that web into a **persistent, queryable knowledge graph** and wires it into project memory, so an agent can recall structure instead of re-deriving it every session.

## The capability

Forge does not build graphs itself. Codebase memory is delegated to a **provider** — `graphify` or `graphiti` — selected in config. The provider parses your specs and source tree, extracts nodes and edges, detects communities, and renders the result. Forge resolves the targets, organizes the output, and makes it recallable.

```mermaid
flowchart TD
  S["specs: .forge/specs/ + memory"] --> PV[graphify / graphiti provider]
  C["code: source tree<br/>respects .gitignore"] --> PV
  PV --> J["graph.json<br/>codebase graph"]
  J --> D[".forge/ graph output<br/>git-ignored"]
  PV -.optional.-> M[Project memory]
```

Forge shells out to the external provider and references the graph artifact it produces — a local `graph.json` codebase graph at the repo root. Whatever additional views the provider itself may render are the provider's own concern; Forge only resolves and organizes the `graph.json` it emits. The output lives under a git-ignored directory — treat it like a build artifact, not something to commit. An incremental **update** refreshes what already exists rather than rebuilding from scratch.

| Target | Input | What it captures |
| --- | --- | --- |
| **specs** | `.forge/specs/`, the constitution, and other memory docs | Requirements, contracts, and the principles they answer to |
| **code** | The project source tree, minus `.forge/`, build output, and anything git-ignored | Modules, files, and the relationships a feature spans |

::: info The graph is git-ignored build output
The `graph.json` codebase graph is regenerated from your specs and code on demand. It's git-ignored automatically. Rebuild or update it whenever the underlying artifacts move; don't commit it.
:::

## Providers

Codebase memory is pluggable. The backend is set in `.forge/config.yaml` under `memory.codebase`:

```yaml
memory:
  spec: engram          # spec memory backend
  codebase: graphify    # engram | graphify | graphiti
  team_sync: false
```

- **`graphify`** and **`graphiti`** are the graph-oriented codebase-memory providers — they turn your code and specs into the queryable graph described above.
- **Engram** backs **[spec memory](/concepts/memory)** — the durable record of decisions and observations that accrues across a change's life.

Because the provider is a boundary, the graph capability degrades cleanly: if the configured provider or its memory server isn't present in the session, Forge reports that it skipped and why, rather than failing the run.

::: warning Providers are external tools
`graphify` and `graphiti` are codebase-memory providers, and Engram is the spec-memory binary — each is its own dependency outside the Forge binary. See [Installation](/installation) for what to have on `PATH` before enabling a backend.
:::

## Recall — querying the graph through memory

The graph earns its keep at recall time. Forge exposes project memory through a small terminal command surface:

```sh
forge recall <query>
forge memory save|search|context|sync
```

- **`forge recall`** answers questions against stored memory and the graph — the `graph.json` codebase graph is exactly the shape a retrieval query wants.
- **`memory save`** persists a decision or observation; **`search`** and **`context`** pull it back; **`sync`** exports committable team memory when `team_sync` is on.

```mermaid
flowchart LR
  Q[Agent question] --> RC[forge recall]
  RC --> KG[Knowledge graph + memory]
  KG --> A["Grounded answer<br/>structure, not guesswork"]
```

This is where the graph ties into the rest of the harness: `verify` can treat the code graph as supporting evidence when checking whether a claimed task status matches what's actually in the tree, so the [enforced ledger](/harness/overview) stays honest against reality rather than narration.

::: tip Graph the specs, recall against the code
Point the specs target at your requirements to see which principle each contract answers to. Point the code target at your source tree to see what a feature really spans. Then let `forge recall` and `forge memory` query both — the agent reasons over structure instead of re-reading the world each session.
:::

## Next steps

- [Configuration](/guide/configuration) — set `memory.codebase` and the spec backend.
- [Persistent memory](/concepts/memory) — the spec-memory store the graph feeds into.
- [Command Reference](/guide/commands) — the full memory and recall surface.
- [Installation](/installation) — external providers to put on `PATH`.
- [Enforcement Doctrine](/harness/overview) — how graph evidence backs verify.