MemoryBridge

Agent ──(OpenAI API + Token)──→ MemoryBridge ──(HTTP)──→ Your LLM Provider
 │ ↑
 │ ├── Retrieve memories (read)
 │ └── Store memories (write)
 │
 ┌───┴────┐
 │ Qdrant │
 └───┬────┘
 │
 Mem0 (memory engine)

Why MemoryBridge?

Quick Start

Prerequisites

3 Steps to Run

# 1. Install
git clone https://github.com/51193/MemoryBridge && cd MemoryBridge
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv sync
# 2. Initialize (downloads Qdrant, creates databases, generates admin token)
uv run python src/memory_bridge/host_manager.py --init
# Output: ADMIN TOKEN (save this): <32-char hex>
# 3. Start
uv run python src/memory_bridge/host_manager.py
# Visit http://localhost:8000/health → {"status":"ok","qdrant":"connected"}

Register a Service Token

curl -X POST http://localhost:8000/v1/admin/tokens \
 -H "Authorization: Bearer <admin_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "label": "my-llm",
 "main_llm_base_url": "https://api.deepseek.com",
 "main_llm_api_key": "sk-xxx",
 "memory_llm_base_url": "https://api.deepseek.com",
 "memory_llm_api_key": "sk-xxx",
 "memory_llm_provider": "openai",
 "embed_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
 "embed_api_key": "sk-xxx",
 "embed_dims": 1024,
 "embed_provider": "openai"
 }'
# Returns: {"token": "<32-char service_token>", ...}

Make Your First Request

# Exactly like calling any LLM API — just use the service token
curl -X POST http://localhost:8000/v1/chat/completions \
 -H "Authorization: Bearer <service_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "deepseek-chat",
 "messages": [{"role": "user", "content": "Hi, my name is Ming"}],
 "stream": false
 }'

Multi-turn Conversation (with Streaming)

curl -X POST http://localhost:8000/v1/chat/completions \
 -H "Authorization: Bearer <service_token>" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "deepseek-chat",
 "messages": [
 {"role": "user", "content": "My name is Ming"},
 {"role": "assistant", "content": "Hello Ming!"},
 {"role": "user", "content": "What is my name?"}
 ],
 "stream": true
 }'

Token System

API Reference

Chat Endpoint

Admin Endpoints

Health

Error Codes

Request Flow

Incoming request
 → TokenAuthMiddleware (auth + request-id + read raw JSON body)
 → router (parse messages, validate, create Handler instance)
 → ChatRequestHandler.execute()
 ├─ SessionStore.get() ← Read recent conversation history
 ├─ MemoryManager.search() ← Memory retrieval (Qdrant vector search)
 ├─ ContextBuilder.build() ← Assemble context (memory block + request)
 ├─ _inject_history() ← Prepend session history after system prompt
 ├─ response_sender.send_*() ← Forward enriched request to LLM
 └─ _store_memory() ← Async store (session + memories)

Project Structure

src/memory_bridge/
├── main.py # FastAPI app factory + lifespan
├── host_manager.py # Process manager (Qdrant + API subprocess)
├── host_process.py # Subprocess lifecycle management
├── host_init.py # First-time initialization
├── config.py # Infrastructure config (pydantic-settings)
├── exceptions.py # Custom exceptions
├── api/ # Routes + middleware + request handling
│ ├── response_sender.py # Non-stream / streaming LLM dispatch
├── core/ # Memory / session / context / token / logging
├── providers/ # HTTP client (transparent proxy)
└── models/ # Request / response models
templates/
 ├── memory_template.md # Memory injection template (English)
 └── memory_template_zh.md # Memory injection template (Chinese)

Development

uv sync --extra dev # Install dev dependencies
uv run mypy src/ # Type check (strict mode)
uv run ruff check src/ tests/ # Lint
uv run pytest -v # Unit tests
uv run pytest --cov=src/memory_bridge --cov-fail-under=95 # Coverage gate

tests/
├── api/ ← src/memory_bridge/api/
├── core/ ← src/memory_bridge/core/
├── providers/ ← src/memory_bridge/providers/
├── architecture/ # Architecture guard tests (boundary checks)
└── integration/ # Integration smoke tests

Install from Release

mkdir -p /opt/memorybridge && cd /opt/memorybridge
wget https://github.com/51193/MemoryBridge/releases/latest/download/memorybridge.pyz
python3 memorybridge.pyz --init # First-time setup
python3 memorybridge.pyz # Start

License