mem-agent-mcp

# mem-agent-mcp This is an MCP server for our model [driaforall/mem-agent](https://huggingface.co/driaforall/mem-agent), which can be connected to apps like Claude Desktop or Lm Studio to interact with an obsidian-like memory system. ## Supported Platforms - macOS (Metal backend) - Linux (with GPU, vLLM backend) ### Platform note: aarch64 (ARM64) Linux - On ARM64 Linux, vLLM is not installed by default to avoid build failures (no stable wheels and source builds can fail). - Installation will succeed without vLLM; you can: - Use the default OpenRouter/OpenAI path (no local vLLM needed), or - Run vLLM on a compatible x86_64 host and point the client at it (see agent/model.py create_vllm_client). ## Running Instructions ### Using a LiteLLM proxy (OpenAI-compatible) - If you have a LiteLLM proxy running locally (e.g., on port 4000), configure the client via .env: ``` VLLM_HOST=localhost VLLM_PORT=4000 ``` - Verify connectivity: ``` curl http://localhost:4000/v1/models ``` - Then use either of these: - CLI: `make chat-cli` - MCP over STDIO: `make serve-mcp` - MCP over HTTP: `make serve-mcp-http` Note: On ARM64 Linux, this is the recommended setup instead of vLLM. 1. `make check-uv` (if you have uv installed, skip this step). 2. `make install`: Installs LmStudio on MacOS. 3. `make setup`: This will open a file selector and ask you to select the directory where you want to store the memory. 4. `make run-agent`: If you're on macOS, this will prompt you to select the precision of the model you want to use. 4-bit is very usable as tested, and higher precision models are more reliable but slower. 5. `make generate-mcp-json`: Generates the `mcp.json` file. That will be used in the next step. 6. Instructions per app/provider: - Claude Desktop: - Copy the generated `mcp.json` to the where your `claude_desktop.json` is located, then, quit and restart Claude Desktop. Check [this guide](https://modelcontextprotocol.io/quickstart/user) for detailed instructions. - Lm Studio: - Copy the generated `mcp.json` to the `mcp.json` of Lm Studio. Check [this guide](https://lmstudio.ai/docs/app/plugins/mcp) for detailed instructions. If there are problems, change the name of the model in .mlx_model_name (found in the root of this repo) from `mem-agent-mlx-4bit` or `mem-agent-mlx-8bit` to `mem-agent-mlx@4bit` or `mem-agent-mlx@8bit` respectively. ## Memory Instructions - Each memory directory should follow the structure below: ``` memory/ ├── user.md └── entities/ └── [entity_name_1].md └── [entity_name_2].md └── ... ``` - `user.md` is the main file that contains information about the user and their relationships, accompanied by links to the enity file in the format of `[[entities/[entity_name].md]]` per relationship. The link format should be followed strictly. - `entities/` is the directory that contains the entity files. - Each entity file follows the same structure as `user.md`. - Modifying the memory manually does not require restarting the MCP server. ### Example user.md ```markdown # User Information - user_name: John Doe - birth_date: 1990-01-01 - birth_location: New York, USA - living_location: Enschede, Netherlands - zodiac_sign: Aquarius ## User Relationships - company: [[entities/acme_corp.md]] - mother: [[entities/jane_doe.md]] ``` ### Example entity files (jane_doe.md and acme_corp.md) ```markdown # Jane Doe - relationship: Mother - birth_date: 1965-01-01 - birth_location: New York, USA ``` ```markdown # Acme Corporation - industry: Software Development - location: Enschede, Netherlands ``` ## Filtering The model is trained to accepts filters on various domains in between <filter> tags after the user query. These filters are used to filter the retrieved information and/or obfuscate it completely. An example of a user query with filters is: ``` What's my mother's age? <filter> 1. Do not reveal explicit age information, 2. Do not reveal any email addresses </filter> ``` To use this, functionality with the MCP, you have two make targets: - `make add-filters`: Opens an input loop and adds the filters given by the user to the .filters file. - `make reset-filters`: Resets the .filters file (clears it). Adding or removing filters does not require restarting the MCP server. ## Memory Connectors ### Available Connectors | Connector | Description | Supported Formats | Type | |-----------|-------------|-------------------|------| | `chatgpt` | ChatGPT conversation exports | `.zip`, `.json` | Export | | `notion` | Notion workspace exports | `.zip` | Export | | `nuclino` | Nuclino workspace exports | `.zip` | Export | | `github` | GitHub repositories via API | Live API | Live | | `google-docs` | Google Docs folders via Drive API | Live API | Live | ### Usage #### 🧙‍♂️ Interactive Memory Wizard (Recommended) The easiest way to connect your memory sources: ```bash make memory-wizard # or python memory_wizard.py ``` The wizard will guide y