MemOS 开发环境搭建指南：从 Fork 仓库到本地调试的完整流程与数据库选型详解

人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin【免费下载链接】MemOSSelf-evolving memory OS for LLM AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址https://gitcode.com/gh_mirrors/memos/MemOS点击查看免费下载本篇指南以 MemOS 开源仓库的 开发环境搭建文档 为核心骨架系统讲解如何从 Fork 仓库、安装 Poetry、执行make install到根据内存模块类型选择配套数据库图数据库 / 向量数据库最终以docker composemake serve在本地跑通服务。读完本文你将掌握 MemOS 文本记忆Textual Memory与偏好记忆Preference Memory的分类逻辑、数据库依赖矩阵以及一套可复现的tree 记忆 Neo4j Community Qdrant 本地内嵌模式零额外服务开发环境。一、前置准备Fork 与克隆仓库参与 MemOS 开发的第一步是在代码托管平台 Fork 仓库再把你的 Fork 克隆到本地并关联上游仓库以便同步最新代码# 克隆你自己的 Fork git clone https://github.com/YOUR-USERNAME/MemOS.git cd MemOS # 添加上游仓库作为 remote方便后续拉取主仓库更新 git remote add upstream https://github.com/MemTensor/MemOS.git建议按惯例维护三个分支状态main跟随上游、dev本地开发、feature/*功能分支并通过git fetch upstream定期同步。更完整的协作流程可参考 development_workflow.md。二、开发依赖与 Poetry 安装本地环境至少需要以下基础工具Git版本管理上文克隆已用到Python 3.9验证命令python3 --version。注意仓库 pyproject.toml 中声明的是requires-python 3.10因此实际开发建议使用Python 3.10 及以上官方 pip 安装示例推荐 3.11Make用于执行项目根目录 Makefile 中定义的安装、测试、启动等命令。MemOS 使用Poetry管理依赖与虚拟环境官方推荐使用官方安装脚本安装curl -sSL https://install.python-poetry.org | python3 -安装完成后验证poetry --version如果出现poetry: command not found说明 Poetry 可执行目录Linux/macOS 通常为~/.local/bin不在PATH中。请按安装脚本提示将对应目录追加到PATH然后重启终端再次验证。安装依赖与 pre-commit 钩子在仓库根目录执行make install对应的 Makefile 目标实际执行两条命令install: poetry install --extras all --with dev --with test poetry run pre-commit install --install-hooks--extras all安装全部可选依赖组tree-mem、mem-reader、mem-scheduler、pref-mem 等详见 pyproject.toml 的[project.optional-dependencies]适合完整功能开发--with dev --with test一并安装开发与测试依赖组pre-commit、pytest、pytest-cov、ruff 等第二步自动安装 pre-commit 钩子在每次提交时执行代码检查。重要提示如果你切换了分支或者依赖声明发生了变化需要重新运行make install以保证虚拟环境与当前代码的依赖一致。三、先弄清内存模块与数据库选型在配置环境之前必须先理解 MemOS 的内存模块分类以及它们对应的数据库依赖——这直接决定了你需要安装哪些组件。相关配置项可在 环境变量解析源码 中找到对应实现。3.1 内存类型括号内为backend配置标识文本记忆Textual Memory基于事实的记忆必须二选一。treetree_text树状记忆官方推荐结构化程度最高generalgeneral_text通用记忆基于向量检索naivenaive_text朴素记忆无特殊依赖仅用于测试。偏好记忆Preference Memory用户偏好可选。pref用于存储与检索用户偏好。从源码看配置解析 中默认的文本记忆后端即tree_text其内部依赖extractor_llmLLM 抽取、dispatcher_llmLLM 分发、graph_db图数据库、embedder向量化、reranker重排等组件这解释了为什么 tree 记忆需要同时准备 LLM、图数据库与向量相关服务。3.2 数据库依赖矩阵不同内存类型对数据库支持的要求如下内存类型组件依赖说明Tree图数据库必需。支持 Neo4j Desktop、Neo4j Community、PolarDBGeneral向量数据库必需。推荐使用 Qdrant或其他兼容向量库Naive无无需安装任何数据库PrefMilvus若启用偏好记忆必须安装 Milvus3.3 Tree 记忆的图数据库三选一如果你选择功能最强大的tree记忆这也是大多数开发者选择的方式需要准备一个图数据库。当前有三种方案Neo4j DesktopPC 端推荐直接在个人电脑安装自带完整 GUI 与功能上手最简单PolarDB阿里云提供的图数据库服务付费Neo4j Community开源免费适合服务器或 Linux 环境。特别说明使用Neo4j Desktop时它通常会独立管理图数据使用Neo4j Community时它不具备原生向量检索能力因此需要额外搭配一个向量数据库如 Qdrant来补充向量检索能力。四、本教程推荐的配置方案为了让开发者快速起步本教程采用如下组合内存类型treetree_text图数据库Neo4j Community通过 Docker 运行向量数据库Qdrant本地内嵌模式由于 Neo4j Community 缺少向量能力我们引入 Qdrant。为了避免再额外启动一个 Qdrant 服务Docker 容器将 Qdrant 配置为本地内嵌模式直接读写本地文件。此时无需安装额外的 Qdrant 服务器——从源码看QDRANT_HOST 环境变量 的默认值即为localhost当未提供外部配置时系统会自动创建本地数据库。4.1 创建.env配置文件.env配置文件需要放在MemOS 项目根目录。快速配置内容可参考 Docker 安装文档中的 env 配置示例详细的逐项说明见 REST API Server 本地运行文档。cd MemOS touch .env一个适用于本教程组合的.env示例LLM 侧以 OpenAI 兼容接口为例# LLMChat / Memory Reader 共用 OPENAI_API_KEYsk-xxx OPENAI_API_BASEhttp://xxx:3000/v1 MOS_CHAT_MODELqwen3-max # Memory Reader记忆抽取模型 MEMRADER_MODELqwen3-max MEMRADER_API_KEYsk-xxx MEMRADER_API_BASEhttp://xxx:3000/v1 # Embedder向量化 MOS_EMBEDDER_MODELtext-embedding-v4 # 可选值ollama | universal_api MOS_EMBEDDER_BACKENDuniversal_api MOS_EMBEDDER_API_BASEhttp://xxx:8081/v1 MOS_EMBEDDER_API_KEYxxx EMBEDDING_DIMENSION1024 # Reranker 后端http_bge 等 MOS_RERANKER_BACKENDcosine_local # 图数据库Neo4j Community # 可选值neo4j-community | neo4j | nebular | polardb NEO4J_BACKENDneo4j-community # backendneo4j* 时必填 NEO4J_URIbolt://localhost:7687 NEO4J_USERneo4j NEO4J_PASSWORD12345678 NEO4J_DB_NAMEneo4j MOS_NEO4J_SHARED_DBfalse # 可选功能 # 是否使用 Redis 调度器 DEFAULT_USE_REDIS_QUEUEfalse # 是否启用 Chat API ENABLE_CHAT_APItrue CHAT_MODEL_LIST[{backend: qwen, api_base: https://xxx/v1, api_key: sk-xxx, model_name_or_path: qwen3-max, extra_body: {enable_thinking: true} ,support_models: [qwen3-max]}]关键参数的源码依据说明NEO4J_BACKEND/GRAPH_DB_BACKEND在 config.py 中解析支持neo4j-community、neo4j、polardb、postgres四种图数据库后端映射EMBEDDING_DIMENSION与neo4j_vec_db文档排错提示指出若检索失败需检查 get_neo4j_community_config 方法 中neo4j_vec_db与EMBEDDING_DIMENSION是否配置正确——Neo4j Community 的向量能力依赖本地内嵌 Qdrant向量维度必须与 Embedder 输出维度一致MOS_NEO4J_SHARED_DB控制在多用户场景下是否共享 Neo4j 数据库实例源码位置。提示如果你使用 Qdrant 作为独立服务而非本地内嵌模式需要在 docker-compose 环境变量中设置QDRANT_HOST与QDRANT_PORT本教程方案无需设置系统自动使用本地内嵌库。五、配置 Dockerfiledocker 目录仓库的 Dockerfile 位于docker目录分为精简模式与全量模式两种基础镜像每种又区分 arm 与 x86 架构# 进入 docker 目录 cd dockerSlim Package精简包简化 nvidia 等重量级依赖镜像轻量适合快速本地部署。registry.cn-shanghai.aliyuncs.com/memtensor/memos-base:v1.0x86registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0armFull Package全量包将 MemOS 全部依赖打入镜像功能完整配置好 Dockerfile 即可直接构建启动。registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base:v1.0.0x86registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base-arm:v1.0.0arm示例使用 arm 精简包请按你的架构替换 base 镜像FROM registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0 WORKDIR /app ENV HF_ENDPOINThttps://hf-mirror.com ENV PYTHONPATH/app/src COPY src/ ./src/ EXPOSE 8000 CMD [uvicorn, memos.api.server_api:app, --host, 0.0.0.0, --port, 8000, --reload]对照仓库自带的 Dockerfile基础镜像是python:3.11-slim安装编译工具链gcc/g/libffi-dev 等后通过docker/requirements.txt安装依赖再复制src/代码并设置PYTHONPATH/app/src最终以同样的 uvicorn 命令启动。两者共同点在于HF_ENDPOINThttps://hf-mirror.com使用 Hugging Face 镜像加速模型下载PYTHONPATH/app/src保证memos包可被导入。六、启动 Docker 客户端如果本机尚未安装 Docker请先安装对应版本。安装完成后可通过客户端或命令行启动# 命令行启动 Dockersystemd 环境 sudo systemctl start docker # 检查 Docker 状态 docker ps # 查看本地镜像可选 docker images七、构建并启动依赖服务仓库根目录的 docker-compose.yml 已预置了 Neo4j 与 Qdrant 两个依赖服务服务镜像端口说明neo4jneo4j:5.26.67474HTTP、7687Bolt默认账号neo4j密码12345678并配置了健康检查qdrantqdrant/qdrant:v1.15.36333REST、6334gRPC数据持久化到qdrant_data卷在本教程方案中Qdrant 使用本地内嵌模式因此只需启动 Neo4j。构建命令同样需要在 docker 目录下执行# 在 docker 目录中 docker compose up neo4j如需完整依赖例如切换为独立 Qdrant 服务也可执行docker compose up届时 compose 会通过env_file: ../.env加载你在根目录配置的环境变量。八、新开终端启动 MemOS 服务Neo4j 就绪后另开一个终端进入项目根目录启动服务cd MemOS make servemake serve对应的 Makefile 目标实际执行serve: poetry run uvicorn memos.api.server_api:app即通过 Poetry 虚拟环境运行 uvicorn加载 memos.api.server_api 中的 FastAPI 应用。服务启动后可访问OpenAPI 交互文档http://localhost:8000/docs健康检查 / 接口调试http://localhost:8000用 curl 验证记忆写入与检索写入curl --location --request POST http://127.0.0.1:8000/product/add \ --header Content-Type: application/json \ --data-raw { messages: [{role: user, content: I like eating strawberries}], user_id: 8736b16e-1d20-4163-980b-a5063c3facdc, writable_cube_ids: [b32d0977-435d-4828-a86f-4f47f8b55bca] }检索curl --location --request POST http://127.0.0.1:8000/product/search \ --header Content-Type: application/json \ --data-raw { query: What do I like to eat, user_id: 8736b16e-1d20-4163-980b-a5063c3facdc, readable_cube_ids: [b32d0977-435d-4828-a86f-4f47f8b55bca], top_k: 20 }成功时返回code: 200检索结果位于data.text_mem每条记忆包含memory记忆正文、metadata用户 ID、类型、置信度、标签等与relativity相关性分数等字段。九、日常开发常用 Make 目标搭建完环境后可复用 Makefile 中已定义的目标完成日常开发闭环test: # 运行全部测试poetry run pytest tests test-report: # 生成带覆盖率与耗时统计的 HTML 测试报告 test-cov: # 运行测试并输出终端覆盖率 format: # ruff check --fix ruff format 自动格式化 pre_commit: # poetry run pre-commit run -a 手动触发全部钩子 openapi: # 导出 OpenAPI 规范到 docs/openapi.json对应的测试代码位于 tests 目录API、chunkers、embedders、graph_dbs、mem_cube、mem_scheduler 等均有覆盖提交前建议先跑make format与make test。更多规范请参阅 commit_guidelines.md 与 writing_tests.md。十、常见问题与排错poetry: command not foundPoetry 可执行目录未加入PATH按安装脚本提示添加Linux/macOS 通常是~/.local/bin重启终端后验证。ModuleNotFoundError: No module named memosPython 导入路径问题。请确认PYTHONPATH指向仓库的src目录export PYTHONPATH/你本地绝对路径/MemOS/srcDocker 环境下由 Dockerfile 中的ENV PYTHONPATH/app/src保证。Neo4j Community 检索失败Community 版无原生向量能力必须搭配 Qdrant。若使用独立 Qdrant 服务需确认QDRANT_HOST/QDRANT_PORT环境变量已设置若使用本地内嵌模式本教程方案需确保EMBEDDING_DIMENSION与 Embedder 输出维度一致源码排错位置见 get_neo4j_community_config。make serve后端口占用或依赖未更新先确认docker compose up neo4j成功、Neo4j 健康检查通过compose 已配置 healthcheck依赖变更或切换分支后请重新执行make install。至此你已经拥有了一个可运行的 MemOS 本地开发环境可以基于tree_text记忆 Neo4j Community Qdrant 本地内嵌模式进行功能开发与调试。后续可参考 getting_started 目录 下的示例文档如 examples.md、your_first_memory.md继续探索记忆写入、检索与更多 API 用法。赞分享人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-plugin【免费下载链接】MemOSSelf-evolving memory OS for LLM AI Agents: ultra-persistent memory, hybrid-retrieval, and cross-task skill reuse, with 35.24% token savings and DeepSeek Harness support.项目地址https://gitcode.com/gh_mirrors/memos/MemOS点击查看免费下载相关推荐MemOS 开发环境配置指南从 Fork 仓库到本地服务启动的完整实操MemOS 开发环境配置指南从 Fork 仓库到本地服务启动的完整实操 本文是 MemOS 贡献者与二次开发者的环境配置实战指南围绕 环境配置指南 http人工智能大模型Agent 记忆AI AgentRAG知识图谱dsh-pluginOumi 开发环境搭建指南从 Fork 仓库到云端 GPU 联调的全流程实践Oumi 开发环境搭建指南从 Fork 仓库到云端 GPU 联调的全流程实践 本文是一份面向 OumiOumi OSS开源 LLM 微调、评估与部署框架人工智能大模型预训练微调强化学习模型推理服务模型评测MCP 服务分布式训练模型量化oauth2-proxy 贡献指南从 Fork 到本地调试环境的完整搭建oauth2 proxy 贡献指南从 Fork 到本地调试环境的完整搭建 oauth2 proxy 是一个以 Go 编写的反向代理提供基于 Google、A后端API网关认证鉴权上一篇突破Switch文件传输瓶颈NS-USBLoader全场景实战指南下一篇4步构建全能音乐中心MusicFree插件系统完全配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考