Home/Documentation

Memories

Production memory write and retrieval use the mounted notes and search APIs below. Older /v1/memories routes documented in earlier drafts are not mounted and must not be called.

Identity: X-User-Id is trusted-server delegation only. Project API keys may set it from a trusted backend to partition end-user memory. It is never browser authentication.

Deletion honesty: current note delete removes the source row only. It does not prove projection purge, backup purge, or GDPR/hard erasure. Successful deletes return HTTP 204 with transitional headers X-MemoAir-Deletion-Scope: source-only, X-MemoAir-Projection-Status: retained, and X-MemoAir-Erasure-Status: incomplete.

POSTclient.notes.add() / batch upsert
HTTP:POST /v1/notes/batchUpsert

Create or update notes in an authorized workspace. This is the mounted production write path.

Parameters

workspaceIdstringRequired

Authorized workspace that owns the notes. Required even when skipMemorySync is true.

notesarrayRequired

Note payloads to create or update (id, content, source metadata, timestamps).

skipMemorySyncbooleanOptionalDefault: false

When true, persists notes without forwarding to the memory projection path.

Example

batch_upsert.sh
BASH
curl -X POST "https://backend.memoair.space/v1/notes/batchUpsert" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-project-key" \
  -H "X-User-Id: end-user-123" \
  -d '{
    "workspaceId": "ws_abc",
    "notes": [{
      "id": "note-1",
      "content": "User prefers FastAPI for backends",
      "sourceUrl": "https://example.com",
      "sourceTitle": "chat",
      "createdAt": 1710000000000,
      "updatedAt": 1710000000000,
      "type": "text"
    }]
  }'
POSTclient.search / POST /v1/search
HTTP:POST /v1/search

Search authorized memory projections for the current workspace or project scope.

Parameters

querystringRequired

Natural-language search query over authorized memory projections.

workspaceIdstringOptional

Workspace scope for the search. Project defaults apply when omitted.

limitnumberOptionalDefault: 10

Maximum number of hits to return.

Example

search.sh
BASH
curl -X POST "https://backend.memoair.space/v1/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-project-key" \
  -H "X-User-Id: end-user-123" \
  -d '{
    "query": "What frameworks does the user prefer?",
    "workspaceId": "ws_abc",
    "limit": 10
  }'
DELETEclient.notes.delete(id, workspace_id=...)
HTTP:DELETE /v1/notes/{id}?workspaceId=...

Delete a note source row in an authorized workspace. Source-only deletion; projection and hard erasure remain incomplete.

Parameters

idstring (path)Required

Note ID to delete from source metadata.

workspaceIdstring (query)Required

Authorized workspace that must own the note.

Example

delete_note.sh
BASH
# Source-only delete: removes the note source row.
# Does not prove projection, backup, or GDPR erasure.
curl -i -X DELETE "https://backend.memoair.space/v1/notes/note-1?workspaceId=ws_abc" \
  -H "X-API-Key: your-project-key" \
  -H "X-User-Id: end-user-123"
 
# Expect: HTTP/1.1 204 No Content
# X-MemoAir-Deletion-Scope: source-only
# X-MemoAir-Projection-Status: retained
# X-MemoAir-Erasure-Status: incomplete