📄 tools/memory_tool.py (第 132-170 行)

def load_from_disk(self):
    """Load entries, capture system prompt snapshot.

    Frozen snapshot = system prompt (stable for prefix cache).
    Live state = tool responses (always current).
    """
    mem_dir = get_memory_dir()
    mem_dir.mkdir(parents=True, exist_ok=True)

    self.memory_entries = self._read_file(mem_dir / "MEMORY.md")
    self.user_entries = self._read_file(mem_dir / "USER.md")

    # Deduplicate (preserves order, keeps first occurrence)
    self.memory_entries = list(dict.fromkeys(self.memory_entries))
    self.user_entries = list(dict.fromkeys(self.user_entries))

    # ── 关键分叉点 ──
    # 快照态: 经过安全扫描，中毒条目被替换为 [BLOCKED: ...]
    sanitized_memory = self._sanitize_entries_for_snapshot(
        self.memory_entries, "MEMORY.md")
    sanitized_user = self._sanitize_entries_for_snapshot(
        self.user_entries, "USER.md")

    # 冻结快照 — 整个会话不再改变
    self._system_prompt_snapshot = {
        "memory": self._render_block("memory", sanitized_memory),
        "user": self._render_block("user", sanitized_user),
    }

    # 活跃态: 保留原始文本，用户可 inspect + remove 中毒条目

为什么用字符而非 token？

字符计数是模型无关的。同一个 MEMORY.md 在 GPT-4、Claude、Qwen 下占用的 token 数不同，但字符数永远一样。2200 字符 ≈ 300-500 token（取决于模型分词器），足够容纳 5-10 条简洁的笔记。

📄 agent/memory_provider.py (第 42-153 行)

class MemoryProvider(ABC):
    """Abstract base class for memory providers."""

    # ── 核心生命周期 (必须实现) ──
    @property
    @abstractmethod
    def name(self) -> str:
        """短标识: 'builtin', 'honcho', 'hindsight'..."""

    @abstractmethod
    def is_available(self) -> bool:
        """配置好 + 有凭证 + 依赖就绪? 不做网络调用。"""

    @abstractmethod
    def initialize(self, session_id: str, **kwargs) -> None:
        """会话初始化: 创建资源、建连接、启动后台线程。
        kwargs: hermes_home, platform, agent_context,
                agent_identity, user_id, parent_session_id..."""

    @abstractmethod
    def get_tool_schemas(self) -> List[Dict[str, Any]]:
        """OpenAI 格式工具 schema 列表。"""

    # ── 核心方法 (有默认实现，可覆盖) ──
    def system_prompt_block(self) -> str:
        """系统提示词静态块。"""
        return ""

    def prefetch(self, query: str, *, session_id: str = "") -> str:
        """每轮调用前的背景召回。要求快速 — 用后台线程。"""
        return ""

    def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
        """排队下一轮的背景召回。"""
        pass

    def sync_turn(self, user_content, assistant_content, ...) -> None:
        """每轮结束后持久化。非阻塞 — 队列后台处理。"""
        pass

    def handle_tool_call(self, tool_name, args, **kwargs) -> str:
        """处理工具调用。返回 JSON 字符串。"""
        raise NotImplementedError(...)

    def shutdown(self) -> None:
        """清理: 刷盘、关连接。"""
        pass

    # ── 可选钩子 (覆盖即启用) ──
    def on_turn_start(turn, message, **kwargs) -> None: ...
    def on_session_end(messages) -> None: ...
    def on_session_switch(new_session_id, **kwargs) -> None: ...
    def on_pre_compress(messages) -> str: ...
    def on_memory_write(action, target, content, metadata) -> None: ...
    def on_delegation(task, result, **kwargs) -> None: ...
    def get_config_schema() -> List[Dict]: ...
    def save_config(values, hermes_home) -> None: ...

📄 agent/memory_manager.py (第 333-396 行)

def add_provider(self, provider: MemoryProvider) -> None:
    is_builtin = provider.name == "builtin"

    if not is_builtin:
        if self._has_external:
            existing = next(
                (p.name for p in self._providers
                 if p.name != "builtin"), "unknown")
            logger.warning(
                "Rejected memory provider '%s' — external provider "
                "'%s' is already registered. Only one external "
                "memory provider is allowed.",
                provider.name, existing,
            )
            return
        self._has_external = True

    self._providers.append(provider)

    # ── 核心工具名保护 ──
    # Provider 的工具不能覆盖内置工具 (clarify, delegate_task...)
    # 否则 _tool_to_provider 路由表会被劫持 (#40466)
    from toolsets import _HERMES_CORE_TOOLS
    _core_tool_names = set(_HERMES_CORE_TOOLS)

    for schema in provider.get_tool_schemas():
        tool_name = schema.get("name", "")
        if tool_name in _core_tool_names:
            logger.warning(
                "Memory provider '%s' tool '%s' shadows a reserved "
                "core tool name; registration ignored.",
                provider.name, tool_name,
            )
            continue

