> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openmem.blog/llms.txt
> Use this file to discover all available pages before exploring further.

# Run omp-server: self-hosted OMP HTTP endpoint

> omp-server is a FastAPI HTTP server that exposes the full OMP verb set over HTTP, letting any language or framework use OMP without the Python SDK.

`omp-server` is a FastAPI application that exposes the full OMP verb set as HTTP endpoints. Because it speaks the OMP protocol natively, any language or framework — not just Python — can store, search, and retrieve memories by making ordinary HTTP requests. You can also connect back to it from the Python SDK using the `passthrough` provider, which gives you a single server process shared across multiple clients or services.

## Install

```bash theme={null}
pip install 'openmem[server]'
```

## Start the server

<CodeGroup>
  ```bash Postgres backend theme={null}
  omp-server --provider postgres --url postgresql://user:pass@host:5432/db
  ```

  ```bash Mem0 backend theme={null}
  omp-server --provider mem0 --api-key $MEM0_API_KEY
  ```

  ```bash Custom host and port theme={null}
  omp-server --provider postgres --url $PG_URL --host 0.0.0.0 --port 8080
  ```
</CodeGroup>

When the server is ready, it prints a single line to stderr:

```
omp-server: serving postgres at http://127.0.0.1:8080
```

## Available routes

| Method   | Path               | Description                      |
| -------- | ------------------ | -------------------------------- |
| `POST`   | `/memories`        | Add a memory                     |
| `GET`    | `/memories`        | List memories                    |
| `GET`    | `/memories/{id}`   | Get a memory by ID               |
| `PATCH`  | `/memories/{id}`   | Update a memory                  |
| `DELETE` | `/memories/{id}`   | Delete a memory                  |
| `GET`    | `/memories/search` | Semantic and keyword search      |
| `POST`   | `/context`         | Get a prompt-ready context block |
| `GET`    | `/audit`           | Retrieve the audit log           |
| `GET`    | `/capabilities`    | Provider capabilities            |
| `GET`    | `/healthz`         | Health check                     |

## Connect using the Python SDK

Point the Python SDK at the running server using the `passthrough` provider. All standard `Memory` methods work exactly as they do against a direct adapter.

```python theme={null}
from openmem import Memory

mem = Memory(provider="passthrough", base_url="http://localhost:8080")

# All standard Memory methods work
mem.add(content="user prefers dark mode", user_id="u1")
results = mem.search("dark mode", user_id="u1")
```

The passthrough adapter probes `/capabilities` on construction. If the server returns `omp_version`, the SDK routes all calls through it as a native OMP server.

## Check server health

```bash theme={null}
curl http://localhost:8080/healthz
# {"status": "ok", "provider": "postgres"}
```

For Postgres and passthrough backends, the health check acquires and releases a real connection to confirm the backend is reachable. For Mem0, Supermemory, and Letta, it returns `200` unconditionally to avoid unnecessary calls to paid external endpoints.

## Server behavior

<Note>
  CORS is disabled by default. If you need browser clients to call the server directly, enable it with the `--cors-origins` flag:

  ```bash theme={null}
  omp-server --provider postgres --url $PG_URL \
    --cors-origins "https://app.example.com,https://staging.example.com"
  ```
</Note>

<Note>
  The default request body limit is 1 MiB. Requests larger than this limit receive a `413` response with `code: payload_too_large` before any schema validation runs. Increase the limit with `--max-request-bytes` if your use case requires larger payloads.
</Note>

## Security

<Warning>
  `omp-server` is designed for trusted-network deployment. Authentication is not yet built in — the server accepts all requests without verifying caller identity. Do not expose it directly to the public internet. Run it inside a private network or behind an authenticated reverse proxy.
</Warning>