Skip to content
Back to search

mem-agent-mcp

mem-agent mcp server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/firstbatchxyz--mem-agent-mcp/badge.svg)](/listings/firstbatchxyz--mem-agent-mcp)

HTML

<a href="/listings/firstbatchxyz--mem-agent-mcp"><img src="/api/listings/firstbatchxyz--mem-agent-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 497 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mem-agent-mcp
  2. 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.
  3. ## Supported Platforms
  4. - macOS (Metal backend)
  5. - Linux (with GPU, vLLM backend)
  6. ### Platform note: aarch64 (ARM64) Linux
  7. - On ARM64 Linux, vLLM is not installed by default to avoid build failures (no stable wheels and source builds can fail).
  8. - Installation will succeed without vLLM; you can:
  9. - Use the default OpenRouter/OpenAI path (no local vLLM needed), or
  10. - Run vLLM on a compatible x86_64 host and point the client at it (see agent/model.py create_vllm_client).
  11. ## Running Instructions
  12. ### Using a LiteLLM proxy (OpenAI-compatible)
  13. - If you have a LiteLLM proxy running locally (e.g., on port 4000), configure the client via .env:
  14. ```
  15. VLLM_HOST=localhost
  16. VLLM_PORT=4000
  17. ```
  18. - Verify connectivity:
  19. ```
  20. curl http://localhost:4000/v1/models
  21. ```
  22. - Then use either of these:
  23. - CLI: `make chat-cli`
  24. - MCP over STDIO: `make serve-mcp`
  25. - MCP over HTTP: `make serve-mcp-http`
  26. Note: On ARM64 Linux, this is the recommended setup instead of vLLM.
  27. 1. `make check-uv` (if you have uv installed, skip this step).
  28. 2. `make install`: Installs LmStudio on MacOS.
  29. 3. `make setup`: This will open a file selector and ask you to select the directory where you want to store the memory.
  30. 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.
  31. 5. `make generate-mcp-json`: Generates the `mcp.json` file. That will be used in the next step.
  32. 6. Instructions per app/provider:
  33. - Claude Desktop:
  34. - 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.
  35. - Lm Studio:
  36. - 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.
  37. ## Memory Instructions
  38. - Each memory directory should follow the structure below:
  39. ```
  40. memory/
  41. ├── user.md
  42. └── entities/
  43. └── [entity_name_1].md
  44. └── [entity_name_2].md
  45. └── ...
  46. ```
  47. - `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.
  48. - `entities/` is the directory that contains the entity files.
  49. - Each entity file follows the same structure as `user.md`.
  50. - Modifying the memory manually does not require restarting the MCP server.
  51. ### Example user.md
  52. ```markdown
  53. # User Information
  54. - user_name: John Doe
  55. - birth_date: 1990-01-01
  56. - birth_location: New York, USA
  57. - living_location: Enschede, Netherlands
  58. - zodiac_sign: Aquarius
  59. ## User Relationships
  60. - company: [[entities/acme_corp.md]]
  61. - mother: [[entities/jane_doe.md]]
  62. ```
  63. ### Example entity files (jane_doe.md and acme_corp.md)
  64. ```markdown
  65. # Jane Doe
  66. - relationship: Mother
  67. - birth_date: 1965-01-01
  68. - birth_location: New York, USA
  69. ```
  70. ```markdown
  71. # Acme Corporation
  72. - industry: Software Development
  73. - location: Enschede, Netherlands
  74. ```
  75. ## Filtering
  76. 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:
  77. ```
  78. What's my mother's age? <filter> 1. Do not reveal explicit age information, 2. Do not reveal any email addresses </filter>
  79. ```
  80. To use this, functionality with the MCP, you have two make targets:
  81. - `make add-filters`: Opens an input loop and adds the filters given by the user to the .filters file.
  82. - `make reset-filters`: Resets the .filters file (clears it).
  83. Adding or removing filters does not require restarting the MCP server.
  84. ## Memory Connectors
  85. ### Available Connectors
  86. | Connector | Description | Supported Formats | Type |
  87. |-----------|-------------|-------------------|------|
  88. | `chatgpt` | ChatGPT conversation exports | `.zip`, `.json` | Export |
  89. | `notion` | Notion workspace exports | `.zip` | Export |
  90. | `nuclino` | Nuclino workspace exports | `.zip` | Export |
  91. | `github` | GitHub repositories via API | Live API | Live |
  92. | `google-docs` | Google Docs folders via Drive API | Live API | Live |
  93. ### Usage
  94. #### 🧙‍♂️ Interactive Memory Wizard (Recommended)
  95. The easiest way to connect your memory sources:
  96. ```bash
  97. make memory-wizard
  98. # or
  99. python memory_wizard.py
  100. ```
  101. The wizard will guide you through:
  102. - ✅ Connector selection with descriptions
  103. - ✅ Authentication setup (tokens, scopes)
  104. - ✅ Source configuration (files, URLs, IDs)
  105. - ✅ Output directory setup
  106. - ✅ Connector-specific options
  107. - ✅ Configuration confirmation
  108. - ✅ Automatic execution
  109. - ✅ Success confirmation with next steps
  110. #### Manual CLI Usage
  111. **Quick Demo with Sample Memories:**
  112. ```bash
  113. make run-agent
  114. make serve-mcp-http
  115. python examples/mem_agent_cli.py
  116. ```
  117. Sample memory packs (`healthcare` and `client_success`) are included to demonstrate mem-agent functionality with different data types. Use the interactive CLI to explore these memories and test prompts.
  118. List Available Connectors:
  119. ```bash
  120. make connect-memory
  121. # or
  122. python memory_connectors/memory_connect.py --list
  123. #### ChatGPT History Import
  124. ```bash
  125. # Basic usage
  126. make connect-memory CONNECTOR=chatgpt SOURCE=/path/to/chatgpt-export.zip
  127. # AI-powered categorization with TF-IDF (fast)
  128. python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method ai --embedding-model tfidf
  129. # AI-powered categorization with LM Studio (high-quality semantic)
  130. python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method ai --embedding-model lmstudio
  131. # Keyword-based with custom categories
  132. python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method keyword --edit-keywords
  133. # Process limited conversations
  134. python memory_connectors/memory_connect.py chatgpt /path/to/export.zip --max-items 100
  135. ```
  136. **Categorization Methods:**
  137. - **Keyword-based**: Fast, customizable categories using predefined keywords
  138. - **AI-powered (TF-IDF)**: Statistical clustering, discovers conversation patterns
  139. - **AI-powered (LM Studio)**: Semantic embeddings via neural networks (requires LM Studio)
  140. # Custom output location
  141. make connect-memory CONNECTOR=chatgpt SOURCE=/path/to/export.zip OUTPUT=./memory/custom
  142. # Process only first 100 conversations
  143. make connect-memory CONNECTOR=chatgpt SOURCE=/path/to/export.zip MAX_ITEMS=100
  144. # Direct CLI usage
  145. python memory_connect.py chatgpt /path/to/export.zip --output ./memory --max-items 100
  146. #### Notion Workspace Import
  147. ```bash
  148. # Basic usage
  149. make connect-memory CONNECTOR=notion SOURCE=/path/to/notion-export.zip
  150. # Custom output location
  151. make connect-memory CONNECTOR=notion SOURCE=/path/to/export.zip OUTPUT=./memory/custom
  152. python memory_connectors/memory_connect.py notion /path/to/export.zip --output ./memory
  153. ```
  154. #### Getting ChatGPT Export
  155. 1. Go to [ChatGPT Settings](https://chatgpt.com/settings/data-controls)
  156. 2. Click "Export data"
  157. 3. Wait for email with download link
  158. 4. Extract the ZIP file
  159. 5. Use the extracted folder or ZIP file with the connector
  160. #### Nuclino Workspace Import
  161. ```bash
  162. # Basic usage
  163. make connect-memory CONNECTOR=nuclino SOURCE=/path/to/nuclino-export.zip
  164. # Custom output location
  165. make connect-memory CONNECTOR=nuclino SOURCE=/path/to/export.zip OUTPUT=./memory/custom
  166. # Direct CLI usage
  167. python memory_connectors/memory_connect.py nuclino /path/to/export.zip --output ./memory
  168. ```
  169. #### Getting Notion Export
  170. 1. Go to your Notion workspace settings
  171. 2. Click "Settings & members" → "Settings"
  172. 3. Scroll to "Export content" and click "Export all workspace content"
  173. 4. Choose "Markdown & CSV" format
  174. 5. Click "Export" and wait for the download
  175. 6. Use the downloaded ZIP file with the connector
  176. #### Getting Nuclino Export
  177. 1. Go to your Nuclino workspace
  178. 2. Open the main menu (☰) in the top left
  179. 3. Click the three dots (⋮) next to your workspace name
  180. 4. Select "Workspace settings"
  181. 5. Click "Export Workspace" in the Export section
  182. 6. Save the generated ZIP file
  183. 7. Use the downloaded ZIP file with the connector
  184. #### GitHub Live Integration
  185. ```bash
  186. # Basic usage - single repository
  187. make connect-memory CONNECTOR=github SOURCE="microsoft/vscode" TOKEN=your_github_token
  188. # Multiple repositories
  189. make connect-memory CONNECTOR=github SOURCE="owner/repo1,owner/repo2" TOKEN=your_token
  190. # Custom output and limits
  191. make connect-memory CONNECTOR=github SOURCE="facebook/react" OUTPUT=./memory/custom MAX_ITEMS=50 TOKEN=your_token
  192. # Direct CLI usage with interactive token input
  193. python memory_connectors/memory_connect.py github "microsoft/vscode" --max-items 100
  194. # Include specific content types
  195. python memory_connectors/memory_connect.py github "owner/repo" --include-issues --include-prs --include-wiki --token your_token
  196. ```
  197. #### Getting GitHub Personal Access Token
  198. 1. Go to [GitHub Settings → Tokens](https://github.com/settings/tokens)
  199. 2. Click "Generate new token" → "Generate new token (classic)"
  200. 3. Set expiration and select scopes:
  201. - For **public repositories**: `public_repo` scope
  202. - For **private repositories**: `repo` scope (full access)
  203. 4. Click "Generate token" and copy the generated token
  204. 5. Use the token with the `--token` parameter or enter it when prompted
  205. **Note**: Keep your token secure and never commit it to version control!
  206. #### Google Docs Live Integration
  207. ```bash
  208. # Basic usage - specific folder
  209. make connect-memory CONNECTOR=google-docs SOURCE="1ABC123DEF456_folder_id" TOKEN=your_access_token
  210. # Using Google Drive folder URL
  211. make connect-memory CONNECTOR=google-docs SOURCE="https://drive.google.com/drive/folders/1ABC123DEF456" TOKEN=your_token
  212. # Custom output and limits
  213. make connect-memory CONNECTOR=google-docs SOURCE="folder_id" OUTPUT=./memory/custom MAX_ITEMS=20 TOKEN=your_token
  214. # Direct CLI usage with interactive token input
  215. python memory_connectors/memory_connect.py google-docs "1ABC123DEF456_folder_id" --max-items 15
  216. ```
  217. #### Getting Google Drive Access Token
  218. **Option 1: Google OAuth 2.0 Playground (Quick Testing)**
  219. 1. Go to [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)
  220. 2. In "Select & Authorize APIs" section:
  221. - Find "Drive API v3"
  222. - Select `https://www.googleapis.com/auth/drive.readonly`
  223. 3. Click "Authorize APIs" and sign in to your Google account
  224. 4. Click "Exchange authorization code for tokens"
  225. 5. Copy the "Access token" (valid for ~1 hour)
  226. **Option 2: Google Cloud Console (Production Use)**
  227. 1. Go to [Google Cloud Console](https://console.cloud.google.com/)
  228. 2. Create a new project or select existing one
  229. 3. Enable the "Google Drive API"
  230. 4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"
  231. 5. Configure OAuth consent screen if needed
  232. 6. Download the credentials JSON file
  233. 7. Use Google's OAuth 2.0 libraries to get access tokens
  234. **Required Scopes**: `https://www.googleapis.com/auth/drive.readonly`
  235. **Finding Folder ID from Google Drive URL**:
  236. - From URL: `https://drive.google.com/drive/folders/1ABC123DEF456ghi789`
  237. - Folder ID: `1ABC123DEF456ghi789`
  238. **Note**: Access tokens expire (usually 1 hour). For production use, implement token refresh or use service accounts.
  239. ### Memory Organization
  240. The connectors automatically organize your conversations into:
  241. - **Topics**: Conversations grouped by subject (AI Agents, Programming, Product Strategy, etc.)
  242. - **User Profile**: Your communication style and preferences
  243. - **Entity Links**: Cross-referenced relationships and projects
  244. - **Search Strategy**: Optimized for mem-agent discovery
  245. Example organized structure:
  246. ```
  247. memory/mcp-server/
  248. ├── user.md # Your profile and navigation
  249. └── entities/
  250. └── chatgpt-history/
  251. ├── index.md # Overview and usage examples
  252. ├── topics/ # Topic-organized conversation lists
  253. │ ├── dria.md
  254. │ ├── ai-agents.md
  255. │ └── programming.md
  256. └── conversations/ # Individual conversation files
  257. ├── conv_0-project-discussion.md
  258. └── conv_1-technical-planning.md
  259. ```
  260. ### Testing Your Memory
  261. After importing, test the memory system:
  262. 1. Start the mem-agent: `make run-agent`
  263. 2. Start Claude Desktop with the MCP server
  264. 3. Ask questions like:
  265. - "What can you tell me about our product roadmap?"
  266. - "What were my thoughts on AI agent frameworks?"
  267. - "Summarize my recent technical discussions"
  268. The agent should access your real conversation history instead of providing generic responses.
  269. ## Architecture
  270. ### Mem-Agent
  271. - **Dria's Memory Agent**: Specialized LLM fine-tuned for memory management and retrieval
  272. - **Local Deployment**: Runs via LM Studio (MLX) or vLLM for privacy and speed
  273. - **Multiple Variants**: 4-bit, 8-bit, and bf16 quantizations available
  274. - **Tool Integration**: Purpose-built for file operations and memory search
  275. ### Memory Structure
  276. - **Obsidian-style**: Markdown files with wikilink navigation
  277. - **Topic Organization**: Automatic categorization by subject matter
  278. - **Entity Relationships**: Cross-referenced connections between conversations
  279. - **Search Optimization**: Structured for efficient agent discovery
  280. ### MCP Integration
  281. - **FastMCP Framework**: High-performance Model Context Protocol server
  282. - **Claude Desktop**: Claude's desktop app
  283. - **Claude Code**: Anthropic's agentic coding tool that lives in your terminal
  284. #### Claude Code Setup
  285. **Prerequisites**: Start your memory server first:
  286. ```bash
  287. make run-agent # Required: vLLM or MLX model server must be running
  288. ```
  289. **Add MCP Server:**
  290. ```bash
  291. claude mcp add mem-agent \
  292. --env MEMORY_DIR="/path/to/your/memory/directory" \
  293. -- python "/path/to/mcp_server/server.py"
  294. ```
  295. **Verify & Use:**
  296. ```bash
  297. claude mcp list # Should show mem-agent as connected
  298. ```
  299. Now Claude Code can access your memory system for contextual assistance during development.
  300. - **Tool Execution**: Sandboxed code execution for memory operations
  301. - **Debug Logging**: Comprehensive logging for troubleshooting
  302. #### ChatGPT Integration
  303. **Prerequisites**: Complete memory setup and start your local agent:
  304. ```bash
  305. make setup # Configure memory directory
  306. make run-agent # Start local vLLM/MLX model server
  307. ```
  308. **Start MCP-Compliant HTTP Server:**
  309. ```bash
  310. make serve-mcp-http # Starts server on localhost:8081/mcp
  311. ```
  312. **Expose with ngrok (separate terminal):**
  313. ```bash
  314. ngrok http 8081 # Copy the forwarding URL
  315. ```
  316. **Configure ChatGPT:**
  317. 1. Go to [ChatGPT Settings → Connectors](https://chatgpt.com/#settings/Connectors)
  318. 2. Enable **Developer mode** in Advanced settings
  319. 3. Add new MCP server:
  320. - **Name**: `mem-agent`
  321. - **URL**: `https://your-ngrok-url.ngrok.io/mcp`
  322. - **Protocol**: HTTP
  323. - **Authentication**: None
  324. **Usage in ChatGPT:**
  325. Select **Developer mode** → Choose `mem-agent` connector → Ask questions like:
  326. - "Use mem-agent to search my memory for discussions about AI research"
  327. - "Query my memory for information about recent project work"
  328. ## Troubleshooting
  329. ### Common Issues
  330. **Agent returns generic responses instead of using memory:**
  331. - Check that memory files exist in the configured path
  332. - Verify user.md contains proper topic navigation
  333. - Enable debug logging to see agent's reasoning process
  334. - Test with direct questions about known conversation topics
  335. **MCP connection issues:**
  336. - Check Claude Desktop configuration in `~/.config/claude/claude_desktop.json`
  337. - Verify PATH configuration includes LM Studio binary
  338. - Increase timeout settings for large memory imports
  339. - Review logs in `~/Library/Logs/Claude/mcp-server-memory-agent-stdio.log`
  340. **Memory import failures:**
  341. - Ensure export format is supported (.zip or .json for ChatGPT)
  342. - Check file permissions and disk space
  343. - Try with --max-items to limit processing scope
  344. - Verify export contains expected data structure
  345. ### Debug Mode
  346. Enable detailed logging by setting environment variables:
  347. ```bash
  348. FASTMCP_LOG_LEVEL=DEBUG make serve-mcp
  349. ```
  350. Or check the agent's internal reasoning in the log files during operation.
  351. ## Development
  352. ### Adding New Connectors
  353. 1. Create connector class inheriting from `BaseMemoryConnector`
  354. 2. Implement required methods: `extract_data()`, `organize_data()`, `generate_memory_files()`
  355. 3. Add to connector registry in `memory_connect.py`
  356. 4. Update README with usage examples
  357. Example connector skeleton:
  358. ```python
  359. from memory_connectors.base import BaseMemoryConnector
  360. class MyConnector(BaseMemoryConnector):
  361. @property
  362. def connector_name(self) -> str:
  363. return "My Service"
  364. @property
  365. def supported_formats(self) -> list:
  366. return ['.zip', '.json']
  367. def extract_data(self, source_path: str) -> Dict[str, Any]:
  368. # Parse source data
  369. pass
  370. def organize_data(self, extracted_data: Dict[str, Any]) -> Dict[str, Any]:
  371. # Organize into topics
  372. pass
  373. def generate_memory_files(self, organized_data: Dict[str, Any]) -> None:
  374. # Generate markdown files
  375. pass
  376. ```
  377. ### Contributing
  378. This system is designed as local add-ons that don't affect the main mem-agent-mcp repository:
  379. - Memory connectors are local extensions
  380. - Legacy compatibility is maintained
  381. - All changes preserve existing functionality
  382. - Debug improvements enhance troubleshooting
  383. Pull requests welcome for new connectors and improvements!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.