Relationship Graph

Remem maintains a relationship graph over all stored memories. Connections are typed via relationship_type, one of: related_to, caused_by, part_of, references, contradicts, supports, similar_to, derived_from. The graph is stored in a compressed sparse row (CSR) structure embedded in-process in remem-server.

Auto-discovery

When a memory is stored, an asynchronous background worker compares its embedding against existing memories in the HNSW index. Pairs at or above the similarity threshold receive a related_to connection automatically.

The threshold is configured in remem-server.toml, not an environment variable:

[connections]
auto_discovery_threshold = 0.7      # minimum similarity to auto-link two memories
auto_discovery_top_k = 5            # max auto-created connections per new memory

store_memory returns before discovery completes — connections appear shortly after the memory is created, not synchronously with it. This means the graph grows automatically without any explicit configuration. As more memories are stored, the graph becomes denser and traversals surface richer context.

Manual connection creation

Add explicit connections via the connections API:

curl -X POST http://localhost:4545/api/v1/connections \
  -H "Authorization: Bearer your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "mem_abc",
    "target_id": "mem_def",
    "relationship_type": "caused_by"
  }'

relationship_type defaults to related_to if omitted. An optional strength (0–1) can also be supplied. The response is 200 with {"source_id", "connection"}.

Relationship types:

• related_to — general semantic relationship (created by auto-discovery or manually)
• caused_by — causal relationship
• part_of — hierarchical relationship
• references — one memory references another
• contradicts — memories conflict
• supports — one memory reinforces another
• similar_to — near-duplicate or closely related content
• derived_from — one memory was derived/summarised from another

Listing and removing connections

curl "http://localhost:4545/api/v1/connections?limit=50&offset=0" \
  -H "Authorization: Bearer your-key"

curl -X DELETE "http://localhost:4545/api/v1/connections/mem_abc/mem_def" \
  -H "Authorization: Bearer your-key"

GET /api/v1/connections returns {"connections": [{"source_id", "connection": Connection}], "total", "limit", "offset"} (max limit is 500). DELETE returns 200 on success or 404 if the connection doesn’t exist.

Traversal

find_related (MCP) and GET /api/v1/memories/{id}/related (REST) traverse the graph starting from a memory node:

curl "http://localhost:4545/api/v1/memories/{id}/related?depth=2&limit=20" \
  -H "Authorization: Bearer your-key"

depth defaults to 1 (max 5), limit defaults to 20 (max 100), and an optional relationship_types comma-separated filter narrows which connection types are followed.

{
  "memory_id": "mem_abc",
  "related": [
    {
      "memory": { "id": "mem_def", "content": "...", "importance": 0.7 },
      "connection": {
        "target_id": "mem_def",
        "relationship_type": "related_to",
        "strength": 0.82,
        "created_at": "2024-01-01T00:00:00Z"
      }
    }
  ]
}

Via MCP

{
  "tool": "find_related",
  "arguments": {
    "memory_id": "mem_abc",
    "depth": 2,
    "limit": 10
  }
}

depth defaults to 1 and limit defaults to 10 for the MCP tool.