Decisions

Decisions record architectural and design choices made during development. Each decision captures the rationale, alternatives considered, and current status. Use the semantic search endpoint to check for existing decisions before making new ones.

Create Decision

POST /v1/decisions

Request Body

Field	Type	Required	Description
`title`	string	Yes	Decision title (1-500 characters)
`rationale`	string	Yes	Why this decision was made (1-50,000 characters)
`alternatives`	string	No	Alternatives considered and why they were rejected (max 50,000 characters)
`status`	string	No	Initial status: `active` or `experimental` (default: `active`)
`agent_id`	string	No	Agent that made this decision (UUID or name)
`session_id`	UUID	No	Session during which this decision was made
`project_slug`	string	No	Project slug for scoping
`tags`	array	No	Tags for categorization (max 20 tags, each max 100 characters)
`metadata`	object	No	Custom metadata (max 10KB)

Response `201 Created`

{
  "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "agent_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "session_id": null,
  "project_slug": "api",
  "title": "Use PostgreSQL instead of MongoDB",
  "rationale": "PostgreSQL supports pgvector for semantic search, has better ACID compliance, and our team has more experience with it.",
  "alternatives": "MongoDB: flexible schema but no native vector search. Redis: fast but not suitable for complex queries.",
  "status": "active",
  "superseded_by": null,
  "tags": ["architecture", "database"],
  "metadata": {},
  "created_at": "2026-03-17T10:00:00Z",
  "updated_at": "2026-03-17T10:00:00Z"
}

curl

curl -X POST https://api.memoryrelay.net/v1/decisions \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Use PostgreSQL instead of MongoDB",
    "rationale": "PostgreSQL supports pgvector for semantic search, has better ACID compliance, and our team has more experience with it.",
    "alternatives": "MongoDB: flexible schema but no native vector search. Redis: fast but not suitable for complex queries.",
    "project_slug": "api",
    "tags": ["architecture", "database"]
  }'

Python SDK

from memoryrelay import MemoryRelay

client = MemoryRelay(api_key="mem_prod_...")

decision = client.decisions.create(
    title="Use PostgreSQL instead of MongoDB",
    rationale="PostgreSQL supports pgvector for semantic search, has better ACID compliance.",
    alternatives="MongoDB: flexible schema but no native vector search.",
    project_slug="api",
    tags=["architecture", "database"],
)
print(decision.id)

List Decisions

GET /v1/decisions

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (1-100)
`offset`	integer	0	Number of results to skip
`project_slug`	string	--	Filter by project
`status`	string	--	Filter by status: `active`, `superseded`, `reverted`, `experimental`
`tag`	string	--	Filter by tag

Response

{
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "title": "Use PostgreSQL instead of MongoDB",
      "rationale": "PostgreSQL supports pgvector for semantic search...",
      "status": "active",
      "tags": ["architecture", "database"],
      "metadata": {},
      "created_at": "2026-03-17T10:00:00Z",
      "updated_at": "2026-03-17T10:00:00Z"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "total_count": 1
}

curl

curl "https://api.memoryrelay.net/v1/decisions?project_slug=api&status=active&limit=20" \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

decisions = client.decisions.list(project_slug="api", status="active")
for d in decisions.data:
    print(f"[{d.status}] {d.title}")

Get Decision

GET /v1/decisions/{id}

Path Parameters

Parameter	Type	Description
`id`	UUID	Decision ID

Response

Returns a single decision object.

curl

curl https://api.memoryrelay.net/v1/decisions/f1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

decision = client.decisions.get("f1a2b3c4-d5e6-7890-abcd-ef1234567890")
print(f"{decision.title}\nRationale: {decision.rationale}")

Update Decision

PATCH /v1/decisions/{id}

Path Parameters

Parameter	Type	Description
`id`	UUID	Decision ID

Request Body

Field	Type	Required	Description
`title`	string	No	Updated title (max 500 characters)
`rationale`	string	No	Updated rationale (max 50,000 characters)
`alternatives`	string	No	Updated alternatives (max 50,000 characters)
`status`	string	No	Updated status: `active`, `superseded`, `reverted`, `experimental`
`tags`	array	No	Updated tags
`metadata`	object	No	Updated metadata

Response

Returns the updated decision object.

curl

curl -X PATCH https://api.memoryrelay.net/v1/decisions/f1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["architecture", "database", "reviewed"]
  }'

Python SDK

updated = client.decisions.update(
    "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    tags=["architecture", "database", "reviewed"],
)

Delete Decision

DELETE /v1/decisions/{id}

Path Parameters

Parameter	Type	Description
`id`	UUID	Decision ID

