title: Hermes Agent 记忆系统使用指南：构建持久化智能体的核心引擎
date: 2026-06-03
description: 深入解析 Hermes Agent 记忆系统的工作原理、配置方法和实战技巧，帮助开发者构建真正具备长期记忆能力的 AI 智能体。

Hermes Agent 记忆系统使用指南：构建持久化智能体的核心引擎

引言

在 AI 智能体的发展历程中，记忆能力一直是区分”玩具级”和”生产级”智能体的关键分水岭。一个没有记忆的智能体，每次对话都是”初次见面”——它无法记住用户的偏好、无法追溯历史任务的状态、无法从过去的交互中学习和改进。而 Hermes Agent 作为新一代开源 AI Agent 框架，其记忆系统（Memory System）正是解决这一问题的核心组件。

Hermes Agent 的记忆系统不仅仅是一个简单的对话历史存储工具，而是一个多层、可扩展、持久化的智能记忆架构。它允许 Agent 在对话间保持上下文连贯性，在不同会话中复用已学知识，甚至通过配置文件对记忆行为进行精细化控制。

AI 智能体记忆系统概念图

图片来源：Unsplash — AI 神经网络与记忆存储概念

本文将深入探讨 Hermes Agent 记忆系统的架构设计、配置方法、实战技巧，以及如何利用记忆系统构建真正具备长期记忆能力的生产级 AI 智能体。无论你是刚接触 Hermes Agent 的新手，还是希望深入优化 Agent 行为的资深开发者，本文都将为你提供全面的指导。

一、Hermes Agent 记忆系统架构概述

1.1 什么是记忆系统？

在 Hermes Agent 中，记忆系统负责管理 Agent 的持久化状态信息。这些信息包括但不限于：

记忆类型	存储内容	生命周期	用途
短期记忆 (Session Memory)	当前对话上下文	单次会话	保持对话连贯性
长期记忆 (Long-term Memory)	用户偏好、历史任务结果	跨会话持久化	个性化体验、知识复用
技能记忆 (Skill Memory)	技能执行状态、中间结果	技能生命周期内	技能间数据传递
工作记忆 (Working Memory)	当前任务的临时数据	任务执行期间	任务中间状态管理

Hermes Agent 的记忆系统不同于简单的键值存储——它采用层次化记忆架构，每种记忆类型有不同的存储后端、过期策略和访问权限控制。

1.2 核心架构组件

Hermes Agent 记忆系统的核心架构由以下几个组件构成：

┌─────────────────────────────────────────────────────────┐
│                    Hermes Agent                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  Memory      │  │  Memory     │  │  Memory     │     │
│  │  Manager     │──│  Store      │──│  Retriever  │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │             │
│  ┌──────┴──────┐  ┌──────┴──────┐  ┌──────┴──────┐     │
│  │  Memory     │  │  Backend    │  │  Embedding  │     │
│  │  Profiles   │  │  Adapters   │  │  Engine     │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘

Memory Manager: 记忆系统的中央调度器，负责读写操作的路由、冲突解决和一致性维护
Memory Store: 实际的存储层，支持多种后端（文件系统、SQLite、Redis 等）
Memory Retriever: 记忆检索器，基于语义相似度和时间衰减算法返回最相关的记忆
Memory Profiles: 记忆行为配置文件，定义不同场景下的记忆策略
Backend Adapters: 后端适配器，使记忆系统可以接入不同的存储基础设施
Embedding Engine: 嵌入引擎，将文本转换为向量用于语义检索

1.3 记忆系统的工作流程

当一个交互发生时，Hermes Agent 记忆系统的工作流程如下：

接收消息：Agent 收到用户输入
检索相关记忆：Memory Retriever 在长期记忆中搜索与当前上下文相关的历史记录
上下文增强：将检索到的记忆注入当前对话上下文
处理响应：LLM 基于增强后的上下文生成响应
存储新记忆：将新的交互记录持久化到记忆存储中
索引更新：更新嵌入索引，确保后续检索可以匹配到新数据

记忆系统数据处理流程

图片来源：Unsplash — 数据中心与数据处理可视化

二、记忆系统的安装与配置

2.1 默认记忆配置

Hermes Agent 开箱即用，默认记忆系统已经启用。默认配置存储在用户的 Hermes 配置目录中：

# 查看默认配置文件位置
hermes config show

