命令 功能/new 开始新会话/clear 清屏并开始新会话/undo 撤销上一次用户/Agent 交互记录/undo [N] v0.16撤销最近 N 轮交互/title session_name 为当前会话命名/history 显示对话历史/sessions 查看和管理会话/compress 手动压缩上下文/stop 停止后台进程/background 在后台运行任务/goalv0.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 会自动压缩历史消息保留关键信息并维持上下文窗口可用官方配置好的不建议修改~/.hermes/config.yamlcompression: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后续可用它继续 ScrollAgent 调用 session_search 时query 参数支持常见 FTS5 查询语法docker deployment # 多关键词默认 AND“exact phrase” # 精确短语docker OR kubernetes # 布尔 ORpython NOT java # 排除关键词deploy* # 前缀匹配session_search 常用可选输入参数参数 说明limit Discovery 返回的会话数量window Scroll 时围绕锚点消息返回前后多少条消息sort newest / oldest在相关性之外按时间排序role_filter 限制搜索角色默认搜索 user,assistant需要调试工具输出时可包含 tool使用示例Agent 内部调用流程当用户问「上次我们讨论的那个 Docker 部署方案后来怎么解决的」时Agent 的内部调用链第一步Discovery —— 按关键词找到相关会话search_result session_search(query“Docker deployment”,limit3,)返回结果简化[{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”,window5, # 前后各取 5 条)Agent 基于拿到的上下文回答用户而不需要让用户再讲一遍上下文文件官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/context-filesHermes Agent 会自动发现并加载上下文文件。这里的上下文文件分两类项目上下文文件用于描述当前仓库或目录规则会话当前目录中的MD文档Hermes的安装目录中SOUL.md 用于描述当前 Hermes 实例的人格和沟通风格2.1 支持的上下文文件.hermes.md / HERMES.md是Hermes安装目录里写的全局规则。进入A文件夹创建AGENTS.md/CLAUDE.md在A文件夹进入cmd开启Hermes会话当前会话就会 启动加载 读取当前文件夹下的AGENTS.md/CLAUDE.md作为会话规则。文件 用途 发现方式.hermes.md / HERMES.md Hermes 专用项目说明优先级最高 从当前目录向上查找到 git rootAGENTS.md 项目说明、架构、约定、注意事项 启动目录子目录中可渐进发现CLAUDE.md 兼容 Claude Code 的上下文文件 启动目录子目录中可渐进发现.cursorrules 兼容 Cursor 的项目规则 启动目录子目录中可渐进发现.cursor/rules/*.mdc Cursor 规则模块 启动目录SOUL.md 当前 Hermes 实例的人格、语气和沟通风格 只从 HERMES_HOME/SOUL.md 加载2.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%中间插入截断标记也就是说重要规则最好放在文件开头或结尾[…truncated AGENTS.md: kept 140004000 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不可见字符 — 零宽空格、双向文本覆盖符、词连接符等命中任意威胁模式后文件将被阻止加载上下文位置替换为[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]核心实现位于 agent/prompt_builder.py使用 _CONTEXT_THREAT_PATTERNS 正则列表和 _CONTEXT_INVISIBLE_CHARS 危险字符集合进行两步检测。2.3 上下文引用v0.4基本不用因为桌面版直接上传文件/输入url链接就行Hermes 支持在对话中通过 file 和 url 注入上下文file:README.md 这个项目的 README 写了什么url:https://example.com/doc 根据这个文档回答问题配合 Tab 补全可以快速引用项目中的文件路径。2.4 SOUL.md 与 /personality官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/personalitySOUL.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-speakphilosopher 哲学家模式会追问问题背后的意义和原因hype MAXIMUM ENERGY极高能量和强烈鼓舞式回应3. 持久记忆官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/memory这个是全自动的了解即可。Hermes 有一套有容量上限、由 Agent 自己维护的持久记忆系统。它会跨会话保存用户偏好、项目环境、工具习惯和经验教训并在新会话开始时注入系统提示词。3.1 工作原理内置记忆由两个文件组成默认存储在 ~/.hermes/memories/文件 用途 字符上限MEMORY.md Agent 的个人笔记环境事实、项目约定、工具细节、经验教训 2,200 字符约 800 tokensUSER.md 用户画像用户信息、沟通风格、期望和习惯 1,375 字符约 500 tokens两个文件会在会话开始时注入系统提示词会话中通过 memory 工具新增、替换或删除的记忆会立即写入磁盘但不会立刻改变当前会话已经注入的提示词快照新的记忆会在下一个会话生效。这样可以保持 LLM prefix cache 稳定记忆相关配置示例~/.hermes/config.yamlmemory:memory_enabled: true # 启用持久记忆user_profile_enabled: true # 启用用户档案memory_char_limit: 2200 # 记忆字符上限约 800 tokensuser_char_limit: 1375 # 用户档案字符上限约 500 tokens系统提示词中的记忆大致长这样══════════════════════════════════════════════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§节号符号用来分隔不同记忆条目标题会显示当前容量占用。3.2 memory 工具一般不用这个工具直接去目录里修改~/.hermes/memories/Agent 通过 memory 工具管理记忆常用动作动作 用途add 添加新的记忆条目replace 替换已有条目使用 old_text 做短唯一子串匹配remove 删除已有条目使用 old_text 做短唯一子串匹配没有 read 动作。记忆内容会自动注入系统提示词Agent 在会话里本来就能看到当前快照。replace 和 remove 不需要传完整条目只要传能唯一定位的短文本memory(action“replace”, target“memory”,old_text“dark mode”,content“User prefers light mode in VS Code, dark mode in terminal”)使用 old_text 匹配时会先去掉首尾空白并在每条记忆中进行精确子串匹配。必须刚好匹配 1 条记忆。3.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 级攻击防护的三道关卡之一另外两道是工具输出分隔符标记和控制文件写保护。3.4 session_search vs memory除了 MEMORY.md 和 USER.mdHermes 还可以通过 session_search 搜索过去的完整会话。两者用途不同对比项 持久记忆memory Session Search容量 约 1,300 tokens总量很小 理论上包含所有历史会话速度 会话开始时直接进入系统提示词 需要按需查询数据库v0.15~20ms用途 必须一直可见的关键事实 查找过去某次讨论的具体内容管理方式 Agent 主动维护、压缩、替换 自动保存所有会话token 成本 每个会话固定占用少量上下文 返回的消息片段占用上下文memory 保存「以后经常要用的稳定事实」session_search 用来回答「上次我们讨论过什么」。补充memory VS SKILL VS Session Searchmemory是在记忆文件中保存简单的一句话一个用户喜好、当前工作环境 等等SKILL是将复杂任务提取成SKILL便于后续执行该任务时调用Session Search是其他会话持久存储在数据库中后续用户询问其他会话内容时会自动查询数据库3.5 外部记忆提供商官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providersHermes 内置了 8 个外部记忆提供商插件提供比 MEMORY.md / USER.md 更强的跨会话记忆能力。外部记忆不会替代内置记忆而是作为叠加能力并行工作。同一时间只能启用一个外部记忆提供商。holographic是本地的不需要key可以直接选择使用。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 或 supermemory4. Toolsets 工具集官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/tools工具Tools是 Hermes 调用外部能力的基本单元——搜索网页、执行命令、读写文件、控制浏览器等。工具按功能分组为「工具集」Toolsets可以按平台按需启用或禁用从而精确控制 Agent 的能力范围。4.1 基本操作桌面版UI直观可以不用命令行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 显示最完整细节包括工具参数和输出适合调试问题4.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 — 网页搜索Agent 调用示例web_search(query“Hermes Agent v0.16 Kanban Swarm architecture”,max_results10,)返回结果包含标题、URL、摘要Agent 可以进一步用 web_extract 获取完整页面内容web_extract — 页面内容提取web_extract(url“https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban”,extract_mode“markdown”, # 将 HTML 转为 Markdown)返回页面的结构化文本内容browser_navigate / browser_snapshot — 浏览器自动化打开一个需要 JS 渲染的页面browser_navigate(url“https://example.com/spa-app”)截取当前页面的无障碍树快照纯文本不下载图片browser_snapshot()返回页面中所有可交互元素按钮、输入框、链接及其标识符需要视觉判断时如图表、布局问题browser_vision(query“首页首屏的主要内容和布局结构”)这会截取实际截图并送给视觉模型分析read_file / patch — 文件读写读取文件支持指定行范围read_file(file_path“/home/user/project/src/main.py”,offset40, # 从第 40 行开始limit80, # 读 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 — 任务规划Agent 在执行复杂多步骤任务时先用 todo 工具制定计划todo(action“create”,todos[{“content”: “搜索 Hermes Agent Kanban Swarm 文档”, “status”: “pending”},{“content”: “提取关键架构信息”, “status”: “pending”},{“content”: “整理成结构化摘要”, “status”: “pending”},])逐步推进todo(action“update”, todo_id0, status“in_progress”)… 完成第一步 …todo(action“update”, todo_id0, status“completed”)todo(action“update”, todo_id1, status“in_progress”)
会话内斜杠命令
命令 功能/new 开始新会话/clear 清屏并开始新会话/undo 撤销上一次用户/Agent 交互记录/undo [N] v0.16撤销最近 N 轮交互/title session_name 为当前会话命名/history 显示对话历史/sessions 查看和管理会话/compress 手动压缩上下文/stop 停止后台进程/background 在后台运行任务/goalv0.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 会自动压缩历史消息保留关键信息并维持上下文窗口可用官方配置好的不建议修改~/.hermes/config.yamlcompression: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后续可用它继续 ScrollAgent 调用 session_search 时query 参数支持常见 FTS5 查询语法docker deployment # 多关键词默认 AND“exact phrase” # 精确短语docker OR kubernetes # 布尔 ORpython NOT java # 排除关键词deploy* # 前缀匹配session_search 常用可选输入参数参数 说明limit Discovery 返回的会话数量window Scroll 时围绕锚点消息返回前后多少条消息sort newest / oldest在相关性之外按时间排序role_filter 限制搜索角色默认搜索 user,assistant需要调试工具输出时可包含 tool使用示例Agent 内部调用流程当用户问「上次我们讨论的那个 Docker 部署方案后来怎么解决的」时Agent 的内部调用链第一步Discovery —— 按关键词找到相关会话search_result session_search(query“Docker deployment”,limit3,)返回结果简化[{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”,window5, # 前后各取 5 条)Agent 基于拿到的上下文回答用户而不需要让用户再讲一遍上下文文件官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/context-filesHermes Agent 会自动发现并加载上下文文件。这里的上下文文件分两类项目上下文文件用于描述当前仓库或目录规则会话当前目录中的MD文档Hermes的安装目录中SOUL.md 用于描述当前 Hermes 实例的人格和沟通风格2.1 支持的上下文文件.hermes.md / HERMES.md是Hermes安装目录里写的全局规则。进入A文件夹创建AGENTS.md/CLAUDE.md在A文件夹进入cmd开启Hermes会话当前会话就会 启动加载 读取当前文件夹下的AGENTS.md/CLAUDE.md作为会话规则。文件 用途 发现方式.hermes.md / HERMES.md Hermes 专用项目说明优先级最高 从当前目录向上查找到 git rootAGENTS.md 项目说明、架构、约定、注意事项 启动目录子目录中可渐进发现CLAUDE.md 兼容 Claude Code 的上下文文件 启动目录子目录中可渐进发现.cursorrules 兼容 Cursor 的项目规则 启动目录子目录中可渐进发现.cursor/rules/*.mdc Cursor 规则模块 启动目录SOUL.md 当前 Hermes 实例的人格、语气和沟通风格 只从 HERMES_HOME/SOUL.md 加载2.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%中间插入截断标记也就是说重要规则最好放在文件开头或结尾[…truncated AGENTS.md: kept 140004000 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不可见字符 — 零宽空格、双向文本覆盖符、词连接符等命中任意威胁模式后文件将被阻止加载上下文位置替换为[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]核心实现位于 agent/prompt_builder.py使用 _CONTEXT_THREAT_PATTERNS 正则列表和 _CONTEXT_INVISIBLE_CHARS 危险字符集合进行两步检测。2.3 上下文引用v0.4基本不用因为桌面版直接上传文件/输入url链接就行Hermes 支持在对话中通过 file 和 url 注入上下文file:README.md 这个项目的 README 写了什么url:https://example.com/doc 根据这个文档回答问题配合 Tab 补全可以快速引用项目中的文件路径。2.4 SOUL.md 与 /personality官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/personalitySOUL.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-speakphilosopher 哲学家模式会追问问题背后的意义和原因hype MAXIMUM ENERGY极高能量和强烈鼓舞式回应3. 持久记忆官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/memory这个是全自动的了解即可。Hermes 有一套有容量上限、由 Agent 自己维护的持久记忆系统。它会跨会话保存用户偏好、项目环境、工具习惯和经验教训并在新会话开始时注入系统提示词。3.1 工作原理内置记忆由两个文件组成默认存储在 ~/.hermes/memories/文件 用途 字符上限MEMORY.md Agent 的个人笔记环境事实、项目约定、工具细节、经验教训 2,200 字符约 800 tokensUSER.md 用户画像用户信息、沟通风格、期望和习惯 1,375 字符约 500 tokens两个文件会在会话开始时注入系统提示词会话中通过 memory 工具新增、替换或删除的记忆会立即写入磁盘但不会立刻改变当前会话已经注入的提示词快照新的记忆会在下一个会话生效。这样可以保持 LLM prefix cache 稳定记忆相关配置示例~/.hermes/config.yamlmemory:memory_enabled: true # 启用持久记忆user_profile_enabled: true # 启用用户档案memory_char_limit: 2200 # 记忆字符上限约 800 tokensuser_char_limit: 1375 # 用户档案字符上限约 500 tokens系统提示词中的记忆大致长这样══════════════════════════════════════════════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§节号符号用来分隔不同记忆条目标题会显示当前容量占用。3.2 memory 工具一般不用这个工具直接去目录里修改~/.hermes/memories/Agent 通过 memory 工具管理记忆常用动作动作 用途add 添加新的记忆条目replace 替换已有条目使用 old_text 做短唯一子串匹配remove 删除已有条目使用 old_text 做短唯一子串匹配没有 read 动作。记忆内容会自动注入系统提示词Agent 在会话里本来就能看到当前快照。replace 和 remove 不需要传完整条目只要传能唯一定位的短文本memory(action“replace”, target“memory”,old_text“dark mode”,content“User prefers light mode in VS Code, dark mode in terminal”)使用 old_text 匹配时会先去掉首尾空白并在每条记忆中进行精确子串匹配。必须刚好匹配 1 条记忆。3.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 级攻击防护的三道关卡之一另外两道是工具输出分隔符标记和控制文件写保护。3.4 session_search vs memory除了 MEMORY.md 和 USER.mdHermes 还可以通过 session_search 搜索过去的完整会话。两者用途不同对比项 持久记忆memory Session Search容量 约 1,300 tokens总量很小 理论上包含所有历史会话速度 会话开始时直接进入系统提示词 需要按需查询数据库v0.15~20ms用途 必须一直可见的关键事实 查找过去某次讨论的具体内容管理方式 Agent 主动维护、压缩、替换 自动保存所有会话token 成本 每个会话固定占用少量上下文 返回的消息片段占用上下文memory 保存「以后经常要用的稳定事实」session_search 用来回答「上次我们讨论过什么」。补充memory VS SKILL VS Session Searchmemory是在记忆文件中保存简单的一句话一个用户喜好、当前工作环境 等等SKILL是将复杂任务提取成SKILL便于后续执行该任务时调用Session Search是其他会话持久存储在数据库中后续用户询问其他会话内容时会自动查询数据库3.5 外部记忆提供商官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providersHermes 内置了 8 个外部记忆提供商插件提供比 MEMORY.md / USER.md 更强的跨会话记忆能力。外部记忆不会替代内置记忆而是作为叠加能力并行工作。同一时间只能启用一个外部记忆提供商。holographic是本地的不需要key可以直接选择使用。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 或 supermemory4. Toolsets 工具集官方文档https://hermes-agent.nousresearch.com/docs/user-guide/features/tools工具Tools是 Hermes 调用外部能力的基本单元——搜索网页、执行命令、读写文件、控制浏览器等。工具按功能分组为「工具集」Toolsets可以按平台按需启用或禁用从而精确控制 Agent 的能力范围。4.1 基本操作桌面版UI直观可以不用命令行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 显示最完整细节包括工具参数和输出适合调试问题4.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 — 网页搜索Agent 调用示例web_search(query“Hermes Agent v0.16 Kanban Swarm architecture”,max_results10,)返回结果包含标题、URL、摘要Agent 可以进一步用 web_extract 获取完整页面内容web_extract — 页面内容提取web_extract(url“https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban”,extract_mode“markdown”, # 将 HTML 转为 Markdown)返回页面的结构化文本内容browser_navigate / browser_snapshot — 浏览器自动化打开一个需要 JS 渲染的页面browser_navigate(url“https://example.com/spa-app”)截取当前页面的无障碍树快照纯文本不下载图片browser_snapshot()返回页面中所有可交互元素按钮、输入框、链接及其标识符需要视觉判断时如图表、布局问题browser_vision(query“首页首屏的主要内容和布局结构”)这会截取实际截图并送给视觉模型分析read_file / patch — 文件读写读取文件支持指定行范围read_file(file_path“/home/user/project/src/main.py”,offset40, # 从第 40 行开始limit80, # 读 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 — 任务规划Agent 在执行复杂多步骤任务时先用 todo 工具制定计划todo(action“create”,todos[{“content”: “搜索 Hermes Agent Kanban Swarm 文档”, “status”: “pending”},{“content”: “提取关键架构信息”, “status”: “pending”},{“content”: “整理成结构化摘要”, “status”: “pending”},])逐步推进todo(action“update”, todo_id0, status“in_progress”)… 完成第一步 …todo(action“update”, todo_id0, status“completed”)todo(action“update”, todo_id1, status“in_progress”)
