记忆系统未生效需按五步排查：一、验证向量数据库连接状态；二、检查本地持久化目录权限与磁盘空间；三、确认嵌入模型加载完整性及缓存命中率；四、排查动态记忆压缩策略是否过度裁剪；五、校验用户级记忆隔离标识（user_id）是否一致。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用Hermes Agent时发现记忆系统（如长期记忆向量库、对话上下文缓存、用户偏好持久化）未生效，表现为历史交互无法回溯、重复提问同一问题、个性化配置不保留等现象，则可能是由于向量数据库连接失败、内存缓存未启用、持久化路径权限异常或嵌入模型加载中断所致。以下是解决此问题的步骤：
一、验证向量数据库服务状态与连接配置
记忆系统依赖外部向量数据库（如ChromaDB、Qdrant或Weaviate）存储和检索语义向量。若服务未运行、端口不可达或认证凭据错误，所有记忆写入与查询操作将静默降级为内存临时缓存，导致重启后丢失。
1、执行内置健康检查脚本：python tools/memory/health_check.py --verbose
2、确认输出中status字段为"connected"且vector_db字段显示活跃连接数大于0
3、若返回ConnectionRefusedError，检查~/.hermes/config.yaml中memory.vector_db.url值是否指向有效地址，例如http://localhost:8000
4、手动测试数据库连通性：curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/health
5、若返回000或404，需启动对应向量服务；若返回401，检查config.yaml中memory.vector_db.api_key是否已正确设置且未被.env文件中的同名变量覆盖
二、检查本地持久化目录权限与磁盘空间
当向量数据库不可用时，Hermes Agent会自动 fallback 至本地SQLite+FAISS混合存储方案，该方案将索引文件与元数据写入~/.hermes/memory/目录。若该路径不可写、磁盘满或SELinux/AppArmor策略拦截，记忆将仅保留在运行时内存中，进程退出即清空。
1、运行命令验证路径可写性：test -w ~/.hermes/memory && echo "writable" || echo "permission denied"
2、检查磁盘剩余空间：df -h ~/.hermes/memory | awk 'NR==2 {print $5}' | sed 's/%//'
3、若数值大于95，执行清理：find ~/.hermes/memory -name "*.faiss" -mtime +7 -delete
4、确认SELinux状态：sudo sestatus | grep "current mode"，若为enforcing，临时设为permissive：sudo setenforce 0
5、重启Agent后验证memory目录下是否生成timestamped_subdir及index.faiss文件且文件大小持续增长
三、确认嵌入模型加载完整性与缓存命中率
记忆检索依赖嵌入模型（embedding model）将文本转为向量。若模型加载失败、分词器缺失或CUDA设备不可用，系统将跳过向量化步骤，直接以原始文本哈希作为伪键存入，导致语义检索失效、召回率趋近于0。
1、查看启动日志中是否包含"Embedding model loaded"字样：hermes logs | grep -i "embedding\|model.*load"
2、若出现"OSError: Can't load tokenizer"，进入tools/embeddings/目录执行：python init_model.py --model-name BAAI/bge-small-zh-v1.5 --force-download
3、检查GPU可用性：python -c "import torch; print(torch.cuda.is_available())"
4、若返回False但配置了cuda:true，修改~/.hermes/config.yaml中embedding.device字段为cpu
5、调用诊断接口验证缓存命中：curl -X POST http://localhost:8001/memory/diagnose -d '{"query":"用户上次提到的项目名称"}' | jq '.cache_hit_rate'
6、若cache_hit_rate低于0.1，说明向量化链路中断，必须重新触发一次完整记忆初始化：hermes memory init --force
四、排查上下文窗口截断与记忆压缩策略冲突
为控制内存占用，Hermes Agent默认启用动态记忆压缩（Dynamic Memory Compression），对长对话历史进行摘要聚合。若压缩阈值设置过激或摘要模型响应超时，原始记忆条目可能被提前合并、覆盖或丢弃，造成“记忆消失”假象。
1、打开~/.hermes/config.yaml，定位memory.compression区块
2、检查max_context_length值是否小于当前对话token总数，可通过hermes debug context-length命令获取实时长度
3、将compression.enabled设为false，重启Agent并复现一次记忆写入操作
4、执行hermes memory list --limit 5，确认返回结果中包含本次新增条目的完整原始文本而非摘要片段
5、若禁用压缩后记忆正常留存，说明原配置存在过度裁剪，应将min_compression_tokens调高至2048以上并启用fallback_to_full_text:true
五、校验用户级记忆隔离标识是否一致
Hermes Agent按user_id进行记忆分区。若前端网关（如飞书机器人、微信插件）未正确传递user_id，或多个客户端共享同一session_id，将导致记忆混杂或无法定位目标用户记忆库，表现为“我的记忆被别人覆盖”或“我的记忆找不到”。
1、在网关日志中搜索"user_id:"字段，确认每次请求携带的ID是否为稳定唯一值，例如feishu_openid_abc123
2、检查tools/gateway/lark_adapter.py中get_user_id()函数是否从event.user_id而非event.sender.id提取标识
3、运行调试命令：hermes memory inspect --user-id feishu_openid_abc123 --show-raw
4、若返回空结果但其他ID有数据，说明该用户ID未被写入；若返回多用户混合数据，说明隔离逻辑失效
5、强制重置用户记忆命名空间：hermes memory reset --user-id feishu_openid_abc123 --hard 此操作不可逆，仅限调试环境执行
