Reference

Relationships API

Navigate the directed relationship graph that connects your workspace memories. Relationships are typed, directed edges discovered post-hoc by multiple heuristics: file overlap, concept overlap, embedding similarity, and session context. Use these endpoints to explore clusters of related knowledge, visualise how concepts connect, and find the shortest path between two memories.

See Relationships Concepts for a full explanation of relationship types and discovery methods.

Base URL and Authentication

https://api.neuroloom.dev

All requests require an API key:

Authorization: Token $MEMORIES_API_TOKEN

Relationship Types

Value	Direction	Meaning
`references`	A → B	A explicitly references or depends on B (file/symbol overlap)
`related_to`	A → B	General semantic relatedness; default for heuristic discovery
`caused_by`	A → B	A is the consequence of B (LLM only; directed)
`contradicts`	A ↔ B	A and B conflict on the same topic (LLM only; symmetric)
`supersedes`	A → B	A replaces B; B is the older knowledge (LLM only; directed)
`similar_to`	A ↔ B	Discovered by embedding cosine similarity (symmetric)
`depends_on`	A → B	A requires B to hold; never heuristic-assigned (LLM/manual only)

Get Raw Graph Data

GET /api/v1/memories/graph

Return all nodes and edges in the workspace's memory graph. Use this for full-graph visualisation or to build a local relationship index. For large workspaces, prefer the explore endpoint to fetch a bounded subgraph.

Response — 200 OK

{
  "nodes": [
    {
      "memory_id": "mem-a1b2c3d4e5f6g7h8",
      "title": "Prefer async SQLAlchemy for all DB calls",
      "memory_type": "pattern",
      "importance_score": 0.9,
      "pagerank_score": 0.51,
      "community_label": "database-patterns"
    }
  ],
  "edges": [
    {
      "source_memory_id": "mem-a1b2c3d4e5f6g7h8",
      "target_memory_id": "mem-zz9988776655aabb",
      "relationship_type": "similar_to",
      "discovery_method": "embedding_similarity",
      "confidence": 0.87,
      "is_bidirectional": false,
      "created_at": "2026-03-20T09:00:00Z"
    }
  ]
}

curl "https://api.neuroloom.dev/api/v1/memories/graph" \
  -H "Authorization: Token $MEMORIES_API_TOKEN"

Note

pagerank_score and community_label are computed by the background graph analysis job. They are null for memories whose embeddings have not yet been processed.

Explore a Topic Subgraph

POST /api/v1/memories/explore

Seed a graph traversal with a query, then expand outward through relationship edges to return a bounded subgraph. Useful for understanding how a topic connects through your workspace knowledge, and for building contextual memory injections without retrieving the entire graph.

memory_explore(
  query="async database patterns and performance",
  max_nodes=30,
  relationship_types=["similar_to", "references", "related_to"],
  min_edge_confidence=0.7,
  seed_limit=5
)

The MCP memory_explore tool exposes all the same parameters as the REST endpoint.

import httpx, os

response = httpx.post(
    "https://api.neuroloom.dev/api/v1/memories/explore",
    headers={"Authorization": f"Token {os.environ['MEMORIES_API_TOKEN']}"},
    json={
        "query": "async database patterns and performance",
        "max_nodes": 30,
        "relationship_types": ["similar_to", "references", "related_to"],
        "min_edge_confidence": 0.7,
        "seed_limit": 5,
    },
)
subgraph = response.json()
print(f"Nodes: {len(subgraph['nodes'])}, Edges: {len(subgraph['edges'])}")

curl -X POST "https://api.neuroloom.dev/api/v1/memories/explore" \
  -H "Authorization: Token $MEMORIES_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "async database patterns and performance",
    "max_nodes": 30,
    "relationship_types": ["similar_to", "references", "related_to"],
    "min_edge_confidence": 0.7,
    "seed_limit": 5
  }'

Request body

Field	Type	Required	Default	Description
`query`	string	Yes	—	Natural language topic or question used to find seed memories via semantic search.
`max_nodes`	integer	No	`50`	Maximum nodes to include in the returned subgraph. Maximum value: `200`.
`relationship_types`	array of strings	No	all types	Restrict traversal to these edge types. Omit to traverse all relationship types.
`min_edge_confidence`	float	No	`0.0`	Minimum edge confidence for an edge to be traversed. Set `0.7` or higher to filter noise.
`seed_limit`	integer	No	`5`	Number of seed memories to start the traversal from. Seeds are chosen by semantic similarity to `query`.

