企业官网建设流程全解析

• 人工智能
• 大模型
• Agent 记忆
• AI Agent
• RAG
• 知识图谱
• dsh-plugin

本篇指南以 MemOS 开源仓库的 开发环境搭建文档 为核心骨架，系统讲解如何从 Fork 仓库、安装 Poetry、执行make install，到根据内存模块类型选择配套数据库（图数据库 / 向量数据库），最终以docker compose+make 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.11）；
• Make：用于执行项目根目录 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）：基于事实的记忆，必须二选一。
  • tree（tree_text）：树状记忆（官方推荐），结构化程度最高；
  • general（general_text）：通用记忆，基于向量检索；
  • naive（naive_text）：朴素记忆，无特殊依赖（仅用于测试）。
• 偏好记忆（Preference Memory）：用户偏好，可选。
  • pref：用于存储与检索用户偏好。

从源码看，配置解析 中默认的文本记忆后端即tree_text，其内部依赖extractor_llm（LLM 抽取）、dispatcher_llm（LLM 分发）、graph_db（图数据库）、embedder（向量化）、reranker（重排）等组件，这解释了为什么 tree 记忆需要同时准备 LLM、图数据库与向量相关服务。

3.2 数据库依赖矩阵

不同内存类型对数据库支持的要求如下：

3.3 Tree 记忆的图数据库三选一

如果你选择功能最强大的tree记忆（这也是大多数开发者选择的方式），需要准备一个图数据库。当前有三种方案：

• Neo4j Desktop（PC 端推荐）：直接在个人电脑安装，自带完整 GUI 与功能，上手最简单；
• PolarDB：阿里云提供的图数据库服务（付费）；
• Neo4j Community：开源免费，适合服务器或 Linux 环境。

特别说明：

• 使用Neo4j Desktop时，它通常会独立管理图数据；
• 使用Neo4j Community时，它不具备原生向量检索能力，因此需要额外搭配一个向量数据库（如 Qdrant）来补充向量检索能力。

四、本教程推荐的配置方案

为了让开发者快速起步，本教程采用如下组合：

• 内存类型：tree（tree_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 兼容接口为例）：

# ========== LLM（Chat / Memory Reader 共用） ========== OPENAI_API_KEY=sk-xxx OPENAI_API_BASE=http://xxx:3000/v1 MOS_CHAT_MODEL=qwen3-max # Memory Reader（记忆抽取）模型 MEMRADER_MODEL=qwen3-max MEMRADER_API_KEY=sk-xxx MEMRADER_API_BASE=http://xxx:3000/v1 # ========== Embedder（向量化） ========== MOS_EMBEDDER_MODEL=text-embedding-v4 # 可选值：ollama | universal_api MOS_EMBEDDER_BACKEND=universal_api MOS_EMBEDDER_API_BASE=http://xxx:8081/v1 MOS_EMBEDDER_API_KEY=xxx EMBEDDING_DIMENSION=1024 # Reranker 后端（http_bge 等） MOS_RERANKER_BACKEND=cosine_local # ========== 图数据库（Neo4j Community） ========== # 可选值：neo4j-community | neo4j | nebular | polardb NEO4J_BACKEND=neo4j-community # backend=neo4j* 时必填 NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=12345678 NEO4J_DB_NAME=neo4j MOS_NEO4J_SHARED_DB=false # ========== 可选功能 ========== # 是否使用 Redis 调度器 DEFAULT_USE_REDIS_QUEUE=false # 是否启用 Chat API ENABLE_CHAT_API=true 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；本教程方案无需设置，系统自动使用本地内嵌库。

五、配置 Dockerfile（docker 目录）

仓库的 Dockerfile 位于docker目录，分为精简模式与全量模式两种基础镜像，每种又区分 arm 与 x86 架构：

# 进入 docker 目录 cd docker

• Slim Package（精简包）：简化 nvidia 等重量级依赖，镜像轻量，适合快速本地部署。
  • registry.cn-shanghai.aliyuncs.com/memtensor/memos-base:v1.0（x86）
  • registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0（arm）
• Full Package（全量包）：将 MemOS 全部依赖打入镜像，功能完整，配置好 Dockerfile 即可直接构建启动。
  • registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base:v1.0.0（x86）
  • registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base-arm:v1.0.0（arm）

示例（使用 arm 精简包，请按你的架构替换 base 镜像）：

FROM registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0 WORKDIR /app ENV HF_ENDPOINT=https://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_ENDPOINT=https://hf-mirror.com使用 Hugging Face 镜像加速模型下载，PYTHONPATH=/app/src保证memos包可被导入。

六、启动 Docker 客户端

如果本机尚未安装 Docker，请先安装对应版本。安装完成后，可通过客户端或命令行启动：

# 命令行启动 Docker（systemd 环境） sudo systemctl start docker # 检查 Docker 状态 docker ps # 查看本地镜像（可选） docker images

七、构建并启动依赖服务

仓库根目录的 docker-compose.yml 已预置了 Neo4j 与 Qdrant 两个依赖服务：

在本教程方案中，Qdrant 使用本地内嵌模式，因此只需启动 Neo4j。构建命令同样需要在 docker 目录下执行：

# 在 docker 目录中 docker compose up neo4j

如需完整依赖（例如切换为独立 Qdrant 服务），也可执行docker compose up，届时 compose 会通过env_file: ../.env加载你在根目录配置的环境变量。

八、新开终端启动 MemOS 服务

Neo4j 就绪后，另开一个终端进入项目根目录启动服务：

cd MemOS make serve

make 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。

十、常见问题与排错

1. poetry: command not found：Poetry 可执行目录未加入PATH，按安装脚本提示添加（Linux/macOS 通常是~/.local/bin），重启终端后验证。

2. ModuleNotFoundError: No module named 'memos'：Python 导入路径问题。请确认PYTHONPATH指向仓库的src目录：

   export PYTHONPATH=/你本地绝对路径/MemOS/src

   Docker 环境下由 Dockerfile 中的ENV PYTHONPATH=/app/src保证。

3. Neo4j Community 检索失败：Community 版无原生向量能力，必须搭配 Qdrant。若使用独立 Qdrant 服务，需确认QDRANT_HOST/QDRANT_PORT环境变量已设置；若使用本地内嵌模式（本教程方案），需确保EMBEDDING_DIMENSION与 Embedder 输出维度一致（源码排错位置见 get_neo4j_community_config）。

4. 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 Agent
• RAG
• 知识图谱
• dsh-plugin