> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flumes.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Store and retrieve your first memory in less than 5 minutes.

<Steps>
  <Step title="Get an API key">
    Sign up at <a href="https://app.flumes.ai" target="_blank">app.flumes.ai</a> and grab your **secret key** from the dashboard.
  </Step>

  <Step title="Assemble context for a turn (optionally ingest)">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -s https://api.flumes.ai/v0/context/assemble \
        -H "Authorization: Bearer $FLUMES_API_KEY" \
        -H "Content-Type: application/json" \
        -H "X-Flumes-Agent: demo" \
        -H "Idempotency-Key: $(uuidgen)" \
        -d '{
          "entity_id": "ent:user_123",
          "turn": "I want to go to Rome in July. Any museum tips?",
          "retrieval": { "preset": "balanced" },
          "ingest": { "extract": false },
          "return": {
            "include_structured_facts": true,
            "include_raw_matches": true,
            "include_scores": true
          },
          "max_context_tokens": 1200
        }'
      ```

      ```javascript Node.js theme={null}
      const res = await fetch("https://api.flumes.ai/v0/context/assemble", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.FLUMES_API_KEY}`,
          "Content-Type": "application/json",
          "X-Flumes-Agent": "demo",
          "Idempotency-Key": crypto.randomUUID(),
        },
        body: JSON.stringify({
          entity_id: "ent:user_123",
          turn: "I want to go to Rome in July. Any museum tips?",
          retrieval: { preset: "balanced" },
          ingest: { extract: false },
          return: { include_structured_facts: true, include_raw_matches: true, include_scores: true },
          max_context_tokens: 1200
        }),
      });
      console.log(await res.json());
      ```

      ```python Python theme={null}
      import os, requests, uuid

      resp = requests.post(
        "https://api.flumes.ai/v0/context/assemble",
        headers={
          "Authorization": f"Bearer {os.getenv('FLUMES_API_KEY')}",
          "Content-Type": "application/json",
          "X-Flumes-Agent": "demo",
          "Idempotency-Key": str(uuid.uuid4()),
        },
        json={
          "entity_id": "ent:user_123",
          "turn": "I want to go to Rome in July. Any museum tips?",
          "retrieval": { "preset": "balanced" },
          "ingest": { "extract": False },
          "return": { "include_structured_facts": True, "include_raw_matches": True, "include_scores": True },
          "max_context_tokens": 1200,
        },
      )
      print(resp.json())
      ```
    </CodeGroup>
  </Step>

  <Step title="Recall explicitly (optional)">
    ```bash theme={null}
    curl -s https://api.flumes.ai/v0/recall \
      -H "Authorization: Bearer $FLUMES_API_KEY" \
      -H "Content-Type": "application/json" \
      -d '{
        "query": "museums in Rome",
        "entity_id": "ent:user_123",
        "return": { "include_structured_facts": true, "include_scores": true },
        "limit": 8
      }'
    ```
  </Step>
</Steps>

<Check>
  That’s it! You now have a persistent memory layer for your app. Explore the auto-generated [API](/api) to dive deeper.
</Check>

<Details>
  <Summary>Example assemble response (trimmed)</Summary>

  ```json theme={null}
  {
    "context": {
      "facts_struct": [
        {
          "memory_id": "mem_123",
          "type": "fact",
          "subject": "ent:user_123",
          "predicate": "likes_city",
          "object_text": "Rome",
          "confidence": 0.86,
          "score": 0.72,
          "tags": ["preference"],
          "provenance": {"source_turn": "mem_turn_1"}
        }
      ],
      "recent_events": [
        "Chatted about Rome museums"
      ],
      "summary": "User plans a July trip to Rome; recommend major museums and ticketing tips.",
      "sources": ["mem_abc", "mem_def"],
      "token_counts": {"planned": 980, "budget": 1200, "dropped": 120},
      "budget_actions": [
        {"action": "drop_low_score", "memory_id": "mem_xyz", "notes": "below threshold"}
      ]
    },
    "trace": {"summary": {"origin": "assembler"}},
    "retrieval_summary": {"weights_used": {"semantic": 0.45, "bm25": 0.25}},
    "flags": {"weights_renormalized": false},
    "request_id": "req_123"
  }
  ```
</Details>