# Mnemo — personal memory API (agent onboarding)

Mnemo is a per-user persistent memory system: semantic vector search (bge-m3
embeddings) plus a knowledge graph. Everything below is self-serve — an agent
can sign up, authenticate, and use the API end-to-end with plain HTTP.

Base URL: https://mnemo.neuralcache.io
All bodies are JSON. Memories are strictly isolated per user account.

## 1. Create an account (once)

An invite code is REQUIRED — include "invite_code" in the signup body.
If you do not have one, ask the operator of this instance; signup without it returns 403.

    POST https://mnemo.neuralcache.io/auth/signup
    {"email": "agent@example.com", "password": "<min 8 chars>", "invite_code": "<code>"}
    -> 201 {"id": "...", "email": "..."}

## 2. Mint an API token (once, store it securely)

    POST https://mnemo.neuralcache.io/auth/token
    {"email": "agent@example.com", "password": "<password>"}
    -> 201 {"token": "mnemo_...", ...}

The raw token is shown ONCE and stored server-side only as a hash. Send it on
every request below as:  Authorization: Bearer <token>
Revoke all your tokens:  DELETE https://mnemo.neuralcache.io/auth/tokens  (same credentials body)



## 3. Memory API (Bearer auth)

    POST   https://mnemo.neuralcache.io/memory                      {"text": "...", "project"?: "...", "topic"?: "..."}
    GET    https://mnemo.neuralcache.io/memory/search?q=<query>&top_k=<1-50>
    GET    https://mnemo.neuralcache.io/memory?limit=<1-200>        (list, newest first)
    GET    https://mnemo.neuralcache.io/memory/<id>
    GET    https://mnemo.neuralcache.io/memory/<id>/related         (knowledge-graph neighbors)
    DELETE https://mnemo.neuralcache.io/memory/<id>

Write rules (server-enforced "truth-hygiene gate", HTTP 422 on rejection):
store short durable facts (>= 20 chars); never secrets/credentials/private
keys, raw transcript dumps, test junk, or chat fluff. Good example:
"decision: use bge-m3 for all new embeddings".

## 4. MCP (recommended for agents)

This server speaks MCP over Streamable HTTP at:

    https://mnemo.neuralcache.io/mcp        (Authorization: Bearer <token> required)

Tools: mnemo_add, mnemo_query, mnemo_get, mnemo_forget, mnemo_related.

Claude Code:

    claude mcp add --transport http mnemo https://mnemo.neuralcache.io/mcp \
      --header "Authorization: Bearer <token>"

Any other MCP client: transport "http" (streamable), url "https://mnemo.neuralcache.io/mcp",
header Authorization: Bearer <token>.

## Notes for agents

- 401 means your token is missing/revoked -> mint a new one (step 2).
- 422 on POST /memory means the gate rejected the text -> rephrase as a
  durable, non-sensitive fact and retry once; do not fight the gate.
- Rate limits apply to auth endpoints (HTTP 429 -> back off).
- Humans use the web dashboard at https://mnemo.neuralcache.io/ with the same accounts.