Memory quickstart

End-to-end: write a memory, search it, inspect the entity, replay history. Assumes the backend is up and you have a service-role apikey for one tenant.

0. Prerequisites

• Nubase backend running on :9999
• Tenant provisioned via POST /auth/v1/admin/init/database
• OPENAI_API_KEY (or Anthropic / DashScope key) set in the backend env
• An export NUBASE_SERVICE_KEY="eyJ…" with the project's service_role JWT

1. Write a memory

Pass conversation messages. The LLM extracts facts and the entities they reference in one call.

curl -X POST http://localhost:9999/mem/v1/memories \
  -H "apikey: $NUBASE_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-42",
    "messages": [
      { "role": "user",
        "content": "Hi, I am John. I work at Anthropic and my dog is named Mochi." }
    ]
  }'

{
  "results": [
    { "id": "…", "event": "ADD", "memory": "Name is John" },
    { "id": "…", "event": "ADD", "memory": "Works at Anthropic" },
    { "id": "…", "event": "ADD", "memory": "Has a dog named Mochi" }
  ]
}

2. Search

Multi-signal: vector cosine, BM25 keyword, and entity boost (the LLM extracts entities from the query if entity-boost-enabled).

curl -X POST http://localhost:9999/mem/v1/search \
  -H "apikey: $NUBASE_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-42",
    "query": "tell me about Mochi",
    "topK": 3
  }'

{
  "results": [
    { "id": "…", "memory": "Has a dog named Mochi", "score": 0.94 },
    { "id": "…", "memory": "Name is John",          "score": 0.42 }
  ]
}

3. Update — let the LLM decide

Send a contradicting fact; the decision LLM emits UPDATE with the old memory's id.

curl -X POST http://localhost:9999/mem/v1/memories \
  -H "apikey: $NUBASE_SERVICE_KEY" \
  -d '{
    "userId": "user-42",
    "messages": [{ "role": "user",
                   "content": "I actually moved to OpenAI last month." }]
  }'
# → {"results":[{"id":"<orig>","event":"UPDATE",
#                "memory":"Works at OpenAI",
#                "previousMemory":"Works at Anthropic"}]}

4. Inspect history

curl http://localhost:9999/mem/v1/memories/<id>/history \
  -H "apikey: $NUBASE_SERVICE_KEY"
# → [
#    {"event":"ADD",    "newValue":"Works at Anthropic", "createdAt":"…"},
#    {"event":"UPDATE", "oldValue":"Works at Anthropic",
#                       "newValue":"Works at OpenAI",    "createdAt":"…"}
#   ]

5. Browse entities

curl "http://localhost:9999/mem/v1/entities?userId=user-42&type=person" \
  -H "apikey: $NUBASE_SERVICE_KEY"
# → { "items":[
#       {"text":"John", "entityType":"person",
#        "linkedMemoryIds":["…"]}
#     ], "total":1, "page":1, "pageSize":25 }

6. Or use the Studio UI

Everything above is available in Studio under the Memory tab: list with stats, search, edit, history, entities, settings. No curl required for day-to-day inspection.

From your app

Use the same two-layer auth model as the rest of nubase:

• Server-to-server (admin): send the tenant's service_role JWT as apikey. You can write/read for any userId.
• End user: send the tenant's anon/authenticated apikey plus the user's Bearer JWT. The body's userId is forced to match sub — there's no way for one user to read another's memories.