Getting started

Quick Start

Give your agent persistent memory in 3 steps. The Mnemos API is a simple REST interface, and the official Python client is installable from this repository while PyPI ownership of `mnemos` is unresolved.

Python client

The `mnemos` name on PyPI is already used by a third-party package, so install the official client from the GitHub subdirectory until ownership is transferred or the SDK is renamed.

pip install mnemos-sdk
01

Register your agent

Call POST /v1/agents/register once to create an agent and receive your API key. Save it — it's shown only once.

curl -X POST https://mnemos.nanocorp.app/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name":"My Agent"}'
02

Store a memory

Send your agent's observations, decisions, or user context to POST /v1/memory with the X-API-Key header.

curl -X POST https://mnemos.nanocorp.app/api/v1/memory \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mnm_live_..." \
  -d '{"agent_id":"agt_01HXYZ","content":"User prefers dark mode"}'
03

Recall with semantic search

Query memories using natural language. Mnemos ranks results by relevance and returns the top_k matches.

curl "https://mnemos.nanocorp.app/api/v1/memory?agent_id=agt_01HXYZ&query=user+preferences&top_k=3" \
  -H "X-API-Key: mnm_live_..."

Authentication

All endpoints except POST /v1/agents/register require authentication via the X-API-Key HTTP header. You receive this key once when registering — store it securely.

Header
X-API-Key: mnm_live_xxxxxxxxxxxxxxxxxxxxxxxx

API keys are stored as SHA-256 hashes. Mnemos cannot recover a lost key — you would need to register a new agent.

POST/v1/agents/register

Register an agent

Creates a new agent and returns a one-time API key. Store this key securely — it won't be shown again. All subsequent calls use this key via the X-API-Key header.

Request Body
namereq
stringHuman-readable name for the agent.
metadata
objectArbitrary key-value pairs attached to the agent.
curl -X POST https://mnemos.nanocorp.app/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "metadata": { "env": "production" }
  }'
Response
200 OK
{
  "agent_id": "agt_01HXYZ",
  "name": "Support Agent",
  "api_key": "mnm_live_...",
  "created_at": "2026-04-16T10:00:00Z"
}
POST/v1/memory

Store a memory

Persists a new memory for the authenticated agent. Memories are indexed for semantic retrieval and can carry structured metadata.

X-API-Key required
Request Body
agent_idreq
stringThe ID of the agent owning this memory.
contentreq
stringThe text content to remember.
metadata
objectOptional structured metadata (tags, type, source, etc.).
curl -X POST https://mnemos.nanocorp.app/api/v1/memory \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mnm_live_..." \
  -d '{
    "agent_id": "agt_01HXYZ",
    "content": "User prefers async communication.",
    "metadata": { "type": "preference" }
  }'
Response
200 OK
{
  "id": "mem_01HABC",
  "agent_id": "agt_01HXYZ",
  "content": "User prefers async communication.",
  "metadata": { "type": "preference" },
  "created_at": "2026-04-16T10:01:00Z"
}
GET/v1/memory

Retrieve memories

Fetches stored memories for an agent. Pass a natural-language query for semantic search — Mnemos returns the most relevant memories ranked by similarity.

X-API-Key required
Query Parameters
agent_idreq
stringFilter memories by agent.
query
stringSemantic search query (natural language).
top_k
integerMaximum number of results. Default: 5.
curl "https://mnemos.nanocorp.app/api/v1/memory?agent_id=agt_01HXYZ&query=communication+style&top_k=5" \
  -H "X-API-Key: mnm_live_..."
Response
200 OK
{
  "memories": [
    {
      "id": "mem_01HABC",
      "content": "User prefers async communication.",
      "metadata": { "type": "preference" },
      "created_at": "2026-04-16T10:01:00Z"
    }
  ],
  "total": 1
}
GET/v1/identity

Get agent identity

Returns the profile of the authenticated agent: name, metadata, and a safe prefix of the API key for verification. Useful for validating credentials and inspecting agent config.

X-API-Key required
curl "https://mnemos.nanocorp.app/api/v1/identity" \
  -H "X-API-Key: mnm_live_..."
Response
200 OK
{
  "agent_id": "agt_01HXYZ",
  "name": "Support Agent",
  "metadata": { "env": "production" },
  "api_key_prefix": "mnm_live_xxxx",
  "created_at": "2026-04-16T10:00:00Z"
}
Base URL: https://mnemos.nanocorp.app/api