Conversations and memory

Conversations persist exactly what a user received from successful chat turns. Semantic memory is an optional layer that distills durable facts into user or project graphs.

These are distinct:

• a conversation is an ordered transcript with a rolling summary;
• memory is a set of temporal facts retrieved across conversations.

Both are owner-scoped and require a user identity.

Create a conversation

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "X-End-User-Id: user-42" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/conversations" \
  -d '{"title":"Architecture review"}'

Optionally set project_id at creation. The project is validated and authorized before the conversation is stored.

Add a chat turn

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "X-End-User-Id: user-42" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/chat/completions" -d "{
  \"model\":\"gpt-5-mini\",
  \"conversation_id\":\"$CONVERSATION_ID\",
  \"messages\":[
    {\"role\":\"user\",\"content\":\"Summarize the decision so far.\"}
  ]
}"

The server replaces ad hoc history with its assembled state: rolling summary, recent verbatim turns, and the caller's new user or tool messages. conversation_id and project_id are mutually exclusive on the request.

Set "store":false when a successful turn must not be persisted.

Read and manage

GET    /v1/conversations?limit=50
GET    /v1/conversations/{id}?limit=100
PATCH  /v1/conversations/{id}
DELETE /v1/conversations/{id}

Patch title or archive state:

{"title":"Final architecture review","archived":true}

Lists and reads are owner-only. Long histories compact asynchronously after the configured token trigger while retaining the newest turns verbatim.

Enable semantic memory

Semantic memory requires MEMORY_URL, MEMORY_TOKEN, and the distinct MEMORY_SIDECAR_TOKEN. An organization administrator configures:

GET /v1/memory/settings
PUT /v1/memory/settings

{
  "memory_enabled": true,
  "retention_days": 90
}

An explicit null retention clears the TTL; omission preserves the current value.

Explicitly remember a fact

curl -H "Authorization: Bearer $DEEPLINQ_API_KEY" \
  -H "X-End-User-Id: user-42" \
  -H "Content-Type: application/json" \
  -X POST "$BASE_URL/v1/memories" -d '{
  "content":"The user prefers concise release notes.",
  "scope":"user"
}'

The content is stored verbatim because this is an explicit user action. For project scope, include project_id; reads require project read permission and writes require project write permission.

GET /v1/memories?scope=user&limit=50&cursor=<opaque>
GET /v1/memories?scope=project&project_id=<id>
DELETE /v1/memories/{fact_id}?scope=user

The ID returned by explicit remember identifies the distillation episode. Fact IDs returned by listing are separate; use listed fact IDs for deletion.

User opt-out

POST   /v1/memory/optout
DELETE /v1/memory/optout

Opt-out is self-service for the authenticated user. Memory routes return 503 memory_unavailable when the sidecar is not configured.

Deletion and retention

Conversation deletion is asynchronous. The cleanup job removes transcript state and asks the memory sidecar to forget linked episodes before final deletion. A memory purge failure retries and prevents a false successful erase. The retention sweep enqueues the same cleanup path.