默认情况下，Hermes Agent 使用文件系统存储作为记忆后端，记忆数据保存在 ~/.hermes/memories/ 目录下：

ls -la ~/.hermes/memories/
# 输出示例：
# -rw-r--r--  1 user user  1024 Jun  3 10:00 memory_store.db
# -rw-r--r--  1 user user  4096 Jun  3 10:00 memory_index.json

2.2 配置文件详解

记忆系统的配置位于 Hermes 配置文件的 [memory] 部分。以下是一个完整的配置示例：

# ~/.hermes/config.toml - 记忆系统配置
[memory]
# 是否启用记忆系统
enabled = true

# 默认记忆配置文件
profile = "default"

# 最大上下文窗口（令牌数）
max_context_tokens = 4096

# 检索的记忆条目最大数量
max_retrieved_items = 5

# 记忆检索的时间衰减因子（0-1）
# 值越大，越旧的记忆被保留的可能性越高
time_decay_factor = 0.85

# 记忆相似度阈值（0-1）
# 只有相似度高于此阈值的记忆才会被检索
similarity_threshold = 0.75

# 是否启用自动记忆摘要
auto_summarize = true

# 摘要间隔（会话数）
summarize_interval = 10

[memory.store]
# 存储后端类型: file, sqlite, redis, postgres
backend = "sqlite"

# SQLite 数据库路径
sqlite_path = "~/.hermes/memories/memory_store.db"

# 是否开启 WAL 模式（提升并发性能）
wal_mode = true

[memory.embedding]
# 嵌入模型
model = "text-embedding-ada-002"

# 嵌入维度
dimensions = 1536

# 本地嵌入模式（离线使用）
local_model = "BAAI/bge-small-zh-v1.5"

[memory.retrieval]
# 检索策略: semantic, recency, hybrid
strategy = "hybrid"

# 混合检索中语义和时效性的权重
semantic_weight = 0.6
recency_weight = 0.4

# 是否启用跨会话检索
cross_session = true

2.3 配置存储后端

Hermes Agent 支持多种存储后端，你可以根据实际需求选择：

SQLite（推荐用于单机部署）

[memory.store]
backend = "sqlite"
sqlite_path = "~/.hermes/memories/memory_store.db"
wal_mode = true

SQLite 是单机部署的首选方案，零配置、轻量级、性能优良。开启 WAL 模式后可以支持并发的读写操作。

Redis（推荐用于生产环境）

[memory.store]
backend = "redis"
redis_url = "redis://localhost:6379/0"
redis_prefix = "hermes:memory:"
redis_ttl = 86400  # 记忆过期时间（秒），0 表示永不过期

Redis 后端提供高性能的内存级读写速度，支持集群部署和数据持久化，适合高并发场景。

PostgreSQL（推荐用于多 Agent 共享）

[memory.store]
backend = "postgres"
postgres_url = "postgresql://user:password@localhost:5432/hermes"
postgres_table = "agent_memories"

PostgreSQL 后端适合多个 Hermes Agent 实例共享同一记忆存储的场景，支持复杂查询和数据备份。

2.4 记忆配置文件（Memory Profiles）

Hermes Agent 支持通过记忆配置文件（Memory Profiles）为不同场景定义不同的记忆行为。每个 Profile 可以设定独立的检索策略、存储后端和衰减参数。

