Skip to main content

​
Quickstart

This page follows the current memorose-server API directly.

​
What you need

  • a running Memorose server on http://127.0.0.1:3000
  • dashboard credentials
  • jq
  • uuidgen
In the current single-node default setup, Memorose auto-initializes Raft at startup. You do not need to call /v1/cluster/initialize before sending writes unless you intentionally disabled raft.auto_initialize.

​
The happy path

  1. Log in and get a bearer token.
  2. Create a stream ID.
  3. Ingest one event.
  4. Retrieve against that stream.
  5. Check whether consolidation backlog is clear.

​
1. Set base variables

export BASE_URL="http://127.0.0.1:3000"
export USER_ID="dylan"
export ORG_ID="default"

​
2. Log in and get a token

Current /v1 routes accept either a dashboard JWT bearer token or an API key. For local development, the dashboard login is the fastest path. 
TOKEN=$(curl -s -X POST "$BASE_URL/v1/dashboard/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin"
  }' | jq -r '.token')

​
3. Create a stream ID

STREAM_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')

​
4. Ingest an event

curl -s -X POST "$BASE_URL/v1/users/$USER_ID/streams/$STREAM_ID/events" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "default",
    "content": "Dylan prefers Rust for systems work and wants concise status updates.",
    "content_type": "text"
  }'
Expected response shape: 
{
  "status": "accepted",
  "event_id": "..."
}

​
5. Retrieve memory

curl -s -X POST "$BASE_URL/v1/users/$USER_ID/streams/$STREAM_ID/retrieve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "default",
    "query": "What does Dylan prefer for systems work?",
    "limit": 5,
    "graph_depth": 1
  }'
Expected response shape: 
{
  "stream_id": "...",
  "query": "What does Dylan prefer for systems work?",
  "results": [
    {
      "unit": {
        "id": "...",
        "memory_type": "factual",
        "content": "...",
        "keywords": ["rust", "systems"],
        "level": 1
      },
      "score": 0.9
    }
  ],
  "query_time_ms": 12
}
Important response fields:
  • results[].unit.level: where the retrieved memory sits in the hierarchy
  • results[].unit.memory_type: factual or procedural
  • score: final ranking score after retrieval fusion
  • query_time_ms: observed server-side latency for the retrieval call

​
6. Check consolidation backlog

curl -s "$BASE_URL/v1/status/pending" \
  -H "Authorization: Bearer $TOKEN"
When "ready": true, the current pending-event backlog is clear.

​
Where to go next