Quick Start

From zero to your first memory stored and retrieved in under five minutes.

Step 1 — Get your API key

Create an account at app.mnemexa.com. Open the workspace, then Settings → API Keys, and create a new key. Workspace keys are prefixed with mnx_ws_.

Export it to your shell for the rest of this guide:

export MNEMEXA_API_KEY=mnx_ws_…

Step 2 — Verify the connection

Before storing anything, confirm your key works:

curl https://api.mnemexa.com/v1/status \
  -H "Authorization: Bearer $MNEMEXA_API_KEY"

You should see a 200 with your workspace identity:

{
  "workspace_id": 42,
  "workspace_name": "Acme Production",
  "workspace_status": "active",
  "plan_name": "Free",
  "billing_cycle": "monthly",
  "api_key_id": 17,
  "api_key_prefix": "mnx_ws_…",
  "healthy": true,
  "server_time": "2026-05-15T18:30:00Z"
}

If workspace_status is anything other than active, see status for what each state means.

Step 3 — Store a memory

curl -X POST https://api.mnemexa.com/v1/memory/store \
  -H "Authorization: Bearer $MNEMEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Client prefers async standups on Tuesdays at 9am IST and mandates passing tests before merging to main."
  }'

import mnemexa

client = mnemexa.Client()  # reads MNEMEXA_API_KEY from env

result = client.memory.store(
    text="Client prefers async standups on Tuesdays at 9am IST and mandates passing tests before merging to main."
)
print(result.memory_id, result.dedup.action, result.importance)

Response:

{
  "status": "ok",
  "memory_id": 8421,
  "workspace_id": 42,
  "dedup": {"action": "stored_new", "existing_id": null},
  "importance": 5,
  "categories": ["project_management", "team_workflow"],
  "temporal": {"type": "persistent", "valid_until": null}
}

What just happened: the text was PII-screened, deduplicated against existing memories, scored for importance, classified as a persistent fact, and tagged with two semantic categories — all before being committed to the vector store. See Memory Pipeline.

Step 4 — Retrieve it back

curl -X POST https://api.mnemexa.com/v1/memory/retrieve \
  -H "Authorization: Bearer $MNEMEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "communication preferences for standups", "top_k": 3}'

result = client.memory.retrieve(query="communication preferences for standups", top_k=3)
for m in result.memories:
    print(f"[score={m.score:.3f}] {m.text}")

The response ranks memories by a hybrid score (not raw cosine):

{
  "memories": [
    {
      "id": 8421,
      "text": "Client prefers async standups on Tuesdays at 9am IST…",
      "score": 0.812,
      "similarity": 0.694,
      "importance": 5,
      "meta": {"temporal": {"type": "persistent"}}
    }
  ]
}

score ≠ similarity by design — see Hybrid Scoring for the four-factor breakdown.

Step 5 — Check memory health

Periodically inspect the workspace’s overall memory quality:

curl https://api.mnemexa.com/v1/optimize/health \
  -H "Authorization: Bearer $MNEMEXA_API_KEY"

The response shows a 0–100 quality score plus signal counts (stale, duplicate, overlong, never-retrieved). See Self-Optimization.

Next steps

• AI agents: install the MCP Adapter so your agent calls brain.remember / brain.recall automatically. Works with Claude, Cursor, Windsurf, VS Code, and any MCP-compatible client.
• Backend services: use the Python SDK for typed responses, sync + async clients, and automatic retries.
• Webhooks: subscribe to workspace events (lifecycle, billing, anomalies) at Webhooks.
• Rate limits + errors: read Rate Limits and Errors before you go to production.