# Graph stores

TnsAI 0.14.0 (`TnsAI@34454153`, TAN-3091 / PR #130) ships two
`GraphStoreProvider` adapters for `@Retrieval(strategy = GRAPH)`. Both
are `@since 0.14.0`. They ship in Maven Central `0.14.1`.

A missing or ambiguous non-default provider still fails with
`GraphCapabilityException` **above** `@Retrieval.onFailure`. Graph
retrieval never falls back to vector search.

## Who claims a Role

| Provider | Name | Claims when | Default? |
|---|---|---|---|
| `InMemoryGraphStoreProvider` | `in-memory` | Role has FILE `@KnowledgeSource` documents | Yes — a consumer adapter wins |
| `Neo4jGraphStoreProvider` | `neo4j` | `tnsai.graph.neo4j.uri` or `TNSAI_GRAPH_NEO4J_URI` is set **and** `org.neo4j.driver` is on the runtime classpath | No — beats bundled defaults |
| `KnowledgeToolsGraphStoreProvider` | `knowledge-tools` | `tnsai-tools` is present **and** the Role has no FILE sources, or the fence names `knowledge-tools` | Yes |

FILE Roles therefore get the in-process graph without writing a
`GraphStore`. KnowledgeTools live triples stay a separate bag and no
longer claim FILE Roles.

## In-memory FILE graph

`FileGraphIngestor` builds nodes and edges from the FILE corpus with
chunk↔entity provenance. Identity collapsing uses
`InMemoryGraphStore.identityKey`: NFKC, `Locale.ROOT` lower-case, then
keep `\p{L}` / `\p{Nd}` (drop punctuation to spaces) and strip a leading
English article. A CJK heading is not an empty id. Turkish `İ` / `ı`
stay distinct from `I` / `i`. Surface variants such as `Auth Service` /
`the auth service` share one node. Corpora are keyed by binding identity
so two builder sources on the same Role do not overwrite each other.
Hits carry source name `in-memory`.

```java
@KnowledgeSource(name = "handbook", path = "knowledge/handbook")
@Retrieval(strategy = Retrieval.Strategy.GRAPH)
public final class HandbookGraphRole extends Role {
}
```

A source fence that names no FILE source leaves this provider silent.

## Optional Neo4j

The official driver is **not** a `tnsai-intelligence` or `tnsai-core`
dependency. Enable the adapter:

```bash
export TNSAI_GRAPH_NEO4J_URI=bolt://localhost:7687
# optional: TNSAI_GRAPH_NEO4J_USER / TNSAI_GRAPH_NEO4J_PASSWORD
# or -Dtnsai.graph.neo4j.uri=...
```

Put `org.neo4j.driver` on the consumer classpath. If the URI is set but
the driver is missing, the provider logs a warning and stays silent
rather than pretending Neo4j ran. When it does claim a Role it is not a
framework default, so it beats `in-memory`.

## Not this page

- The GRAPH / HYBRID strategy inventory
- Maven Central `0.14.1` ships the bundled FILE graph