# 列出所有可用的记忆配置文件
ls -la ~/.hermes/profiles/*/memories/

创建一个新的记忆配置文件：

# ~/.hermes/profiles/developer/memories/config.toml
cat > ~/.hermes/profiles/developer/memories/config.toml << 'EOF'
[memory]
# 开发者配置文件：更长的记忆窗口和更高的检索数量
max_context_tokens = 8192
max_retrieved_items = 10
time_decay_factor = 0.9
similarity_threshold = 0.6  # 更宽松的匹配阈值

[memory.store]
backend = "sqlite"
sqlite_path = "~/.hermes/profiles/developer/memories/dev_memory.db"

[memory.retrieval]
strategy = "hybrid"
semantic_weight = 0.7
recency_weight = 0.3
cross_session = true
EOF

切换记忆配置文件：

hermes config set memory.profile developer

三、记忆系统的实战应用

3.1 基础记忆操作

Hermes Agent 提供了一套命令行工具和 API 用于操作记忆系统：

查看当前记忆状态

# 查看记忆系统统计信息
hermes memory stats

# 输出示例：
# Memory System Statistics
# ──────────────────────────────
# Total memories stored: 1,247
# Memory profiles: 3
# Active profile: developer
# Storage backend: sqlite
# Storage size: 2.3 MB
# Last cleanup: 2026-06-03 09:15:00

手动管理记忆

# 搜索记忆
hermes memory search "docker 配置问题"

# 清除所有记忆
hermes memory clear

# 清除特定类型的记忆
hermes memory clear --type session

# 导出记忆为 JSON
hermes memory export --output memories_backup.json

# 导入记忆
hermes memory import --input memories_backup.json

在技能中使用记忆 API

Hermes Agent 的技能系统可以直接访问记忆 API，实现技能级别的记忆管理：

# skills/memory_demo.py
from hermes.skill import Skill
from hermes.memory import MemoryManager

class MemoryDemoSkill(Skill):
    """展示记忆系统 API 使用的示例技能"""

    def __init__(self):
        super().__init__()
        self.memory = MemoryManager()

    async def execute(self, context):
        # 存储记忆
        await self.memory.store(
            key="deployment_preference",
            value={
                "env": "production",
                "port": 8080,
                "ssl": True
            },
            tags=["config", "deployment"],
            ttl=86400 * 30  # 30天过期
        )

        # 检索记忆
        result = await self.memory.retrieve(
            query="deployment configuration",
            max_results=3,
            min_score=0.7
        )

        # 删除记忆
        await self.memory.delete("deployment_preference")

        # 检查记忆是否存在
        exists = await self.memory.exists("deployment_preference")

        return {"memories_retrieved": len(result)}

3.2 跨会话记忆实战

跨会话记忆是 Hermes Agent 最强大的特性之一。它允许 Agent 在不同对话之间保持记忆，实现真正的持续学习。

场景：用户偏好学习

以下示例展示了如何让 Agent 记住用户的技术栈偏好：

# 在技能中实现用户偏好学习
class UserPreferenceSkill(Skill):
    async def learn_preference(self, context):
        user_id = context.user_id

        # 检查已有偏好
        existing = await self.memory.retrieve(
            key=f"user:{user_id}:preferences",
            namespace="user_prefs"
        )

        if existing:
            # 更新已有偏好
            existing.value["last_interaction"] = datetime.now().isoformat()
            existing.value["interaction_count"] += 1
            await self.memory.update(existing)
        else:
            # 创建新偏好记录
            await self.memory.store(
                key=f"user:{user_id}:preferences",
                value={
                    "preferred_language": "Python",
                    "framework": "FastAPI",
                    "database": "PostgreSQL",
                    "deployment": "Docker",
                    "first_interaction": datetime.now().isoformat(),
                    "interaction_count": 1
                },
                namespace="user_prefs",
                ttl=None  # 永不过期
            )

    async def get_preference_context(self, user_id):
        """获取偏好上下文，用于注入 LLM prompt"""
        prefs = await self.memory.retrieve(
            key=f"user:{user_id}:preferences",
            namespace="user_prefs"
        )

        if prefs:
            return f"用户偏好：{prefs.value}"
        return "用户偏好：未知"

场景：任务状态追溯

当执行长时间运行的任务时，记忆系统可以帮助 Agent 追踪任务状态：

class LongRunningTaskSkill(Skill):
    async def track_task(self, task_id, task_name, status, result=None):
        """追踪长时间运行的任务状态"""
        memory_key = f"task:{task_id}:status"

        # 存储任务状态
        await self.memory.store(
            key=memory_key,
            value={
                "task_id": task_id,
                "task_name": task_name,
                "status": status,
                "start_time": datetime.now().isoformat(),
                "last_update": datetime.now().isoformat(),
                "result": result,
                "progress": 0
            },
            tags=["task", task_name],
            ttl=86400 * 7  # 7天后过期
        )

    async def check_interrupted_tasks(self):
        """检查是否有中断的任务需要恢复"""
        # 检索所有状态为 running 的任务
        tasks = await self.memory.search(
            query="task status running",
            tags=["task"],
            max_results=50
        )

        for task in tasks:
            if task.value["status"] == "running":
                # 检查是否超时（超过30分钟无更新）
                last_update = datetime.fromisoformat(task.value["last_update"])
                if (datetime.now() - last_update).seconds > 1800:
                    task.value["status"] = "interrupted"
                    await self.memory.update(task)
                    logger.warning(f"Task {task.value['task_id']} was interrupted")

        return [t for t in tasks if t.value["status"] == "running"]

开发者使用记忆系统架构

图片来源：Unsplash — 开发者工作环境与数据可视化

3.3 语义检索与混合检索策略

Hermes Agent 的记忆检索器支持三种检索策略，各有适用场景：

语义检索（Semantic）

基于向量相似度的语义检索，能理解用户意图的深层含义：

[memory.retrieval]
strategy = "semantic"

适用场景：需要根据内容含义而非关键词进行匹配的场景。例如用户问”上次那个数据库问题怎么解决的”，Agent 会检索到与数据库相关的历史对话，即使关键词不完全匹配。

时效检索（Recency）

基于时间戳的时效性检索，优先返回最近的记忆：

[memory.retrieval]
strategy = "recency"

适用场景：需要获取最新状态信息的场景。例如，Agent 需要知道当前正在运行的任务列表，最近的任务信息比早期的更相关。

混合检索（Hybrid）

结合语义和时效性的混合策略，通过权重参数平衡两者：

[memory.retrieval]
strategy = "hybrid"
semantic_weight = 0.6
recency_weight = 0.4

适用场景：大多数生产环境，既需要语义理解又需要时效性。默认推荐配置。

3.4 记忆摘要与压缩

随着记忆数量增长，记忆系统会占用越来越多的存储空间和检索时间。Hermes Agent 内置了自动记忆摘要功能：

[memory]
auto_summarize = true
summarize_interval = 10  # 每10次会话执行一次摘要

摘要的工作原理：

触发条件：当会话数达到 summarize_interval 的倍数时
分组：将相关记忆按时间窗口和主题分组
摘要生成：使用 LLM 对每组记忆生成摘要
压缩存储：用摘要替换原始详细记忆
索引更新：更新嵌入索引以包含摘要内容

你也可以手动触发摘要：

# 手动执行记忆摘要
hermes memory summarize

# 指定摘要策略
hermes memory summarize --strategy topic  # 按主题分组摘要
hermes memory summarize --strategy time   # 按时间窗口摘要

# 查看摘要结果
hermes memory list --type summary

四、高级配置与优化技巧

4.1 多级记忆管道

对于生产级部署，你可以配置多级记忆管道，将不同优先级的记忆存储在不同后端：

[memory.pipeline]
# 一级：Redis 热存储（毫秒级访问）
[[memory.pipeline.tiers]]
name = "hot"
backend = "redis"
ttl = 3600  # 1小时后降级
max_items = 1000

# 二级：SQLite 温存储
[[memory.pipeline.tiers]]
name = "warm"
backend = "sqlite"
ttl = 86400 * 7  # 7天后降级
max_items = 10000

# 三级：PostgreSQL 冷存储（长期归档）
[[memory.pipeline.tiers]]
name = "cold"
backend = "postgres"
ttl = null  # 永不过期
max_items = null  # 无限制

数据在各级存储中自动迁移：
– 新记忆优先写入热存储
– TTL 到期后自动降级到下一级
– 检索时在所有级别并行查找，合并结果

4.2 记忆分区与命名空间

对于多用户或多项目的场景，记忆分区可以隔离不同上下文的记忆：

# 为不同项目创建独立的记忆命名空间
hermes memory namespace create project-alpha
hermes memory namespace create project-beta

# 在特定命名空间中存储记忆
hermes memory store --namespace project-alpha --key "config" --value '{"port": 3000}'

# 检索特定命名空间的记忆
hermes memory search --namespace project-alpha "config"

# 列出所有命名空间
hermes memory namespace list

在配置中设置默认命名空间：

[memory]
default_namespace = "default"

[memory.namespaces]
project-alpha = { backend = "sqlite", path = "~/.hermes/memories/alpha.db" }
project-beta = { backend = "sqlite", path = "~/.hermes/memories/beta.db" }

4.3 性能优化建议

以下是经过生产验证的性能优化建议：

优化项	建议配置	预期效果
检索数量限制	`max_retrieved_items = 5`	减少 LLM 上下文长度，降低 Token 消耗
相似度阈值	`similarity_threshold = 0.75`	过滤低质量匹配，提高检索精度
WAL 模式	`wal_mode = true`	SQLite 并发写性能提升 5-10 倍
自动摘要	`auto_summarize = true`	长期运行后存储空间减少 60-80%
索引缓存	开启嵌入缓存	重复查询的响应时间降低 90%
批量操作	使用批量 API	大量写入时吞吐量提升 3-5 倍

4.4 监控与调试

Hermes Agent 提供内置的监控工具：

# 查看记忆系统性能指标
hermes memory metrics

# 输出示例：
# Memory Performance Metrics
# ──────────────────────────
# Avg write latency: 2.3ms
# Avg read latency:  1.8ms
# Avg search latency: 15.7ms
# Cache hit rate:    87.3%
# Total operations:  45,231
# Error rate:        0.02%

# 开启详细日志
hermes config set memory.debug true

# 查看记忆检索调试信息
hermes memory search --debug "查询内容"

五、常见问题与最佳实践

5.1 常见问题（FAQ）

Q1: 记忆系统会影响 LLM 的 Token 消耗吗？

是的。检索到的记忆内容会注入到 LLM 的上下文中，消耗 prompt token。建议通过 max_retrieved_items 和 similarity_threshold 控制注入的记忆数量。默认配置下每次检索约消耗 500-1000 tokens。

Q2: 记忆数据的安全性如何保障？

记忆数据默认存储在本地文件系统。对于敏感信息，建议：
1. 使用加密文件系统或全盘加密
2. 启用记忆内容的自动脱敏（auto_sanitize = true）
3. 定期清理过期记忆（hermes memory cleanup --age 30）
4. 使用 Redis 或 PostgreSQL 的 TLS 加密传输

Q3: 如何清除用户的所有记忆？

# 清除特定用户的记忆
hermes memory clear --user-id user_123

# 清除所有跨会话记忆
hermes memory clear --type long_term

# 清除特定命名空间的所有记忆
hermes memory namespace delete project-alpha

Q4: 记忆系统的数据会不会无限增长？

Hermes Agent 内置了多重防无限增长机制：
– TTL 过期自动清理
– 自动摘要压缩
– 容量阈值告警（capacity_warning_threshold = 0.9）
– 最大条目限制（max_entries_per_namespace = 100000）

Q5: 可以禁用记忆系统吗？

可以，将配置中的 enabled 设为 false 即可：

[memory]
enabled = false

5.2 最佳实践总结

从小开始，逐步扩展：初次部署使用 SQLite + 默认配置，根据实际使用情况调整参数
合理设置 TTL：为不同类型的记忆设置合适的过期时间，避免存储过多无用数据
善用命名空间：多项目或多用户场景下，使用命名空间隔离不同上下文的记忆
定期监控指标：关注检索延迟、缓存命中率、错误率等关键指标
备份重要记忆：定期使用 hermes memory export 导出重要记忆数据
结合技能系统：在技能中合理使用记忆 API，实现复杂的业务逻辑
性能与成本平衡：根据 Token 预算和响应速度要求，调整检索数量和摘要策略
测试不同检索策略：在开发环境中测试 semantic、recency、hybrid 三种策略，选择最适合业务的方案

总结

Hermes Agent 的记忆系统是一个设计精巧、功能全面的持久化智能体记忆框架。它通过层次化记忆架构、多后端支持、灵活的检索策略和自动摘要机制，为构建真正具备长期记忆能力的生产级 AI 智能体提供了坚实的基础。

从本文的讲解中，我们了解到：

架构设计：记忆系统的四个核心组件（Manager、Store、Retriever、Profiles）协同工作，实现了从短期上下文到长期记忆的完整生命周期管理
配置灵活：支持 SQLite、Redis、PostgreSQL 等多种后端，以及可自定义的记忆配置文件（Profiles）
实战能力：通过跨会话记忆、语义检索、任务状态追踪等功能，记忆系统在 DevOps 自动化、用户偏好学习、长时间任务管理等场景中发挥关键作用
生产级特性：自动摘要、多级记忆管道、命名空间隔离、性能监控等特性确保了系统的可扩展性和可靠性

Hermes Agent 的记忆系统不仅是一个功能模块，更是一种设计范式——它重新定义了 AI 智能体与用户交互的方式，让每一次对话都不再是孤立的片段，而是持续累积的学习过程。

随着 AI Agent 技术向更复杂的生产环境演进，记忆系统的重要性只会越来越大。掌握 Hermes Agent 的记忆系统，就是掌握了构建下一代智能应用的钥匙。立即开始配置你的记忆系统，让你的 Agent 真正”记住”用户的每一次交互吧！