Graph
About 341 wordsAbout 1 min
2026-03-30
The Graph capability stores (subject, relation, object) triples in a GraphStore and lets the agent traverse them.
Default backend: NetworkX, persisted as a single JSON file at storage/<profile>/graph.json. Good for up to ~100k edges; swap for Neo4j by registering another provider.
Ingesting triples
Two modes:
A. From profile JSONL
Drop files under data/profiles/<profile>/triplets/*.jsonl, one object per line:
{"subject": "Ann", "relation": "leads", "object": "Search platform"}
{"subject": "Acme", "relation": "located_in", "object": "Shanghai", "confidence": 1.0}Then warmup will load them automatically:
await agent.warmup()
# -> calls graph.load_from_profile()B. Via the graph_upsert_triples tool
Useful when the user tells the agent to remember a fact:
{
"triples": [
{"subject": "Ann", "relation": "manages", "object": "Bob"},
{"subject": "Bob", "relation": "works_on", "object": "Search platform"}
]
}Data model
Each triple maps to:
- A node for
subjectandobject(withlabeldefaulting to the id andtypedefaulting to"entity"). - An edge keyed by the relation, carrying
weight = confidenceand any properties.
Node type and edge relation are free strings — set a convention and stick to it.
Tools exposed to the agent
| Tool | What it does |
|---|---|
graph_search_entities | Exact + fuzzy name match against node ids/labels |
graph_traverse | BFS out to max_hops, optionally filtered by allowed relation_filter. Returns paths sorted by avg edge weight. |
graph_neighbors | Every in/out edge for one node (direction: both / out / in) |
graph_upsert_triples | Add / update triples (marked destructive) |
Example walkthrough
python -m datamind.scripts.hello_graphWith these seed triples:
Ann —leads→ Search platform
Bob —member_of→ Search platform
Search — part_of→ Acme Engineering
Acme —located_in→ Shanghai
Shanghai —in_country→ China3-hop traverse from Ann returns:
Ann → Acme → Shanghai [works_at | located_in]
Ann → Project Alpha [leads]
Ann → Acme → Shanghai → China [works_at | located_in | in_country]
…Add relation_filter=["works_at", "located_in", "in_country"] to restrict the walk to the business chain.
Configuration
DATAMIND__GRAPH__BACKEND=networkx # networkx | neo4j (future)
# DATAMIND__GRAPH__DSN=bolt://user:pw@host:7687
DATAMIND__GRAPH__EMBED_ENTITIES=falseAdding Neo4j is a new file under datamind/capabilities/graph/providers/neo4j_store.py plus @graph_registry.register("neo4j"). build_graph_service already routes backend != "networkx" through a DSN-based constructor.
