Mem0 文档站维护指南Mintlify 站点结构、新增页面三要素与 llms.txt 同步机制【免费下载链接】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本文基于 Mem0embedchain仓库的 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/记忆模型、图记忆、作用域scopingcookbooks/端到端示例食谱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.mdxdocs/cookbooks/ 下再细分为essentials/、companions/、operations/、integrations/、frameworks/五个子集。另有两个辅助目录值得注意docs/_snippets/ 存放可复用的 MDX 片段如async-memory-add.mdxdocs/templates/ 存放撰写新文档时套用的模板如integration_guide_template.mdx、migration_guide_template.mdx。三、新增页面的三项硬性要求否则 CI 失败这是 docs/AGENTS.md 中最核心的规则每一个新的.mdx页面必须同时满足三件事否则 CI 会失败页面本身放在正确的 section 目录下在 docs/docs.json 中增加一条导航条目navigation entry在 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对应 PlatformMemory对应 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、## OptionalOSS 专属的 LLM/Embedding/Vector DB/Reranker 提供者配置等 H2 分区组织Agent 可以按作用域只加载与用户场景相关的部分而不必拉取整份文档。四、llms.txt 同步校验的源码级解析文档与索引的同步由 scripts/check-llms-txt-coverage.py 强制保证。阅读该脚本源码可以确认其完整工作机制4.1 双向 diff 模型脚本的模块 docstring 明确定义了两类漂移driftmissingdocs/中存在、但docs/llms.txt未链接的页面staledocs/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 triageH2 下然后以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_callworkflow_dispatch。注释说明在 PR 上它由 .github/workflows/ci-gate.yml唯一的 required check统一调用手动触发时也可独立运行运行环境ubuntu-24.04-arm超时 2 分钟contents: read权限检查逻辑actions/checkoutv4拉取代码后直接执行python3 scripts/check-llms-txt-coverage.py只读模式。失败时工作流会输出一段::error titlellms.txt out of sync::诊断并逐条列出修复步骤本地运行python scripts/check-llms-txt-coverage.py --write在## Unclassified - needs triage下生成占位条目逐个占位条目处理把[TODO: Platform|OSS|Both]替换为正确的作用域标签、把描述改写为Use when ...、迁移到正确分区、清空后删除 triage 标题处理脚本列出的 stale URL更新或移除链接将更新后的docs/llms.txt提交进同一个 PR。这意味着 docs/AGENTS.md 中“docs-llms-txt-check.yml会在每个触碰docs/**/*.mdx的 PR 上运行并在llms.txt失步时阻断合并”这一描述在工作流层面得到了验证门禁不通过时 PR 的 required check 即为红色。六、撰写规范Conventionsdocs/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 文档站的维护流程可以归纳为一条闭环写作在正确 section 下按 docs/templates/ 模板新建.mdx补全title/description/iconFrontmatter代码样例与 mem0/、mem0-ts/ 源码签名保持一致导航在 docs/docs.json 的对应 Tab/Group 中登记页面路径索引在 docs/llms.txt 中加入带[Platform]/[OSS]/[Both]标签、以Use when ...开头的条目自检本地运行python scripts/check-llms-txt-coverage.py确认双向无漂移失步时可用--write生成 triage 占位再手工整理门禁PR 上由 ci-gate.yml 调用 docs-llms-txt-check.yml 复跑同一脚本失步即阻断合并。这套机制的价值在于人类读docs.json驱动的站点导航Agent 读llms.txt的带作用域索引两者由同一个脚本保证不漂移——文档站因此同时对人、对搜索引擎、对 AI Agent 保持了一致性和可检索性。【免费下载链接】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），仅供参考