Core Concepts

Relationships and Graph

Relationships are typed, directed edges between memories. A bug_fix memory that traces back to an architecture decision has a caused_by edge connecting them. An integration memory that builds on a pattern has a references edge. These edges make the memory store navigable: from any starting point, you can explore the neighborhood of related context or find the shortest path between two memories across the knowledge structure.

Neuroloom discovers relationships automatically after each memory is stored. You do not need to declare them. The discovery pipeline runs eight heuristics — file overlap, concept overlap, semantic similarity, and others — and assigns each discovered edge a type from the relationship StrEnum.

Edge Types

Every relationship has a relationship_type that describes the nature of the connection between two memories.

Type	Direction	Description
`references`	A → B	A cites or directly depends on B. Used for file/symbol overlap — two memories that touch the same code.
`related_to`	A → B	A is contextually connected to B without a more specific relationship. The default for concept overlap, temporal proximity, and session co-occurrence.
`caused_by`	A → B	A is the consequence of B. Example: a bug that was introduced by an architecture change.
`contradicts`	A ↔ B	A and B represent conflicting knowledge — a convention that was reversed, or two conflicting decisions.
`supersedes`	A → B	A replaces B. B is the older knowledge; A is the current truth.
`similar_to`	A ↔ B	A and B cover the same conceptual ground. Used for semantic similarity matches; effectively undirected.
`depends_on`	A → B	A requires B to hold. Never heuristic-assigned — only set by LLM or manually.

Discovery Heuristics

After a memory is stored, the relationship discovery pipeline runs eight heuristics against the memory store to find candidates for new edges.

Method	Trigger	Assigned Edge Type	Description
`file_overlap`	Two memories share source files	`references`	If two memories were created during work on the same files, they reference common code.
`symbol_overlap`	Two memories reference the same code symbols	`references`	Symbol-level overlap is more precise than file overlap — same function, class, or variable.
`concept_overlap`	Two memories share extracted concepts	`related_to`	Concepts are extracted from the narrative at write time. Shared concepts imply related context.
`semantic_similarity`	Embedding cosine distance below threshold	`similar_to`	Pure vector similarity — catches paraphrased or semantically equivalent memories.
`temporal_proximity`	Two memories created in the same session window	`related_to`	Memories captured close together in time likely reflect connected work.
`session_context`	Two memories share a `source_session_id`	`related_to`	Same session = same working context. A reliable signal for relatedness.
`manual`	Developer-created via the relationships API	`related_to` (default)	You specify the relationship type explicitly. The default is `related_to` unless overridden.
`llm_extraction`	LLM inference pass over the narrative	`related_to` (reclassified)	An LLM reads the narrative and infers the relationship. The initial assignment is `related_to`; the LLM may reclassify to a more specific type.

Note

Discovery runs asynchronously after memory creation. Relationships appear in the graph within seconds under normal load. The manual method via the relationships API is synchronous.

How LLM Reclassification Works

The llm_extraction heuristic starts with related_to as the assigned type and then passes both memories to an LLM with a prompt that asks it to identify the most precise relationship from the StrEnum. If the LLM determines the relationship is caused_by or supersedes, the edge is updated. If the LLM is not confident, the edge stays as related_to. This prevents over-classification while catching relationships that pure heuristics miss.

The Relationship Graph

The edge network across a workspace forms a navigable structure. Every memory is a node; every relationship is a directed, typed edge. This structure powers two retrieval patterns beyond basic semantic search.

In this example, an incident that caused N+1 queries (incident) traces back to an architecture decision (architecture) via caused_by. The fix introduced a performance convention (discovery) that supersedes the incident. A SQLAlchemy integration memory (pattern) references that performance discovery.

Starting from the integration memory and exploring one hop out surfaces all five memories — giving an agent the full context chain without a keyword match to any of them.

Graph Retrieval

Three endpoints expose the relationship graph.

Topic Subgraph

POST /api/v1/memories/explore

Seeds a subgraph from a topic query. Neuroloom finds the most semantically similar memories to the query, then expands one hop along relationship edges to include their neighbors. The result is a subgraph of nodes and edges centered on the topic.

curl -X POST https://api.neuroloom.dev/api/v1/memories/explore \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "database query performance",
    "depth": 1,
    "limit": 20
  }'

The response includes the seed memories, their one-hop neighbors, and all edges between them with their types and discovery methods.

Shortest Path

POST /api/v1/memories/path

Runs BFS (breadth-first search) to find the shortest path between two specific memories across the edge network. Useful for understanding how two seemingly unrelated memories connect.

curl -X POST https://api.neuroloom.dev/api/v1/memories/path \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_memory_id": "mem_abc123",
    "target_memory_id": "mem_xyz789"
  }'

Raw Graph

GET /api/v1/memories/graph

Returns all nodes and edges in the workspace graph. Suitable for visualization or bulk analysis. For large workspaces, use pagination parameters to limit the result set.

Community Detection

In addition to individual edges, Neuroloom runs community detection across the full workspace graph to identify clusters of closely related memories.

The algorithm is label propagation — a fast, iterative method that assigns each memory a community_label based on the labels of its neighbors. Communities naturally form around related problem domains: a database community, an authentication community, a testing community. The labels are strings assigned per workspace.

Schedule: daily cron job at 01:30 UTC.

Community labels appear on each memory as community_label and power the workspace overview view in the dashboard, which shows your memory store partitioned into its discovered clusters.

Note

Community labels are workspace-specific strings — they are not a shared taxonomy. Two workspaces with similar memories get independently labeled communities. The labels reflect the structure of that workspace's edge network.

Creating Relationships Manually

The discovery pipeline covers most cases. When you need a precise relationship that heuristics miss, create it manually.

curl -X POST https://api.neuroloom.dev/api/v1/relationships \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_memory_id": "mem_abc123",
    "target_memory_id": "mem_xyz789",
    "relationship_type": "supersedes",
    "notes": "The new caching strategy replaces the Redis-based approach documented in the older memory."
  }'

Manual relationships are created with discovery_method: manual and the default relationship_type: related_to unless you specify otherwise.

What is a Memory — memory fields, types, and the data model
Relationships API Reference — full endpoint documentation for creating and querying edges

Ready to get started?

Start building with Neuroloom for free.

Start Building Free