Hermes Agent能力篇：会话、工具、MCP、记忆

第二部分 · 能力篇：会话、工具、MCP、记忆

1. 会话管理

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

1.1 基本操作

perl 复制代码

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	在后台运行任务
/goal	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 重建）

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 查询语法：

bash 复制代码

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 的内部调用链：

ini 复制代码

# 第一步：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 基于拿到的上下文回答用户，而不需要让用户再讲一遍

2. 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 状态

简体中文界面：完整的中文本地化

3. Toolsets 工具集

工具（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 --- 网页搜索

ini 复制代码

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


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

web_extract --- 页面内容提取

ini 复制代码

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

browser_navigate / browser_snapshot --- 浏览器自动化

ini 复制代码

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


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


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

read_file / patch --- 文件读写

ini 复制代码

# 读取文件，支持指定行范围
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 --- 任务规划

ini 复制代码

# 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

切换后端：

arduino 复制代码

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

配置国内镜像并拉取正确镜像：

bash 复制代码

# 配置国内的镜像
"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 协议

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。推荐使用魔搭广场 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.上下文文件

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%，中间插入截断标记：

arduino 复制代码

[...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 元素 --- 例如

凭证外泄 --- 例如 curl ... $API_KEY

敏感文件读取 --- 例如 cat .env、cat credentials

不可见字符 --- 零宽空格、双向文本覆盖符、词连接符等

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

csharp 复制代码

[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 注入上下文：

less 复制代码

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

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

5.4 SOUL.md 与 /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. 持久记忆

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）

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

css 复制代码

══════════════════════════════════════════════
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 做短唯一子串匹配

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

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

ini 复制代码

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 字符等风险模式的内容会被阻止。

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 外部记忆提供商

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