模块二：能力篇 — 会话、工具、MCP、记忆

学习理念：熟练掌握 Hermes Agent 日常使用核心能力——会话管理、工具调用、MCP 扩展和持久记忆。 海外对标：对标 Claude Code 的 Project Knowledge + Codebase Context，Hermes 在跨会话记忆和 Agent 自主管理方面更灵活。
本节 AI 替代率：~30% | 人工干预率：~70%
角色能力范围
🤖 AI 擅长工具调用配置、会话搜索、记忆条目管理
👤 人类需理解安全边界、上下文文件策略、外部记忆提供商选型

角色	能力范围
🤖 AI 擅长	工具调用配置、会话搜索、记忆条目管理
👤 人类需理解	安全边界、上下文文件策略、外部记忆提供商选型

1. 会话管理

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/sessions

每一次与 Hermes 的对话都是一个会话（Session），系统会自动保存和索引。

1.1 基本操作

bash

hermes sessions list                                    # 列出近期会话
hermes sessions browse                                  # 打开交互式会话选择器
hermes --continue                                       # 继续上次会话
hermes -c                                               # 继续上次会话的短参数
hermes --resume 20250225_143052_a1b2c3                  # 按会话 ID 恢复
hermes -r "我的项目设置"                                  # 按标题恢复
hermes sessions rename 20250225_143052_a1b2c3 "后端 API 开发"  # 重命名会话
hermes sessions delete session_id                       # 删除会话
hermes sessions prune --older-than 30                   # 清理 30 天前的旧会话

1.2 会话内斜杠命令

命令	功能
`/new`	开始新会话
`/clear`	清屏并开始新会话
`/undo`	撤销上一次用户/Agent 交互记录
`/undo [N]`	v0.16+：撤销最近 N 轮交互
`/title <session_name>`	为当前会话命名
`/history`	显示对话历史
`/sessions`	查看和管理会话
`/compress`	手动压缩上下文
`/stop`	停止后台进程
`/background <prompt>`	在后台运行任务
`/goal <text>`	v0.13+：设置持续性目标。辅助评判模型检查目标是否完成，未完成则自动继续

1.3 会话存储

Hermes 主要使用 SQLite 数据库（~/.hermes/state.db）保存会话状态：会话元数据、完整消息历史、模型配置、token / 费用统计，以及用于跨会话搜索的 FTS5 索引。数据库采用 WAL（预写日志）模式，支持并发读取和单个写入。

早期版本使用 ~/.hermes/sessions/ 下的 JSONL 文件保存逐会话转录；当前 state.db 是会话查询、恢复和搜索的主要存储。

SQLite 中主要有这几张表：

表	内容
`sessions`	会话元数据：会话 ID、来源平台、用户 ID、模型配置、系统提示词、会话标题等
`messages`	完整消息历史：所属会话、角色、正文、工具调用、工具名称、时间戳、结束原因、推理内容等
`state_meta`	键值元数据表，用于记录状态型信息
`schema_version`	数据库 schema 版本号，用于迁移判断

Hermes 还会维护 FTS5 搜索索引表：messages_fts 用于英文 / 拉丁语系全文搜索，messages_fts_trigram 用于 CJK（中日韩）子串搜索。SQLite 中还包括 messages_fts_data、messages_fts_idx、messages_fts_content、messages_fts_docsize、messages_fts_config 等影子表，以及对应的 messages_fts_trigram_* 表。

1.4 上下文压缩

当会话上下文接近模型限制时，Hermes 会自动压缩历史消息，保留关键信息并维持上下文窗口可用。

yaml

# ~/.hermes/config.yaml
compression:
  enabled: true       # 启用/禁用压缩
  threshold: 0.50     # 当 prompt tokens 达到模型上下文窗口的 50% 时触发压缩
  target_ratio: 0.20  # 最近消息保留预算：threshold_tokens 的 20%，即默认保留约 10% 总上下文不压缩
  protect_last_n: 20  # 最少保留不压缩的最近消息数

也可通过 /compress 斜杠命令手动触发压缩。

1.5 Session Search 会话搜索（★ v0.15 重建）

v0.15 重大更新：session_search 在 v0.15 中被完全重建，去除了 LLM 依赖，速度提升 4,500 倍（从 ~90s 降至 ~20ms），且零费用。旧版本中每次搜索都要调用 LLM 做摘要，既慢又贵。

