Relationship Graph

Remem maintains a relationship graph over stored memories. Connections are typed via relationship_type and persisted with the corpus, so graph traversal remains available after a restart.

Auto-discovery

When a memory is stored, a durable background job compares it with existing memories through the vector index. Strong candidate pairs receive a similar_to connection automatically; explicit connections can use the full relationship type set.

Discovery is configured in remem.toml:

[discovery]
enabled = true
threshold = 0.7
top_k = 5

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.