> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to development documentation. Use it only with the matching development source. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# 参考

> ReMe 稳定的 workspace、配置、CLI、HTTP 和 MCP 契约。

本页只记录用户可以依赖的稳定语义，并指向当前版本的权威接口。具体参数以运行时 schema 和源码为准。

## Workspace

默认 workspace 是启动目录下的 `.reme/`，可在启动时覆盖：

```bash theme={null}
reme start workspace_dir=/path/to/workspace
```

Workspace 使用以下顶层目录：

| 目录             | 语义                            | 用户是否应编辑    |
| -------------- | ----------------------------- | ---------- |
| `session/`     | 记忆流程使用的来源对话                   | 通常只读       |
| `mem_session/` | Agent wrapper 生成的 session 和配置 | 不要当作用户记忆   |
| `resource/`    | 导入的原始资料                       | 可以添加、替换或删除 |
| `daily/`       | 由对话和资料生成的主题卡片与日期索引            | 可以检查和修正    |
| `digest/`      | 可长期复用的个人事实、流程与知识              | 主要人工编辑入口   |
| `metadata/`    | 索引、图谱、catalog 等派生状态           | 不应手工编辑     |

<Note>
  `metadata/` 可以从用户文件重建，不应被当作唯一记忆来源。备份时至少保留 `session/`、`resource/`、`daily/` 和 `digest/`；`mem_session/` 是生成的运行态，不是持久用户记忆。
</Note>

## Markdown 记忆

记忆文件使用普通 Markdown，可带 YAML frontmatter：

```markdown theme={null}
---
name: Build checks
description: 提交代码前的检查约定
---

# Build checks

提交前运行 pytest。该约定记录在 [[daily/2026-07-13/build-checks.md]] 中。
```

* 路径始终相对于 workspace；读写命令只接受 workspace 内路径。
* `.md` 可以省略，ReMe 会在需要时补全。
* `[[path/to/file.md]]` 表示 workspace 内的 wikilink。
* Wikilink 按 workspace 相对字面路径解析；ReMe 不会自动推断 `.md`、按文件名搜索或解析文件夹笔记。
* frontmatter 的 `name` 和 `description` 是常用摘要字段；其他元数据是否稳定，应以 schema 和实际写入工具为准。
* 移动或删除带链接的文件时优先使用 ReMe 的 `move` / `delete` action，以便检查相关链接。

## 配置

未传入 `config=` 时，ReMe 会加载内置 `default` 配置。通过 `config=` 指定的文件会替代内置默认配置，因此必须包含完整的应用配置。命令行点号参数会继续覆盖最终选中的配置：

```bash theme={null}
# 使用内置默认配置，仅覆盖端口
reme start service.port=8181

# 使用完整的自定义配置，再覆盖其中的端口
reme start config=/path/to/config.yaml service.port=8181
```

常用顶层配置包括：

| 配置                              | 含义                    |
| ------------------------------- | --------------------- |
| `workspace_dir`                 | workspace 根目录         |
| `timezone`                      | daily 和定时任务使用的时区      |
| `service.backend`               | `http` 或 `mcp`        |
| `service.host` / `service.port` | 服务监听地址                |
| `service.transport`             | MCP transport         |
| `jobs`                          | 后台、定时和公开 action       |
| `components`                    | LLM、embedding、存储和图谱实现 |

Embedding 检索默认关闭。启用时需同时配置 `components.as_embedding` 和 `components.embedding_store`，再将 `components.file_store.default.embedding_store` 设为 `default`。向量维度必须与所选模型一致。

字符串中的 `${VAR}` 和 `${VAR:-default}` 会从环境变量展开。包含密钥的配置和 `.env` 不应提交到版本库。

权威配置来源：

* [`reme/config/default.yaml`](https://github.com/agentscope-ai/ReMe/blob/main/reme/config/default.yaml)：默认 job、组件和参数；
* [`reme/schema/application_config.py`](https://github.com/agentscope-ai/ReMe/blob/main/reme/schema/application_config.py)：顶层配置结构；
* [`reme/config/config_parser.py`](https://github.com/agentscope-ai/ReMe/blob/main/reme/config/config_parser.py)：合并、点号覆盖和环境变量规则。

## CLI

CLI 形式统一为：

```text theme={null}
reme <action> key=value nested.key=value
```

常用入口：

```bash theme={null}
reme help          # 当前服务公开的 action
reme version       # 版本
reme health_check  # 组件状态
reme status        # 组件内存估算和进程 RSS
reme find_reme     # 定位运行中的 ReMe 进程
reme reindex       # 清理并重建文件索引
reme traverse      # 查看 wikilink 邻域
reme graph_snapshot # 返回以分类为根的 digest 图
reme chat          # 与只读 workspace agent 流式对话，需要 LLM
```

`reme search` 支持 `start_date` 和 `end_date` 两个闭区间 `YYYY-MM-DD` 过滤参数。实时 watcher 索引 `daily/` 和 `digest/` 下的 Markdown；`reme reindex` 还会扫描 `resource/` 和 JSONL。`reme read` 只读 Markdown；对其他文本结果，先用 `reme stat` 检查大小，再用会返回完整文件的 `reme load`。

Auto Resource 会监听直接放在 `resource/` 或 `resource/YYYY-MM-DD/` 下的 `md`、`txt`、`json`、`jsonl`、`csv`、`yaml` 和 `html` 文件。Auto Memory 将来源消息保存到 `session/dialog/`，但会从 transcript 中排除召回的 tool result 和 base64 数据。生成的 daily 文件名来自经过校验的内容名称；`session_id`、`source_conversation` 和 `source_resource` 等来源字段才是稳定查询标识。

`start` 之外的 action 会连接正在运行的服务。运行时 `reme help` 和 `reme/config/default.yaml` 是 action 与参数的权威清单。

## HTTP 与 MCP

默认 HTTP 服务将公开 job 暴露为 `POST /{action}`。服务运行后访问：

* `/`：当 Web 构建可用时打开 ReMe Studio；
* `/docs`：交互式 OpenAPI 页面；
* `/openapi.json`：机器可读 schema。

MCP 服务通过以下方式启动：

```bash theme={null}
reme start service.backend=mcp service.transport=streamable-http
```

默认 MCP URL 为 `http://127.0.0.1:2333/mcp`。工具清单由 MCP 客户端在连接时自动发现。`chat` 等流式 job 不会暴露为 MCP tool。

## 兼容性与变更

* Python 要求和依赖范围以 [`pyproject.toml`](https://github.com/agentscope-ai/ReMe/blob/main/pyproject.toml) 为准。
* 请求、响应和持久化结构以 [`reme/schema/`](https://github.com/agentscope-ai/ReMe/tree/main/reme/schema) 为准。
* 行为边界以 [`tests/`](https://github.com/agentscope-ai/ReMe/tree/main/tests) 为准。
* 版本变化见 [GitHub Releases](https://github.com/agentscope-ai/ReMe/releases)。