Agent 内置 session_search 工具，用 SQLite FTS5 在过去所有会话中做全文搜索。它解决的是"我之前是不是和 Hermes 说过这件事"的问题。

Agent 被提示在用户提到过去对话，或者怀疑历史会话里有相关上下文时，先调用 session_search 回忆历史，而不是直接要求用户重复信息。

借助这个工具 Agent 可以先搜索命中的会话，再沿着同一个会话向前或向后翻看更多上下文。

session_search 没有显式 mode 参数，而是根据传入参数自动判断调用形态：

调用形态	参数	用途
Discovery	`query`	按关键词搜索历史会话，返回最相关的若干会话
Scroll	`session_id` + `around_message_id`	在某个命中的会话里，以指定消息为中心继续向前 / 向后翻看
Browse	无参数	按时间列出最近会话，适合用户只问"我之前在做什么"

Discovery 搜索结果通常包含：

session_id、标题、时间、来源平台
FTS5 命中的高亮片段
会话开头几条用户 / assistant 消息，用来还原任务开始时的目标
命中消息前后的一小段上下文
会话结尾几条用户 / assistant 消息，用来判断最后结论或决策
命中的 message_id，后续可用它继续 Scroll

Agent 调用 session_search 时，query 参数支持常见 FTS5 查询语法：

text

docker deployment        # 多关键词，默认 AND
"exact phrase"           # 精确短语
docker OR kubernetes     # 布尔 OR
python NOT java          # 排除关键词
deploy*                  # 前缀匹配

session_search 常用可选输入参数：

参数	说明
`limit`	Discovery 返回的会话数量
`window`	Scroll 时围绕锚点消息返回前后多少条消息
`sort`	`newest` / `oldest`，在相关性之外按时间排序
`role_filter`	限制搜索角色；默认搜索 `user,assistant`，需要调试工具输出时可包含 `tool`

使用示例：Agent 内部调用流程

当用户问「上次我们讨论的那个 Docker 部署方案，后来怎么解决的？」时，Agent 的内部调用链：

text

# 第一步：Discovery —— 按关键词找到相关会话
search_result = session_search(
    query="Docker deployment",
    limit=3,
)

# 返回结果（简化）：
# [
#   {session_id: "20260610_143052_a1b2c3", title: "Docker 部署问题排查",
#    snippet: "...Docker 部署到生产环境后遇到端口冲突...",
#    matched_message_id: "msg_789"},
#   ...
# ]

# 第二步：Scroll —— 围绕命中消息上下翻看完整上下文
detail = session_search(
    session_id="20260610_143052_a1b2c3",
    around_message_id="msg_789",
    window=5,  # 前后各取 5 条
)

# Agent 基于拿到的上下文回答用户，而不需要让用户再讲一遍

1.6 证据验证（🆕 v0.18+）

v0.18 引入证据验证机制——Agent 完成编码任务后会实际运行项目检查来验证完成状态，而非仅凭自我感觉。/goal 新增 completion contracts：你声明"完成"的标准，standing-goal loop 根据实际证据判断。可通过 pre_verify hook 接入自定义检查。

2. Dashboard

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard

Hermes 提供了一个基于浏览器的 Web 管理界面，替代手动编辑 YAML 和 CLI 命令，用于配置管理、API 密钥设置和会话监控。

2.1 启动与配置

bash

hermes dashboard                       # 启动，自动打开浏览器 http://127.0.0.1:9119
hermes dashboard --port 8080           # 自定义端口
hermes dashboard --tui                 # 启用浏览器内 Chat 标签页
hermes dashboard --status              # 查看运行状态
hermes dashboard --stop                # 停止运行
hermes dashboard &>/dev/null &         # 后台运行
hermes dashboard &>/dev/null & disown  # 后台运行并脱离终端

2.2 v0.16 Web 管理面板（★ 新增）

v0.16 将 Dashboard 升级为完整的 Web 管理面板，支持：

消息渠道配置：在网页中配置 Telegram、Discord、Slack 等平台
MCP 目录管理：浏览和配置 MCP 服务器
凭证管理：可视化编辑 .env 和 auth.json
Webhooks：配置外部系统回调
Gateway 控制：启动、停止、监控 Gateway 状态
简体中文界面：完整的中文本地化

🆕 v0.17 新增 Profile Builder：在 Dashboard 网页中创建和管理 Profile，无需 CLI 命令。

