Mem0 文档站维护指南：Mintlify 站点结构、新增页面三要素与 llms.txt 同步机制

本文基于 Mem0（embedchain）仓库的 docs/AGENTS.md 展开，系统讲解官方文档站（发布在 docs.mem0.ai）的目录结构、新增 .mdx 页面的三项硬性要求、作者规范（Frontmatter、Mintlify 组件、代码样例签名一致性），并结合 scripts/check-llms-txt-coverage.py 源码与 CI 工作流 深入剖析 docs/llms.txt 与 .mdx 页面双向同步校验的实现原理，帮助维护者理解这套“面向 Agent 的文档索引”是如何在每次 PR 上被强制保持一致的。

一、文档站的定位与本地运行方式

Mem0 的官方文档是一个 Mintlify 站点，发布在 https://docs.mem0.ai。根据 docs/AGENTS.md 的定义，本地开发与调试文档站只有两条命令路径：

make docs          # 从仓库根目录执行
cd docs && mintlify dev

第一条命令是第二条的封装。从根目录 Makefile 的 docs 目标可以确认这一点：

docs:
	cd docs && mintlify dev

即 make docs 等价于进入 docs/ 目录后启动 Mintlify 的本地开发服务器。文档站的站点元数据（名称、主题、配色、导航树）集中定义在 docs/docs.json 中：该文件声明站点名为 Mem0、主题为 aspen、主色 #8F74E0，并以 navigation.anchors.tabs 的组织形式划分出 Get Started、Mem0 Platform、Open Source 等顶级 Tab，每个 Tab 下再按 groups（如 Core Concepts、Features、Support、Migration）组织页面。修改任何导航条目都需要直接编辑这份 JSON。

二、docs/ 目录结构总览

docs/AGENTS.md 用一张表规定了 docs/ 下各路径的语义分工，这是理解整个文档站信息架构的骨架：

路径	内容
api-reference/	Platform REST 端点参考
open-source/	自托管 SDK 指南
platform/	托管平台指南
integrations/	每个集成一页（LangChain、LlamaIndex、CrewAI、n8n 等）
core-concepts/	记忆模型、图记忆、作用域（scoping）
cookbooks/	端到端示例食谱
contributing/	贡献者指南
docs.json	导航树
openapi.json	平台 API 规范
llms.txt	面向 Agent 的、带作用域标签的索引

从仓库实际内容看，这一结构被严格执行：例如 docs/api-reference/memory/ 下按端点拆分为 add-memories.mdx、search-memories.mdx、batch-update.mdx 等文件；docs/integrations/ 下每个框架一页（langchain.mdx、crewai.mdx、n8n.mdx）；docs/cookbooks/ 下再细分为 essentials/、companions/、operations/、integrations/、frameworks/ 五个子集。另有两个辅助目录值得注意：docs/_snippets/ 存放可复用的 MDX 片段（如 async-memory-add.mdx），docs/templates/ 存放撰写新文档时套用的模板（如 integration_guide_template.mdx、migration_guide_template.mdx）。

三、新增页面的三项硬性要求（否则 CI 失败）

这是 docs/AGENTS.md 中最核心的规则：每一个新的 .mdx 页面必须同时满足三件事，否则 CI 会失败：

1. 页面本身放在正确的 section 目录下；
2. 在 docs/docs.json 中增加一条导航条目（navigation entry）；
3. 在 docs/llms.txt 中增加一行，且必须携带作用域标签（[Platform]、[OSS] 或 [Both]）与一条以 Use when ... 开头的描述。

之所以要求第三点，是因为 docs/llms.txt 不是普通的人读索引，而是“Scope-tagged index for agents”——面向 AI Agent 的文档检索入口。观察 docs/llms.txt 的实际内容可以看到这一设计意图：文件开头有一段 ## For agents reading this file，指导 Agent 根据用户的 import 语句（MemoryClient 对应 Platform，Memory 对应 OSS）决定加载哪些文档区块；随后每条索引行都严格遵循统一格式，例如：

