Graph

How do I query the knowledge graph?

Use GET /api/memories/{id}/graph to retrieve a subgraph of nodes and edges. Pass a subject parameter to start a BFS traversal from that entity, or omit it to see the most connected subjects by out-degree.

The knowledge graph is a read-only projection of the belief grains stored in your context database. Every belief with subject, relation, and object fields becomes an edge in the graph, and every unique subject or object becomes a node. The graph endpoint runs a breadth-first search from the specified root entity and returns all discovered nodes and edges within the depth and size limits. This is the primary way to visualize how AI memory entities relate to each other.

Only belief grains populate the graph — other grain types (events, states, actions, etc.) are not traversed. If you need a comprehensive view of all knowledge, use recall or CAL queries. The graph is best suited for exploring entity relationships, mapping out who-knows-what, and understanding the structure of accumulated AI agent memory.

import requests

response = requests.get(
    "http://localhost:4009/api/memories/knowledge-base/graph",
    params={"subject": "john", "depth": 2, "max_nodes": 50}
)
graph = response.json()
print(f"{len(graph['nodes'])} nodes, {len(graph['edges'])} edges")

GET /api/memories/knowledge-base/graph?subject=john&depth=2&max_nodes=50

What does the graph response contain?

Nodes represent entities (unique subject strings) and edges represent relationships between them. Each edge corresponds to a stored belief grain.

A node carries five fields: subject (the entity name), out_degree (number of outgoing edges), depth (BFS distance from the query root, 0 for the root), grain_count (total grains where this entity appears as subject or object), and entity_type (inferred classification). An edge carries subject, relation, object, grain_hash (SHA-256 of the underlying belief), confidence, grain_type, and created_at (epoch milliseconds).

The response also includes truncated (boolean indicating whether max_nodes was reached before traversal completed) and total_nodes_explored (how many nodes the BFS visited). When the graph is truncated, increase max_nodes or reduce depth to see the full picture.

{
  "nodes": [
    {"subject": "john", "out_degree": 5, "depth": 0, "grain_count": 8, "entity_type": "Person"},
    {"subject": "coffee", "out_degree": 0, "depth": 1, "grain_count": 2, "entity_type": "Concept"}
  ],
  "edges": [
    {"subject": "john", "relation": "likes", "object": "coffee", "grain_hash": "a1b2c3...", "confidence": 0.95, "grain_type": "belief", "created_at": 1709251200000}
  ],
  "truncated": false,
  "total_nodes_explored": 6
}

How do I control traversal depth and size?

Use depth and max_nodes to limit how far and how wide the BFS traversal goes. Depth ranges from 1 to 4 hops, and max_nodes ranges from 1 to 500.

A depth of 1 returns only direct neighbors of the root entity — the entities it has relationships with. Depth 2 (the default) extends one hop further, showing neighbors-of-neighbors. Depth 3 and 4 reveal increasingly distant connections but can produce large result sets. The max_nodes parameter caps the total number of nodes returned; when it is reached, the BFS stops and sets truncated: true.

When subject is omitted, the endpoint returns the top entities by out-degree — the most connected nodes in the context database. This is useful for getting an overview of the graph without knowing specific entity names.

GET /api/memories/knowledge-base/graph?subject=john&depth=1&max_nodes=200
GET /api/memories/knowledge-base/graph?subject=john&depth=4&max_nodes=30
GET /api/memories/knowledge-base/graph?max_nodes=100

How are entity types inferred?

Areev infers entity types from belief relations and name patterns. This is best-effort classification — it is not guaranteed to be correct for all entities.

The inference engine uses heuristics: names and relations like “prefers” or “works_at” suggest a Person; IDs starting with “agent:” or relations like “executes” suggest an Agent; relations like “calls” or “uses_tool” suggest a Tool; “org:” prefixes and “works_at” objects suggest an Organization; “located_in” relations suggest a Location. Everything else defaults to Concept.

The entity_type field appears on each node and can be used by frontends to render different icons or colors. Because inference is heuristic, treat it as a hint rather than a guarantee. You can override display logic in your frontend if needed.

Related

• Add and Query — belief grains that populate the graph
• Search — text and structural search across all grain types
• CAL — RECALL beliefs queries that the graph is built from