Graph stores

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

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.

@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:

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