Memory semantics and privacy

Workspace-scoped memory

Memory is scoped to the authenticated workspace. Structured queries return exact matches by scope, role, status, and task reference; semantic retrieval ranks by similarity.

Store

POST /v1/memory/store takes content plus optional metadata and returns a memory_id.

curl https://api.hardcarrx.com/v1/memory/store \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Prefer concise launch-readiness summaries.",
    "metadata": {"source": "api", "category": "preference"}
  }'
# {"ok": true, "memory_id": "mem_..."}

Structured query vs semantic retrieval

They answer different questions. /v1/memory/query filters by exact attributes (scope_type, status, memory_roles, task_ref) and returns structured memory objects — no scoring. /v1/memory/semantic/retrieve ranks by similarity to a natural-language query.

curl https://api.hardcarrx.com/v1/memory/query \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"memory_roles": ["durable"], "limit": 50}'
# {"items": [ ...memory objects... ]}

curl https://api.hardcarrx.com/v1/memory/semantic/retrieve \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What launch-readiness details should be remembered?",
    "limit": 5,
    "scope_type": "workspace"
  }'

POST /memory/query (unversioned) is an alias of /v1/memory/query with identical behavior.

Deletion and recovery window

Default deletion is a soft delete: recoverable until the recovery window elapses, then purged. Pass permanent=true to purge immediately with no recovery window.

# Soft delete (recoverable until the recovery window elapses, then purged)
curl -X DELETE https://api.hardcarrx.com/memory/<memory_id> \
  -H "Authorization: Bearer ***"

# Permanent immediate purge
curl -X DELETE "https://api.hardcarrx.com/memory/<memory_id>?permanent=true" \
  -H "Authorization: Bearer ***"

Privacy boundaries

Memory is workspace-scoped — never cross-workspace visible.
Memory writeback during chat is a separate text-only view of message content; raw wire payloads are not stored into memory.
POST /memory/embedding-eligibility (public, unauthenticated) reports whether a memory type is eligible for semantic embedding and why — useful before storing content you intend to retrieve semantically.