[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-firstbatchxyz--mem-agent-mcp":3,"tool-firstbatchxyz--mem-agent-mcp":61},[4,18,26,36,44,52],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",141543,2,"2026-04-06T11:32:54",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":10,"last_commit_at":50,"category_tags":51,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":53,"name":54,"github_repo":55,"description_zh":56,"stars":57,"difficulty_score":10,"last_commit_at":58,"category_tags":59,"status":17},4292,"Deep-Live-Cam","hacksider\u002FDeep-Live-Cam","Deep-Live-Cam 是一款专注于实时换脸与视频生成的开源工具，用户仅需一张静态照片，即可通过“一键操作”实现摄像头画面的即时变脸或制作深度伪造视频。它有效解决了传统换脸技术流程繁琐、对硬件配置要求极高以及难以实时预览的痛点，让高质量的数字内容创作变得触手可及。\n\n这款工具不仅适合开发者和技术研究人员探索算法边界，更因其极简的操作逻辑（仅需三步：选脸、选摄像头、启动），广泛适用于普通用户、内容创作者、设计师及直播主播。无论是为了动画角色定制、服装展示模特替换，还是制作趣味短视频和直播互动，Deep-Live-Cam 都能提供流畅的支持。\n\n其核心技术亮点在于强大的实时处理能力，支持口型遮罩（Mouth Mask）以保留使用者原始的嘴部动作，确保表情自然精准；同时具备“人脸映射”功能，可同时对画面中的多个主体应用不同面孔。此外，项目内置了严格的内容安全过滤机制，自动拦截涉及裸露、暴力等不当素材，并倡导用户在获得授权及明确标注的前提下合规使用，体现了技术发展与伦理责任的平衡。",88924,"2026-04-06T03:28:53",[14,15,13,60],"视频",{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":77,"owner_twitter":78,"owner_website":79,"owner_url":80,"languages":81,"stars":94,"forks":95,"last_commit_at":96,"license":97,"difficulty_score":98,"env_os":99,"env_gpu":100,"env_ram":101,"env_deps":102,"category_tags":110,"github_topics":76,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":112,"updated_at":113,"faqs":114,"releases":129},4368,"firstbatchxyz\u002Fmem-agent-mcp","mem-agent-mcp","mem-agent mcp server","mem-agent-mcp 是一款专为构建个性化记忆系统设计的 AI 工具，它作为模型上下文协议（MCP）服务器，能将强大的 driaforall\u002Fmem-agent 模型无缝接入 Claude Desktop 或 Lm Studio 等应用。它的核心作用是让 AI 助手拥有类似人类的结构化长期记忆，能够像管理 Obsidian 笔记一样，精准存储和检索用户信息、人际关系及实体数据，从而在对话中保持连贯的上下文理解，解决传统 AI“聊完即忘”的痛点。\n\n这款工具特别适合开发者、AI 研究人员以及希望深度定制本地智能助手的进阶用户。其独特亮点在于采用类 Markdown 的文件结构来组织记忆库，支持动态更新而无需重启服务，并内置了灵活的隐私过滤机制——用户可通过标签指令控制敏感信息的披露程度，兼顾了智能化与数据安全。在技术实现上，它针对 macOS（Metal 后端）和 Linux（vLLM 后端）进行了优化，既支持高性能本地部署，也兼容 LiteLLM 代理方案，为不同硬件环境的用户提供了灵活的运行选择。通过简单的配置，你就能拥有一个真正“记得住”你过往交互的智能伙伴。","# mem-agent-mcp\n\nThis is an MCP server for our model [driaforall\u002Fmem-agent](https:\u002F\u002Fhuggingface.co\u002Fdriaforall\u002Fmem-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\u002FOpenAI path (no local vLLM needed), or\n  - Run vLLM on a compatible x86_64 host and point the client at it (see agent\u002Fmodel.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:\u002F\u002Flocalhost:4000\u002Fv1\u002Fmodels\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\u002Fprovider:\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:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fuser) for detailed instructions.\n    - Lm Studio:\n        - Copy the generated `mcp.json` to the `mcp.json` of Lm Studio. Check [this guide](https:\u002F\u002Flmstudio.ai\u002Fdocs\u002Fapp\u002Fplugins\u002Fmcp) 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\u002F\n    ├── user.md\n    └── entities\u002F\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\u002F[entity_name].md]]` per relationship. The link format should be followed strictly.\n- `entities\u002F` 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\u002Facme_corp.md]]\n- mother: [[entities\u002Fjane_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> tags after the user query. These filters are used to filter the retrieved information and\u002For obfuscate it completely. An example of a user query with filters is:\n\n```\nWhat's my mother's age? \u003Cfilter> 1. Do not reveal explicit age information, 2. Do not reveal any email addresses \u003C\u002Ffilter>\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\u002Fmem_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\u002Fmemory_connect.py --list\n\n#### ChatGPT History Import\n```bash\n# Basic usage\nmake connect-memory CONNECTOR=chatgpt SOURCE=\u002Fpath\u002Fto\u002Fchatgpt-export.zip\n\n# AI-powered categorization with TF-IDF (fast)\npython memory_connectors\u002Fmemory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --method ai --embedding-model tfidf\n\n# AI-powered categorization with LM Studio (high-quality semantic)\npython memory_connectors\u002Fmemory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --method ai --embedding-model lmstudio\n\n# Keyword-based with custom categories\npython memory_connectors\u002Fmemory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --method keyword --edit-keywords\n\n# Process limited conversations\npython memory_connectors\u002Fmemory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.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=\u002Fpath\u002Fto\u002Fexport.zip OUTPUT=.\u002Fmemory\u002Fcustom\n\n# Process only first 100 conversations\nmake connect-memory CONNECTOR=chatgpt SOURCE=\u002Fpath\u002Fto\u002Fexport.zip MAX_ITEMS=100\n\n# Direct CLI usage\npython memory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --output .\u002Fmemory --max-items 100\n\n#### Notion Workspace Import\n```bash\n# Basic usage\nmake connect-memory CONNECTOR=notion SOURCE=\u002Fpath\u002Fto\u002Fnotion-export.zip\n\n# Custom output location\nmake connect-memory CONNECTOR=notion SOURCE=\u002Fpath\u002Fto\u002Fexport.zip OUTPUT=.\u002Fmemory\u002Fcustom\n  \npython memory_connectors\u002Fmemory_connect.py notion \u002Fpath\u002Fto\u002Fexport.zip --output .\u002Fmemory\n```\n\n#### Getting ChatGPT Export\n1. Go to [ChatGPT Settings](https:\u002F\u002Fchatgpt.com\u002Fsettings\u002Fdata-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=\u002Fpath\u002Fto\u002Fnuclino-export.zip\n\n# Custom output location  \nmake connect-memory CONNECTOR=nuclino SOURCE=\u002Fpath\u002Fto\u002Fexport.zip OUTPUT=.\u002Fmemory\u002Fcustom\n\n# Direct CLI usage\npython memory_connectors\u002Fmemory_connect.py nuclino \u002Fpath\u002Fto\u002Fexport.zip --output .\u002Fmemory\n```\n\n#### Getting Notion Export\n1. Go to your Notion workspace settings\n2. Click \"Settings & members\" → \"Settings\"\n3. Scroll to \"Export content\" and click \"Export all workspace content\"\n4. Choose \"Markdown & 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\u002Fvscode\" TOKEN=your_github_token\n\n# Multiple repositories\nmake connect-memory CONNECTOR=github SOURCE=\"owner\u002Frepo1,owner\u002Frepo2\" TOKEN=your_token\n\n# Custom output and limits\nmake connect-memory CONNECTOR=github SOURCE=\"facebook\u002Freact\" OUTPUT=.\u002Fmemory\u002Fcustom MAX_ITEMS=50 TOKEN=your_token\n\n# Direct CLI usage with interactive token input\npython memory_connectors\u002Fmemory_connect.py github \"microsoft\u002Fvscode\" --max-items 100\n\n# Include specific content types\npython memory_connectors\u002Fmemory_connect.py github \"owner\u002Frepo\" --include-issues --include-prs --include-wiki --token your_token\n```\n\n#### Getting GitHub Personal Access Token\n1. Go to [GitHub Settings → Tokens](https:\u002F\u002Fgithub.com\u002Fsettings\u002Ftokens)\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:\u002F\u002Fdrive.google.com\u002Fdrive\u002Ffolders\u002F1ABC123DEF456\" TOKEN=your_token\n\n# Custom output and limits\nmake connect-memory CONNECTOR=google-docs SOURCE=\"folder_id\" OUTPUT=.\u002Fmemory\u002Fcustom MAX_ITEMS=20 TOKEN=your_token\n\n# Direct CLI usage with interactive token input\npython memory_connectors\u002Fmemory_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:\u002F\u002Fdevelopers.google.com\u002Foauthplayground\u002F)\n2. In \"Select & Authorize APIs\" section:\n   - Find \"Drive API v3\"\n   - Select `https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fdrive.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:\u002F\u002Fconsole.cloud.google.com\u002F)\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:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fdrive.readonly`\n\n**Finding Folder ID from Google Drive URL**:\n- From URL: `https:\u002F\u002Fdrive.google.com\u002Fdrive\u002Ffolders\u002F1ABC123DEF456ghi789`  \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\u002Fmcp-server\u002F\n├── user.md                     # Your profile and navigation\n└── entities\u002F\n    └── chatgpt-history\u002F\n        ├── index.md            # Overview and usage examples\n        ├── topics\u002F             # Topic-organized conversation lists\n        │   ├── dria.md\n        │   ├── ai-agents.md\n        │   └── programming.md\n        └── conversations\u002F      # 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=\"\u002Fpath\u002Fto\u002Fyour\u002Fmemory\u002Fdirectory\" \\\n  -- python \"\u002Fpath\u002Fto\u002Fmcp_server\u002Fserver.py\"\n```\n\n**Verify & 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\u002FMLX model server\n```\n\n**Start MCP-Compliant HTTP Server:**\n```bash\nmake serve-mcp-http  # Starts server on localhost:8081\u002Fmcp\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:\u002F\u002Fchatgpt.com\u002F#settings\u002FConnectors)\n2. Enable **Developer mode** in Advanced settings\n3. Add new MCP server:\n   - **Name**: `mem-agent`\n   - **URL**: `https:\u002F\u002Fyour-ngrok-url.ngrok.io\u002Fmcp`\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 `~\u002F.config\u002Fclaude\u002Fclaude_desktop.json`\n- Verify PATH configuration includes LM Studio binary\n- Increase timeout settings for large memory imports\n- Review logs in `~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp-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) -> str:\n        return \"My Service\"\n    \n    @property \n    def supported_formats(self) -> list:\n        return ['.zip', '.json']\n    \n    def extract_data(self, source_path: str) -> Dict[str, Any]:\n        # Parse source data\n        pass\n    \n    def organize_data(self, extracted_data: Dict[str, Any]) -> Dict[str, Any]:\n        # Organize into topics  \n        pass\n    \n    def generate_memory_files(self, organized_data: Dict[str, Any]) -> 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","# mem-agent-mcp\n\n这是我们模型 [driaforall\u002Fmem-agent](https:\u002F\u002Fhuggingface.co\u002Fdriaforall\u002Fmem-agent) 的 MCP 服务器，可以连接到 Claude Desktop 或 Lm Studio 等应用，与类似 Obsidian 的记忆系统进行交互。\n\n## 支持的平台\n\n- macOS（Metal 后端）\n- Linux（配备 GPU，vLLM 后端）\n\n### 平台说明：aarch64（ARM64）Linux\n- 在 ARM64 Linux 上，默认不会安装 vLLM，以避免构建失败（没有稳定的 wheel 包，源码构建也可能失败）。\n- 即使不安装 vLLM，安装也能成功；你可以：\n  - 使用默认的 OpenRouter\u002FOpenAI 路径（无需本地 vLLM），或\n  - 在兼容的 x86_64 主机上运行 vLLM，并让客户端指向它（参见 agent\u002Fmodel.py 中的 create_vllm_client 方法）。\n\n## 运行说明\n\n### 使用 LiteLLM 代理（OpenAI 兼容）\n- 如果你本地运行着 LiteLLM 代理（例如在端口 4000 上），可以通过 .env 文件配置客户端：\n```\nVLLM_HOST=localhost\nVLLM_PORT=4000\n```\n- 验证连接性：\n```\ncurl http:\u002F\u002Flocalhost:4000\u002Fv1\u002Fmodels\n```\n- 然后可以选择以下方式之一：\n  - CLI：`make chat-cli`\n  - 通过 STDIO 的 MCP：`make serve-mcp`\n  - 通过 HTTP 的 MCP：`make serve-mcp-http`\n\n注意：在 ARM64 Linux 上，这是推荐的设置，而不是使用 vLLM。\n\n1. `make check-uv`（如果你已经安装了 uv，则跳过此步骤）。\n2. `make install`：在 macOS 上安装 LmStudio。\n3. `make setup`：这将打开文件选择器，要求你选择用于存储记忆的目录。\n4. `make run-agent`：如果你在 macOS 上，系统会提示你选择要使用的模型精度。经测试，4-bit 已经非常实用，而更高精度的模型虽然更可靠，但速度较慢。\n5. `make generate-mcp-json`：生成 `mcp.json` 文件。该文件将在下一步中使用。\n6. 各应用\u002F提供商的具体说明：\n    - Claude Desktop：\n        - 将生成的 `mcp.json` 复制到你的 `claude_desktop.json` 所在目录，然后退出并重新启动 Claude Desktop。详细说明请参阅 [这篇指南](https:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fuser)。\n    - Lm Studio：\n        - 将生成的 `mcp.json` 复制到 Lm Studio 的 `mcp.json` 文件中。详细说明请参阅 [这篇指南](https:\u002F\u002Flmstudio.ai\u002Fdocs\u002Fapp\u002Fplugins\u002Fmcp)。如果出现问题，可以将 .mlx_model_name 文件中的模型名称（位于本仓库根目录下）从 `mem-agent-mlx-4bit` 或 `mem-agent-mlx-8bit` 分别改为 `mem-agent-mlx@4bit` 或 `mem-agent-mlx@8bit`。\n\n\n## 记忆使用说明\n\n- 每个记忆目录应遵循以下结构：\n```\nmemory\u002F\n    ├── user.md\n    └── entities\u002F\n        └── [entity_name_1].md\n        └── [entity_name_2].md\n        └── ...\n```\n\n- `user.md` 是主文件，包含用户及其关系的信息，并通过链接指向实体文件，格式为 `[[entities\u002F[entity_name].md]]`，每种关系对应一个链接。链接格式必须严格遵守。\n- `entities\u002F` 是包含实体文件的目录。\n- 每个实体文件的结构与 `user.md` 相同。\n- 手动修改记忆内容无需重启 MCP 服务器。\n\n### 示例 user.md\n\n```markdown\n# 用户信息\n- 用户名：John Doe\n- 出生日期：1990-01-01\n- 出生地：纽约，美国\n- 居住地：恩斯赫德，荷兰\n- 星座：水瓶座\n\n## 用户关系\n- 公司：[[entities\u002Facme_corp.md]]\n- 母亲：[[entities\u002Fjane_doe.md]]\n```\n\n### 示例实体文件（jane_doe.md 和 acme_corp.md）\n\n```markdown\n# Jane Doe\n- 关系：母亲\n- 出生日期：1965-01-01\n- 出生地：纽约，美国\n```\n\n```markdown \n# Acme Corporation\n- 行业：软件开发\n- 地点：恩斯赫德，荷兰\n```\n\n## 过滤功能\n\n该模型经过训练，能够在用户查询后的 `\u003Cfilter>` 标签中接受各种领域的过滤条件。这些过滤条件用于筛选检索到的信息，甚至完全隐藏相关信息。带有过滤条件的用户查询示例如下：\n\n```\n我妈妈多大了？\u003Cfilter> 1. 不透露具体的年龄信息，2. 不透露任何电子邮件地址 \u003C\u002Ffilter>\n```\n\n要在 MCP 中使用此功能，你需要两个 make 目标：\n- `make add-filters`：打开输入循环，将用户提供的过滤条件添加到 .filters 文件中。\n- `make reset-filters`：重置 .filters 文件（清空内容）。\n\n添加或移除过滤条件无需重启 MCP 服务器。\n\n## 记忆连接器\n\n### 可用连接器\n\n| 连接器 | 描述 | 支持的格式 | 类型 |\n|-----------|-------------|-------------------|------|\n| `chatgpt` | ChatGPT 对话导出 | `.zip`, `.json` | 导出 |\n| `notion` | Notion 工作区导出 | `.zip` | 导出 |\n| `nuclino` | Nuclino 工作区导出 | `.zip` | 导出 |\n| `github` | GitHub 仓库通过 API | 实时 API | 实时 |\n| `google-docs` | Google Docs 文件夹通过 Drive API | 实时 API | 实时 |\n\n### 使用方法\n\n#### 🧙‍♂️ 交互式记忆向导（推荐）\n连接记忆来源的最简单方法：\n\n```bash\nmake memory-wizard\n# 或\npython memory_wizard.py\n```\n\n向导将引导你完成以下步骤：\n- ✅ 选择连接器并查看描述\n- ✅ 设置身份验证（令牌、权限范围）\n- ✅ 配置数据源（文件、URL、ID）\n- ✅ 设置输出目录\n- ✅ 连接器特定选项\n- ✅ 确认配置\n- ✅ 自动执行\n- ✅ 成功确认及后续步骤\n\n#### 手动 CLI 使用\n\n**快速演示：使用示例记忆**\n```bash\nmake run-agent\nmake serve-mcp-http\npython examples\u002Fmem_agent_cli.py\n```\n\n示例记忆包（`healthcare` 和 `client_success`）包含在内，用于展示 mem-agent 在不同数据类型上的功能。使用交互式 CLI 探索这些记忆并测试提示。\n\n列出可用连接器：\n```bash\nmake connect-memory\n# 或\npython memory_connectors\u002Fmemory_connect.py --list\n```\n\n#### ChatGPT 历史导入\n```bash\n# 基本用法\nmake connect-memory CONNECTOR=chatgpt SOURCE=\u002Fpath\u002Fto\u002Fchatgpt-export.zip\n\n# 基于 TF-IDF 的 AI 助力分类（快速）\npython memory_connectors\u002Fmemory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --method ai --embedding-model tfidf\n\n# 基于 LM Studio 的 AI 助力分类（高质量语义）\npython memory_connectors\u002Fmemory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --method ai --embedding-model lmstudio\n\n# 基于关键词的自定义分类\npython memory_connectors\u002Fmemory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --method keyword --edit-keywords\n\n# 处理有限数量的对话\npython memory_connectors\u002Fmemory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --max-items 100\n```\n\n**分类方法：**\n- **基于关键词**：快速，可使用预定义关键词自定义分类\n- **AI 助力（TF-IDF）**：统计聚类，发现对话模式\n- **AI 助力（LM Studio）**：通过神经网络进行语义嵌入（需要 LM Studio）\n\n# 自定义输出位置\nmake connect-memory CONNECTOR=chatgpt SOURCE=\u002Fpath\u002Fto\u002Fexport.zip OUTPUT=.\u002Fmemory\u002Fcustom\n\n# 仅处理前 100 条对话\nmake connect-memory CONNECTOR=chatgpt SOURCE=\u002Fpath\u002Fto\u002Fexport.zip MAX_ITEMS=100\n\n# 直接使用命令行\npython memory_connect.py chatgpt \u002Fpath\u002Fto\u002Fexport.zip --output .\u002Fmemory --max-items 100\n\n#### Notion 工作区导入\n```bash\n# 基本用法\nmake connect-memory CONNECTOR=notion SOURCE=\u002Fpath\u002Fto\u002Fnotion-export.zip\n\n# 自定义输出位置\nmake connect-memory CONNECTOR=notion SOURCE=\u002Fpath\u002Fto\u002Fexport.zip OUTPUT=.\u002Fmemory\u002Fcustom\n  \npython memory_connectors\u002Fmemory_connect.py notion \u002Fpath\u002Fto\u002Fexport.zip --output .\u002Fmemory\n```\n\n#### 获取 ChatGPT 导出文件\n1. 前往 [ChatGPT 设置](https:\u002F\u002Fchatgpt.com\u002Fsettings\u002Fdata-controls)\n2. 点击“导出数据”\n3. 等待包含下载链接的邮件\n4. 解压 ZIP 文件\n5. 使用解压后的文件夹或 ZIP 文件与连接器配合使用\n\n#### Nuclino 工作区导入\n```bash\n# 基本用法\nmake connect-memory CONNECTOR=nuclino SOURCE=\u002Fpath\u002Fto\u002Fnuclino-export.zip\n\n# 自定义输出位置  \nmake connect-memory CONNECTOR=nuclino SOURCE=\u002Fpath\u002Fto\u002Fexport.zip OUTPUT=.\u002Fmemory\u002Fcustom\n\n# 直接使用命令行\npython memory_connectors\u002Fmemory_connect.py nuclino \u002Fpath\u002Fto\u002Fexport.zip --output .\u002Fmemory\n```\n\n#### 获取 Notion 导出文件\n1. 进入你的 Notion 工作区设置\n2. 点击“设置与成员”→“设置”\n3. 滚动到“导出内容”并点击“导出全部工作区内容”\n4. 选择“Markdown & CSV”格式\n5. 点击“导出”并等待下载完成\n6. 使用下载的 ZIP 文件与连接器配合使用\n\n#### 获取 Nuclino 导出文件\n1. 打开你的 Nuclino 工作区\n2. 在左上角打开主菜单 (☰)\n3. 点击工作区名称旁边的三个点 (⋮)\n4. 选择“工作区设置”\n5. 在“导出工作区”部分点击“导出工作区”\n6. 保存生成的 ZIP 文件\n7. 使用下载的 ZIP 文件与连接器配合使用\n\n#### GitHub 实时集成\n```bash\n# 基本用法 - 单个仓库\nmake connect-memory CONNECTOR=github SOURCE=\"microsoft\u002Fvscode\" TOKEN=your_github_token\n\n# 多个仓库\nmake connect-memory CONNECTOR=github SOURCE=\"owner\u002Frepo1,owner\u002Frepo2\" TOKEN=your_token\n\n# 自定义输出和限制\nmake connect-memory CONNECTOR=github SOURCE=\"facebook\u002Freact\" OUTPUT=.\u002Fmemory\u002Fcustom MAX_ITEMS=50 TOKEN=your_token\n\n# 直接使用命令行，并交互式输入令牌\npython memory_connectors\u002Fmemory_connect.py github \"microsoft\u002Fvscode\" --max-items 100\n\n# 包含特定内容类型\npython memory_connectors\u002Fmemory_connect.py github \"owner\u002Frepo\" --include-issues --include-prs --include-wiki --token your_token\n```\n\n#### 获取 GitHub 个人访问令牌\n1. 前往 [GitHub 设置 → 令牌](https:\u002F\u002Fgithub.com\u002Fsettings\u002Ftokens)\n2. 点击“生成新令牌”→“生成新令牌（经典版）”\n3. 设置过期时间并选择作用范围：\n   - 对于 **公共仓库**：选择 `public_repo` 范围\n   - 对于 **私有仓库**：选择 `repo` 范围（完全访问权限）\n4. 点击“生成令牌”，复制生成的令牌\n5. 将令牌与 `--token` 参数一起使用，或在提示时输入\n\n**注意**：请妥善保管您的令牌，切勿将其提交到版本控制系统中！\n\n#### Google Docs 实时集成\n```bash\n# 基本用法 - 特定文件夹\nmake connect-memory CONNECTOR=google-docs SOURCE=\"1ABC123DEF456_folder_id\" TOKEN=your_access_token\n\n# 使用 Google Drive 文件夹 URL\nmake connect-memory CONNECTOR=google-docs SOURCE=\"https:\u002F\u002Fdrive.google.com\u002Fdrive\u002Ffolders\u002F1ABC123DEF456\" TOKEN=your_token\n\n# 自定义输出和限制\nmake connect-memory CONNECTOR=google-docs SOURCE=\"folder_id\" OUTPUT=.\u002Fmemory\u002Fcustom MAX_ITEMS=20 TOKEN=your_token\n\n# 直接使用命令行，并交互式输入令牌\npython memory_connectors\u002Fmemory_connect.py google-docs \"1ABC123DEF456_folder_id\" --max-items 15\n```\n\n#### 获取 Google Drive 访问令牌\n\n**选项 1：Google OAuth 2.0 Playground（快速测试）**\n1. 前往 [Google OAuth 2.0 Playground](https:\u002F\u002Fdevelopers.google.com\u002Foauthplayground\u002F)\n2. 在“选择并授权 API”部分：\n   - 找到“Drive API v3”\n   - 选择 `https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fdrive.readonly`\n3. 点击“授权 API”，并登录您的 Google 账号\n4. 点击“交换授权码以获取令牌”\n5. 复制“访问令牌”（有效期约 1 小时）\n\n**选项 2：Google Cloud 控制台（生产环境使用）**\n1. 前往 [Google Cloud 控制台](https:\u002F\u002Fconsole.cloud.google.com\u002F)\n2. 创建一个新项目或选择现有项目\n3. 启用“Google Drive API”\n4. 进入“凭据”→“创建凭据”→“OAuth 2.0 客户端 ID”\n5. 如有必要，配置 OAuth 同意屏幕\n6. 下载凭据 JSON 文件\n7. 使用 Google 的 OAuth 2.0 库获取访问令牌\n\n**所需作用范围**：`https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fdrive.readonly`\n\n**从 Google Drive URL 中提取文件夹 ID**：\n- 例如，URL：`https:\u002F\u002Fdrive.google.com\u002Fdrive\u002Ffolders\u002F1ABC123DEF456ghi789`\n- 文件夹 ID：`1ABC123DEF456ghi789`\n\n**注意**：访问令牌会过期（通常为 1 小时）。对于生产环境，建议实现令牌刷新机制或使用服务账号。\n\n### 内存组织\n\n连接器会自动将您的对话整理成：\n\n- **主题**：按主题分组的对话（如 AI 代理、编程、产品战略等）\n- **用户档案**：您的沟通风格和偏好\n- **实体链接**：交叉引用的关系和项目\n- **搜索策略**：优化用于 mem-agent 发现\n\n示例组织结构：\n```\nmemory\u002Fmcp-server\u002F\n├── user.md                     # 您的个人资料和导航\n└── entities\u002F\n    └── chatgpt-history\u002F\n        ├── index.md            # 概述和使用示例\n        ├── topics\u002F             # 按主题组织的对话列表\n        │   ├── dria.md\n        │   ├── ai-agents.md\n        │   └── programming.md\n        └── conversations\u002F      # 个别对话文件\n            ├── conv_0-project-discussion.md\n            └── conv_1-technical-planning.md\n```\n  \n### 测试您的内存\n\n导入完成后，请测试内存系统：\n\n1. 启动 mem-agent：`make run-agent`\n2. 使用 MCP 服务器启动 Claude Desktop\n3. 提出问题，例如：\n   - “你能告诉我关于我们产品路线图的信息吗？”\n   - “我对 AI 代理框架有什么看法？”\n   - “总结一下我最近的技术讨论”\n\n该代理应能访问您真实的对话历史，而不是给出通用的回答。\n\n## 架构\n\n### Mem-Agent\n- **Dria 的 Memory Agent**：专为内存管理和检索而微调的专用 LLM\n- **本地部署**：通过 LM Studio (MLX) 或 vLLM 运行，以确保隐私和速度\n- **多种版本**：提供 4 位、8 位和 bf16 量化版本\n- **工具集成**：专为文件操作和内存搜索设计\n\n### 内存结构\n- **Obsidian 风格**：带有维基链接导航的 Markdown 文件\n- **主题组织**：按主题自动分类\n- **实体关系**：对话之间的交叉引用连接\n- **搜索优化**：为高效的 agent 发现而构建\n\n### MCP 集成\n- **FastMCP 框架**: 高性能模型上下文协议服务器\n- **Claude Desktop**: Claude 的桌面应用\n- **Claude Code**: Anthropic 提供的代理式编码工具，运行在终端中\n\n#### Claude Code 设置\n\n**先决条件**: 首先启动你的记忆服务器：\n```bash\nmake run-agent  # 必需：vLLM 或 MLX 模型服务器必须正在运行\n```\n\n**添加 MCP 服务器：**\n```bash\nclaude mcp add mem-agent \\\n  --env MEMORY_DIR=\"\u002Fpath\u002Fto\u002Fyour\u002Fmemory\u002Fdirectory\" \\\n  -- python \"\u002Fpath\u002Fto\u002Fmcp_server\u002Fserver.py\"\n```\n\n**验证与使用：**\n```bash\nclaude mcp list  # 应显示 mem-agent 已连接\n```\n\n现在，Claude Code 可以访问你的记忆系统，在开发过程中获得上下文帮助。\n- **工具执行**: 用于记忆操作的沙箱代码执行\n- **调试日志**: 全面的日志记录以便排查问题\n\n#### ChatGPT 集成\n\n**先决条件**: 完成记忆设置并启动本地代理：\n```bash\nmake setup      # 配置记忆目录\nmake run-agent  # 启动本地 vLLM\u002FMLX 模型服务器\n```\n\n**启动符合 MCP 标准的 HTTP 服务器：**\n```bash\nmake serve-mcp-http  # 在 localhost:8081\u002Fmcp 上启动服务器\n```\n\n**使用 ngrok 暴露（在另一个终端中）：**\n```bash\nngrok http 8081  # 复制转发 URL\n```\n\n**配置 ChatGPT：**\n1. 前往 [ChatGPT 设置 → 连接器](https:\u002F\u002Fchatgpt.com\u002F#settings\u002FConnectors)\n2. 在高级设置中启用 **开发者模式**\n3. 添加新的 MCP 服务器：\n   - **名称**: `mem-agent`\n   - **URL**: `https:\u002F\u002Fyour-ngrok-url.ngrok.io\u002Fmcp`\n   - **协议**: HTTP\n   - **认证**: 无\n\n**在 ChatGPT 中使用：**\n选择 **开发者模式** → 选择 `mem-agent` 连接器 → 提出类似以下的问题：\n- “使用 mem-agent 搜索我的记忆中关于 AI 研究的讨论”\n- “查询我的记忆中关于最近项目工作的信息”\n\n## 故障排除\n\n### 常见问题\n\n**代理返回通用回复而非使用记忆：**\n- 检查配置路径中是否存在记忆文件\n- 确认 user.md 是否包含正确的主题导航\n- 启用调试日志以查看代理的推理过程\n- 尝试直接询问已知对话主题进行测试\n\n**MCP 连接问题：**\n- 检查 Claude Desktop 的配置文件 `~\u002F.config\u002Fclaude\u002Fclaude_desktop.json`\n- 确认 PATH 配置中包含 LM Studio 二进制文件\n- 增加超时设置以处理大型记忆导入\n- 查看日志文件 `~\u002FLibrary\u002FLogs\u002FClaude\u002Fmcp-server-memory-agent-stdio.log`\n\n**记忆导入失败：**\n- 确保导出格式受支持（ChatGPT 支持 .zip 或 .json）\n- 检查文件权限和磁盘空间\n- 尝试使用 --max-items 限制处理范围\n- 验证导出文件是否包含预期的数据结构\n\n### 调试模式\n\n通过设置环境变量启用详细日志记录：\n```bash\nFASTMCP_LOG_LEVEL=DEBUG make serve-mcp\n```\n\n或者在运行期间检查代理的日志文件以了解其内部推理过程。\n\n## 开发\n\n### 添加新连接器\n\n1. 创建继承自 `BaseMemoryConnector` 的连接器类\n2. 实现所需方法：`extract_data()`、`organize_data()`、`generate_memory_files()`\n3. 将其添加到 `memory_connect.py` 中的连接器注册表\n4. 更新 README 文件以提供使用示例\n\n连接器示例框架：\n```python\nfrom memory_connectors.base import BaseMemoryConnector\n\nclass MyConnector(BaseMemoryConnector):\n    @property\n    def connector_name(self) -> str:\n        return \"My Service\"\n    \n    @property \n    def supported_formats(self) -> list:\n        return ['.zip', '.json']\n    \n    def extract_data(self, source_path: str) -> Dict[str, Any]:\n        # 解析源数据\n        pass\n    \n    def organize_data(self, extracted_data: Dict[str, Any]) -> Dict[str, Any]:\n        # 按主题整理\n        pass\n    \n    def generate_memory_files(self, organized_data: Dict[str, Any]) -> None:\n        # 生成 Markdown 文件\n        pass\n```\n\n### 贡献\n\n本系统设计为不影响主 mem-agent-mcp 仓库的本地插件：\n\n- 记忆连接器是本地扩展\n- 保持对旧版的兼容性\n- 所有更改均不破坏现有功能\n- 调试改进有助于问题排查\n\n欢迎提交拉取请求以添加新连接器或进行改进！","# mem-agent-mcp 快速上手指南\n\nmem-agent-mcp 是一个模型上下文协议（MCP）服务器，用于连接 [driaforall\u002Fmem-agent](https:\u002F\u002Fhuggingface.co\u002Fdriaforall\u002Fmem-agent) 模型。它允许 Claude Desktop、Lm Studio 等应用与类 Obsidian 的记忆系统进行交互，实现基于个人知识库的智能对话。\n\n## 环境准备\n\n### 系统要求\n- **macOS**: 需配备 Apple Silicon (ARM64) 芯片，使用 Metal 后端。\n- **Linux**: 需配备 GPU，推荐使用 x86_64 架构以支持 vLLM 后端。\n  - *注意*: ARM64 (aarch64) Linux 默认不安装 vLLM（因构建不稳定），建议通过 LiteLLM 代理或远程 x86_64 主机运行模型。\n\n### 前置依赖\n- Python 环境（推荐配合 `uv` 包管理器使用）\n- Git\n- 目标客户端软件（Claude Desktop 或 Lm Studio）\n\n## 安装步骤\n\n1. **检查并安装 uv (可选)**\n   如果已安装 `uv` 可跳过此步。\n   ```bash\n   make check-uv\n   ```\n\n2. **安装项目依赖**\n   在 macOS 上这将自动配置 LmStudio 相关组件。\n   ```bash\n   make install\n   ```\n\n3. **配置记忆存储目录**\n   运行设置命令，通过文件选择器指定记忆文件的存储路径。\n   ```bash\n   make setup\n   ```\n\n4. **启动 Agent 并选择模型精度**\n   运行 Agent，根据提示选择模型精度（推荐 `4-bit`，兼顾速度与可用性；高精度模型更可靠但较慢）。\n   ```bash\n   make run-agent\n   ```\n\n5. **生成 MCP 配置文件**\n   生成 `mcp.json` 文件，用于后续客户端连接。\n   ```bash\n   make generate-mcp-json\n   ```\n\n6. **连接客户端**\n   将生成的 `mcp.json` 复制到对应应用的配置目录：\n   - **Claude Desktop**: 复制到 `claude_desktop.json` 所在目录，重启应用。\n   - **Lm Studio**: 复制到 Lm Studio 的 `mcp.json` 位置。\n     *注*: 若遇问题，请将根目录下 `.mlx_model_name` 文件中的模型名从 `mem-agent-mlx-4bit` 改为 `mem-agent-mlx@4bit`（8bit 同理）。\n\n## 基本使用\n\n### 1. 初始化记忆结构\n确保你的记忆目录包含以下结构（手动创建或通过导入工具生成）：\n```text\nmemory\u002F\n    ├── user.md              # 用户主档案\n    └── entities\u002F            # 实体文件夹\n        ├── [entity_1].md\n        └── [entity_2].md\n```\n- `user.md`: 包含用户信息及关系链接（格式严格为 `[[entities\u002Fname.md]]`）。\n- `entities\u002F`: 存放具体实体（如人物、公司）的详细 Markdown 文件。\n- *提示*: 修改这些文件无需重启 MCP 服务。\n\n### 2. 导入外部数据（可选）\n使用内置向导快速导入 ChatGPT、Notion、GitHub 等数据源：\n```bash\nmake memory-wizard\n```\n或者手动导入 ChatGPT 导出包示例：\n```bash\nmake connect-memory CONNECTOR=chatgpt SOURCE=\u002Fpath\u002Fto\u002Fchatgpt-export.zip\n```\n\n### 3. 开始对话\n配置完成后，在支持的客户端（Claude Desktop \u002F Lm Studio）中即可直接提问。系统会自动检索记忆库并回答。\n\n**高级用法：添加过滤规则**\n若需在查询时隐藏特定信息（如年龄、邮箱），可使用过滤功能：\n```bash\n# 添加过滤规则\nmake add-filters\n\n# 清除过滤规则\nmake reset-filters\n```\n*示例查询*: `What's my mother's age? \u003Cfilter> 1. Do not reveal explicit age information \u003C\u002Ffilter>`\n\n### 4. 本地代理模式（ARM64 Linux 推荐）\n如果在 ARM64 Linux 上运行，建议使用 LiteLLM 代理而非本地 vLLM：\n1. 配置 `.env`:\n   ```\n   VLLM_HOST=localhost\n   VLLM_PORT=4000\n   ```\n2. 验证连接:\n   ```bash\n   curl http:\u002F\u002Flocalhost:4000\u002Fv1\u002Fmodels\n   ```\n3. 启动服务:\n   ```bash\n   make serve-mcp\n   ```","自由职业开发者李明正在使用 Claude Desktop 协助管理其复杂的跨项目客户网络与长期技术债务，他需要 AI 助手能像人类一样“记住”过往的合作细节和个人偏好。\n\n### 没有 mem-agent-mcp 时\n- **记忆碎片化**：每次开启新对话，AI 都忘记了他三个月前在\"Acme 公司”项目中约定的特定代码规范，导致重复沟通成本极高。\n- **关系网断裂**：当询问“之前那位住在荷兰的合作伙伴是谁”时，AI 无法关联分散在不同聊天记录中的实体信息，只能回答不知道。\n- **隐私控制缺失**：在生成报告时，AI 偶尔会意外泄露客户的私人邮箱或确切年龄，缺乏细粒度的过滤机制来保护敏感数据。\n- **手动上下文注入繁琐**：为了保持连贯性，李明不得不每次手动复制粘贴大量的背景文档到提示词中，操作效率低下且容易出错。\n\n### 使用 mem-agent-mcp 后\n- **持久化类脑记忆**：mem-agent-mcp 将李明的客户信息和项目细节以 Obsidian 式的 Markdown 文件（如 `user.md` 和 `entities\u002F`）本地存储，AI 能随时精准调用半年前的合作约定。\n- **实体关系自动关联**：基于构建的知识图谱，当李明询问荷兰的合作伙伴时，AI 能立即通过链接定位到具体实体文件，准确回答是\"Acme Corporation\"及其相关背景。\n- **动态隐私过滤**：利用 `\u003Cfilter>` 标签功能，李明可以指令 AI“不要透露具体年龄”，mem-agent-mcp 会在检索记忆时自动屏蔽敏感字段，确保输出合规。\n- **无缝集成工作流**：配置一次后，Claude Desktop 即可通过 MCP 协议直接读取本地记忆库，无需手动搬运上下文，让对话始终保持高度连贯和个性化。\n\nmem-agent-mcp 通过将静态文档转化为 AI 可理解的动态长期记忆，彻底解决了大模型在垂直场景中“聊完即忘”的核心痛点。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffirstbatchxyz_mem-agent-mcp_7fc7be35.png","firstbatchxyz","FirstBatch","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ffirstbatchxyz_a32d16c7.png","",null,"info@firstbatch.xyz","driaforall","dria.co","https:\u002F\u002Fgithub.com\u002Ffirstbatchxyz",[82,86,90],{"name":83,"color":84,"percentage":85},"Python","#3572A5",97.6,{"name":87,"color":88,"percentage":89},"Makefile","#427819",2.3,{"name":91,"color":92,"percentage":93},"Shell","#89e051",0,622,100,"2026-04-06T04:38:52","Apache-2.0",4,"macOS, Linux","macOS: 需要支持 Metal 后端的 Apple Silicon (ARM64) 芯片；Linux: 需要 NVIDIA GPU 以运行 vLLM 后端。未明确具体显存大小，但提及可使用 4-bit 量化模型以降低资源需求。","未说明",{"notes":103,"python":104,"dependencies":105},"1. Windows 系统不支持。2. ARM64 Linux 默认不安装 vLLM（因构建困难），建议使用 LiteLLM 代理连接外部模型或在 x86_64 主机运行 vLLM。3. macOS 用户通过 Makefile 安装 LM Studio 并选择模型精度（推荐 4-bit）。4. 支持通过 MCP 协议连接 Claude Desktop 或 LM Studio。5. 提供多种记忆导入连接器（ChatGPT, Notion, GitHub 等）。","未说明 (项目使用 uv 和 Makefile 管理环境)",[106,107,108,109],"vLLM (Linux GPU 可选)","LiteLLM (代理模式)","LM Studio (macOS 推荐)","OpenRouter\u002FOpenAI API (替代方案)",[35,13,111],"插件","2026-03-27T02:49:30.150509","2026-04-06T19:58:14.130837",[115,120,124],{"id":116,"question_zh":117,"answer_zh":118,"source_url":119},19864,"如何更改 LMStudio 的端口号？","虽然脚本默认将端口改为 8000，但你可以通过编辑项目根目录下的 Python 文件中的 `MCP_PORT` 变量来指定不同的端口。如果你不熟悉编程，可以直接修改相关配置文件以避开端口冲突。","https:\u002F\u002Fgithub.com\u002Ffirstbatchxyz\u002Fmem-agent-mcp\u002Fissues\u002F6",{"id":121,"question_zh":122,"answer_zh":123,"source_url":119},19865,"如何切换 MCP 服务器使用的模型？","运行 `make run-agent` 命令时，选择的模型会被保存到项目根目录下的 `.mlx_model_name` 文件中。你可以通过手动编辑该文件来更改模型，或者更推荐的做法是：重新运行 `make run-agent` 并按照屏幕上的提示选择新模型。",{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},19866,"Linux 用户遇到 'TclError: no display name' 错误且 'make setup-cli' 无效怎么办？","这是一个已知问题，维护者已修复了 `make setup-cli` 的目标规则。请拉取最新的 main 分支代码（git pull），修复后该命令即可在无图形界面的 Linux 环境中正常工作，允许你在终端中直接输入路径进行配置。","https:\u002F\u002Fgithub.com\u002Ffirstbatchxyz\u002Fmem-agent-mcp\u002Fissues\u002F7",[]]