📄 agent/memory_manager.py (第 130-293 行)

class StreamingContextScrubber:
    """Stateful scrubber for streaming text with split memory-context spans.

    一次性正则无法存活 chunk 边界:
    <memory-context> 在一个 delta 打开,
    </memory-context> 在后面的 delta 关闭,
    中间内容会泄漏到 UI。这个 scrubber 跨 delta
    运行状态机, 扣留部分标签尾部, 丢弃 span 内所有内容。
    """

    def feed(self, text: str) -> str:
        """返回清洗后的可见部分。
        可能成为标签开头的尾部片段被扣留,
        下次 feed() 或 flush() 时释放。"""

    def flush(self) -> str:
        """流结束时释放扣留的缓冲区。
        如果仍在未终止 span 内, 丢弃剩余内容
        (更安全: 泄漏部分记忆上下文 > 截断回答)。"""

📄 SKILL.md 格式 (agentskills.io 兼容)

---
name: github-code-review             # 必需, ≤64 字符
description: Perform code review...  # 必需, ≤1024 字符
version: 1.0.0                       # 可选
license: MIT                         # 可选
platforms: [macos, linux]            # 可选 — 平台限制
prerequisites:                       # 可选 — 运行时要求
  env_vars: [GITHUB_TOKEN]
  commands: [git, curl]
required_environment_variables:      # 新版声明方式
  - name: GITHUB_TOKEN
    prompt: "Enter your GitHub token"
    help: "Get one at https://github.com/settings/tokens"
    required_for: API authentication
  - name: SLACK_WEBHOOK_URL
    optional: true
setup:                               # 可选 — 交互式设置
  help: "Configure GitHub access"
  collect_secrets:
    - env_var: GITHUB_TOKEN
      prompt: "GitHub Personal Access Token"
      provider_url: https://github.com/settings/tokens
metadata:                            # 可选 — 任意键值
  hermes:
    tags: [code-review, github]
    related_skills: [test-driven-development]
    config:                          # 技能级配置
      default_reviewer: senior
---

# GitHub Code Review Skill

Full instructions here...

📄 agent/skill_preprocessing.py (第 124-140 行)

def preprocess_skill_content(
    content: str,
    skill_dir: Path | None,
    session_id: str | None = None,
    skills_cfg: dict | None = None,
) -> str:
    """Apply configured SKILL.md template and inline-shell preprocessing."""
    cfg = skills_cfg or load_skills_config()

    # 1. 模板变量替换
    if cfg.get("template_vars", True):
        content = substitute_template_vars(content, skill_dir, session_id)
        # ${HERMES_SKILL_DIR} → /home/user/.hermes/skills/my-skill
        # ${HERMES_SESSION_ID} → abc123-def456

    # 2. 内联 shell 执行 (需显式启用)
    if cfg.get("inline_shell", False):
        timeout = int(cfg.get("inline_shell_timeout", 10) or 10)
        content = expand_inline_shell(content, skill_dir, timeout)
        # !`date +%Y-%m-%d` → 2026-06-19
        # 每个命令独立 try/except, 超时 10s, 输出上限 4000 chars

📄 agent/skill_bundles.py — Bundle 格式

# ~/.hermes/skill-bundles/backend-dev.yaml
name: backend-dev
description: Backend feature work — code review, testing, PR workflow.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Optional extra guidance to inject above the skill bodies.

# 存储: ~/.hermes/skill-bundles/*.yaml
# 冲突: bundle 优先于同名 skill (用户显式命名 = 用户意图)
# 缓存: mtime 感知, 文件变更自动刷新

📄 agent/memory_provider.py (第 279-296 行)

def on_memory_write(
    self,
    action: str,          # 'add', 'replace', 'remove'
    target: str,          # 'memory', 'user'
    content: str,         # 条目内容
    metadata: Optional[Dict[str, Any]] = None,
) -> None:
    """Called when the built-in memory tool writes an entry.

    metadata 包含结构化溯源信息:
      write_origin, execution_context, session_id,
      parent_session_id, platform, tool_name

    用于将内置记忆写入镜像到你的后端。"""