How do I query the knowledge graph?
http://localhost:3001 Daemion stores long-term knowledge in Engram, a graph memory system backed by Neo4j. Every agent conversation, insight, and fact gets written into the graph as entities and relationships. These endpoints let you query that graph directly — inspect what Daemion knows, find entities by type, and traverse local neighborhoods.
How do I get graph statistics?
Return node and relationship counts for the entire graph. Useful for a quick health check or dashboard widget.
curl “http://localhost:3001/graph/stats”
-H “Authorization: Bearer $DAEMION_TOKEN”
Response shape:
{ “stats”: { “Entity”: 342, “Fact_total”: 891, “Fact_active”: 874 } }
The stats object is keyed by Neo4j node label. Fact_total is the total number of FACT relationships; Fact_active counts only those where is_active is true.
How do I get the full graph?
Return the top N entities by activation score, plus all facts between those entities. Designed for graph visualization.
| Parameter | Type | Description |
|---|---|---|
limit | number | Maximum number of entities to return. Capped at 300. Defaults to 200. |
Default limit (200 entities)
curl “http://localhost:3001/graph/full”
-H “Authorization: Bearer $DAEMION_TOKEN”
Smaller snapshot for visualization
curl “http://localhost:3001/graph/full?limit=50”
-H “Authorization: Bearer $DAEMION_TOKEN”
Response shape:
{ “entities”: [ { “uuid”: “a1b2c3d4-…”, “name”: “Daemion”, “entity_type”: “project”, “summary”: “Persistent autonomous AI copartner system.”, “group_id”: “daemion”, “confidence”: 1, “activation_score”: 0.95, “created_at”: “2026-03-01T10:00:00Z”, “last_accessed”: “2026-03-31T08:00:00Z”, “access_count”: 47 } ], “facts”: [ { “uuid”: “e5f6…”, “from_name”: “Daemion”, “to_name”: “Neo4j”, “fact”: “Daemion uses Neo4j as its graph memory store.”, “predicate”: “USES”, “confidence”: 0.98, “created_at”: “2026-03-01T10:00:00Z”, “is_active”: true } ] }
Facts are limited to relationships between the returned entities. Maximum 600 facts per call.
How do I list entity types?
Return all distinct entity_type values in the graph with their counts, ordered by count descending.
curl “http://localhost:3001/graph/types”
-H “Authorization: Bearer $DAEMION_TOKEN”
Response shape:
{ “types”: [ { “type”: “person”, “count”: 12 }, { “type”: “project”, “count”: 8 }, { “type”: “concept”, “count”: 34 } ] }
How do I search entities?
List entities with optional filters. Returns up to 100 entities ordered by activation_score descending.
| Parameter | Type | Description |
|---|---|---|
type | string | Filter by entity_type. Case-insensitive. |
group | string | Filter by group_id. Matches exactly. |
limit | number | Maximum entities to return. Defaults to 100. |
search | string | Substring search over entity name and summary. Case-insensitive. |
All entities of type “concept”
curl “http://localhost:3001/graph/entities?type=concept”
-H “Authorization: Bearer $DAEMION_TOKEN”
Search for entities mentioning “gateway”
curl “http://localhost:3001/graph/entities?search=gateway&limit=20”
-H “Authorization: Bearer $DAEMION_TOKEN”
Entities in the daemion group
curl “http://localhost:3001/graph/entities?group=daemion”
-H “Authorization: Bearer $DAEMION_TOKEN”
Response shape:
{ “entities”: [ { “uuid”: ”…”, “name”: ”…”, “entity_type”: “concept”, ”…” : ”…” } ], “count”: 14 }
How do I get an entity with its facts?
Fetch a single entity by UUID or exact name, plus all outgoing and incoming FACT relationships. Returns 404 if no match.
The :id segment can be either the entity’s UUID or its exact name.
Look up by name
curl “http://localhost:3001/graph/entity/Daemion”
-H “Authorization: Bearer $DAEMION_TOKEN”
Look up by UUID
curl “http://localhost:3001/graph/entity/a1b2c3d4-e5f6-7890-abcd-ef1234567890”
-H “Authorization: Bearer $DAEMION_TOKEN”
Response shape:
{ “entity”: { “uuid”: “a1b2c3d4-…”, “name”: “Daemion”, “entity_type”: “project”, “summary”: “Persistent autonomous AI copartner system.”, “group_id”: “daemion”, “confidence”: 1, “activation_score”: 0.95, “created_at”: “2026-03-01T10:00:00Z”, “last_accessed”: “2026-03-31T08:00:00Z”, “access_count”: 47 }, “outgoing”: [ { “uuid”: ”…”, “from_name”: “Daemion”, “to_name”: “Neo4j”, “fact”: “Daemion uses Neo4j as its graph memory store.”, “predicate”: “USES”, “confidence”: 0.98, “created_at”: “2026-03-01T10:00:00Z”, “is_active”: true } ], “incoming”: [] }
Outgoing and incoming are each capped at 50 facts, ordered by confidence descending.
How do I get a local subgraph?
Return the neighborhood around an entity: all entities reachable within N hops, plus the facts connecting them.
| Parameter | Type | Description |
|---|---|---|
depth | number | Traversal depth from the center entity. Defaults to 2. Capped at 3. |
2-hop neighborhood around “Daemion”
curl “http://localhost:3001/graph/local/Daemion”
-H “Authorization: Bearer $DAEMION_TOKEN”
1-hop neighborhood (immediate neighbors only)
curl “http://localhost:3001/graph/local/Daemion?depth=1”
-H “Authorization: Bearer $DAEMION_TOKEN”
Response shape is the same as /graph/full — an object with entities and facts arrays. Entities are capped at 60; facts at 100.
Frequently asked questions
search_history and find_relevant. The graph endpoints here give you direct read access to the same store./graph/full and /graph/entities results. It is updated by Engram automatically as agents read and write the graph — you don't set it manually.daemion group by default (configurable via the DAEMION_SHARED_GROUP environment variable). Individual agents may write to their own group. Use ?group=daemion to filter to project-level memory./graph/entities with filters for programmatic access to specific subsets.What can go wrong
404 {"error": "entity not found"} — No entity matched the UUID or name you provided in /graph/entity/:id or /graph/local/:id. Entity names are case-sensitive and must match exactly. Use /graph/entities?search=... to find the correct name first.
Empty stats object — Neo4j is not running or is unreachable. The gateway connects to NEO4J_URL (default http://localhost:7474). Check that the Neo4j service is up and that NEO4J_USER / NEO4J_PASS environment variables are correct. Graph endpoints return empty results rather than erroring when Neo4j is down.
facts array is empty on /graph/entity/:id — The entity exists but has no FACT relationships yet. This is normal for newly created entities that haven’t been linked to others through conversation.
/graph/local/:id returns only the center entity — The entity has no neighbors within the requested depth. Try ?depth=3 or use /graph/entity/:id to inspect its direct outgoing and incoming facts.
What’s next?
- Signals API — query system telemetry and job execution metrics
- Conversations API — send messages to agents and read thread history
- Extensions API — manage agents, jobs, and all other extension types