Quickstart

Add persistent memory to your AI agent in about five minutes.

Install from the public SDK repository. PyPI publishing is coming soon.

pip install "git+https://github.com/anonalabs/Anona-Memory-SDK.git"

For automatic LiteLLM injection, also install pip install litellm.

Sign up (free tier available), then:

1. Create an API key on the API Keys page.
2. Create a memory space on the Memory Spaces page.

Option A: LiteLLM callback (recommended). Two lines: every LLM call automatically recalls relevant memories and stores the exchange afterward.

import litellm
from anona.integrations.litellm import AnonaMemory

mem = AnonaMemory(
    api_key="anona_live_YOUR_KEY",
    space_id="your-space-id",
    base_url="http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com",
)
mem.enable()  # registers callback with litellm

response = litellm.completion(
    model="gemini/gemini-2.5-flash",
    messages=[{"role": "user", "content": "What should I focus on today?"}],
)
print(response.choices[0].message.content)

Option B: Direct SDK: full control over what you store and when you recall.

from anona import AnonaClient

client = AnonaClient(
    api_key="anona_live_YOUR_KEY",
    base_url="http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com",
)

# Retain: store a memory
client.add_memory(
    space_id="your-space-id",
    content="User prefers concise Python answers.",
)

# Recall: semantic search
results = client.search(
    space_id="your-space-id",
    query="what does the user prefer?",
    limit=5,
)
for r in results:
    print(r["content"])

# Reflect: synthesize insights
summary = client.insights(
    space_id="your-space-id",
    query="Summarise what you know about this user",
)
print(summary)

client.close()

Not using LiteLLM? Retrieve memories yourself and inject them before calling any LLM provider.

from anona import AnonaClient

client = AnonaClient(api_key="anona_live_YOUR_KEY", base_url="http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com")

user_message = "What should I work on today?"

memories = client.search(space_id="your-space-id", query=user_message, limit=5)
memory_block = "\n".join(f"{i+1}. {r['content']}" for i, r in enumerate(memories))

messages = []
if memory_block:
    messages.append({
        "role": "system",
        "content": f"# Relevant Memories\n{memory_block}",
    })
messages.append({"role": "user", "content": user_message})

# Send to OpenAI, Anthropic, Gemini, etc.
# response = your_llm_client.chat(messages)

# Optionally retain the exchange
# client.add_memory(space_id="your-space-id", content=f"User: {user_message}\nAssistant: {response}")

What's next

• MCP integration: connect Claude Code or Cursor
• REST API reference: full endpoint documentation
• Browse memory spaces: view stored memories
• Monitor usage: operations over time

REST API

Customer-facing HTTP API for memory operations. All endpoints require Bearer authentication and are billed per operation against your plan quota.

Authentication

Include your API key on every request:

Authorization: Bearer anona_live_YOUR_KEY

Errors

Errors return a consistent JSON shape:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "You have exceeded the rate limit. Retry after 30 seconds."
  }
}

Rate limits

Every response includes rate-limit headers:

• X-RateLimit-Limit: max requests per window
• X-RateLimit-Remaining: requests left
• X-RateLimit-Reset: window reset (Unix timestamp)

Memories & spaces

curl -s http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com/v1/spaces/ \
  -H "Authorization: Bearer anona_live_YOUR_KEY"

{
  "name": "my-agent",
  "description": "Production agent memory"
}

curl -s -X POST http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com/v1/memories \
  -H "Authorization: Bearer anona_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "your-space-id",
    "content": "User prefers Python and morning standups.",
    "metadata": { "source": "onboarding" }
  }'

curl -s -X POST http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com/v1/search \
  -H "Authorization: Bearer anona_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "your-space-id",
    "query": "What language does the user prefer?",
    "limit": 5
  }'

curl -s -X POST http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com/v1/insights \
  -H "Authorization: Bearer anona_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "your-space-id",
    "query": "What do we know about this project?"
  }'

curl -s -X POST http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com/v1/chat/completions \
  -H "Authorization: Bearer anona_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini/gemini-2.5-flash",
    "space_id": "your-space-id",
    "messages": [{"role": "user", "content": "What should I focus on today?"}]
  }'

Space members

Spaces with no member rows are treated as org-wide (any member of your org can access them). Adding a member row switches the space to enforced, invite-only access.

{
  "member_id": "mem_..."
}

Organization members

{
  "email": "teammate@company.com",
  "role": "member"
}

Organization & projects

{
  "name": "production"
}

API keys

Usage & billing

Python SDK

The SDK wraps these endpoints (see quickstart for install and usage). Method mapping:

MCP Integration

Give Claude Desktop, Claude Code, or Cursor direct access to your memory spaces via the Model Context Protocol.

Tools

The Anona MCP server exposes four tools:

Tool errors (denied space, quota exceeded) return as MCP isError content, not HTTP errors: so the transport stays intact.

Create a key on the API Keys page. Keys are scoped to your organization and can only access spaces you are a member of.

Hosted (recommended)

Point your MCP client at http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com/mcp. No local install: works with HTTP-capable clients. Authenticate with your Bearer API key.

{
  "mcpServers": {
    "anona": {
      "url": "http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com/mcp",
      "headers": {
        "Authorization": "Bearer anona_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop: add to claude_desktop_config.json and restart. Cursor: add to ~/.cursor/mcp.json and reload.

Local (stdio)

Run the MCP server on your machine via uvx. Useful when your client only supports stdio transport.

{
  "mcpServers": {
    "anona": {
      "command": "uvx",
      "args": ["--from", "anona[mcp] @ git+https://github.com/anonalabs/Anona-Memory-SDK.git", "anona-mcp"],
      "env": {
        "ANONA_API_KEY": "anona_live_YOUR_KEY",
        "ANONA_SPACE_ID": "your-space-id"
      }
    }
  }
}

MCP tools load at session start: restart your client after adding the server. Then ask your agent to remember something, or call the API directly:

curl -s http://anona-prod-alb-747552680.us-east-1.elb.amazonaws.com/mcp \
  -H "Authorization: Bearer anona_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "remember",
      "arguments": {
        "content": "User ships on Fridays.",
        "space_id": "your-space-id"
      }
    }
  }'

Protocol details

• Transport: Streamable HTTP, stateless JSON mode at POST /mcp
• Auth: Authorization: Bearer anona_live_…
• Billing: each tool call counts as an API operation against your plan

OAuth 2.1 (beta)

As an alternative to a static Bearer key, the gateway supports full OAuth 2.1 with PKCE for MCP clients that discover and authorize dynamically. Currently opt-in server-side and off by default: use the API key flow above unless your deployment has this enabled.

Access tokens are short-lived signed JWTs; authorization codes and refresh tokens are stored hashed. Refresh tokens rotate on use.