Response — 200 OK

{
  "nodes": [
    {
      "memory_id": "mem-a1b2c3d4e5f6g7h8",
      "title": "Prefer async SQLAlchemy for all DB calls",
      "memory_type": "pattern",
      "importance_score": 0.9,
      "pagerank_score": 0.51,
      "community_label": "database-patterns"
    },
    {
      "memory_id": "mem-bb3344556677ccdd",
      "title": "Configure connection pool for production load",
      "memory_type": "decision",
      "importance_score": 0.82,
      "pagerank_score": 0.38,
      "community_label": "database-patterns"
    }
  ],
  "edges": [
    {
      "source_memory_id": "mem-a1b2c3d4e5f6g7h8",
      "target_memory_id": "mem-bb3344556677ccdd",
      "relationship_type": "references",
      "confidence": 0.81
    }
  ],
  "seed_memories": ["mem-a1b2c3d4e5f6g7h8"]
}

seed_memories lists the memory IDs used as traversal starting points. All remaining nodes were reached via graph traversal from those seeds.

Find Shortest Path

POST /api/v1/memories/path

Find the shortest relationship path between two memories using BFS traversal. Returns the sequence of memory IDs and the edges connecting them. Useful for understanding how two apparently unrelated concepts connect through the workspace's relationship graph.

Request body

Field	Type	Required	Default	Description
`source_memory_id`	string	Yes	—	Starting memory `memory_id`.
`target_memory_id`	string	Yes	—	Destination memory `memory_id`.
`max_depth`	integer	No	`5`	Maximum BFS depth. Higher values find longer paths but take more time.
`relationship_types`	array of strings	No	all types	Restrict path search to these edge types.

Response — 200 OK

{
  "path": [
    "mem-a1b2c3d4e5f6g7h8",
    "mem-bb3344556677ccdd",
    "mem-zz9988776655aabb"
  ],
  "edges": [
    {
      "source_memory_id": "mem-a1b2c3d4e5f6g7h8",
      "target_memory_id": "mem-bb3344556677ccdd",
      "relationship_type": "references",
      "confidence": 0.81
    },
    {
      "source_memory_id": "mem-bb3344556677ccdd",
      "target_memory_id": "mem-zz9988776655aabb",
      "relationship_type": "references",
      "confidence": 0.91
    }
  ],
  "depth": 2
}

If no path exists within max_depth, returns:

{ "path": [], "edges": [], "depth": 0 }

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-a1b2c3d4e5f6g7h8",
    "target_memory_id": "mem-zz9988776655aabb",
    "max_depth": 5,
    "relationship_types": ["references", "related_to", "similar_to"]
  }'

How Relationships Are Discovered

Relationships are created automatically by background jobs that run after each memory is stored or updated. The four discovery heuristics are:

Method	How It Works
`embedding_similarity`	pgvector cosine similarity between memory embeddings. Creates `similar_to` edges above a confidence threshold.
`file_overlap`	Memories sharing one or more `source_files` entries. Creates `references` or `related_to` edges.
`concept_overlap`	Memories sharing `concepts` labels. Creates `related_to` edges weighted by overlap count.
`session_context`	Memories created in the same session or temporally proximate sessions. Creates `related_to` edges.

Manual relationship creation is not exposed through the Relationships API endpoints on this page. Use POST /api/v1/relationships (see Relationships Concepts) to create explicit edges, or the Decision Tracking cookbook for a worked example.

Error Responses

Status	When
`401 Unauthorized`	Missing or invalid `Authorization` header.
`404 Not Found`	A `memory_id` supplied in the path request does not exist.
`422 Unprocessable Entity`	Invalid parameter value (e.g. `max_nodes` > 200, unknown `relationship_types` value).

Relationships and Graph — relationship types, discovery heuristics, and community detection
Graph Exploration — topic subgraphs, shortest paths, and cluster discovery

Ready to get started?

Start building with Neuroloom for free.

Start Building Free

Relationships API

Base URL and Authentication

Relationship Types

Get Raw Graph Data

Explore a Topic Subgraph

Find Shortest Path

How Relationships Are Discovered

Error Responses

Related