文档编写指南

本项目使用 Nuxt Content 构建支持 Markdown 和富 Vue 组件的文档系统。

创建新文档

创建 Markdown 文件

在 content/ 目录或其子目录中创建新的 .md 文件。根据内容类型选择合适的位置。

添加 Frontmatter

在文件顶部添加 YAML frontmatter 来提供元数据。frontmatter 支持以下字段：

Frontmatter 字段

必填字段：

title（字符串） - 显示在导航和页面标题中的文档标题

可选字段：

desc（字符串） - 文档内容的简要描述
banner（字符串） - 页面顶部展示的横幅图片链接
links（数组） - 包含标签、URL 和图标的相关链接数组

Frontmatter 示例

完整 Frontmatter 示例：

---
title: MemOS 文档
desc: 欢迎阅读 MemOS 的官方文档——一个旨在赋能大语言模型（LLMs）实现高级、模块化记忆能力的 Python 包。
banner: https://statics.memtensor.com.cn/memos/memos-banner.gif
links:
  - label: 'PyPI'
    to: https://pypi.org/project/MemoryOS/
    target: _blank
    avatar:
      src: https://statics.memtensor.com.cn/icon/pypi.svg
      alt: PyPI logo
  - label: '开源地址'
    to: https://github.com/MemTensor/MemOS
    target: _blank
    icon: i-simple-icons-github
---

编写内容

使用 Markdown 语法和 MDC 组件撰写文档内容。利用已有组件构建结构清晰、交互友好、内容丰富的文档。

更新导航

将新文档添加到 content/settings.yml 中的 nav 部分，以便在站点导航中访问。

合并到主分支

一旦变更合并到 main 分支，文档将自动更新并部署。

组件示例

本项目使用 Nuxt Content 的 MDC（Markdown Components）语法，支持在 Markdown 中使用 Vue 组件。这些组件有助于创建风格一致、结构良好、体验优秀的文档内容。

Image

为文档添加图片时，可以使用多种方式进行引用：

使用 Base64Image 组件引用本地图片

对于存储在 public/assets 目录下的图片，推荐使用 Base64Image 组件，该组件能将图片直接嵌入页面以提高性能：

:Base64Image{src="/assets/memos-architecture.png" alt="MemOS Architecture"}

使用 Markdown 语法引用远程图片

对于托管在外部服务器上的图片，使用标准的 Markdown 图片语法：

