skpassegna/openmemory-mcp repository overview

⁠OpenMemory API & MCP Server

This Docker image contains the backend API and Model Context Protocol (MCP) server for OpenMemory.

OpenMemory is your personal memory layer for LLMs - private, portable, and open-source. Your memories live locally, giving you complete control over your data. Build AI applications with personalized memories while keeping your data secure.

⁠Features

• Backend API: Provides RESTful endpoints for managing users, applications, memories, categories, and system configuration.
• MCP Server: Enables AI clients (e.g., Claude, Cursor, custom applications) to interact with the memory layer using standardized tools like add_memories and search_memory via Server-Sent Events (SSE).
• Configurable LLM & Embedder Integration:
  • Defaults to using OpenAI for LLM and embedding tasks.
  • Supports configuring various providers including Ollama, LM Studio, Mistral AI (via OpenAI-compatible API), Anthropic, and others supported by the underlying mem0 library.
  • Configuration is managed via API and stored in the database.
• Database Backend:
  • Uses SQLAlchemy as an ORM.
  • Defaults to an SQLite database (openmemory.db) within the container if DATABASE_URL is not specified.
  • Supports PostgreSQL (requires psycopg2-binary and a DATABASE_URL).
  • Alembic is used for database migrations.
• Vector Store: Integrates with Qdrant for vector storage and semantic search of memories.
• Automatic Memory Categorization: Can use a configured LLM to automatically categorize memories.
• Access Control & Logging: Features for managing memory access and logging interactions.

⁠How to Run

This image is designed to be run as part of the OpenMemory stack, typically orchestrated with Docker Compose. For the easiest setup, refer to the docker-compose.yml or run.sh script in the main OpenMemory GitHub repository⁠.

Basic Docker Run Example (requires a running Qdrant instance):

docker run -d \
  --name openmemory-mcp-container \
  -p 8765:8765 \
  -e OPENAI_API_KEY="your_openai_api_key" \
  -e USER="$(whoami)" \
  -e QDRANT_HOST="your_qdrant_host_or_service_name" \
  -e QDRANT_PORT="6333" \
  # -e DATABASE_URL="your_database_url" # Optional: for external DB
  # -e OLLAMA_HOST="host.docker.internal" # If using Ollama on host
  skpassegna/openmemory-mcp:latest

Required Services:

• Qdrant: A Qdrant instance is required for vector storage. The image expects Qdrant to be available.
  • Example: docker run -d -p 6333:6333 -p 6334:6334 -v qdrant_storage:/qdrant/storage qdrant/qdrant
• Database (Optional): If not using the default SQLite, an external database (like PostgreSQL) needs to be accessible.

⁠Environment Variables

• OPENAI_API_KEY (Required for default OpenAI functionality): Your API key for OpenAI.
  • Example: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
• USER (Recommended): Sets a default user ID for operations.
  • Example: yourusername
• DATABASE_URL (Optional): Connection string for the SQL database. If not set, defaults to SQLite within the container (/usr/src/openmemory/openmemory.db).
  • Example for PostgreSQL: postgresql://user:password@host:port/database
• QDRANT_HOST (Required if not using default Docker Compose networking): Hostname or IP of your Qdrant instance.
  • Default when used with docker-compose.yml from the project: mem0_store
  • Example: qdrant-server
• QDRANT_PORT (Optional): Port for your Qdrant instance.
  • Default: 6333
• OLLAMA_HOST (Optional): If using Ollama as a provider and it's running on your Docker host machine, you might need to set this to host.docker.internal or the appropriate IP address for the container to reach it. The application attempts to auto-detect this for Docker environments.
  • Example: host.docker.internal
• Other *_API_KEY (e.g., MISTRAL_API_KEY, ANTHROPIC_API_KEY): If you configure OpenMemory (via its UI/API settings) to use other LLM/Embedder providers that require API keys, you can set them as environment variables and reference them in the configuration (e.g., api_key: "env:MISTRAL_API_KEY").

⁠Ports Exposed

• 8765: The port on which the FastAPI application (API and MCP server) listens.

⁠API Documentation

Once the container is running, API documentation is available at:

• Swagger UI: http://<host_ip>:8765/docs
• ReDoc: http://<host_ip>:8765/redoc

⁠Source Code

The source code for this API and MCP server can be found in the api/ directory of the OpenMemory GitHub repository⁠.

⁠Contributing

OpenMemory welcomes contributions! Please see the CONTRIBUTING.md⁠ file in the main repository for guidelines.