mem0-python-server/API.md

API Reference — mem0-python-server

This document defines the REST surface for mem0-python-server. All endpoints return JSON and use UTF‑8.

GET /health

Returns server status, active collection names, and a preview of each extraction prompt.

Response

{
  "status": "ok",
  "reranker_url": "http://192.168.0.200:5200/rerank",
  "collections": {
    "conversational": "openclaw_mem",
    "knowledge": "knowledge_mem"
  },
  "prompts": {
    "conversational": "You are a personal memory assistant…",
    "knowledge": "You are a knowledge extraction assistant…"
  }
}

---

/memories — conversational collection (OpenClaw)

POST /memories

Add a memory. Accepts plain text or a messages array.

Request

{ "text": "I prefer Python over JavaScript.", "user_id": "alice" }

{
  "messages": [{"role": "user", "content": "I've used Vim for 10 years."}],
  "user_id": "alice"
}

Response Returns the mem0 add response with the created memory payload.

---

POST /memories/search

Search with reranking. Fetches limit × 3 candidates, reranks locally, returns top limit.

Request

{ "query": "editor preferences", "user_id": "alice", "limit": 5 }

Response Returns a list of memories with an added rerank_score field.

---

POST /memories/recent

Return the most recently created memories for a user.

Request

{ "user_id": "alice", "limit": 5 }

Response Returns the most recent memory entries.

---

DELETE /memories

Delete memories by filter.

Request

{ "filter": { "user_id": "alice" } }

Response Returns deletion metadata from the underlying mem0 store.

---

/knowledge — knowledge collection (book-ingestor)

Same shape as /memories with two additions:

metadata

Arbitrary key/value dict stored alongside the memory. Useful for provenance tagging:

{
  "text": "Silvio Gesell proposed demurrage to discourage currency hoarding.",
  "user_id": "knowledge_base",
  "metadata": { "source_file": "gesell_neo.pdf", "chapter": 3, "page": 47 }
}

infer: false

Bypasses LLM extraction and stores the text verbatim (best for pre‑summarised chunks).

{
  "text": "MIDI SysEx messages use a 7-bit checksum.",
  "user_id": "knowledge_base",
  "infer": false,
  "metadata": { "source_file": "midi_spec.pdf", "chapter": 9, "page": 112 }
}

Endpoints

• POST /knowledge
• POST /knowledge/search
• POST /knowledge/recent
• DELETE /knowledge

Each route uses the same request/response shape as its /memories counterpart.

---

POST /search — merged search (both collections)

Queries both collections simultaneously, tags each result with _source, then runs a single rerank pass over the merged pool.

Request

{ "query": "Gesell economic theory", "user_id": "knowledge_base", "limit": 8 }

Response Each result includes "_source": "conversational" or "_source": "knowledge".

---

Reranker contract

The server expects a reranker at RERANKER_URL accepting:

Request

{
  "query": "...",
  "documents": ["doc1", "doc2"],
  "top_k": 5
}

Response

{
  "results": [
    { "text": "doc1", "score": 0.99 },
    { "text": "doc2", "score": 0.87 }
  ]
}

If the reranker is unreachable, the server falls back to raw mem0 results without error.

---

Resetting a collection

reset_memory.py deletes and recreates a collection via the Chroma HTTP API, then restarts the mem0server container:

python reset_memory.py openclaw_mem   # wipe conversational
python reset_memory.py knowledge_mem  # wipe knowledge

---

Testing

tests.sh exercises every endpoint. Run it after server changes:

bash tests.sh

Suggested checks:

• /knowledge/search query "Gesell demurrage" → Gesell result ranked #1, MIDI near the bottom
• /knowledge/search query "free money currency hoarding" → Gesell rerank_score > 0.9, MIDI < 0.001
• /search results include _source on every item
• infer: false stores text verbatim (not rewritten)