|
| 1 | +<h1 align="center">Memobase-MCP: Long-Term Memory for AI Agents</h1> |
| 2 | + |
| 3 | +> This project is forked from [coleam00/mcp-mem0](https://github.com/coleam00/mcp-mem0) |
| 4 | +
|
| 5 | +A template implementation of the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server integrated with [Memobase](https://memobase.io) for providing AI agents with persistent memory capabilities. |
| 6 | + |
| 7 | +Use this as a reference point to build your MCP servers yourself, or give this as an example to an AI coding assistant and tell it to follow this example for structure and code correctness! |
| 8 | + |
| 9 | +To run this mcp, you need to have your own Memobase backend: |
| 10 | + |
| 11 | +- You can [deploy](../server/readme.md) a local one |
| 12 | +- Or use [free credits](https://www.memobase.io/en) of Memobase Cloud |
| 13 | + |
| 14 | +You should have: |
| 15 | + |
| 16 | +- A project url. (local: `http://localhost:8019` , cloud `https://api.memobase.dev`) |
| 17 | +- A project token. (local: `secret` , cloud `sk-proj-xxxxxx`) |
| 18 | + |
| 19 | +## Overview |
| 20 | + |
| 21 | +This project demonstrates how to build an MCP server that enables AI agents to store, retrieve, and search memories using semantic search. It serves as a practical template for creating your own MCP servers, simply using Memobase and a practical example. |
| 22 | + |
| 23 | +The implementation follows the best practices laid out by Anthropic for building MCP servers, allowing seamless integration with any MCP-compatible client. |
| 24 | + |
| 25 | +## Features |
| 26 | + |
| 27 | +The server provides three essential memory management tools: |
| 28 | + |
| 29 | +1. **`save_memory`**: Store any information in long-term memory with semantic indexing |
| 30 | +2. **`get_user_profiles`**: Retrieve complete user profiles |
| 31 | +3. **`search_memories`**: Find relevant context for a given query |
| 32 | + |
| 33 | +## Prerequisites |
| 34 | +- Python 3.11+ |
| 35 | + |
| 36 | +## Installation |
| 37 | + |
| 38 | +### Using uv |
| 39 | + |
| 40 | +1. Install uv if you don't have it: |
| 41 | + ```bash |
| 42 | + pip install uv |
| 43 | + ``` |
| 44 | + |
| 45 | +2. Clone the repository: |
| 46 | + ```bash |
| 47 | + git clone https://github.com/memodb-io/memobase |
| 48 | + ``` |
| 49 | + |
| 50 | +3. Navigate to the project directory: |
| 51 | + ```bash |
| 52 | + cd memobase/src/mcp |
| 53 | + ``` |
| 54 | + |
| 55 | +3. Install dependencies: |
| 56 | + ```bash |
| 57 | + uv pip install -e . |
| 58 | + ``` |
| 59 | + |
| 60 | +4. Create a `.env` file based on `.env.example`: |
| 61 | + ```bash |
| 62 | + cp .env.example .env |
| 63 | + ``` |
| 64 | + |
| 65 | +5. Configure your environment variables in the `.env` file (see Configuration section) |
| 66 | + |
| 67 | +### Using Docker (Recommended) |
| 68 | + |
| 69 | +1. Build the Docker image: |
| 70 | + ```bash |
| 71 | + docker build -t memobase-mcp --build-arg PORT=8050 . |
| 72 | + ``` |
| 73 | + |
| 74 | +2. Create a `.env` file based on `.env.example` and configure your environment variables |
| 75 | + |
| 76 | +## Configuration |
| 77 | + |
| 78 | +The following environment variables can be configured in your `.env` file: |
| 79 | + |
| 80 | +| Variable | Description | Example | |
| 81 | +|----------|-------------|----------| |
| 82 | +| `TRANSPORT` | Transport protocol (sse or stdio) | `sse` | |
| 83 | +| `HOST` | Host to bind to when using SSE transport | `0.0.0.0` | |
| 84 | +| `PORT` | Port to listen on when using SSE transport | `8050` | |
| 85 | +| `MEMOBASE_API_KEY` | Memobase API key | `secret` | |
| 86 | +| `MEMOBASE_BASE_URL` | Memobase base URL | `http://localhost:8019` | |
| 87 | + |
| 88 | +## Running the Server |
| 89 | + |
| 90 | +### Using uv |
| 91 | + |
| 92 | +#### SSE Transport |
| 93 | + |
| 94 | +```bash |
| 95 | +# Set TRANSPORT=sse in .env then: |
| 96 | +uv run src/main.py |
| 97 | +``` |
| 98 | + |
| 99 | +The MCP server will essentially be run as an API endpoint that you can then connect to with config shown below. |
| 100 | + |
| 101 | +#### Stdio Transport |
| 102 | + |
| 103 | +With stdio, the MCP client iself can spin up the MCP server, so nothing to run at this point. |
| 104 | + |
| 105 | +### Using Docker |
| 106 | + |
| 107 | +#### SSE Transport |
| 108 | + |
| 109 | +```bash |
| 110 | +docker run --env-file .env -p:8050:8050 memobase-mcp |
| 111 | +``` |
| 112 | + |
| 113 | +The MCP server will essentially be run as an API endpoint within the container that you can then connect to with config shown below. |
| 114 | + |
| 115 | +#### Stdio Transport |
| 116 | + |
| 117 | +With stdio, the MCP client iself can spin up the MCP server container, so nothing to run at this point. |
| 118 | + |
| 119 | +## Integration with MCP Clients |
| 120 | + |
| 121 | +### SSE Configuration |
| 122 | + |
| 123 | +Once you have the server running with SSE transport, you can connect to it using this configuration: |
| 124 | + |
| 125 | +```json |
| 126 | +{ |
| 127 | + "mcpServers": { |
| 128 | + "memobase": { |
| 129 | + "transport": "sse", |
| 130 | + "url": "http://localhost:8050/sse" |
| 131 | + } |
| 132 | + } |
| 133 | +} |
| 134 | +``` |
| 135 | + |
| 136 | +> **Note for Windsurf users**: Use `serverUrl` instead of `url` in your configuration: |
| 137 | +> ```json |
| 138 | +> { |
| 139 | +> "mcpServers": { |
| 140 | +> "memobase": { |
| 141 | +> "transport": "sse", |
| 142 | +> "serverUrl": "http://localhost:8050/sse" |
| 143 | +> } |
| 144 | +> } |
| 145 | +> } |
| 146 | +> ``` |
| 147 | +
|
| 148 | +> **Note for n8n users**: Use host.docker.internal instead of localhost since n8n has to reach outside of it's own container to the host machine: |
| 149 | +> |
| 150 | +> So the full URL in the MCP node would be: http://host.docker.internal:8050/sse |
| 151 | +
|
| 152 | +Make sure to update the port if you are using a value other than the default 8050. |
| 153 | +
|
| 154 | +### Python with Stdio Configuration |
| 155 | +
|
| 156 | +Add this server to your MCP configuration for Claude Desktop, Windsurf, or any other MCP client: |
| 157 | +
|
| 158 | +```json |
| 159 | +{ |
| 160 | + "mcpServers": { |
| 161 | + "memobase": { |
| 162 | + "command": "your/path/to/mcp/.venv/Scripts/python.exe", |
| 163 | + "args": ["your/path/to/mcp/src/main.py"], |
| 164 | + "env": { |
| 165 | + "TRANSPORT": "stdio", |
| 166 | + "MEMOBASE_API_KEY": "YOUR-API-KEY", |
| 167 | + "MEMOBASE_BASE_URL": "YOUR-MEMOBASE-URL", |
| 168 | + } |
| 169 | + } |
| 170 | + } |
| 171 | +} |
| 172 | +``` |
| 173 | +
|
| 174 | +### Docker with Stdio Configuration |
| 175 | + |
| 176 | +```json |
| 177 | +{ |
| 178 | + "mcpServers": { |
| 179 | + "memobase": { |
| 180 | + "command": "docker", |
| 181 | + "args": ["run", "--rm", "-i", |
| 182 | + "-e", "TRANSPORT", |
| 183 | + "-e", "MEMOBASE_API_KEY", |
| 184 | + "-e", "MEMOBASE_BASE_URL", |
| 185 | + "memobase-mcp"], |
| 186 | + "env": { |
| 187 | + "TRANSPORT": "stdio", |
| 188 | + "MEMOBASE_API_KEY": "YOUR-API-KEY", |
| 189 | + "MEMOBASE_BASE_URL": "https://api.memobase.io", |
| 190 | + } |
| 191 | + } |
| 192 | + } |
| 193 | +} |
| 194 | +``` |
| 195 | + |
| 196 | +## Building Your Own Server |
| 197 | + |
| 198 | +This template provides a foundation for building more complex MCP servers. To build your own: |
| 199 | + |
| 200 | +1. Add your own tools by creating methods with the `@mcp.tool()` decorator |
| 201 | +2. Create your own lifespan function to add your own dependencies (clients, database connections, etc.) |
| 202 | +3. Modify the `utils.py` file for any helper functions you need for your MCP server |
| 203 | +4. Feel free to add prompts and resources as well with `@mcp.resource()` and `@mcp.prompt()` |
0 commit comments