数据库查询性能不足时，应依次执行七步优化：启用EXPLAIN QUERY PLAN分析执行计划；构建FTS5全文索引；创建复合索引加速多条件过滤；改写为参数化查询；引入连接池空闲回收机制；实施批量读取；启用索引缓存。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用Hermes Agent时发现会话检索缓慢、全文搜索响应迟滞或高并发下查询超时，则很可能是数据库查询执行效率不足所致。以下是针对性的优化步骤：
一、启用并分析SQLite执行计划
执行计划揭示了SQLite如何实际执行SQL语句，是定位低效操作的直接依据。通过EXPLAIN QUERY PLAN可识别全表扫描、缺失索引或临时表生成等关键问题。
1、在hermes_state.py中定位核心查询语句，例如会话搜索逻辑所在的session_search_tool.py模块。
2、在目标SQL语句前添加EXPLAIN QUERY PLAN前缀，例如：EXPLAIN QUERY PLAN SELECT * FROM conversations WHERE content MATCH 'agent';
3、运行该语句并检查输出结果中是否出现SCAN（顺序扫描）或USING TEMP B-TREE等提示，这些表明存在性能风险点。
二、构建FTS5全文索引
FTS5索引专为自然语言文本搜索设计，能将关键词匹配类查询从秒级响应压缩至毫秒级，适用于conversations表等含大量对话内容的场景。
1、确认当前conversations表是否已启用FTS5虚拟表，检查hermes_state.py中是否存在类似CREATE VIRTUAL TABLE IF NOT EXISTS conversations USING fts5(task_id, content, timestamp, tokenize = 'porter unicode61');的定义。
2、若未启用，执行该建表语句，并确保后续插入数据走虚拟表路径而非普通表。
3、对新增字段补充索引列，例如增加user_id字段以支持按用户+内容联合检索：CREATE VIRTUAL TABLE IF NOT EXISTS conversations USING fts5(task_id, user_id, content, timestamp, tokenize = 'porter unicode61');
三、创建复合索引加速多条件过滤
当查询同时包含WHERE子句中的多个字段（如task_id与timestamp范围组合），单一列索引无法生效，必须建立覆盖全部筛选条件的复合索引，使SQLite可直接通过B-tree快速定位数据区间。
1、识别高频组合查询模式，例如SELECT * FROM conversations WHERE task_id = ? AND timestamp BETWEEN ? AND ?;
2、在hermes_state.py初始化阶段执行索引创建命令：CREATE INDEX IF NOT EXISTS idx_conversations_task_time ON conversations(task_id, timestamp);
3、验证索引是否被命中：再次运行EXPLAIN QUERY PLAN，确认输出中出现SEARCH conversations USING INDEX idx_conversations_task_time。
四、改写查询为参数化形式
参数化查询不仅防止SQL注入攻击，还能使SQLite复用预编译的查询计划，避免每次解析带来的开销，尤其在高频重复查询场景下效果显著。
1、定位skills/github/github-code-review/SKILL.md中明确标注的高危代码段：“?Critical: User input passed directly to SQL query— use parameterized queries to prevent injection.”
2、将所有动态拼接SQL替换为占位符形式，例如将cursor.execute(f"SELECT * FROM sessions WHERE user_id = {user_id}")改为cursor.execute("SELECT * FROM sessions WHERE user_id = ?", (user_id,))。
3、检查toolset_distributions.py中涉及数据库访问的工具函数，统一应用?占位符与元组传参模式。
五、引入连接池空闲连接回收机制
长时间空闲的数据库连接可能因网络中断或数据库端超时而失效，继续复用将导致查询失败；定期回收可确保连接池内连接始终处于可用状态，间接提升查询成功率与稳定性。
1、打开environments/default.yaml配置文件，定位database.connection_pool区块。
2、设置idle_timeout: 300（单位秒），即空闲连接超过5分钟自动关闭并从池中移除。
3、同步调整connection_timeout: 5，限制获取连接的最大等待时间为5秒，避免线程阻塞过久。
六、实施批量读取减少往返次数
单条记录逐次查询会产生大量网络与解析开销，尤其在需要拉取时间范围内全部会话摘要时；合并为一次LIMIT/OFFSET或IN列表查询，可大幅降低I/O总量。
1、在session_search_tool.py中查找分页逻辑，将原本循环调用get_conversation_by_id()的方式重构为单次查询：SELECT * FROM conversations WHERE timestamp BETWEEN ? AND ? ORDER BY timestamp DESC LIMIT 100;
2、若需按多个task_id批量获取，改用WHERE task_id IN (?, ?, ?)配合参数化传入ID列表。
3、对于导出类操作，在scripts/sample_and_compress.py参考其分批策略，设定batch_size=200，避免单次加载超限内存。
七、启用索引缓存减少重复加载
技能中心模块已内置索引缓存机制，用于暂存远程索引元数据，避免每次查询都触发HTTP请求与数据库反序列化；激活该机制可直接降低CPU与网络负载。
1、确认agent/prompt_builder.py中调用_read_index_cache()函数的位置，确保其在索引构建前被优先尝试。
2、检查_write_index_cache()是否在索引更新后被正确调用，写入路径应指向持久化目录如./.cache/skill_index.db。
3、设置环境变量HERMES_INDEX_CACHE_ENABLED=true，强制开启缓存开关。