3. Toolsets 工具集

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/tools

工具（Tools）是 Hermes 调用外部能力的基本单元——搜索网页、执行命令、读写文件、控制浏览器等。工具按功能分组为「工具集」（Toolsets），可以按平台按需启用或禁用，从而精确控制 Agent 的能力范围。

3.1 基本操作

bash

hermes tools                  # 交互式管理工具集
hermes tools list             # 查看所有工具集
hermes tools list --platform weixin  # 查看指定平台的工具集
hermes tools enable yuanbao   # 启用 yuanbao 工具集
hermes tools disable yuanbao  # 禁用 yuanbao 工具集

/tools    # 会话内查看 / 管理可用工具
/verbose  # 切换工具执行展示模式（all → verbose → off → new）

/verbose 控制工具执行过程在会话里显示多少信息：

模式	含义
`off`	只显示最终回复，不展示工具调用、日志或推理信息
`new`	工具调用发生时显示简短的一行进度
`all`	显示所有工具活动，包括工具结果
`verbose`	显示最完整细节，包括工具参数和输出，适合调试问题

3.2 工具分类

Hermes 内置的工具按用途分为以下几类：

类别	包含工具	用途
Web	`web_search`, `web_extract`, `x_search`	搜索网页、提取页面内容、跨平台搜索
终端与文件	`terminal`, `process`, `read_file`, `patch`	执行命令、读写文件
浏览器	`browser_navigate`, `browser_snapshot`, `browser_vision`, `computer_use`	交互式浏览器自动化，支持文本与视觉
媒体	`vision_analyze`, `image_generate`, `text_to_speech`, `video_analyze`	多模态分析与内容生成
编排	`todo`, `clarify`, `execute_code`, `delegate_task`	任务规划、澄清需求、代码执行、委托子 Agent
记忆与召回	`memory`, `session_search`	持久化记忆、搜索历史会话
自动化与推送	`cronjob`, `send_message`	定时任务、消息推送
集成	`ha_`, MCP 工具, `rl_`	Home Assistant、MCP 服务器、RL 训练等

新增工具（v0.13~v0.14）

工具	版本	用途
`computer_use`	v0.14+	桌面自动化操作（点击、输入、截图）
`x_search`	v0.14+	跨平台聚合搜索
`video_analyze`	v0.13+	视频内容理解（需 Gemini 或兼容模型）

关键工具用法示例

web_search — 网页搜索

text

# Agent 调用示例
web_search(
    query="Hermes Agent v0.16 Kanban Swarm architecture",
    max_results=10,
)

# 返回结果包含：标题、URL、摘要
# Agent 可以进一步用 web_extract 获取完整页面内容

web_extract — 页面内容提取

text

web_extract(
    url="https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban",
    extract_mode="markdown",   # 将 HTML 转为 Markdown
)
# 返回页面的结构化文本内容

browser_navigate / browser_snapshot — 浏览器自动化

text

# 打开一个需要 JS 渲染的页面
browser_navigate(url="https://example.com/spa-app")

# 截取当前页面的无障碍树快照（纯文本，不下载图片）
browser_snapshot()
# 返回页面中所有可交互元素：按钮、输入框、链接及其标识符

# 需要视觉判断时（如图表、布局问题）
browser_vision(query="首页首屏的主要内容和布局结构")
# 这会截取实际截图并送给视觉模型分析

read_file / patch — 文件读写

text

# 读取文件，支持指定行范围
read_file(
    file_path="/home/user/project/src/main.py",
    offset=40,    # 从第 40 行开始
    limit=80,     # 读 80 行
)

# 精确字符串替换（不改动无关代码）
patch(
    file_path="/home/user/project/src/main.py",
    old_string="def process(data):\n    return data.strip()",
    new_string="def process(data: str) -> str:\n    return data.strip()",
)
# patch 要求 old_string 在文件中唯一匹配，否则报错拒绝执行

todo — 任务规划

text

# Agent 在执行复杂多步骤任务时，先用 todo 工具制定计划
todo(
    action="create",
    todos=[
        {"content": "搜索 Hermes Agent Kanban Swarm 文档", "status": "pending"},
        {"content": "提取关键架构信息", "status": "pending"},
        {"content": "整理成结构化摘要", "status": "pending"},
    ]
)

# 逐步推进
todo(action="update", todo_id=0, status="in_progress")
# ... 完成第一步 ...
todo(action="update", todo_id=0, status="completed")
todo(action="update", todo_id=1, status="in_progress")

