# https://github.com/memodb-io/memobase Project Manual

Generated at: 2026-06-24 08:05:42 UTC

## Table of Contents

- [Memobase Overview and System Architecture](#page-1)
- [Backend Server: FastAPI, Controllers, and Data Models](#page-2)
- [Client SDKs: Python, TypeScript, and Go](#page-3)
- [MCP Server, Deployment, and Customization](#page-4)

<a id='page-1'></a>

## Memobase Overview and System Architecture

### Related Pages

Related topics: [Backend Server: FastAPI, Controllers, and Data Models](#page-2), [Client SDKs: Python, TypeScript, and Go](#page-3), [MCP Server, Deployment, and Customization](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)
- [src/server/api/readme.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/readme.md)
- [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md)
- [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md)
- [src/server/api/memobase_server/__init__.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/__init__.py)
- [src/server/api/memobase_server/prompts/extract_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/extract_profile.py)
- [src/server/api/memobase_server/prompts/organize_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/organize_profile.py)
- [src/server/api/memobase_server/prompts/merge_profile_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/merge_profile_yolo.py)
- [src/server/api/memobase_server/prompts/pick_related_profiles.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/pick_related_profiles.py)
- [src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py)
</details>

# Memobase Overview and System Architecture

## 1. Project Purpose and Design Goals

Memobase is a **user profile-based memory system** that brings long-term user memory to LLM applications such as virtual companions, educational tools, and personalized assistants. The system enables an AI to remember, understand, and evolve with its users by maintaining a structured user profile and a per-user event timeline (Source: [readme.md:39-44]()).

The project is intentionally optimized against three competing metrics that are typically hard to satisfy together:

- **Performance** — Memobase achieves top-tier retrieval in the LOCOMO benchmark even though it is not built primarily as a RAG/search engine.
- **LLM Cost** — A built-in per-user buffer batches incoming chats so the per-message overhead is amortized. Workflows and prompts are hand-tuned to avoid "agent" loops. As of `0.0.40`, a single flush now performs a fixed three LLM calls (down from 3–10), reducing token cost by ~40–50%.
- **Latency** — Because a user profile and an event timeline are always precomputed, the online read path is a handful of SQL operations that complete in under 100 ms.

Source: [readme.md:44-58](), [readme.md:23-25]()

## 2. High-Level System Architecture

Memobase is delivered as a FastAPI backend with versioned endpoints under `/api/v1`, an auxiliary MCP server that exposes the same memory features to AI agents, and a Python SDK consumed by client applications (Source: [src/server/api/readme.md:3-9](), [src/mcp/README.md:24-32]()).

```mermaid
graph TD
    Client[Client App / AI Agent] --> SDK[Memobase Python SDK]
    Client --> MCP[MCP Server]
    SDK --> API[FastAPI /api/v1]
    MCP --> API
    API --> Auth[Auth Middleware]
    API --> Ctrls[Controllers]
    Ctrls --> UserCtrl[user]
    Ctrls --> BlobCtrl[blob]
    Ctrls --> BufferCtrl[buffer]
    Ctrls --> ProfileCtrl[profile]
    Ctrls --> ModalCtrl[modal / chat]
    UserCtrl --> DB[(PostgreSQL)]
    BlobCtrl --> DB
    BufferCtrl --> DB
    ProfileCtrl --> DB
    ProfileCtrl --> Cache[(Redis)]
    ModalCtrl --> LLM[LLM Service]
    LLM --> Prompts[Prompt Templates]
```

The control plane routes every request through FastAPI middleware for authentication, then dispatches to one of the five controller groups. Persisted state lives in PostgreSQL while ephemeral state and caches are served by Redis. Memory-formation work is delegated to a "modal" layer that calls the LLM service using versioned prompt templates (Source: [src/server/api/DEVELOPMENT.md:9-26]()).

## 3. Core Components and Data Model

The backend code is organized under `memobase_server/` and is split into three layers (Source: [src/server/api/DEVELOPMENT.md:28-47]()):

| Layer | Module | Responsibility |
|---|---|---|
| API | `api.py` | FastAPI routes, auth middleware, `/api/v1` versioning |
| Controllers | `user`, `blob`, `buffer`, `profile`, `modal` | Business logic for each domain |
| Models | `database.py`, `blob.py`, `response.py`, `utils.py` | SQLAlchemy ORM, blob schema, Promise pattern |
| Connectors | `connectors.py` | PostgreSQL/Redis pools, health checks |
| LLM | `llms` | Model provider adapters, prompt loading |

The persisted data model is intentionally compact: `User`, `GeneralBlob`, `BufferZone`, and `UserProfile`. `GeneralBlob` is polymorphic and can carry any of the supported content kinds listed in the table below (Source: [src/server/api/readme.md:11-30]()).

| Blob Type | Intended Use |
|---|---|
| Chat | Conversations between the user and an assistant |
| Document | Long-form text ingested for memory extraction |
| Image | Visual content associated with a user |
| Code | Snippets saved by developers building agents |
| Transcript | Audio/video transcripts of user interactions |

The modal layer wraps the LLM calls that turn blobs into structured profiles. As of `__version__ = "0.0.42"`, the modal chat pipeline consists of three LLM invocations: profile extraction, sub-topic organization, and YOLO-style profile merging (Source: [src/server/api/memobase_server/__init__.py:1](), [src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py:1-35]()).

## 4. Memory Processing Workflow

The end-to-end flow is designed to keep online reads cheap while pushing all heavy work to a batched background flush:

1. **Insert** — A client pushes messages into the user's `BufferZone` via the `blob` and `buffer` controllers. No LLM is invoked yet.
2. **Flush (modal processing)** — On a trigger, the modal layer runs the three-stage LLM pipeline:
   - **Extract** — `extract_profile.py` emits `TOPIC{tab}SUB_TOPIC{tab}MEMO` rows from raw text, guided by topic guidelines and few-shot examples.
   - **Organize** — `organize_profile.py` re-clusters memos under no more than `max_subtopics` sub-topics per topic.
   - **Merge (YOLO)** — `merge_profile_yolo.py` / `merge_yolo.py` decide for each existing memo whether to `UPDATE`, `APPEND`, or `ABORT`, preserving any `[mentioned on ...]` time annotations.
3. **Store** — The resulting structured rows are written into `UserProfile` and the latest events into the user timeline.
4. **Read** — A `context(max_token_size=…, prefer_topics=[…])` call renders a prompt-ready string in milliseconds, optionally filtering by topic or running `pick_related_profiles.py` to select only relevant memos for a given conversation.

Sources: [src/server/api/memobase_server/prompts/extract_profile.py:3-58](), [src/server/api/memobase_server/prompts/organize_profile.py:30-72](), [src/server/api/memobase_server/prompts/merge_profile_yolo.py:1-26](), [src/server/api/memobase_server/prompts/pick_related_profiles.py:60-88]()

The same features are exposed to MCP-compatible agents through three tools — `save_memory`, `get_user_profiles`, and `search_memories` — so a tool-using LLM can persist and recall context against a Memobase backend in the same way a developer would via the SDK (Source: [src/mcp/README.md:38-43]()).

## See Also

- [Memobase Profile Customization](https://docs.memobase.io/features/profile/profile)
- [Memobase-Playground (full-stack chatbot template)](https://github.com/memodb-io/memobase-playground)
- [Memobase-Inspector (web UI for project inspection)](https://github.com/memodb-io/memobase-inspector)
- [LOCOMO Benchmark Results](./docs/experiments/locomo-benchmark)

---

<a id='page-2'></a>

## Backend Server: FastAPI, Controllers, and Data Models

### Related Pages

Related topics: [Memobase Overview and System Architecture](#page-1), [Client SDKs: Python, TypeScript, and Go](#page-3), [MCP Server, Deployment, and Customization](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/server/api/api.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/api.py)
- [src/server/api/memobase_server/api_layer/user.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/user.py)
- [src/server/api/memobase_server/api_layer/blob.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/blob.py)
- [src/server/api/memobase_server/api_layer/buffer.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/buffer.py)
- [src/server/api/memobase_server/api_layer/profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/profile.py)
- [src/server/api/memobase_server/api_layer/context.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/context.py)
- [src/server/api/memobase_server/api_layer/roleplay.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/roleplay.py)
- [src/server/api/memobase_server/api_layer/chore.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/chore.py)
- [src/server/api/memobase_server/api_layer/middleware.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/middleware.py)
- [src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py)
- [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md)
- [src/server/api/readme.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/readme.md)
</details>

# Backend Server: FastAPI, Controllers, and Data Models

## 1. Purpose and High-Level Role

The Memobase backend is a FastAPI server that provides persistent user-memory services for LLM applications. According to [src/server/api/readme.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/readme.md), it exposes versioned endpoints under `/api/v1` and centralizes four concerns: user identity, raw data blobs, a transient processing buffer, and the extracted user profile that downstream clients retrieve to enrich conversations.

The server is structured into four cooperating layers:

- **API layer** — FastAPI route handlers that parse requests and return `BaseResponse` objects.
- **Controllers** — Business logic that orchestrates database, Redis, and LLM operations.
- **Models** — SQLAlchemy ORM entities and Pydantic-style response/dataclass types.
- **Connectors** — Connection pools for PostgreSQL and Redis, plus LLM/embedding clients.

Source: [src/server/api/readme.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/readme.md), [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md)

## 2. Request Lifecycle and Middleware

Every incoming HTTP request flows through `global_wrapper_middleware` before reaching a route handler. The middleware ([src/server/api/memobase_server/api_layer/middleware.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/middleware.py)) performs several cross-cutting tasks:

1. Generates or reads the `X-Request-ID` header and binds it to `structlog` context.
2. Resolves `project_id` from the bearer token via `parse_project_id` and `check_project_secret` from `auth/token.py`.
3. Records a per-project counter and latency histogram through `telemetry_manager`.
4. Maps the matched path against `PATH_MAPPINGS` to decide which business counters to increment.
5. Catches unhandled exceptions and returns a `JSONResponse` with the framework `CODE` enum.

Health and admin endpoints live alongside business routes in `chore.py` ([src/server/api/memobase_server/api_layer/chore.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/chore.py)). `healthcheck()` verifies PostgreSQL via `db_health_check`, Redis via `redis_health_check`, embedding sanity via `check_embedding_sanity`, and LLM reachability via `llm_sanity_check`. `root_running_status_check()` is restricted to the `DEFAULT_PROJECT_ID` and rejects other callers with HTTP 405.

```mermaid
sequenceDiagram
    participant Client
    participant Middleware
    participant API Route
    participant Controller
    participant DB/Redis/LLM

    Client->>Middleware: HTTP request + bearer token
    Middleware->>Middleware: parse_project_id, structlog bind, telemetry
    Middleware->>API Route: Forward with request.state.memobase_project_id
    API Route->>Controller: controllers.user/blob/buffer/profile
    Controller->>DB/Redis/LLM: CRUD + LLM calls
    Controller-->>API Route: Promise[result]
    API Route-->>Middleware: BaseResponse / IdResponse / typed payload
    Middleware-->>Client: JSON + X-Request-ID
```

## 3. API Layer: Route Handlers

Route handlers are thin adapters that read `project_id` from `request.state`, call into `controllers.full`, and convert the resulting `Promise` to a typed response via `.to_response(...)`. The user routes ([src/server/api/memobase_server/api_layer/user.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/user.py)) cover the full CRUD lifecycle:

| Endpoint group | Representative operations | Source |
| --- | --- | --- |
| `/users` | `create_user`, `get_user`, `update_user`, `delete_user` | [api_layer/user.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/user.py) |
| `/blobs` | `insert_blob`, `get_blob`, `list_blob_ids`, `delete_blob` | [api_layer/blob.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/blob.py) |
| `/users/buffer` | `flush_buffer`, `buffer_status` for batched processing | [api_layer/buffer.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/buffer.py) |
| `/users/profile` | Read / patch / overwrite user profile entries | [api_layer/profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/profile.py) |
| `/users/context` | Build a prompt-ready context block for an LLM | [api_layer/context.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/context.py) |
| `/users/event` | Append and list timeline events | [api_layer/roleplay.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/roleplay.py) |

The roleplay surface ([src/server/api/memobase_server/api_layer/roleplay.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/roleplay.py)) extends profile reads with parameters such as `prefer_topics`, `only_topics`, `max_subtopic_size`, and a `topic_limits_json` override that are forwarded to `proactive_topics` inside `controllers.modal.roleplay`. The Go SDK mirrors these surfaces through `User.Delete`, `User.Flush`, and `User.GetAll` ([src/client/memobase-go/core/user.go](https://github.com/memodb-io/memobase/blob/main/src/client/memobase-go/core/user.go)).

## 4. Controllers and LLM-Driven Modal Logic

Controllers in `memobase_server/controllers/` host the business rules. The modal sub-package coordinates LLM work: `controllers/modal/chat/merge_yolo.py` merges incoming memos into existing profile slots by issuing a low-temperature `llm_complete` call with the `merge_yolo` prompt and then dispatching per-memo actions returned by the model. The prompt module (`prompts/extract_profile.py`, `prompts/pick_related_profiles.py`, and the Chinese variant `prompts/zh_summary_entry_chats.py`) supplies the extraction, selection, and summarization templates consumed by the chat modal. Source: [src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/modal/chat/merge_yolo.py), [src/server/api/memobase_server/prompts/extract_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/extract_profile.py)

## 5. Data Models and Persistence

The persistence layer uses SQLAlchemy ORM with four core entities described in [src/server/api/readme.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/readme.md):

- `User` — Core identity and metadata; mutated through `create_user`, `update_user`, `delete_user` in [api_layer/user.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/user.py).
- `GeneralBlob` — Polymorphic storage for `chat`, `document`, `image`, `code`, and `transcript` blob types, typed via `BlobType` ([api_layer/user.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/user.py)).
- `BufferZone` — Per-user staging area where newly inserted blobs wait to be flushed into profiles by the LLM pipeline.
- `UserProfile` — Topic / sub-topic / memo triples that are produced by modal chat processing and exposed through `users/profile` and `users/context`.

Response shaping is centralized in `models/response.py` (`BaseResponse`, `IdResponse`, `UserDataResponse`) and the `Promise` monad in `models/utils.py` so that controllers can return either success data or a `CODE` error without throwing across async boundaries.

## 6. Common Failure Modes

When integrating against this backend, watch for the following:

- **Missing bearer token** — Middleware leaves `request.state.memobase_project_id` unset; handlers that depend on it will raise `AttributeError`.
- **Health-check failures** — `healthcheck` returns HTTP 500 with `Database not available` or `Redis not available` if the corresponding connector fails ([chore.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/api_layer/chore.py)).
- **LLM extraction gaps** — `merge_yolo` logs `No Corresponding Merge Action` warnings and skips memos when the model omits an action id; callers should expect occasional missing profile updates rather than a transactional guarantee.
- **Non-default project status** — `root_running_status_check` rejects all projects other than `DEFAULT_PROJECT_ID`, so admin probes must use the bootstrap credentials.

## See Also

- [Backend Architecture & Data Flow](./Backend-Architecture.md)
- [LLM Prompts and Modal Processing](./LLM-Prompts-and-Modal-Processing.md)
- [Authentication, Telemetry, and Middleware](./Auth-Telemetry-Middleware.md)
- [MCP Server Integration](./MCP-Server-Integration.md)

---

<a id='page-3'></a>

## Client SDKs: Python, TypeScript, and Go

### Related Pages

Related topics: [Memobase Overview and System Architecture](#page-1), [Backend Server: FastAPI, Controllers, and Data Models](#page-2), [MCP Server, Deployment, and Customization](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/client/memobase/__init__.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/__init__.py)
- [src/client/memobase/core/entry.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/entry.py)
- [src/client/memobase/core/async_entry.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/async_entry.py)
- [src/client/memobase/core/user.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/user.py)
- [src/client/memobase/core/blob.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/blob.py)
- [src/client/memobase/network.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/network.py)
- [src/client/memobase-go/core/user.go](https://github.com/memodb-io/memobase/blob/main/src/client/memobase-go/core/user.go)
- [src/server/api/memobase_server/models/blob.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/models/blob.py)
- [src/server/api/memobase_server/controllers/context.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/context.py)
- [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md)
- [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)
</details>

# Client SDKs: Python, TypeScript, and Go

## Overview and Scope

Memobase exposes a unified HTTP API for long-term user memory and ships official client SDKs that wrap the REST endpoints in idiomatic language bindings. The repository organizes these SDKs under `src/client/memobase/` (Python) and `src/client/memobase-go/` (Go); both target the same backend hosted by `memobase_server` Source: [src/client/memobase/core/async_entry.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/async_entry.py). The Python package offers a synchronous entry point (`core/entry.py`) and an asynchronous counterpart (`core/async_entry.py`) for asyncio-based applications, while the Go package provides a `User`-centric API in `core/user.go`. The author of the Python package states explicit design rules in `core/__init__.py`, including "Flat is better than nested", "Secretly handling errors for users is arrogant", and "Any single type should be fully functional on its own" Source: [src/client/memobase/core/__init__.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/__init__.py) — guiding the SDK toward transparent wrappers rather than opinionated abstractions.

## Python SDK

### Package Layout

The Python package at `src/client/memobase/` is split into focused modules:

- `core/entry.py` — synchronous high-level client.
- `core/async_entry.py` — asynchronous high-level client.
- `core/user.py` — per-user object representing a single Memobase user.
- `core/blob.py` — typed models for the various blob payloads (chat, summary, doc, code, image, transcript).
- `network.py` — shared HTTP transport, response unpacking, and error helpers.

### Context Assembly

The most prominent API is `User.context(...)`. It accepts a rich set of options for shaping the memory string that gets injected into a prompt Source: [src/client/memobase/core/async_entry.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/async_entry.py):

| Parameter | Type | Purpose |
| --- | --- | --- |
| `max_token_size` | `int` | Budget for the rendered context. |
| `prefer_topics` | `list[str]` | Bias retrieval toward these profile topics. |
| `only_topics` | `list[str]` | Restrict retrieval to these topics only. |
| `max_subtopic_size` | `int` | Cap on memos per sub-topic. |
| `topic_limits` | `dict[str, int]` | Per-topic memo caps, serialized as JSON. |
| `chats` | `list[OpenAICompatibleMessage]` | Current conversation, used for relevance scoring. |
| `need_json` | `bool` | Return structured JSON instead of a formatted string. |

These options are encoded into query parameters against `/users/profile/{user_id}`; the response is unpacked into `UserProfile` objects and (optionally) re-rendered as JSON. The `readme.md` quickstart demonstrates the typical call Source: [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md):

```python
print(u.context(max_token_size=500, prefer_topics=["basic_info"]))
```

On the server side, the same call triggers parallel retrieval of profile data and event gists, bounded by a `profile_event_ratio` and a `max_profile_token_size` Source: [src/server/api/memobase_server/controllers/context.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/context.py).

### Profile Updates and Errors

`User.update_profile(profile_id, content, topic, sub_topic)` issues `PUT /users/profile/...` to overwrite a single memo Source: [src/client/memobase/core/async_entry.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/async_entry.py). The client intentionally surfaces server errors rather than swallowing them, consistent with the "no silent error handling" guideline.

### Blob Models

`core/blob.py` defines a tagged union of blob types using `Literal` discriminators Source: [src/client/memobase/core/blob.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/blob.py): `ChatBlob` (OpenAI-style messages), `DocBlob` (free-form text), `SummaryBlob`, `CodeBlob` (with optional `language`), `ImageBlob` (URL or base64), and `TranscriptBlob` (list of `TranscriptStamp`). A `BlobData` envelope carries the type, the underlying payload, optional `fields`, and timestamps, and `to_blob()` rehydrates the appropriate subclass — except for `ImageBlob` and `TranscriptBlob`, which currently raise `NotImplementedError`. The same schema is mirrored on the server in `src/server/api/memobase_server/models/blob.py`, ensuring a round-trippable contract Source: [src/server/api/memobase_server/models/blob.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/models/blob.py).

## Go SDK

The Go client (`src/client/memobase-go/core/user.go`) exposes a `User` type bound to a project-scoped HTTP client. Three representative methods illustrate the pattern Source: [src/client/memobase-go/core/user.go](https://github.com/memodb-io/memobase/blob/main/src/client/memobase-go/core/user.go):

- `GetAll(blobType, page, pageSize) ([]string, error)` — paginates `/users/{id}/blobs/{blobType}` and returns blob IDs. Response shapes are validated with explicit type assertions on the unpacked JSON, returning descriptive errors when the server deviates from the expected schema.
- `Delete(blobID) error` — issues `DELETE /blobs/{user_id}/{blob_id}`.
- `Flush(blobType BlobType, sync bool) error` — triggers buffer flushing for a user, with a synchronous flag that lets callers ensure profile extraction completes before continuing.

The Go client follows the same "transparent error" philosophy: it returns errors directly and delegates decoding to `network.UnpackResponse` for a consistent envelope.

## Common Architectural Flow

```mermaid
sequenceDiagram
    participant App as Application
    participant SDK as Client SDK
    participant API as Memobase Server
    participant LLM as LLM Provider

    App->>SDK: u.context(max_token_size, prefer_topics, chats)
    SDK->>API: GET /users/profile/{user_id}?...
    API->>LLM: pick_related_profiles / summary prompts
    LLM-->>API: ranked memos + event gists
    API-->>SDK: profiles + events JSON
    SDK-->>App: rendered context string or UserProfile list
    App->>App: inject into LLM system prompt
```

## TypeScript SDK Status

The retrieved source fragments do not include a TypeScript SDK under `src/client/`. The top-level `readme.md` links to "Memobase-Playground" and "Memobase-Inspector" as application examples rather than client libraries Source: [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md). Until TS sources are added, applications targeting JavaScript runtimes should either call the HTTP API directly or wrap the Python SDK.

## MCP Integration

`src/mcp/README.md` documents a Model Context Protocol server built on top of the Memobase Python SDK. It exposes three tools — `save_memory`, `get_user_profiles`, and `search_memories` — and demonstrates the canonical integration path: the SDK does the network work, the MCP server translates each tool into SDK calls, and any MCP-compatible client can drive it Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

## Common Failure Modes

- **NotImplementedError on image / transcript blobs** — `BlobData.to_blob()` does not yet support `ImageBlob` or `TranscriptBlob`; the server-side models in `src/server/api/memobase_server/models/blob.py` carry the same limitation Source: [src/client/memobase/core/blob.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/blob.py).
- **Invalid `chats` payloads** — the async client validates each chat against `OpenAICompatibleMessage` and raises `ValueError` with the underlying `ValidationError` if it fails Source: [src/client/memobase/core/async_entry.py](https://github.com/memodb-io/memobase/blob/main/src/client/memobase/core/async_entry.py).
- **Profile / event ratio misconfiguration** — the server asserts `0 < profile_event_ratio <= 1`; passing an out-of-range value raises `AssertionError` Source: [src/server/api/memobase_server/controllers/context.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/controllers/context.py).

## See Also

- Server context assembly and `profile_event_ratio`
- Prompt system: topic / sub-topic configuration
- Profile extraction and `merge_yolo` controller
- Event gisting and tagging pipeline
- Memobase MCP server (`src/mcp/`)

---

<a id='page-4'></a>

## MCP Server, Deployment, and Customization

### Related Pages

Related topics: [Memobase Overview and System Architecture](#page-1), [Backend Server: FastAPI, Controllers, and Data Models](#page-2), [Client SDKs: Python, TypeScript, and Go](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md)
- [readme.md](https://github.com/memodb-io/memobase/blob/main/readme.md)
- [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md)
- [src/server/api/memobase_server/prompts/profile_init_utils.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/profile_init_utils.py)
- [src/server/api/example_config/profile_for_assistant/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_assistant/config.yaml)
- [src/server/api/example_config/profile_for_companion/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_companion/config.yaml)
- [src/server/api/memobase_server/prompts/extract_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/extract_profile.py)
</details>

# MCP Server, Deployment, and Customization

## 1. Purpose and Scope

The **Memobase MCP Server** is a template implementation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) that connects AI agents to Memobase's long-term, persistent memory. It is forked from [`coleam00/mcp-mem0`](https://github.com/coleam00/mcp-mem0) and acts as a practical reference for engineers who want to expose Memobase storage, retrieval, and semantic search behind an MCP-compatible interface. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

The server itself does not host the memory backend. To function, it requires a reachable Memobase backend with a project URL and a project token. The two supported backends are:

- A **self-hosted local instance** exposed at `http://localhost:8019` with the default token `secret`. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).
- **Memobase Cloud**, reachable at `https://api.memobase.dev` with a `sk-proj-…` token obtained from the cloud console. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

The wider Memobase project is described as a *user memory system for LLM applications that maintains persistent user context and memory*; the MCP server is the thin agent-facing adapter that lets any MCP client tap into that system. Source: [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md).

## 2. Exposed Tools and Runtime Architecture

The server exposes three essential memory-management tools to MCP clients. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

| Tool | Purpose |
| --- | --- |
| `save_memory` | Store arbitrary information in long-term memory with semantic indexing. |
| `get_user_profiles` | Retrieve the complete user profile set for a given user. |
| `search_memories` | Find relevant context for a given query via semantic search. |

The server implements the best practices described by Anthropic for MCP servers, so it is compatible with any MCP-aware client (Cursor, Windsurf, Claude Desktop, n8n, or custom Python clients). Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

Internally, the broader Memobase backend that the MCP server calls into follows a layered architecture: a FastAPI entry point routes requests through controllers (User, Blob, Buffer, Profile, Modal) backed by PostgreSQL, Redis, and an LLM service. The MCP server is the lightweight client-side layer that surfaces only the user-relevant operations to the agent. Source: [src/server/api/DEVELOPMENT.md](https://github.com/memodb-io/memobase/blob/main/src/server/api/DEVELOPMENT.md).

```mermaid
graph LR
    A[MCP Client<br/>Cursor / Claude / n8n] -- MCP/JSON-RPC --> B[Memobase MCP Server]
    B -- save / get / search --> C[Memobase Backend<br/>FastAPI + Postgres + Redis]
    C -- LLM calls --> D[LLM Provider]
    B -. context string .-> A
```

## 3. Deployment Options

### 3.1 Local install with `uv` (Python 3.11+)

The recommended path for development is [`uv`](https://github.com/astral/uv). The flow is: install `uv`, clone the repository, `cd memobase/src/mcp`, run `uv pip install -e .` to install in editable mode, then copy `.env.example` to `.env` and fill in the project URL and token. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

### 3.2 Docker (recommended for production-like use)

A Docker image can be built and run on port 8050 (the default MCP SSE port). The MCP server then runs as a long-lived SSE endpoint that any MCP client can connect to. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

### 3.3 Client wiring

The server can be reached in two transport modes:

- **SSE transport** (HTTP-based, used by Cursor and Windsurf). For Windsurf, the configuration key is `serverUrl` instead of `url`. For n8n, the host must be `host.docker.internal` because n8n reaches outside its own container. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).
- **Stdio transport**, used by Claude Desktop and other local clients. The configuration points at the Python executable inside the project's `.venv`. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

### 3.4 Required environment variables

The `.env` file must contain the project URL and the project token that identify which Memobase backend the MCP server should talk to. Without them, the three tools will fail at request time. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).

## 4. Customization

The MCP server is deliberately a *template*. The README describes four extension points. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md):

1. **Add new tools** by defining methods with the `@mcp.tool()` decorator on the `mcp` instance.
2. **Add a custom lifespan** function to inject additional dependencies (database connections, custom clients, telemetry, etc.) into each request.
3. **Add helper functions** in `utils.py` to keep tool bodies small and readable.
4. **Add prompts and resources** using the `@mcp.prompt()` and `@mcp.resource()` decorators.

### 4.1 Customizing user-profile schemas

The memory model is not hard-coded. The server-side prompt module [`profile_init_utils.py`](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/profile_init_utils.py) exposes two configuration knobs sourced from `CONFIG`:

- `overwrite_user_profiles` — when set, *replaces* the default topic/sub-topic schema with the supplied list. Source: [src/server/api/memobase_server/prompts/profile_init_utils.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/profile_init_utils.py).
- `additional_user_profiles` — when set, *extends* the default schema with extra topics. Source: [src/server/api/memobase_server/prompts/profile_init_utils.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/profile_init_utils.py).

These two modes map to the example configurations shipped with the repository:

- `example_config/profile_for_assistant/config.yaml` — a productivity-oriented schema with topics such as `task_management` (with `priorities`, `task_categories`, `deadline_buffer`, `recurring_tasks`, `task_format`) and `productivity_settings` (with `focus_mode`, `notification_prefs`, `automation_rules`, `report_frequency`, `tracking_metrics`, `tool_integrations`). Source: [src/server/api/example_config/profile_for_assistant/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_assistant/config.yaml).
- `example_config/profile_for_companion/config.yaml` — a companion-oriented schema including `personalization` (with `humor_pref`, `response_len`, `tech_depth`, `learn_style`) and a session-tracking topic that records `convo_count`, `favorite_topics`, `active_projects`, `saved_convos`, and `feedback_hist`. Source: [src/server/api/example_config/profile_for_companion/config.yaml](https://github.com/memodb-io/memobase/blob/main/src/server/api/example_config/profile_for_companion/config.yaml).

The extraction prompt is parameterized over the supplied schema: it asks the LLM to "consider using the same topic/subtopic if it's mentioned in the conversation again" and to fall back to creating new topics only when necessary, which keeps memories stable across runs. Source: [src/server/api/memobase_server/prompts/extract_profile.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/extract_profile.py).

## 5. Common Failure Modes

- **Missing or wrong `MEMOBASE_PROJECT_URL` / token** — the three MCP tools will return auth or connection errors because the server cannot reach the backend. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).
- **Wrong port in client config** — the default is 8050; clients such as Cursor, Windsurf, and n8n must match the port the server was actually launched on. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).
- **`localhost` inside n8n** — n8n cannot reach the host's loopback; use `host.docker.internal` instead. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).
- **Conflicting Windsurf config key** — Windsurf expects `serverUrl`; using `url` will silently fail. Source: [src/mcp/README.md](https://github.com/memodb-io/memobase/blob/main/src/mcp/README.md).
- **Schema drift** — if `overwrite_user_profiles` is changed, previously stored profile entries under removed topics will be ignored by extraction until they are re-ingested. Source: [src/server/api/memobase_server/prompts/profile_init_utils.py](https://github.com/memodb-io/memobase/blob/main/src/server/api/memobase_server/prompts/profile_init_utils.py).

## See Also

- [Memobase-Playground](https://github.com/memodb-io/memobase-playground) — full-stack reference chatbot that demonstrates end-to-end memory usage.
- [Memobase-Inspector](https://github.com/memodb-io/memobase-inspector) — web UI for inspecting users, profiles, and test prompts.
- [Profile customization docs](https://docs.memobase.io/features/profile/profile) — official guide for designing the profile schema.
- [`get_context` API reference](https://docs.memobase.io/api-reference/prompt/get_context) — the backend call that produces the context string the MCP server eventually returns to the agent.

---

<!-- evidence_pipeline_checked: true -->

---

## Pitfall Log

Project: memodb-io/memobase

Summary: Found 12 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/memodb-io/memobase/issues/155

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/memodb-io/memobase/issues/158

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/memodb-io/memobase/issues/76

## 4. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/memodb-io/memobase/issues/159

## 5. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/memodb-io/memobase

## 6. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/memodb-io/memobase/issues/137

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/memodb-io/memobase

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/memodb-io/memobase

## 9. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/memodb-io/memobase

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/memodb-io/memobase/issues/153

## 11. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/memodb-io/memobase

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/memodb-io/memobase

<!-- canonical_name: memodb-io/memobase; human_manual_source: deepwiki_human_wiki -->