API Reference

Create Relation

Create a typed directional relation from one scoped memory to another.

Endpoint and request fields

POST/memory/{memory_id}/relations

201 Created

Field	Type	Contract
`memory_id` / `fromMemoryId`	integer	Positive source memory ID in the path or first SDK argument.
`to_memory_id` / `toMemoryId`	integer	Required target ID returned by MemorySync; must differ from the source.
`relationship_type` / `relationshipType`	string	`similar`, `derived_from`, `continuation`, `contradiction`, `summary_of`, `detail_of`, `caused_by`, `references`, `supports`, or `extends`.
`confidence`	number	Optional value from 0 to 1; defaults to 1.0.
`metadata`	object	Optional application metadata.

Create a relation

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="usr_7f3a9c2e",
)

relation = client.create_relation(
    101,
    to_memory_id=102,
    relationship_type="supports",
    confidence=0.9,
)

Result paths

201 relation result

Directional relation

The result identifies the relation and both endpoints.

Identity: Python `relation.id`; Node.js `relation.id`; REST `id`
Relation ID.
Endpoints: `from_memory_id` / `fromMemoryId`, `to_memory_id` / `toMemoryId`
Source and target IDs.
Meaning: `relationship_type` / `relationshipType`, `confidence`
Declared relation semantics.
Context: `metadata`, `created_at` / `createdAt`
Optional metadata and creation time.

201-response.json

{"id":31,"from_memory_id":101,"to_memory_id":102,"relationship_type":"supports","confidence":0.9,"metadata":null,"created_at":"2026-05-04T12:31:00Z"}

Errors and next action

Use source and target IDs returned by MemorySync, keep them different, and choose a supported relationship type. A 404 means a referenced memory is unavailable in the current scope. For 429 or 5xx, preserve the pending product action without assuming creation.

Safety notes

Relationship type guide

Type	Use when the target memory…
`similar`	Expresses closely related information.
`derived_from`	Was produced from the source memory.
`continuation`	Continues the same event or narrative.
`contradiction`	Conflicts with the source and should be reviewed.
`summary_of` / `detail_of`	Represents a summary-detail direction.
`caused_by`	Records an application-declared causal direction.
`references` / `supports` / `extends`	References, supports, or extends the source.

Create relations deliberately

Use IDs returned by MemorySync and authorize both records for the current product action.
Keep source and target IDs different.
Select the narrowest supported relationship type your application can justify.
Use confidence from 0 to 1 only when your application has a meaningful confidence signal.
Treat a relation as application context, not proof that either memory is currently correct.

Get Memory

Inspect either endpoint by ID.

Query Memory

Find relevant memories first.

Forget Memory

Remove selected memory IDs.

Was this page helpful?

← Previous

Summarize

Export