Graph Retrieval

How Engram combines vector similarity with graph traversal for more accurate recall.

Why vector search alone isn’t enough

Pure vector search finds memories that are semantically similar to the query. But relevant memories aren’t always semantically close to the query string.

Consider: “What does this user do for work?”

If the agent has:

• Memory A: “User is a software engineer” (high similarity to query)
• Memory B: “User’s company was acquired by Stripe last month” (low similarity to query — mentions company/Stripe, not “work”)
• Memory C: “User’s team uses Go for all backend services” (medium similarity)

Memory B is highly relevant context but vector search alone might rank it 15th. Graph traversal finds it because B is connected to A via a causal relationship edge.

Graph structure

Every memory is a node. Edges are created between memories with typed relationships:

Relationship Type	Decay Multiplier	Example
entity_link	0.98	Both mention “Alice”
causal	0.97	A caused B
temporal	0.97	A happened before B
thematic	0.95	Same topic cluster
contradicts	0.95	A and B conflict
supports	0.96	A reinforces B
derived_from	0.96	B was inferred from A
supersedes	0.94	B replaces A

Note: contradicts edges decay slowly (0.95) — the system must remember which beliefs conflict.

Hybrid recall

Every recall query uses a weighted combination:

final_score = vector_score × 0.60 + graph_score × 0.40

Graph score is computed via BFS (breadth-first search) from the top vector results, with score attenuation per hop:

hop_score = source_score × (1 - hop_penalty)^hops

This means memories one hop away from a top result still surface if they’re strongly connected.

Controlling the blend

results = client.memories.recall(
    agent_id=agent.id,
    query="What does this user do for work?",
    top_k=10,
    graph_weight=0.5,   # increase graph influence (default 0.4)
    max_hops=2,         # how deep to traverse (default 2)
)

Embedding-only mode

When LLM_PROVIDER=none, entity extraction and relationship detection are disabled. The graph still exists and thematic links (clustering by embedding similarity) are still created — but entity and causal edges are not.

In practice, the thematic link graph is sufficient for most use cases. The additional entity/causal edges add richest context for complex multi-entity queries.

Graph visualisation

The knowledge graph is exposed via the health dashboard and the graph API:

# Get graph edges for a memory
edges = client.graph.get_edges(memory_id="uuid")

for edge in edges:
    print(f"{edge.relation_type}: {edge.target_memory_id} (weight: {edge.weight:.2f})")