Relationships API

Connect memories with typed relationships to build knowledge graphs.

Updated Oct 6, 2026

Overview

Relationships connect memories to each other, creating a traversable knowledge graph. Each relationship has a type, direction, and strength (weight) that indicates confidence.

Relationship Types: Use built-in types like supports, contradicts, references, or define custom types for your domain.

Create Relationship

Endpoint

POST /relationships/:sourceId

Creates a directed relationship from :sourceId to target_id. The relationship's natural key is (source_id, target_id, relationship_type) — the same triple cannot be created twice.

Path Parameters

Field	Type	Description
sourceId	string (UUID, required)	Source memory UUID — the relationship points FROM this memory.

Body Parameters

Field	Type	Description
target_id	string (UUID, required)	Target memory UUID — the relationship points TO this memory.
relationship_type	string (required)	The relationship type. Must be one of the enum values in `RELATIONSHIP_TYPES` (see Relationship Types below). Custom strings are rejected.
description	string	Optional human-readable explanation (max 1000 chars).
weight	number	Initial weight/strength of the relationship. Minimum 0, default 1.0.
decay_rate	number	How fast this relationship decays over time. Range 0-1, default 0.02.
rules	object	Optional JSON rules for when this relationship applies.
metadata	object	Optional key-value pairs for additional context.
bidirectional	boolean	Optional. If true, the API records this as a bidirectional edge (two rows). Default: false.

Response (201)

Example Response

{
  "id": "<relationship-uuid>",
  "source_id": "<source-uuid>",
  "target_id": "<target-uuid>",
  "relationship_type": "supports",
  "description": "Both describe research findings",
  "weight": 0.9,
  "usage_count": 0,
  "metadata": {
    "verified": true
  },
  "created_at": "2026-04-15T10:30:00Z",
  "updated_at": "2026-04-15T10:30:00Z"
}

List a Memory's Relationships

Endpoint

GET /relationships/:memoryId

Returns outgoing and/or incoming relationships for the given memory.

Path Parameters

Field	Type	Description
memoryId	string (UUID, required)	Memory UUID.

Query Parameters

Field	Type	Description
direction	string	`outgoing`, `incoming`, or `both` (default).
type	string	Filter by relationship type (must be in the `RELATIONSHIP_TYPES` enum).

List related memories (graph walk)

Endpoint

GET /relationships/:memoryId/related

Returns memories reachable from :memoryId across the relationship graph, optionally filtered by type and depth.

Path Parameters

Field	Type	Description
memoryId	string (UUID, required)	Starting memory UUID.

Update Relationship

Endpoint

PATCH /relationships/:sourceId/:targetId/:type

Updates an existing relationship identified by the (source, target, type) triple.

Path Parameters

Field	Type	Description
sourceId	string (UUID, required)	Source memory UUID.
targetId	string (UUID, required)	Target memory UUID.
type	string (required)	Relationship type — must match the existing row.

Body Parameters

Field	Type	Description
weight	number	New weight value (≥ 0).
description	string	Updated description.
metadata	object	Updated metadata. Merges with existing.

Response (200)

Example Response

{
  "id": "<relationship-uuid>",
  "source_id": "<source-uuid>",
  "target_id": "<target-uuid>",
  "relationship_type": "supports",
  "weight": 0.95,
  "metadata": {
    "verified": true,
    "verified_by": "<user-id>",
    "verified_at": "2026-04-20T10:00:00Z"
  },
  "updated_at": "2026-04-20T10:00:00Z"
}

Weaken Relationship

Endpoint

POST /relationships/:sourceId/:targetId/:type/weaken

Decrease the weight of a relationship (used when memories diverge in usage).

Path Parameters

Field	Type	Description
sourceId	string (UUID, required)	Source memory UUID.
targetId	string (UUID, required)	Target memory UUID.
type	string (required)	Relationship type.

Note: Relationship weights decay naturally over time without reinforcement (see the decay_rate field).

Delete Relationship

Endpoint

DELETE /relationships/:sourceId/:targetId/:type

Removes a relationship identified by the (source, target, type) triple.

Path Parameters

