# 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**
```json
{
  "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**
```json
{ "text": "I prefer Python over JavaScript.", "user_id": "alice" }
```

```json
{
  "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**
```json
{ "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**
```json
{ "user_id": "alice", "limit": 5 }
```

**Response**
Returns the most recent memory entries.

---

### `DELETE /memories`
Delete memories by filter.

**Request**
```json
{ "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:

```json
{
  "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).

```json
{
  "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**
```json
{ "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**
```json
{
  "query": "...",
  "documents": ["doc1", "doc2"],
  "top_k": 5
}
```

**Response**
```json
{
  "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:

```bash
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
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)