![MemOS Architecture](https://statics.memtensor.com.cn/memos/memos-architecture.png)

Steps

使用 steps 组件将文档标题自动编号，生成逐步引导的教程。

Fork 并克隆仓库

在本地设置项目仓库：

在 GitHub 上 fork 仓库
将你的 fork 克隆到本地：

git clone https://github.com/YOUR-USERNAME/MemOS.git
cd MemOS

添加上游仓库作为远程源：

git remote add upstream https://github.com/MemTensor/MemOS.git

准备开发依赖

确保本地已安装：

Git
Python 3.9+
Make

验证 Python：

python3 --version

安装 Poetry

MemOS 使用 Poetry 管理 Python 依赖。推荐使用官方安装脚本：

curl -sSL https://install.python-poetry.org | python3 -

验证安装是否成功：

poetry --version

如果提示 poetry: command not found，请将安装器输出中提示的 Poetry 可执行文件目录加入 PATH，然后重新打开终端再验证。

更多安装选项参考：官方安装指南。

安装依赖并设置 Pre-commit 钩子

在仓库根目录安装所有依赖与开发工具：

make install

提示：

如果你切换分支或依赖发生变化，可能需要重新运行 make install 以保持环境一致

::steps{level="4"}

#### Fork 并克隆仓库

在本地设置项目仓库：

- 在 GitHub 上 fork 仓库
- 将你的 fork 克隆到本地：

```bash
git clone https://github.com/YOUR-USERNAME/MemOS.git
cd MemOS
```

- 添加上游仓库作为远程源：

```bash
git remote add upstream https://github.com/MemTensor/MemOS.git
```

#### 准备开发依赖

确保本地已安装：

- Git
- Python 3.9+
- Make

验证 Python：

```bash
python3 --version
```

#### 安装 Poetry

MemOS 使用 Poetry 管理 Python 依赖。推荐使用官方安装脚本：

```bash
curl -sSL https://install.python-poetry.org | python3 -
```

验证安装是否成功：

```bash
poetry --version
```

如果提示 `poetry: command not found`，请将安装器输出中提示的 Poetry 可执行文件目录加入 PATH，然后重新打开终端再验证。

更多安装选项参考：[官方安装指南](https://python-poetry.org/docs/#installing-with-the-official-installer)。

#### 安装依赖并设置 Pre-commit 钩子

在仓库根目录安装所有依赖与开发工具：

```bash
make install
```

提示：

- 如果你切换分支或依赖发生变化，可能需要**重新运行 `make install`** 以保持环境一致
::

Accordion

使用 accordion 和 accordion-item 创建可折叠内容区域。适用于组织 FAQ、可展开详情或分组信息等场景。

::accordion

:::accordion-item{label="MemOS 是否兼容通过 API 访问的大语言模型（LLM）？" icon="i-lucide-circle-help"}
是的。MemOS 的设计目标是尽可能兼容各种类型的模型。然而需要注意的是，如果你使用的是基于 API 的模型，那么激活记忆和参数记忆将无法使用。
:::

:::accordion-item{label="MemOS 如何提升大语言模型应用的效果？" icon="i-lucide-circle-help"}
MemOS 通过提供结构化、持久化的记忆，配合智能调度、长期知识保留机制以及用于快速推理的 KV cache，有效增强了大语言模型的应用能力。它支持细粒度的访问控制与用户隔离机制，确保在多用户环境中的记忆安全。其模块化架构支持无缝集成新的记忆类型、LLM 和存储后端，能够适配多种智能应用场景。
:::

:::accordion-item{label="MemOS 的定价是多少？" icon="i-lucide-circle-help"}
MemOS 开源版本是免费的。
:::

::

Badge

使用 badge 展示状态指示或标签。在内容中高亮版本号、状态或分类信息时非常实用。

v1.0.0

::badge
**v1.0.0**
::

Callout

使用 callout 可以强调重要的上下文信息。Callout 用于引起用户注意，例如备注、提示、警告或注意事项，使关键信息更加突出。

你可以通过 icon 和 color 属性自定义样式，或者使用预定义的语义样式 note、tip、warning、caution 进行快捷调用。

这是一个支持完整 markdown 的 callout 提示框。

::callout
这是一个支持完整 **markdown** 的 `callout` 提示框。
::

基础备注内容

带链接的备注 —— 点击跳转到快速开始指南

带自定义图标的备注 —— 了解更多关于 MemCube 的信息

这里是一个有用的建议。

请谨慎操作，此行为可能导致意外结果。

此操作无法撤销。

::note
基础备注内容
::

::note{to="/open_source/getting_started/quick_start"}
带链接的备注 —— 点击跳转到快速开始指南
::

::note{to="/open_source/modules/mem_cube" icon="ri:database-line"}
带自定义图标的备注 —— 了解更多关于 MemCube 的信息
::

::tip
这里是一个有用的建议。
::

::warning
请小心执行此操作，它可能会导致意外结果。
::

::caution
此操作无法撤销。
::

Card

使用 card 可高亮展示内容模块。卡片适用于展示功能、资源或相关信息，以视觉上区分并增强交互性。

你可以通过 title、icon 和 color 属性自定义样式。Card 还支持使用 <NuxtLink> 属性进行导航跳转。

开源项目

使用我们的开源版本

::card
---
title: 开源项目
icon: i-simple-icons-github
to: https://github.com/MemTensor/MemOS
target: _blank
---
使用我们的开源版本
::

CardGroup

使用 card-group 可将多个卡片以网格形式排列。适合展示结构化、响应式布局的卡片集合，视觉效果良好。

最简Pipeline

最小可用Pipeline — 添加、搜索、更新和导出明文记忆。

仅 TreeTextMemory

使用基于 Neo4j 的分层记忆，构建结构化、多跳的知识图谱。

仅 KVCacheMemory

通过短期 KV cache加速会话，实现快速上下文注入。

混合 TreeText + KVCache

在单一 MemCube 中结合可解释的图记忆与快速 KV cache。

::card-group

:::card
---
icon: ri:play-line
title: 最简Pipeline 示例
to: /open_source/getting_started/examples#example-1-minimal-pipeline
---
最小可运行的Pipeline 示例——添加、搜索、更新及导出明文记忆。
:::

:::card
---
icon: ri:tree-line
title: 仅使用 TreeTextMemory
to: /open_source/getting_started/examples#example-2-treetextmemory-only
---
使用基于 Neo4j 的层级记忆构建结构化的多跳知识图谱。
:::

:::card
---
icon: ri:database-2-line
title: 仅使用 KVCacheMemory
to: /open_source/getting_started/examples#example-3-kvcachememory-only
---
通过短期KV cache加速会话，实现快速上下文注入。
:::

:::card
---
icon: hugeicons:share-07
title: 混合使用 TreeText 和 KVCache
to: /open_source/getting_started/examples#example-4-hybrid
---
在单一 MemCube 中结合可解释的图记忆与高速KV cache。
:::

::

导航图标

在 content/settings.yml 中添加导航条目时，可以使用 (ri:图标名称) 的语法嵌入图标：

- "(ri:home-line) 首页": overview.md
- "(ri:team-line) 用户管理": modules/mos/users.md
- "(ri:flask-line) 测试编写": contribution/writing_tests.md

可用图标请参考：https://icones.js.org/

本地预览

若需本地预览文档，可在项目根目录下执行以下命令。

首先安装依赖：

pnpm install

启动开发服务器：

pnpm dev

上述命令将启动本地 Web 服务器，通常访问地址为 http://127.0.0.1:3000。

深入了解

Nuxt Content 与排版系统

本项目使用 Nuxt Content，支持丰富的排版组件与样式。如需了解更多组件用法与自定义选项，请参考：

Nuxt UI Typography 文档

编写规范

文档编写建议

结构清晰：使用恰当的标题层级组织内容
合理使用组件：如 note、card 等组件提升可读性与互动性
代码示例清晰：为技术文档提供清晰的代码片段，并使用语法高亮
图标使用：在导航中使用合适的图标以增强用户体验与层次感

Quick Reference

提交前请先本地测试你的文档效果。运行 pnpm dev 以预览你的变更并确保所有组件正确渲染。

提交规范

如何编写测试

本项目使用 pytest 进行单元测试。