Mem0 文档站维护指南Mintlify 目录结构、docs.json 导航与 llms.txt Agent 索引的 CI 同步机制【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain本文基于 Mem0 仓库中docs/目录的维护规范文档展开说明这套 Mintlify 文档站的目录组织方式、新增文档页面的完整流程以及保证docs/llms.txt这个面向 AI Agent 的索引文件与.mdx页面双向同步的校验脚本和 CI 拦截机制。读完本文你将掌握 Mem0 文档站的分层结构、导航树配置方法以及从脚本实现层面理解llms.txt 覆盖率检查是如何在 PR 门禁中阻断失同步合入的。1. 文档站总览基于 Mintlify 的发布链路Mem0 的官方文档站由 Mintlify 构建发布在 docs.mem0.ai。整个站点以仓库中的docs/目录为单一事实来源Single Source of Truth所有页面都是.mdx文件导航、主题、Logo 等站点级配置集中在docs/docs.json中。本地预览有两条等价路径来自 Makefile 与 docs/CLAUDE.md# 方式一从仓库根目录通过 Make 目标 make docs # 方式二直接调用 Mintlify CLI等价于 make docs 的内部实现 cd docs mintlify devMakefile 中docs目标的全部实现就是cd docs mintlify dev即依赖全局安装的 Mintlify CLI 在docs/目录下启动开发服务器。站点元数据站点名Mem0、aspen 主题、主色#8F74E0、Logo 路径都定义在 docs/docs.json 的顶层字段中。2. 目录结构每个目录承担一种内容职责docs/下的子目录不是随意划分的每个目录对应一类明确的内容职责路径内容api-reference/Platform REST API 端点参考open-source/自托管 SDKOSS使用指南platform/托管平台Platform使用指南integrations/每个集成一页LangChain、Vercel AI SDK、CrewAI 等core-concepts/记忆模型、图谱记忆、作用域等核心概念cookbooks/端到端实战配方contributing/贡献者指南docs.json站点导航树openapi.jsonPlatform API 的 OpenAPI 规范llms.txt面向 Agent 的带范围标签索引在这个骨架之上还有两个重要的辅助区它们不出现在导航中、也不进入llms.txt索引——这正是scripts/llms-txt-ignore.txt中登记的前缀_snippets/可复用的 MDX 片段不是独立页面templates/写作模板12 个如quickstart_template.mdx、api_reference_template.mdx面向作者而非用户changelog/版本化发布说明索引中只保留一个汇总链接。该忽略文件按行前缀匹配每行一个前缀#开头为注释check-llms-txt-coverage.py 在扫描时会把这些前缀下的.mdx从覆盖率检查中排除。3. 导航树docs.json 如何组织三个 Tabdocs/docs.json 的navigation.anchors数组定义了站点的顶部导航结构一个Documentation锚点下挂三个 Tab——Get Started、Mem0 Platform、Open Source。每个 Tab 由若干group分组如 Getting Started、Features、Configuration组成分组内列出的pages就是不带.mdx后缀的页面相对路径例如platform/quickstart对应docs/platform/quickstart.mdx。从 docs/docs.json 可以看到几个结构特点分组可嵌套OSS Tab 的 Features 组下可以再嵌 Essentials、Advanced、Data Management 子分组LLM/向量库等配置页也能三级嵌套如components/llms/models/openai页面可以跨 Tab 复用同一个页面路径如vibecoding可以同时出现在 Platform 和 Open Source 两个 Tab 中这是 Mintlify 导航支持页面在多处引用的机制每个页面/分组可配icon用于侧边栏视觉标识。因此新增页面时在docs.json中加入导航条目不是可选步骤而是让页面出现在站点上的必要步骤之一。4. 新增页面的三项硬性要求按 docs/CLAUDE.md 的规范每新增一个.mdx页面都需要同时完成三件事缺任何一项 CI 都会失败页面本身放在正确的目录下例如 LLM 提供商页放docs/components/llms/models/下导航条目在docs/docs.json的对应 Tab/分组中登记索引条目在docs/llms.txt中加一行包含范围标签[Platform]、[OSS]或[Both]和以Use when ...开头的描述。第三条要求值得单独展开llms.txt不是普通文档索引而是写给 AI Agent 看的检索入口。从 docs/llms.txt 的开头几节可以看出其设计意图——文件顶部专门有一节 For agents reading this file指导 Agent 在没有 API key 时如何用 CLI 自行签发每个链接条目都带范围标签例如- [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.标签语义固定[Platform] 仅托管版[OSS] 仅自托管[Both] 两种形态 API 一致。Agent 可以据此只加载当前用户所需的文档子集避免上下文浪费。描述统一用Use when .../Use for ...句式让 Agent 能按用户意图做路由匹配例如 docs/llms.txt 中 Getting Started 各条目的写法。写作时如果不确定页面该套哪种结构可以直接从 docs/templates/ 目录取对应模板quickstart_template.mdx、concept_guide_template.mdx、cookbook_template.mdx等 12 个模板覆盖各页面类型。5. 覆盖率检查脚本双向 diff 的实现原理同步llms.txt不是靠人肉自觉仓库提供了一个零第三方依赖纯标准库的校验脚本 scripts/check-llms-txt-coverage.py它做双向 diffmissing磁盘上存在docs/**/*.mdx页面但llms.txt中没有对应链接stalellms.txt中链接了某个 URL但磁盘上已不存在对应页面可能是页面被重命名或删除。关键实现细节均以 check-llms-txt-coverage.py 为准页面枚举canonical_repo_pages()递归docs/下所有.mdx去掉后缀得到相对路径如platform/quickstart再剔除scripts/llms-txt-ignore.txt中登记的前缀返回全部页面与应收录页面两个集合L52-L60。索引解析indexed_urls()用正则\(?https://docs\.mem0\.ai/([^)\s#]*)从llms.txt中提取所有链接路径即只认https://docs.mem0.ai/前缀的 URLL38、L63-L69。这意味着索引条目必须使用发布域名的绝对 URL不能写仓库内相对路径。差异计算missing 应收录页面 - 已链接页面stale 已链接页面 - 全部页面L111-L112。注意 stale 是相对全部页面而非应收录页面所以被忽略前缀下的页面被链接也算 stale。--write 模式默认是只读检查加--write时脚本会为 missing 页面在llms.txt末尾追加## Unclassified - needs triage区块每条占位符形如L72-L77- [Quickstart](https://docs.mem0.ai/platform/quickstart-x) [TODO: Platform|OSS|Both]: TODO - rewrite as Use when ... and move into the correct section.标题由文件名的最后一段把-/_换成空格后title()化生成。stale URL 从不自动删除脚本只报告、不清理由人工判断页面是被重命名手改链接还是被删除删条目——这是有意设计防止自动清理误删重命名页面的索引L118-L125。退出码0 已同步或--write完成脚手架1 只读模式下发现漂移L127-L143。标准修复流程也是 CI 失败时输出的指引# 只读检查发现漂移会打印 missing / stale 清单 python scripts/check-llms-txt-coverage.py # 为 missing 页面生成占位条目 python scripts/check-llms-txt-coverage.py --write生成占位后人工对每条[TODO: ...]做四件事替换为正确的范围标签、把描述改写为Use when ...句式、把条目移入正确章节、triage 区块清空后删除该 H2 标题。6. CI 拦截检查如何挂到 PR 门禁上该脚本被封装为工作流 .github/workflows/docs-llms-txt-check.yml其触发与行为以该工作流文件为准触发方式为workflow_call由 PR 门禁ci-gate.yml作为必需检查调用和workflow_dispatch手动触发在ubuntu-24.04-arm上执行超时 2 分钟核心步骤就是python3 scripts/check-llms-txt-coverage.py失败时通过::error注解输出docs/llms.txt does not match docs/**/*.mdx并附完整修复指引L25-L42。由于ci-gate.yml是 PR 的单一必需检查workflow 文件头注释说明因此任何让llms.txt失同步的 PR 都会被这个检查阻断合并——docs/CLAUDE.md中所说的blocks the merge就是这条链路的最终效果。换句话说文档页面的增删改必须与llms.txt索引条目在同一 PR 内完成脚本 工作流共同保证这一点无需 code review 额外盯防。7. 编写约定Frontmatter、组件与示例代码纪律除结构与流程外docs/CLAUDE.md 还约定了页面级的编写纪律Frontmatter 最小集合每个.mdx需要title、description通常还有icon。以 docs/open-source/overview.mdx 为例--- title: Overview description: Self-host Mem0 with full control over your infrastructure and data icon: house ---其中description会进入llms.txt风格的路由匹配和搜索结果摘要icon则是docs.json侧边栏图标的来源。优先使用 Mintlify 组件Note、Card、Tabs、CodeGroup等组件可用应优先于裸 HTML保证渲染一致性代码示例必须可运行如果示例调用了公开 SDK 方法签名必须与真实实现一致——这条纪律与下一条互相咬合公开 SDK 签名变更必须同步文档任何改动公开 SDK 签名的 PR必须在本仓库的对应文档页面同一 PR 内更新防止文档与代码签名漂移PR 政策纯文档 PR 免除了 PR 门禁中acceptedissue 的要求但不免除 CLA贡献者协议。8. 小结这套文档体系的三个设计要点把 docs/CLAUDE.md 的规范放回仓库实际代码中可以归纳出 Mem0 文档站维护机制的三个要点单一事实来源分层明确docs.json管导航、.mdx管内容、openapi.json管 API 契约、llms.txt管 Agent 索引四者职责不重叠任何新增页面只需在正确位置补齐对应条目机器可校验的人机双读索引llms.txt同时服务人类和 Agent带范围标签 Use when路由描述而覆盖率由 check-llms-txt-coverage.py 双向 diff 保证--write降低补齐成本、stale 条目保留人工判断避免了全自动同步的误删风险流程闭环到 CIdocs-llms-txt-check.yml 把检查挂进 PR 必需门禁文档页 导航 索引三者齐备才能合并使规范从口头约定变成了可执行的工程约束。对贡献者而言实际动手路径就是在正确目录写.mdx可套 docs/templates/ 模板→ 在 docs/docs.json 挂导航 → 本地跑python scripts/check-llms-txt-coverage.py看 missing/stale 清单 → 按Use when ...句式补llms.txt条目并提交同一 PR。【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考