API Reference v0.23.0

MemDB REST API for storing, searching, and managing agent memories. All endpoints require Bearer token authentication.

https://api.memdb.ai

Interactive API Reference →

Full API spec

docs/API.md on GitHub

Claude integrations

Code plugin · MCP · memory_20250818 adapter

Python adapter v0.1.0

memdb-claude-memory-tool repo

Authentication

All requests (except GET /health) require a Bearer token in the Authorization header.

Authorization: Bearer sk-memdb-xxxx

curl https://api.memdb.ai/health

curl https://api.memdb.ai/product/search \
  -H "Authorization: Bearer sk-memdb-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"agent-1","query":"preferences"}'

Endpoints

GET /health POST /product/add POST /product/search POST /product/delete_memory POST /product/get_all POST /product/get_memory GET /product/get_memory/{memory_id} POST /product/get_memory_by_key POST /product/list_memories_by_prefix POST /product/chat/complete POST /product/chat/stream POST /product/feedback

Health Check

GET/health

No authentication required. Returns service status, Go version, and hostname.

Example

{"code":200,"status":"healthy","go_version":"go1.26","hostname":"memdb-go","service":"memdb-go"}

Add Memories

POST/product/add

Store new memories from conversations or raw text. MemDB extracts entities, classifies memory types, deduplicates, and persists asynchronously by default.

Request Body

Field	Type	Description
user_id	string	User/agent identifier
messages *	array	Messages: `[{"role":"user","content":"..."}]`
custom_tags	string[]	Tags for filtering: `["preference","style"]`
async_mode	string	`"async"` (default) or `"sync"`
mode	string	`"raw"` (store as-is) or `"fast"` (LLM extraction). Sync only.
session_id	string	Group memories by session
info	object	Metadata: `{"agent_id":"...", "source_type":"web"}`

Example

curl -X POST https://api.memdb.ai/product/add \
  -H "Authorization: Bearer sk-memdb-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"agent-123","messages":[{"role":"user","content":"I prefer bullet points"}],"custom_tags":["preference"]}'

Search Memories

POST/product/search

Hybrid search: HNSW vector + tsvector fulltext, merged via RRF, with temporal decay and optional LLM reranking. 1.7ms cached, ~350ms uncached.

Request Body

Field	Type	Description
user_id *	string	User/agent identifier
query *	string	Natural language search query
top_k	int	Number of memories to return (default: 10)
mode	string	`"fast"` (default), `"fine"` (LLM filter + recall hint)
dedup	string	`"no"`, `"sim"`, or `"mmr"`
include_preference	bool	Include preference memories (default: true)
include_skill_memory	bool	Include skill memories (default: true)
internet_search	bool	Search web via SearXNG (default: false)
filter	object	Structured filter: `{"and":[{"created_at":{"gt":"2024-01-01"}}]}`
relativity	float	Minimum relevance threshold (0 = disabled)

Example

curl -X POST https://api.memdb.ai/product/search \
  -H "Authorization: Bearer sk-memdb-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"agent-123","query":"How does this user prefer responses?","top_k":5}'

Delete Memories

POST/product/delete_memory

Delete specific memories by ID, or all memories for a user. Instant — no reindex needed.

Request Body

Field	Type	Description
user_id *	string	User/agent identifier
memory_ids	string[]	IDs to delete: `["mem_abc","mem_def"]`
delete_all	bool	Delete all memories for this user

Example

curl -X POST https://api.memdb.ai/product/delete_memory \
  -H "Authorization: Bearer sk-memdb-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"agent-123","memory_ids":["mem_abc123","mem_def456"]}'

Get All Memories

POST/product/get_all

Retrieve all memories for a user with pagination. 70× faster than the Python baseline.

Request Body

Field	Type	Description
user_id *	string	User/agent identifier
page	int	Page number (default: 1)
page_size	int	Results per page (default: 20)

Get Memories

POST/product/get_memory

Retrieve memories matching specific criteria.

Request Body

Field	Type	Description
user_id *	string	User/agent identifier
filter	object	Structured filter

Get Memory by ID

GET/product/get_memory/{memory_id}

Retrieve a single memory by its ID.

Get Memory by Key

POST/product/get_memory_by_key

Look up a single memory by user_id + opaque key. O(1) keyed lookup, used by the Anthropic memory_20250818 adapter for stable per-conversation slots.

Request Body

Field	Type	Description
user_id *	string	User/agent identifier
key *	string	Opaque key (e.g. `"conversation:abc123"`)

Example

curl -X POST https://api.memdb.ai/product/get_memory_by_key \
  -H "Authorization: Bearer sk-memdb-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"agent-123","key":"conversation:abc123"}'

List Memories by Prefix

POST/product/list_memories_by_prefix

List all memories whose key starts with the given prefix. Used by the Anthropic memory adapter to enumerate slots under a namespace (e.g. all turns of a conversation).

Request Body

Field	Type	Description
user_id *	string	User/agent identifier
prefix *	string	Key prefix (e.g. `"conversation:"`)
limit	int	Max results (default: 100)

Example

curl -X POST https://api.memdb.ai/product/list_memories_by_prefix \
  -H "Authorization: Bearer sk-memdb-xxxx" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"agent-123","prefix":"conversation:","limit":50}'

Chat Complete

POST/product/chat/complete

Memory-augmented chat completion. Searches relevant memories and injects them into LLM context.

Request Body

Field	Type	Description
user_id *	string	User/agent identifier
messages *	array	Chat messages: `[{"role":"user","content":"..."}]`
system_prompt	string	System prompt override
add_message_on_answer	bool	Store exchange after completion (default: false)

Chat Stream

POST/product/chat/stream

Same as Chat Complete but returns SSE stream for real-time UIs.

Feedback

POST/product/feedback

Submit feedback on a memory to improve future search ranking.

Request Body

Field	Type	Description
user_id *	string	User/agent identifier
memory_id *	string	Memory to rate
feedback	string	`"positive"` or `"negative"`