{"id":31228038,"url":"https://github.com/firstbatchxyz/mem-agent-mcp","last_synced_at":"2026-01-18T03:26:38.152Z","repository":{"id":314088076,"uuid":"1048299996","full_name":"firstbatchxyz/mem-agent-mcp","owner":"firstbatchxyz","description":"mem-agent mcp server","archived":false,"fork":false,"pushed_at":"2025-10-07T13:31:19.000Z","size":204,"stargazers_count":519,"open_issues_count":4,"forks_count":87,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-10-07T15:12:15.946Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firstbatchxyz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T08:29:31.000Z","updated_at":"2025-10-07T13:55:15.000Z","dependencies_parsed_at":"2025-09-10T15:30:39.167Z","dependency_job_id":"dd2a6e1f-2aee-4a99-8f7c-c15614f7cfb1","html_url":"https://github.com/firstbatchxyz/mem-agent-mcp","commit_stats":null,"previous_names":["firstbatchxyz/mem-agent-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/firstbatchxyz/mem-agent-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Fmem-agent-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Fmem-agent-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Fmem-agent-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Fmem-agent-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firstbatchxyz","download_url":"https://codeload.github.com/firstbatchxyz/mem-agent-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firstbatchxyz%2Fmem-agent-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28528038,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-22T05:01:42.391Z","updated_at":"2026-01-18T03:26:38.138Z","avatar_url":"https://github.com/firstbatchxyz.png","language":"Python","funding_links":[],"categories":["📚 Projects (1974 total)","Python","Other (143 servers)"],"sub_categories":["MCP Servers"],"readme":"# mem-agent-mcp\n\nThis 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.\n\n## Supported Platforms\n\n- macOS (Metal backend)\n- Linux (with GPU, vLLM backend)\n\n### Platform note: aarch64 (ARM64) Linux\n- On ARM64 Linux, vLLM is not installed by default to avoid build failures (no stable wheels and source builds can fail).\n- Installation will succeed without vLLM; you can:\n  - Use the default OpenRouter/OpenAI path (no local vLLM needed), or\n  - Run vLLM on a compatible x86_64 host and point the client at it (see agent/model.py create_vllm_client).\n\n## Running Instructions\n\n### Using a LiteLLM proxy (OpenAI-compatible)\n- If you have a LiteLLM proxy running locally (e.g., on port 4000), configure the client via .env:\n```\nVLLM_HOST=localhost\nVLLM_PORT=4000\n```\n- Verify connectivity:\n```\ncurl http://localhost:4000/v1/models\n```\n- Then use either of these:\n  - CLI: `make chat-cli`\n  - MCP over STDIO: `make serve-mcp`\n  - MCP over HTTP: `make serve-mcp-http`\n\nNote: On ARM64 Linux, this is the recommended setup instead of vLLM.\n\n1. `make check-uv` (if you have uv installed, skip this step).\n2. `make install`: Installs LmStudio on MacOS.\n3. `make setup`: This will open a file selector and ask you to select the directory where you want to store the memory. \n4. `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.\n5. `make generate-mcp-json`: Generates the `mcp.json` file. That will be used in the next step.\n6. Instructions per app/provider:\n    - Claude Desktop:\n        - 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.\n    - Lm Studio:\n        - 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.\n\n\n## Memory Instructions\n\n- Each memory directory should follow the structure below:\n```\nmemory/\n    ├── user.md\n    └── entities/\n        └── [entity_name_1].md\n        └── [entity_name_2].md\n        └── ...\n```\n\n- `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.\n- `entities/` is the directory that contains the entity files.\n- Each entity file follows the same structure as `user.md`.\n- Modifying the memory manually does not require restarting the MCP server.\n\n### Example user.md\n\n```markdown\n# User Information\n- user_name: John Doe\n- birth_date: 1990-01-01\n- birth_location: New York, USA\n- living_location: Enschede, Netherlands\n- zodiac_sign: Aquarius\n\n## User Relationships\n- company: [[entities/acme_corp.md]]\n- mother: [[entities/jane_doe.md]]\n```\n\n### Example entity files (jane_doe.md and acme_corp.md)\n\n```markdown\n# Jane Doe\n- relationship: Mother\n- birth_date: 1965-01-01\n- birth_location: New York, USA\n```\n\n```markdown \n# Acme Corporation\n- industry: Software Development\n- location: Enschede, Netherlands\n```\n\n## Filtering\n\nThe model is trained to accepts filters on various domains in between \u003cfilter\u003e 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:\n\n```\nWhat's my mother's age? \u003cfilter\u003e 1. Do not reveal explicit age information, 2. Do not reveal any email addresses \u003c/filter\u003e\n```\n\nTo use this, functionality with the MCP, you have two make targets:\n- `make add-filters`: Opens an input loop and adds the filters given by the user to the .filters file.\n- `make reset-filters`: Resets the .filters file (clears it).\n\nAdding or removing filters does not require restarting the MCP server.\n\n\n## Memory Connectors\n\n### Available Connectors\n\n| Connector | Description | Supported Formats | Type |\n|-----------|-------------|-------------------|------|\n| `chatgpt` | ChatGPT conversation exports | `.zip`, `.json` | Export |\n| `notion` | Notion workspace exports | `.zip` | Export |\n| `nuclino` | Nuclino workspace exports | `.zip` | Export |\n| `github` | GitHub repositories via API | Live API | Live |\n| `google-docs` | Google Docs folders via Drive API | Live API | Live |\n\n### Usage\n\n#### 🧙‍♂️ Interactive Memory Wizard (Recommended)\nThe easiest way to connect your memory sources:\n\n```bash\nmake memory-wizard\n# or\npython memory_wizard.py\n```\n\nThe wizard will guide you through:\n- ✅ Connector selection with descriptions\n- ✅ Authentication setup (tokens, scopes)  \n- ✅ Source configuration (files, URLs, IDs)\n- ✅ Output directory setup\n- ✅ Connector-specific options\n- ✅ Configuration confirmation\n- ✅ Automatic execution\n- ✅ Success confirmation with next steps\n\n#### Manual CLI Usage\n\n**Quick Demo with Sample Memories:**\n```bash\nmake run-agent\nmake serve-mcp-http\npython examples/mem_agent_cli.py\n```\n\nSample 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.\n\nList Available Connectors:\n```bash\nmake connect-memory\n# or\npython memory_connectors/memory_connect.py --list\n\n#### ChatGPT History Import\n```bash\n# Basic usage\nmake connect-memory CONNECTOR=chatgpt SOURCE=/path/to/chatgpt-export.zip\n\n# AI-powered categorization with TF-IDF (fast)\npython memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method ai --embedding-model tfidf\n\n# AI-powered categorization with LM Studio (high-quality semantic)\npython memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method ai --embedding-model lmstudio\n\n# Keyword-based with custom categories\npython memory_connectors/memory_connect.py chatgpt /path/to/export.zip --method keyword --edit-keywords\n\n# Process limited conversations\npython memory_connectors/memory_connect.py chatgpt /path/to/export.zip --max-items 100\n```\n\n**Categorization Methods:**\n- **Keyword-based**: Fast, customizable categories using predefined keywords\n- **AI-powered (TF-IDF)**: Statistical clustering, discovers conversation patterns\n- **AI-powered (LM Studio)**: Semantic embeddings via neural networks (requires LM Studio)\n\n# Custom output location\nmake connect-memory CONNECTOR=chatgpt SOURCE=/path/to/export.zip OUTPUT=./memory/custom\n\n# Process only first 100 conversations\nmake connect-memory CONNECTOR=chatgpt SOURCE=/path/to/export.zip MAX_ITEMS=100\n\n# Direct CLI usage\npython memory_connect.py chatgpt /path/to/export.zip --output ./memory --max-items 100\n\n#### Notion Workspace Import\n```bash\n# Basic usage\nmake connect-memory CONNECTOR=notion SOURCE=/path/to/notion-export.zip\n\n# Custom output location\nmake connect-memory CONNECTOR=notion SOURCE=/path/to/export.zip OUTPUT=./memory/custom\n  \npython memory_connectors/memory_connect.py notion /path/to/export.zip --output ./memory\n```\n\n#### Getting ChatGPT Export\n1. Go to [ChatGPT Settings](https://chatgpt.com/settings/data-controls)\n2. Click \"Export data\"\n3. Wait for email with download link\n4. Extract the ZIP file\n5. Use the extracted folder or ZIP file with the connector\n\n#### Nuclino Workspace Import\n```bash\n# Basic usage\nmake connect-memory CONNECTOR=nuclino SOURCE=/path/to/nuclino-export.zip\n\n# Custom output location  \nmake connect-memory CONNECTOR=nuclino SOURCE=/path/to/export.zip OUTPUT=./memory/custom\n\n# Direct CLI usage\npython memory_connectors/memory_connect.py nuclino /path/to/export.zip --output ./memory\n```\n\n#### Getting Notion Export\n1. Go to your Notion workspace settings\n2. Click \"Settings \u0026 members\" → \"Settings\"\n3. Scroll to \"Export content\" and click \"Export all workspace content\"\n4. Choose \"Markdown \u0026 CSV\" format\n5. Click \"Export\" and wait for the download\n6. Use the downloaded ZIP file with the connector\n\n#### Getting Nuclino Export\n1. Go to your Nuclino workspace\n2. Open the main menu (☰) in the top left\n3. Click the three dots (⋮) next to your workspace name\n4. Select \"Workspace settings\"\n5. Click \"Export Workspace\" in the Export section\n6. Save the generated ZIP file\n7. Use the downloaded ZIP file with the connector\n\n#### GitHub Live Integration\n```bash\n# Basic usage - single repository\nmake connect-memory CONNECTOR=github SOURCE=\"microsoft/vscode\" TOKEN=your_github_token\n\n# Multiple repositories\nmake connect-memory CONNECTOR=github SOURCE=\"owner/repo1,owner/repo2\" TOKEN=your_token\n\n# Custom output and limits\nmake connect-memory CONNECTOR=github SOURCE=\"facebook/react\" OUTPUT=./memory/custom MAX_ITEMS=50 TOKEN=your_token\n\n# Direct CLI usage with interactive token input\npython memory_connectors/memory_connect.py github \"microsoft/vscode\" --max-items 100\n\n# Include specific content types\npython memory_connectors/memory_connect.py github \"owner/repo\" --include-issues --include-prs --include-wiki --token your_token\n```\n\n#### Getting GitHub Personal Access Token\n1. Go to [GitHub Settings → Tokens](https://github.com/settings/tokens)\n2. Click \"Generate new token\" → \"Generate new token (classic)\"\n3. Set expiration and select scopes:\n   - For **public repositories**: `public_repo` scope\n   - For **private repositories**: `repo` scope (full access)\n4. Click \"Generate token\" and copy the generated token\n5. Use the token with the `--token` parameter or enter it when prompted\n\n**Note**: Keep your token secure and never commit it to version control!\n\n#### Google Docs Live Integration\n```bash\n# Basic usage - specific folder\nmake connect-memory CONNECTOR=google-docs SOURCE=\"1ABC123DEF456_folder_id\" TOKEN=your_access_token\n\n# Using Google Drive folder URL\nmake connect-memory CONNECTOR=google-docs SOURCE=\"https://drive.google.com/drive/folders/1ABC123DEF456\" TOKEN=your_token\n\n# Custom output and limits\nmake connect-memory CONNECTOR=google-docs SOURCE=\"folder_id\" OUTPUT=./memory/custom MAX_ITEMS=20 TOKEN=your_token\n\n# Direct CLI usage with interactive token input\npython memory_connectors/memory_connect.py google-docs \"1ABC123DEF456_folder_id\" --max-items 15\n```\n\n#### Getting Google Drive Access Token\n\n**Option 1: Google OAuth 2.0 Playground (Quick Testing)**\n1. Go to [Google OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)\n2. In \"Select \u0026 Authorize APIs\" section:\n   - Find \"Drive API v3\"\n   - Select `https://www.googleapis.com/auth/drive.readonly`\n3. Click \"Authorize APIs\" and sign in to your Google account\n4. Click \"Exchange authorization code for tokens\"\n5. Copy the \"Access token\" (valid for ~1 hour)\n\n**Option 2: Google Cloud Console (Production Use)**\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create a new project or select existing one\n3. Enable the \"Google Drive API\"\n4. Go to \"Credentials\" → \"Create Credentials\" → \"OAuth 2.0 Client ID\"\n5. Configure OAuth consent screen if needed\n6. Download the credentials JSON file\n7. Use Google's OAuth 2.0 libraries to get access tokens\n\n**Required Scopes**: `https://www.googleapis.com/auth/drive.readonly`\n\n**Finding Folder ID from Google Drive URL**:\n- From URL: `https://drive.google.com/drive/folders/1ABC123DEF456ghi789`  \n- Folder ID: `1ABC123DEF456ghi789`\n\n**Note**: Access tokens expire (usually 1 hour). For production use, implement token refresh or use service accounts.\n\n### Memory Organization\n\nThe connectors automatically organize your conversations into:\n\n- **Topics**: Conversations grouped by subject (AI Agents, Programming, Product Strategy, etc.)\n- **User Profile**: Your communication style and preferences\n- **Entity Links**: Cross-referenced relationships and projects\n- **Search Strategy**: Optimized for mem-agent discovery\n\nExample organized structure:\n```\nmemory/mcp-server/\n├── user.md                     # Your profile and navigation\n└── entities/\n    └── chatgpt-history/\n        ├── index.md            # Overview and usage examples\n        ├── topics/             # Topic-organized conversation lists\n        │   ├── dria.md\n        │   ├── ai-agents.md\n        │   └── programming.md\n        └── conversations/      # Individual conversation files\n            ├── conv_0-project-discussion.md\n            └── conv_1-technical-planning.md\n```\n  \n### Testing Your Memory\n\nAfter importing, test the memory system:\n\n1. Start the mem-agent: `make run-agent`\n2. Start Claude Desktop with the MCP server\n3. Ask questions like:\n   - \"What can you tell me about our product roadmap?\"\n   - \"What were my thoughts on AI agent frameworks?\"\n   - \"Summarize my recent technical discussions\"\n\nThe agent should access your real conversation history instead of providing generic responses.\n\n## Architecture\n\n### Mem-Agent\n- **Dria's Memory Agent**: Specialized LLM fine-tuned for memory management and retrieval\n- **Local Deployment**: Runs via LM Studio (MLX) or vLLM for privacy and speed\n- **Multiple Variants**: 4-bit, 8-bit, and bf16 quantizations available\n- **Tool Integration**: Purpose-built for file operations and memory search\n\n### Memory Structure\n- **Obsidian-style**: Markdown files with wikilink navigation\n- **Topic Organization**: Automatic categorization by subject matter\n- **Entity Relationships**: Cross-referenced connections between conversations\n- **Search Optimization**: Structured for efficient agent discovery\n\n### MCP Integration\n- **FastMCP Framework**: High-performance Model Context Protocol server\n- **Claude Desktop**: Claude's desktop app\n- **Claude Code**: Anthropic's agentic coding tool that lives in your terminal\n\n#### Claude Code Setup\n\n**Prerequisites**: Start your memory server first:\n```bash\nmake run-agent  # Required: vLLM or MLX model server must be running\n```\n\n**Add MCP Server:**\n```bash\nclaude mcp add mem-agent \\\n  --env MEMORY_DIR=\"/path/to/your/memory/directory\" \\\n  -- python \"/path/to/mcp_server/server.py\"\n```\n\n**Verify \u0026 Use:**\n```bash\nclaude mcp list  # Should show mem-agent as connected\n```\n\nNow Claude Code can access your memory system for contextual assistance during development.\n- **Tool Execution**: Sandboxed code execution for memory operations\n- **Debug Logging**: Comprehensive logging for troubleshooting\n\n#### ChatGPT Integration\n\n**Prerequisites**: Complete memory setup and start your local agent:\n```bash\nmake setup      # Configure memory directory\nmake run-agent  # Start local vLLM/MLX model server\n```\n\n**Start MCP-Compliant HTTP Server:**\n```bash\nmake serve-mcp-http  # Starts server on localhost:8081/mcp\n```\n\n**Expose with ngrok (separate terminal):**\n```bash\nngrok http 8081  # Copy the forwarding URL\n```\n\n**Configure ChatGPT:**\n1. Go to [ChatGPT Settings → Connectors](https://chatgpt.com/#settings/Connectors)\n2. Enable **Developer mode** in Advanced settings\n3. Add new MCP server:\n   - **Name**: `mem-agent`\n   - **URL**: `https://your-ngrok-url.ngrok.io/mcp`\n   - **Protocol**: HTTP\n   - **Authentication**: None\n\n**Usage in ChatGPT:**\nSelect **Developer mode** → Choose `mem-agent` connector → Ask questions like:\n- \"Use mem-agent to search my memory for discussions about AI research\"\n- \"Query my memory for information about recent project work\"\n\n## Troubleshooting\n\n### Common Issues\n\n**Agent returns generic responses instead of using memory:**\n- Check that memory files exist in the configured path\n- Verify user.md contains proper topic navigation\n- Enable debug logging to see agent's reasoning process\n- Test with direct questions about known conversation topics\n\n**MCP connection issues:**\n- Check Claude Desktop configuration in `~/.config/claude/claude_desktop.json`\n- Verify PATH configuration includes LM Studio binary\n- Increase timeout settings for large memory imports\n- Review logs in `~/Library/Logs/Claude/mcp-server-memory-agent-stdio.log`\n\n**Memory import failures:**\n- Ensure export format is supported (.zip or .json for ChatGPT)\n- Check file permissions and disk space\n- Try with --max-items to limit processing scope\n- Verify export contains expected data structure\n\n### Debug Mode\n\nEnable detailed logging by setting environment variables:\n```bash\nFASTMCP_LOG_LEVEL=DEBUG make serve-mcp\n```\n\nOr check the agent's internal reasoning in the log files during operation.\n\n## Development\n\n### Adding New Connectors\n\n1. Create connector class inheriting from `BaseMemoryConnector`\n2. Implement required methods: `extract_data()`, `organize_data()`, `generate_memory_files()`\n3. Add to connector registry in `memory_connect.py`\n4. Update README with usage examples\n\nExample connector skeleton:\n```python\nfrom memory_connectors.base import BaseMemoryConnector\n\nclass MyConnector(BaseMemoryConnector):\n    @property\n    def connector_name(self) -\u003e str:\n        return \"My Service\"\n    \n    @property \n    def supported_formats(self) -\u003e list:\n        return ['.zip', '.json']\n    \n    def extract_data(self, source_path: str) -\u003e Dict[str, Any]:\n        # Parse source data\n        pass\n    \n    def organize_data(self, extracted_data: Dict[str, Any]) -\u003e Dict[str, Any]:\n        # Organize into topics  \n        pass\n    \n    def generate_memory_files(self, organized_data: Dict[str, Any]) -\u003e None:\n        # Generate markdown files\n        pass\n```\n\n### Contributing\n\nThis system is designed as local add-ons that don't affect the main mem-agent-mcp repository:\n\n- Memory connectors are local extensions\n- Legacy compatibility is maintained\n- All changes preserve existing functionality\n- Debug improvements enhance troubleshooting\n\nPull requests welcome for new connectors and improvements!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstbatchxyz%2Fmem-agent-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirstbatchxyz%2Fmem-agent-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstbatchxyz%2Fmem-agent-mcp/lists"}