3.3 终端后端

终端工具支持 7 种后端，适应不同的安全隔离和运行环境需求：

后端	说明	适用场景
`local`	在本机直接执行（默认）	本地开发、可信任务
`docker`	隔离容器中执行	安全隔离、可复现环境
`ssh`	远程服务器执行	沙箱化，防止 Agent 修改自身代码
`singularity`	HPC 容器（Apptainer）	集群计算、无 root 环境
`modal`	云端无服务器执行	弹性伸缩
`daytona`	云端沙箱工作区	持久化远程开发环境
`vercel_sandbox`	Vercel 云端微虚拟机	部署与长期运行进程

选择建议：

默认先用 local，适合本机开发和可信任务
不信任任务内容、担心误改本机文件时，用 docker
目标环境在远程服务器上时，用 ssh
HPC / 集群环境优先考虑 singularity
需要云端隔离或弹性资源时，考虑 modal、daytona、vercel_sandbox

切换后端：

bash

hermes config set terminal.backend docker
hermes config set terminal.backend local

#配置国内的镜像
"registry-mirrors": [
    "https://docker.xuanyuan.me",
    "https://docker.1ms.run"
  ]
#使用docker desktop拉取正确的镜像

docker pull nikolaik/python-nodejs:python3.11-nodejs20

各后端的具体配置示例：

yaml

# ~/.hermes/config.yaml
terminal:
  backend: docker
  modal_mode: auto
  cwd: /workspace
  timeout: 180
  daemon_term_grace_seconds: 2
  env_passthrough: []
  home_mode: auto
  shell_init_files: []
  auto_source_bashrc: true
  docker_image: nikolaik/python-nodejs:python3.11-nodejs20
  docker_forward_env: []
  docker_env: {}
  singularity_image: docker://nikolaik/python-nodejs:python3.11-nodejs20
  modal_image: nikolaik/python-nodejs:python3.11-nodejs20
  daytona_image: nikolaik/python-nodejs:python3.11-nodejs20
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true
  docker_volumes: []
  docker_mount_cwd_to_workspace: false
  docker_extra_args: []
  docker_run_as_host_user: false
  persistent_shell: true
  lifetime_seconds: 300
    # 如需挂载宿主机目录：
    # volumes:
    #   - /home/user/project:/workspace

  # SSH 后端 — 在远程服务器上执行命令
  # backend: ssh
  # ssh:
  #   host: "192.168.1.100"
  #   port: 22
  #   user: "hermes"
  #   # 认证方式二选一：
  #   key_path: "~/.ssh/id_ed25519"    # SSH 密钥
  #   # password: "***"                 # 或密码（推荐放 .env）

  # Modal 后端 — 云端无服务器执行
  # backend: modal
  # modal:
  #   token_id: "ak-xxxx"           # Modal API token ID（放 .env）
  #   token_secret: "as-xxxx"       # Modal API token secret（放 .env）

当命令需要 sudo 权限时，终端会提示输入密码（会话内缓存）。也可以在 ~/.hermes/.env 中设置 SUDO_PASSWORD 环境变量。

3.4 并行工具执行

Hermes 支持通过 ThreadPoolExecutor 并行执行多个独立的工具调用（最多 8 个并行 worker）。当 Agent 在同一轮中发出多个互不依赖的工具调用时，它们会自动并行执行，显著减少总耗时。

3.5 Smart Approvals 智能审批

受 Codex CLI 启发，Hermes 会学习哪些命令是安全的。当你反复批准同一类命令（如 git status、ls），Hermes 会逐步减少审批提示。审批模式可以通过 /yolo 切换。

3.6 Post-Write Linting 写入后检查（v0.13+）

Agent 通过 patch 或 write_file 写入文件后，会自动进行格式检查，支持 Python、JSON、YAML、TOML。这减少了 Agent 写入格式错误内容的概率。

4. MCP 协议

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp

MCP（Model Context Protocol）可以把外部工具服务器接入 Hermes。

4.1 添加 MCP 服务器

配置示例：

yaml

# ~/.hermes/config.yaml
mcp_servers:
  project-fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

  company_api:
    url: "https://mcp.internal.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

上面两个 server 分别代表两种传输方式：