- [Platform Quickstart](https://docs.mem0.ai/platform/quickstart) [Platform]: Use for the first Platform integration - API key plus `MemoryClient.add/search`.
- [Open Source Overview](https://docs.mem0.ai/open-source/overview) [OSS]: Use when the user needs full infra control and custom provider wiring.
- [How Mem0 Works](https://docs.mem0.ai/core-concepts/how-it-works) [Both]: Use when explaining the end-to-end pipeline: extraction (ADD-only distillation), storage across vector/entity/history stores, and multi-signal retrieval.

[Platform] 表示仅托管版适用、[OSS] 表示仅自托管适用、[Both] 表示两侧 API 表面一致。全文按 ## Getting Started、## Core Concepts、## Platform、## Open Source、## Integrations、## Cookbooks、## API Reference、## Optional（OSS 专属的 LLM/Embedding/Vector DB/Reranker 提供者配置）等 H2 分区组织，Agent 可以按作用域只加载与用户场景相关的部分，而不必拉取整份文档。

四、llms.txt 同步校验的源码级解析

文档与索引的同步由 scripts/check-llms-txt-coverage.py 强制保证。阅读该脚本源码可以确认其完整工作机制：

4.1 双向 diff 模型

脚本的模块 docstring 明确定义了两类漂移（drift）：

• missing：docs/ 中存在、但 docs/llms.txt 未链接的页面；
• stale：docs/llms.txt 中链接指向的页面已经不存在（.mdx 文件已被删除或重命名）。

具体实现上，canonical_repo_pages() 遍历 docs/ 下所有 *.mdx 文件（DOCS_DIR.rglob("*.mdx")），剥离 .mdx 后缀得到规范化路径；indexed_urls() 用正则 r"\(https://docs\.mem0\.ai/([^)\s#]*)" 从 llms.txt 全文中提取所有指向 https://docs.mem0.ai/... 的链接路径（对应源码中的 BASE_URL = "https://docs.mem0.ai/" 与 URL_RE）。两组集合相减即得 missing = included_pages - linked 与 stale = linked - all_pages。

4.2 忽略清单机制

并非所有 .mdx 文件都应当进入 llms.txt。脚本支持从 scripts/llms-txt-ignore.txt 读取“路径前缀”形式的忽略清单（# 开头为注释，每行一个前缀）。当前清单排除了三类内容，且每类都附带了排除理由注释：

#   _snippets/   — reusable MDX fragments, not standalone pages
#   templates/   — authoring templates for new docs, not user-facing
#   changelog/   — versioned release notes; one rollup link lives in the index
_snippets/
templates/
changelog/

即 MDX 片段、撰写模板和按版本拆分的 changelog 页面不单独入索引（changelog 只保留一个汇总链接）。值得注意的是，忽略清单中的前缀会把这些页面从 included_pages 中剔除（不计入 missing），但仍保留在 all_pages 中，因此如果有人手工在 llms.txt 里链向这些被忽略的页面，依然会被报为 stale——这是一个值得留意的边界行为。

4.3 两种运行模式与退出码

脚本只有两个入口形态：

python scripts/check-llms-txt-coverage.py           # 只读检查
python scripts/check-llms-txt-coverage.py --write   # 脚手架占位条目

• 只读模式（默认）：发现任何漂移即打印缺失/过期清单并以退出码 1 退出；完全同步则打印 docs/llms.txt is in sync with docs/**/*.mdx. 并以 0 退出。

• --write 模式：将缺失页面的占位条目追加到 llms.txt 末尾的 ## Unclassified - needs triage H2 下，然后以 0 退出（表示“脚手架已生成，可继续提 PR”）。format_placeholder() 生成的占位行长这样：

  - [My New Page](https://docs.mem0.ai/my/new/page) [TODO: Platform|OSS|Both]: TODO - rewrite as 'Use when ...' and move into the correct section.
  

  标题由页面路径的最后一段把 -/_ 替换为空格后 title-case 得到。若 triage 标题尚不存在，脚本还会补一段引导语（append_triage_block() 中的 preamble），提示操作者替换作用域标签、改写描述、迁移条目、清空后删除该 H2。

• stale 链接永不自动删除：无论哪种模式，脚本只报告 stale URL 而不删除，由人判断页面是被重命名（应改链接）还是真正删除（应删条目），源码注释写明 “human decides whether a page was renamed or genuinely deleted”。

脚本仅依赖 Python 标准库（argparse、pathlib、re、sys），因此任何环境都能直接运行。

五、CI 门禁：docs-llms-txt-check 工作流

本地校验之上，仓库还配有一道 CI 门禁 .github/workflows/docs-llms-txt-check.yml。其要点：

• 触发方式：on: workflow_call + workflow_dispatch。注释说明在 PR 上它由 .github/workflows/ci-gate.yml（唯一的 required check）统一调用，手动触发时也可独立运行；

• 运行环境：ubuntu-24.04-arm，超时 2 分钟，contents: read 权限；

• 检查逻辑：actions/checkout@v4 拉取代码后直接执行 python3 scripts/check-llms-txt-coverage.py（只读模式）。失败时工作流会输出一段 ::error title=llms.txt out of sync:: 诊断，并逐条列出修复步骤：

  1. 本地运行 python scripts/check-llms-txt-coverage.py --write，在 ## Unclassified - needs triage 下生成占位条目；
  2. 逐个占位条目处理：把 [TODO: Platform|OSS|Both] 替换为正确的作用域标签、把描述改写为 Use when ...、迁移到正确分区、清空后删除 triage 标题；
  3. 处理脚本列出的 stale URL（更新或移除链接）；
  4. 将更新后的 docs/llms.txt 提交进同一个 PR。

这意味着 docs/AGENTS.md 中“docs-llms-txt-check.yml 会在每个触碰 docs/**/*.mdx 的 PR 上运行并在 llms.txt 失步时阻断合并”这一描述，在工作流层面得到了验证：门禁不通过时 PR 的 required check 即为红色。

六、撰写规范（Conventions）

docs/AGENTS.md 还约定了五条文档撰写规范，其中前两条是写作时的硬性约束：

• Frontmatter 要求：每个页面需要 title、description，通常还需要 icon；
• 优先使用 Mintlify 组件：<Note>、<Card>、<Tabs>、<CodeGroup> 等组件可用，应优先于裸 HTML；
• 代码样例必须可运行：如果样例调用了公开 SDK 方法，其签名必须与真实实现一致——这一条把文档正确性与 mem0/、mem0-ts/src/ 下的 SDK 源码绑定在了一起；
• 文档类 PR 的准入豁免：纯文档 PR 免除 PR gate 中的 accepted-issue 要求，但不免除 CLA（贡献者协议）；
• SDK 签名变更的联动义务：任何公开 SDK 签名的变更，必须在同一个 PR 中更新这里对应的文档页面。

配合 docs/templates/ 中的模板文件（api_reference_template.mdx、concept_guide_template.mdx、cookbook_template.mdx、integration_guide_template.mdx、migration_guide_template.mdx 等 12 份），新页面应当先选对模板再动手撰写，以保证 Frontmatter、章节结构与既有页面风格一致。

七、小结：一套可验证的文档工程流程

把 docs/AGENTS.md 与配套资产串起来，Mem0 文档站的维护流程可以归纳为一条闭环：

1. 写作：在正确 section 下按 docs/templates/ 模板新建 .mdx，补全 title/description/icon Frontmatter，代码样例与 mem0/、mem0-ts/ 源码签名保持一致；
2. 导航：在 docs/docs.json 的对应 Tab/Group 中登记页面路径；
3. 索引：在 docs/llms.txt 中加入带 [Platform]/[OSS]/[Both] 标签、以 Use when ... 开头的条目；
4. 自检：本地运行 python scripts/check-llms-txt-coverage.py 确认双向无漂移（失步时可用 --write 生成 triage 占位再手工整理）；
5. 门禁：PR 上由 ci-gate.yml 调用 docs-llms-txt-check.yml 复跑同一脚本，失步即阻断合并。

这套机制的价值在于：人类读 docs.json 驱动的站点导航，Agent 读 llms.txt 的带作用域索引，两者由同一个脚本保证不漂移——文档站因此同时对人、对搜索引擎、对 AI Agent 保持了一致性和可检索性。