API Reference

Base URL

https://api.memoid.dev

Authentication

All API requests require authentication via Bearer token:

curl -H "Authorization: Bearer YOUR_API_KEY" 
  https://api.memoid.dev/v1/memories

Get your API key from the dashboard.

---

Memories

Add Memories

Extract and store memories from conversations.

POST /v1/memories

Request Body

Field	Type	Required	Description
messages	array	Yes	Conversation messages with role and content
user_id	string	One required	User identifier
agent_id	string	One required	Agent identifier
run_id	string	One required	Run/session identifier
project_id	string	No	Project identifier
metadata	object	No	Custom key-value pairs
infer	boolean	No	Extract facts automatically (default: true)
extract_graph	boolean	No	Extract entities to graph (default: false)

Example

curl -X POST https://api.memoid.dev/v1/memories 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "messages": [
      {"role": "user", "content": "I love hiking and Italian food"},
      {"role": "assistant", "content": "Great! I will remember that."}
    ],
    "user_id": "user_123"
  }'

Response

{
  "results": [
    {
      "id": "mem_abc123",
      "memory": "User loves hiking",
      "event": "ADD"
    },
    {
      "id": "mem_abc124",
      "memory": "User loves Italian food",
      "event": "ADD"
    }
  ]
}

---

List Memories

GET /v1/memories

Query Parameters

Parameter	Type	Required	Description
user_id	string	One required	Filter by user
agent_id	string	One required	Filter by agent
run_id	string	One required	Filter by run
project_id	string	One required	Filter by project

Example

curl "https://api.memoid.dev/v1/memories?user_id=user_123" 
  -H "Authorization: Bearer YOUR_API_KEY"

---

Get Memory

GET /v1/memories/:id

---

Update Memory

PUT /v1/memories/:id

Request Body

Field	Type	Required	Description
text	string	Yes	New memory text
metadata	object	No	Updated metadata

---

Delete Memory

DELETE /v1/memories/:id

---

Delete All Memories

DELETE /v1/memories

Query Parameters

At least one filter is required: user_id, agent_id, run_id, or project_id.

---

Memory History

GET /v1/memories/:id/history

Returns change history for a memory including ADD, UPDATE, and DELETE events.

---

Search

Search Memories

POST /v1/search

Request Body

Field	Type	Required	Default	Description
query	string	Yes	-	Natural language search
user_id	string	No	-	Filter by user
agent_id	string	No	-	Filter by agent
run_id	string	No	-	Filter by run
project_id	string	No	-	Filter by project
limit	int	No	100	Maximum results
threshold	float	No	0.7	Minimum similarity (0-1)
filters	object	No	-	Metadata filters

Example

curl -X POST https://api.memoid.dev/v1/search 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "query": "What food does the user like?",
    "user_id": "user_123",
    "limit": 5
  }'

Response

{
  "results": [
    {
      "id": "mem_abc123",
      "memory": "User loves Italian food",
      "score": 0.92,
      "user_id": "user_123"
    }
  ]
}

---

Batch Operations

Batch Update

PUT /v1/batch

Request Body

{
  "memories": [
    {"memory_id": "mem_123", "text": "Updated text"},
    {"memory_id": "mem_456", "text": "Another update"}
  ]
}

---

Batch Delete

DELETE /v1/batch

Request Body

{
  "memories": [
    {"memory_id": "mem_123"},
    {"memory_id": "mem_456"}
  ]
}

---

Projects

Create Project

POST /v1/projects

Request Body

Field	Type	Required	Description
name	string	Yes	Project name

---

List Projects

GET /v1/projects

---

Get Project

GET /v1/projects/:id

---

Update Project

PATCH /v1/projects/:id

Request Body

Field	Type	Description
name	string	Project name
custom_instructions	string	Custom extraction instructions
custom_categories	array	Custom memory categories

---

Delete Project

DELETE /v1/projects/:id

---

Webhooks

Create Webhook

POST /v1/projects/:id/webhooks

Request Body

Field	Type	Required	Description
name	string	Yes	Webhook name
url	string	Yes	Webhook endpoint URL
event_types	array	Yes	Events to trigger on

Event Types: memory.created, memory.updated, memory.deleted

---

List Webhooks

GET /v1/projects/:id/webhooks

---

Delete Webhook

DELETE /v1/projects/:id/webhooks/:webhook_id

---

Entities

List Entities

GET /v1/entities

Returns all users/agents that have memories.

---

Delete Entity

DELETE /v2/entities/:type/:id

Delete all memories for an entity. Currently only user type is supported.

---

Knowledge Graph

Graph endpoints require Dgraph to be enabled.

Add Entity

POST /v1/graph/entities

List Entities

GET /v1/graph/entities

Get Entity

GET /v1/graph/entities/:name

Delete Entity

DELETE /v1/graph/entities/:name

Add Relationship

POST /v1/graph/relationships

List Relationships

GET /v1/graph/relationships

Delete Relationship

DELETE /v1/graph/relationships

Query Graph

POST /v1/graph/query

Search Graph

POST /v1/graph/search

Extract Knowledge

POST /v1/graph/extract

See Graph API for detailed documentation.

---

Health Checks

API Health

GET /health

Returns {"status": "ok"} if the API is running.

LLM Health

GET /health/llm

Tests connection to the LLM provider (Gemini/OpenAI).

Graph Health

GET /health/graph

Tests connection to Dgraph (if enabled).

---

Error Responses

All errors return JSON with a message field:

{
  "message": "unauthorized"
}

HTTP Status Codes

Code	Description
200	Success
400	Bad request - invalid parameters
401	Unauthorized - invalid API key
404	Not found
500	Server error

---

Rate Limits

Plan	Requests/minute
Free	60
Pro	600
Enterprise	Unlimited

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1705320000