模式	配置方式	工作方式	适用场景
stdio	`command` + `args`	Hermes 在本机启动 MCP server 进程，通过 stdin / stdout 与其通信	本地文件系统、CLI 工具、开发环境里的集成
HTTP	`url`	Hermes 连接一个已经运行的 MCP server	公司内部服务、远程 API、共享的工具服务器

常用配置项：

配置项	说明
`command`	本地 stdio MCP Server 的启动命令
`args`	传给启动命令的参数
`env`	传给 stdio server 的环境变量
`url`	远程 HTTP MCP Server 地址
`headers`	远程 HTTP 请求头
`auth: oauth`	仅用于 HTTP server，启用 OAuth 2.1 授权流程
`enabled`	是否启用该 server
`timeout`	工具调用超时时间
`connect_timeout`	初次连接超时时间

auth: oauth 通常需要一次浏览器交互式授权。授权完成后，Hermes 会缓存授权结果，后续调用复用已授权 token。

推荐使用魔搭广场 https://www.modelscope.cn/mcp

可以在每个 server 下配置 tools.include 或 tools.exclude，来控制注册工具白名单或黑名单：

yaml

# ~/.hermes/config.yaml
mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      resources: false
      prompts: false

  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

4.2 管理与重载

bash

hermes mcp list                  # 列出已配置的服务器
hermes mcp test project-fs       # 测试连接
hermes mcp configure project-fs  # 管理服务器中的工具启用状态
hermes mcp remove project-fs     # 移除服务器

/reload-mcp  # 修改配置后，在会话内重载 MCP 工具

Hermes 启动时会自动发现 MCP 工具。修改 mcp_servers 配置后，用 /reload-mcp 重新加载；如果 MCP Server 支持动态工具变更通知，Hermes 可以自动刷新工具列表。

4.3 MCP Server Mode（v0.6+，★ 反向暴露）

MCP Server Mode 是 Hermes 的一个独特功能：它反过来把 Hermes 的会话暴露给 MCP 兼容的客户端。这意味着你可以在 Claude Desktop、VS Code、Cursor 等支持 MCP 的工具中，把 Hermes 当作一个工具服务器来使用。

配置方式：在 MCP 客户端配置中将 Hermes 注册为 MCP server，客户端就可以调用 Hermes 的能力。

例如在 Claude Desktop 中，编辑 claude_desktop_config.json：

json