Response

Returns 204 No Content on success.

curl

curl -X DELETE https://api.memoryrelay.net/v1/decisions/f1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

client.decisions.delete("f1a2b3c4-d5e6-7890-abcd-ef1234567890")

Check for Existing Decisions

POST /v1/decisions/check

Semantic search across existing decisions. Use this before creating a new decision to see if a similar one already exists.

Request Body

Field	Type	Required	Description
`query`	string	Yes	Natural language description of the decision you are considering
`project_slug`	string	No	Scope search to a specific project
`limit`	integer	No	Number of results (default: 5)

Response

{
  "data": [
    {
      "decision": {
        "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "title": "Use PostgreSQL instead of MongoDB",
        "rationale": "PostgreSQL supports pgvector for semantic search...",
        "status": "active",
        "tags": ["architecture", "database"],
        "created_at": "2026-03-17T10:00:00Z",
        "updated_at": "2026-03-17T10:00:00Z"
      },
      "score": 0.87
    }
  ],
  "query": "Should we use a relational database for vector search?",
  "total": 1
}

curl

curl -X POST https://api.memoryrelay.net/v1/decisions/check \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Should we use a relational database for vector search?",
    "project_slug": "api"
  }'

Python SDK

results = client.decisions.check(
    query="Should we use a relational database for vector search?",
    project_slug="api",
)
for r in results.data:
    print(f"[{r.score:.2f}] {r.decision.title} ({r.decision.status})")

Decision-Driven Development

Call POST /v1/decisions/check at the start of every design discussion. If a relevant decision already exists, your agent can reference it instead of re-debating the same topic.

Supersede Decision

POST /v1/decisions/{id}/supersede

Create a new decision that supersedes an existing one. The old decision's status is set to superseded and its superseded_by field points to the new decision.

Path Parameters

Parameter	Type	Description
`id`	UUID	ID of the decision being superseded

Request Body

Field	Type	Required	Description
`title`	string	Yes	Title of the new decision (1-500 characters)
`rationale`	string	Yes	Why the old decision is being superseded (1-50,000 characters)
`alternatives`	string	No	Alternatives considered
`tags`	array	No	Tags for the new decision
`metadata`	object	No	Custom metadata

Response

Returns the newly created decision. The original decision's status is automatically set to superseded.

{
  "id": "a2b3c4d5-e6f7-8901-bcde-f23456789012",
  "title": "Migrate to pgvector 0.8 with HNSW indexes",
  "rationale": "pgvector 0.8 supports HNSW indexes which are 10x faster for our dataset size. The original IVFFlat decision is superseded.",
  "status": "active",
  "superseded_by": null,
  "tags": ["architecture", "database", "performance"],
  "created_at": "2026-03-17T14:00:00Z",
  "updated_at": "2026-03-17T14:00:00Z"
}

curl

curl -X POST https://api.memoryrelay.net/v1/decisions/f1a2b3c4-d5e6-7890-abcd-ef1234567890/supersede \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Migrate to pgvector 0.8 with HNSW indexes",
    "rationale": "pgvector 0.8 supports HNSW indexes which are 10x faster for our dataset size.",
    "tags": ["architecture", "database", "performance"]
  }'

Python SDK

new_decision = client.decisions.supersede(
    "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    title="Migrate to pgvector 0.8 with HNSW indexes",
    rationale="pgvector 0.8 supports HNSW indexes which are 10x faster for our dataset size.",
    tags=["architecture", "database", "performance"],
)
print(f"New decision: {new_decision.id}")

Create Decision​

Request Body​

Response 201 Created​

curl​

Python SDK​

List Decisions​

Query Parameters​

Response​

curl​

Python SDK​

Get Decision​

Path Parameters​

Response​

curl​

Python SDK​

Update Decision​

Path Parameters​

Request Body​

Response​

curl​

Python SDK​

Delete Decision​

Path Parameters​

Response​

curl​

Python SDK​

Check for Existing Decisions​

Request Body​

Response​

curl​

Python SDK​

Supersede Decision​

Path Parameters​

Request Body​

Response​

curl​

Python SDK​

Create Decision

Request Body

Response `201 Created`

curl

Python SDK

List Decisions

Query Parameters

Response

curl

Python SDK

Get Decision

Path Parameters

Response

curl

Python SDK

Update Decision

Path Parameters

Request Body

Response

curl

Python SDK

Delete Decision

Path Parameters

Response

curl

Python SDK

Check for Existing Decisions

Request Body

Response

curl

Python SDK

Supersede Decision

Path Parameters

Request Body

Response

curl

Python SDK