Field	Type	Description
sourceId	string (UUID, required)	Source memory UUID.
targetId	string (UUID, required)	Target memory UUID.
type	string (required)	Relationship type.

Response (204)

Returns no content on successful deletion.

Reinforce Relationship

Endpoint

POST /relationships/:sourceId/:targetId/:type/reinforce

Increase the weight of a relationship when both memories are used together successfully.

Path Parameters

Field	Type	Description
sourceId	string (UUID, required)	Source memory UUID.
targetId	string (UUID, required)	Target memory UUID.
type	string (required)	Relationship type.

Batch Create Relationships

Endpoint

POST /relationships/batch

Creates multiple relationships in a single request. Useful for importing knowledge graphs.

Body Parameters

Field	Type	Description
relationships	array (required)	Array of relationship objects. Each must include `source_id`, `target_id`, `relationship_type`, and may include `weight`, `description`, `metadata`, `bidirectional`.

Response (201)

Example Response

{
  "succeeded": [
    { "id": "<relationship-uuid>", "source_id": "<source-uuid>", "target_id": "<target-uuid>", "relationship_type": "supports", "weight": 0.9 },
    { "id": "<relationship-uuid>", "source_id": "<source-uuid>", "target_id": "<target2-uuid>", "relationship_type": "references", "weight": 0.7 }
  ],
  "failed": []
}

Relationship Types

Built-in relationship types and their semantics:

Type	Description	Direction
`related_to`	Generic relationship between related concepts	Bidirectional
`parent_of`	Hierarchical parent-child relationship	Parent → Child
`child_of`	Inverse of parent_of	Child → Parent
`supersedes`	Source replaces or updates target	New → Old
`references`	Source mentions or cites target	Citing → Cited
`derived_from`	Source was created based on target	Derived → Original
`contradicts`	Source conflicts with target	Bidirectional
`supports`	Source provides evidence for target	Evidence → Claim
`similar_to`	Semantic similarity (often auto-generated)	Bidirectional
`depends_on`	Source requires target to be valid	Dependent → Dependency
`caused_by`	Source is an effect of target	Effect → Cause
`leads_to`	Source causes target (inverse of caused_by)	Cause → Effect

Custom Types: You can use any string as a relationship type. Custom types are treated as directional by default.

Inverse Type Mappings

When creating bidirectional relationships, the API automatically creates an inverse relationship with the appropriate type:

Type	Inverse Type
`parent_of`	`child_of`
`child_of`	`parent_of`
`supersedes`	`superseded_by`
`superseded_by`	`supersedes`
`references`	`referenced_by`
`referenced_by`	`references`
`derived_from`	`source_of`
`source_of`	`derived_from`
`depends_on`	`dependency_of`
`dependency_of`	`depends_on`
`caused_by`	`leads_to`
`leads_to`	`caused_by`
`supports`	`supported_by`
`supported_by`	`supports`
`related_to`	`related_to` (symmetric)
`contradicts`	`contradicts` (symmetric)
`similar_to`	`similar_to` (symmetric)

Bidirectional Example Response

{
  "id": "rel_x1y2z3w4v5u6",
  "source_id": "mem_abc123",
  "target_id": "mem_def456",
  "type": "supports",
  "strength": 0.9,
  "created_at": "2024-01-15T10:30:00Z",
  "inverse_relationship": {
    "id": "rel_a1b2c3d4e5f6",
    "source_id": "mem_def456",
    "target_id": "mem_abc123",
    "type": "supported_by",
    "strength": 0.9
  }
}

Relationship Object

The relationship object contains the following fields:

Field	Type	Description
id	string	Unique identifier for the relationship. Prefixed with `rel_`.
source_id	string	The source memory ID.
target_id	string	The target memory ID.
type	string	The relationship type.
strength	number	Confidence/weight of the relationship (0.0 to 1.0).
metadata	object	Custom key-value pairs.
reinforcement_count	integer	Number of times this relationship has been reinforced.
created_at	string	ISO 8601 timestamp of when the relationship was created.
updated_at	string	ISO 8601 timestamp of when the relationship was last updated.
last_reinforced_at	string \| null	ISO 8601 timestamp of last reinforcement.