{
  "mcpServers": {
    "hermes-agent": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

配置后重启 Claude Desktop，即可在对话中调用 Hermes 的所有已启用工具。VS Code 和 Cursor 的配置方式类似，将同样的 server 定义加入对应客户端的 mcpServers 配置块即可。

4.4 Nous-Approved MCP Catalog（v0.15+）

v0.15 引入了 Nous 精选的 MCP 服务器目录，提供交互式选择器。不用再去 GitHub 搜索 MCP server，直接在 Hermes 里浏览和安装：

bash

hermes mcp catalog    # 浏览精选 MCP 目录

5. 上下文文件

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files

Hermes Agent 会自动发现并加载上下文文件。这里的"上下文文件"分两类：项目上下文文件用于描述当前仓库或目录规则；SOUL.md 用于描述当前 Hermes 实例的人格和沟通风格。

5.1 支持的上下文文件

文件	用途	发现方式
`.hermes.md` / `HERMES.md`	Hermes 专用项目说明，优先级最高	从当前目录向上查找到 git root
`AGENTS.md`	项目说明、架构、约定、注意事项	启动目录；子目录中可渐进发现
`CLAUDE.md`	兼容 Claude Code 的上下文文件	启动目录；子目录中可渐进发现
`.cursorrules`	兼容 Cursor 的项目规则	启动目录；子目录中可渐进发现
`.cursor/rules/*.mdc`	Cursor 规则模块	启动目录
`SOUL.md`	当前 Hermes 实例的人格、语气和沟通风格	只从 `HERMES_HOME/SOUL.md` 加载

5.2 加载流程与安全处理

项目上下文有两条加载路径：启动加载和渐进加载。

启动加载

发生在会话开始时。流程如下：

扫描当前工作目录，按优先级查找项目上下文文件
以 UTF-8 文本格式读取
执行安全扫描
超过 20,000 字符时截断，保留头部和尾部
组合到 # Project Context 部分并注入系统提示词

启动时的项目上下文只加载一种类型，优先级是：.hermes.md / HERMES.md → AGENTS.md → CLAUDE.md → .cursorrules / .cursor/rules/*.mdc。SOUL.md 独立加载，不参与这个优先级竞争。

截断策略：启动加载的默认截断上限是 20,000 字符。超过上限后，Hermes 保留前 70% 和后 20%，中间插入截断标记：

text

[...truncated AGENTS.md: kept 14000+4000 of 35620 chars. Use file tools to read the full file.]

也就是说，重要规则最好放在文件开头或结尾。

渐进加载

发生在会话进行中：

Agent 调用工具时，如果有文件路径，Hermes 会从这些路径推断当前正在访问的目录
从该路径所在目录向上检查最多 5 层父目录
每个目录按 AGENTS.md → CLAUDE.md → .cursorrules 优先级只加载首个匹配项
执行安全扫描
单个渐进提示文件超过 8,000 字符时，只保留前 8,000 字符
内容追加到工具结果中

安全扫描

安全扫描检查以下内容：

指令覆盖 — 例如 ignore previous instructions、disregard your rules
欺骗行为 — 例如 do not tell the user
系统提示词覆盖 — 例如 system prompt override
隐藏 HTML 注释 — 例如 
隐藏 div 元素 — 例如 <div style="display:none">
凭证外泄 — 例如 curl ... $API_KEY
敏感文件读取 — 例如 cat .env、cat credentials
不可见字符 — 零宽空格、双向文本覆盖符、词连接符等

命中任意威胁模式后，文件将被阻止加载，上下文位置替换为：

text

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

核心实现位于 agent/prompt_builder.py，使用 _CONTEXT_THREAT_PATTERNS 正则列表和 _CONTEXT_INVISIBLE_CHARS 危险字符集合进行两步检测。

5.3 @ 上下文引用（v0.4+）

Hermes 支持在对话中通过 @file 和 @url 注入上下文：

text

@file:README.md  这个项目的 README 写了什么？
@url:https://example.com/doc  根据这个文档回答问题

配合 Tab 补全，可以快速引用项目中的文件路径。

5.4 SOUL.md 与 /personality

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/personality

Hermes 的个性主要由 SOUL.md 控制。它是 Agent 的主身份文件，会拼入系统提示词开头部分。默认位置在 ~/.hermes/SOUL.md。

SOUL.md 适合写长期稳定的个性和沟通偏好：

语气
风格
直接程度
默认互动方式
不希望出现的表达习惯
面对不确定性、分歧、模糊需求时的处理方式

不适合写项目规则、文件路径、仓库约定、临时流程。这些应该放进 AGENTS.md。

/personality 是一层额外的系统提示覆盖。它不会修改 SOUL.md，而是在当前基础系统提示之后追加一段 personality prompt。

Hermes 内置以下人格，可通过 /personality 切换：

人格	说明
`helpful`	友好、通用的基础助手
`concise`	简短直接，回答尽量切中要点
`technical`	详细、准确的技术专家模式
`creative`	创新发散，偏向非常规方案和新思路
`teacher`	耐心教学，用清晰解释和示例辅助理解
`kawaii`	可爱、闪亮、热情的表达风格
`catgirl`	Neko-chan 猫娘风格，带猫系口癖和可爱表达
`pirate`	Captain Hermes，懂技术的数字海盗船长风格
`shakespeare`	莎士比亚式文风，戏剧化、华丽而夸张
`surfer`	轻松随性的冲浪者语气
`noir`	硬汉侦探小说式叙述，偏黑色电影氛围
`uwu`	极致可爱和 uwu-speak
`philosopher`	哲学家模式，会追问问题背后的意义和原因
`hype`	MAXIMUM ENERGY，极高能量和强烈鼓舞式回应

6. 持久记忆

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/memory

Hermes 有一套有容量上限、由 Agent 自己维护的持久记忆系统。它会跨会话保存用户偏好、项目环境、工具习惯和经验教训，并在新会话开始时注入系统提示词。

6.1 工作原理

内置记忆由两个文件组成，默认存储在 ~/.hermes/memories/：

文件	用途	字符上限
`MEMORY.md`	Agent 的个人笔记：环境事实、项目约定、工具细节、经验教训	2,200 字符（约 800 tokens）
`USER.md`	用户画像：用户信息、沟通风格、期望和习惯	1,375 字符（约 500 tokens）

两个文件会在会话开始时注入系统提示词
会话中通过 memory 工具新增、替换或删除的记忆会立即写入磁盘，但不会立刻改变当前会话已经注入的提示词快照
新的记忆会在下一个会话生效。这样可以保持 LLM prefix cache 稳定

记忆相关配置示例：

yaml

# ~/.hermes/config.yaml
memory:
  memory_enabled: true        # 启用持久记忆
  user_profile_enabled: true  # 启用用户档案
  memory_char_limit: 2200     # 记忆字符上限（约 800 tokens）
  user_char_limit: 1375       # 用户档案字符上限（约 500 tokens）

系统提示词中的记忆大致长这样：

text

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations

§（节号符号）用来分隔不同记忆条目，标题会显示当前容量占用。

6.2 memory 工具

Agent 通过 memory 工具管理记忆，常用动作：

动作	用途
`add`	添加新的记忆条目
`replace`	替换已有条目，使用 `old_text` 做短唯一子串匹配
`remove`	删除已有条目，使用 `old_text` 做短唯一子串匹配
🆕 `operations`（v0.17+）	原子批量操作数组，一次调用完成多条增删改，自动处理容量预算

没有 read 动作。记忆内容会自动注入系统提示词，Agent 在会话里本来就能看到当前快照。

replace 和 remove 不需要传完整条目，只要传能唯一定位的短文本：

text

memory(action="replace", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

使用 old_text 匹配时，会先去掉首尾空白，并在每条记忆中进行精确子串匹配。必须刚好匹配 1 条记忆。

6.3 记忆管理原则

记忆管理由 MEMORY_GUIDANCE 提示词驱动。核心原则：

应该保存到记忆：

用户偏好：例如「用户偏好 TypeScript 而不是 JavaScript」
环境事实：例如「这台服务器运行 Debian 12 和 PostgreSQL 16」
用户纠正：例如「Docker 命令不要用 sudo，用户已在 docker 组」
项目约定：例如「项目使用 tabs、120 字符行宽、Google 风格 docstring」
显式要求：例如「记住 API key 每月轮换」

不应该保存到记忆：

太模糊的信息：例如「用户问过 Python」
容易重新查询的通用知识
大段代码、日志、数据表
临时任务状态、一次性文件路径、短期 TODO
已经写在 SOUL.md、AGENTS.md 等上下文文件里的内容

记忆应该写成陈述性事实，而不是命令式指令：

✓ User prefers concise responses
✗ Always respond concisely

容量管理：记忆有严格字符上限。当新增内容会超过上限时，memory 工具会返回错误，Agent 应该先合并、替换或删除旧条目。

安全扫描：记忆条目在写入前还会做安全扫描，包含提示词注入、凭证外泄、SSH 后门、不可见 Unicode 字符等风险模式的内容会被阻止。

v0.15 新增 Promptware Defense：记忆在加载时也会被扫描。这是 Brainworm 级攻击防护的三道关卡之一（另外两道是工具输出分隔符标记和控制文件写保护）。

6.4 session_search vs memory

除了 MEMORY.md 和 USER.md，Hermes 还可以通过 session_search 搜索过去的完整会话。两者用途不同：

对比项	持久记忆	Session Search
容量	约 1,300 tokens，总量很小	理论上包含所有历史会话
速度	会话开始时直接进入系统提示词	需要按需查询数据库（v0.15：~20ms）
用途	必须一直可见的关键事实	查找过去某次讨论的具体内容
管理方式	Agent 主动维护、压缩、替换	自动保存所有会话
token 成本	每个会话固定占用少量上下文	返回的消息片段占用上下文

memory 保存「以后经常要用的稳定事实」；session_search 用来回答「上次我们讨论过什么」。

6.5 外部记忆提供商

官方文档：https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers

Hermes 内置了 8 个外部记忆提供商插件，提供比 MEMORY.md / USER.md 更强的跨会话记忆能力。外部记忆不会替代内置记忆，而是作为叠加能力并行工作。同一时间只能启用一个外部记忆提供商。

bash

hermes memory setup   # 交互式选择并配置外部记忆提供商
hermes memory status  # 查看当前启用状态
hermes memory off     # 关闭外部记忆提供商

可选 provider：

分档	Provider	重点功能 / 优势
入门	`honcho`	跨会话用户建模、session 级上下文、基于历史上下文的综合判断
入门	`mem0`	服务端 LLM 事实抽取、语义搜索、重排和自动去重
进阶	`openviking`	文件系统式知识层级、分层读取、自动抽取 6 类记忆
进阶	`byterover`	CLI 驱动的层级知识树、分层检索、压缩前自动提取洞察
复杂	`hindsight`	知识图谱、实体关系、多策略检索、跨记忆综合
复杂	`holographic`	FTS5 全文搜索、信任评分、HRR 组合查询、冲突检测
复杂	`retaindb`	Vector + BM25 + Reranking 混合搜索、7 类记忆、增量压缩
复杂	`supermemory`	语义长期记忆、用户画像、会话图谱摄取、上下文防污染

选择建议：

只是想让记忆更智能，先从 honcho 或 mem0 开始
更偏本地 / 文件系统式知识管理，可以看 openviking 或 byterover
需要知识图谱、实体关系和复杂关联检索，再考虑 hindsight
需要混合检索、评分、冲突检测等进阶能力，再看 holographic、retaindb 或 supermemory

6.6 `/journey` 学习时间线（🆕 v0.18+）

CLI 和 TUI 中运行 /journey，展示 Agent 随时间积累的所有记忆和技能的可视化时间线，可直接在此界面编辑或删除条目。在 Desktop 中对应 Memory Graph（辐射状可操作时间线）。这是 Hermes Agent 记忆透明化的核心功能——你终于可以看到 Agent 知道什么、如何增长。

模块二：能力篇 — 会话、工具、MCP、记忆 ​

目录 ​

1. 会话管理 ​

1.1 基本操作 ​

1.2 会话内斜杠命令 ​

1.3 会话存储 ​

1.4 上下文压缩 ​

1.5 Session Search 会话搜索（★ v0.15 重建） ​

1.6 证据验证（🆕 v0.18+） ​

2. Dashboard ​

2.1 启动与配置 ​

2.2 v0.16 Web 管理面板（★ 新增） ​

3. Toolsets 工具集 ​

3.1 基本操作 ​

3.2 工具分类 ​

新增工具（v0.13~v0.14） ​

关键工具用法示例 ​

3.3 终端后端 ​

3.4 并行工具执行 ​

3.5 Smart Approvals 智能审批 ​

3.6 Post-Write Linting 写入后检查（v0.13+） ​

4. MCP 协议 ​

4.1 添加 MCP 服务器 ​

4.2 管理与重载 ​

4.3 MCP Server Mode（v0.6+，★ 反向暴露） ​

4.4 Nous-Approved MCP Catalog（v0.15+） ​

5. 上下文文件 ​

5.1 支持的上下文文件 ​

5.2 加载流程与安全处理 ​

启动加载 ​

渐进加载 ​

安全扫描 ​

5.3 @ 上下文引用（v0.4+） ​

5.4 SOUL.md 与 /personality ​

6. 持久记忆 ​

6.1 工作原理 ​

6.2 memory 工具 ​

6.3 记忆管理原则 ​

6.4 session_search vs memory ​

6.5 外部记忆提供商 ​

6.6 /journey 学习时间线（🆕 v0.18+） ​

模块二：能力篇 — 会话、工具、MCP、记忆

目录

1. 会话管理

1.1 基本操作

1.2 会话内斜杠命令

1.3 会话存储

1.4 上下文压缩

1.5 Session Search 会话搜索（★ v0.15 重建）

1.6 证据验证（🆕 v0.18+）

2. Dashboard

2.1 启动与配置

2.2 v0.16 Web 管理面板（★ 新增）

3. Toolsets 工具集

3.1 基本操作

3.2 工具分类

新增工具（v0.13~v0.14）

关键工具用法示例

3.3 终端后端

3.4 并行工具执行

3.5 Smart Approvals 智能审批

3.6 Post-Write Linting 写入后检查（v0.13+）

4. MCP 协议

4.1 添加 MCP 服务器

4.2 管理与重载

4.3 MCP Server Mode（v0.6+，★ 反向暴露）

4.4 Nous-Approved MCP Catalog（v0.15+）

5. 上下文文件

5.1 支持的上下文文件

5.2 加载流程与安全处理

启动加载

渐进加载

安全扫描

5.3 @ 上下文引用（v0.4+）

5.4 SOUL.md 与 /personality

6. 持久记忆

6.1 工作原理

6.2 memory 工具

6.3 记忆管理原则

6.4 session_search vs memory

6.5 外部记忆提供商

6.6 `/journey` 学习时间线（🆕 v0.18+）