应依次执行五步优化：一、用EXPLAIN QUERY PLAN分析查询计划，识别SCAN或临时表问题；二、为conversations表创建FTS5虚拟表并启用porter分词；三、对task_id与timestamp等高频组合字段建复合索引；四、全面改用参数化查询防止注入并复用执行计划；五、按CPU核心数×2配置连接池，设pool_recycle=300、connect_timeout=3。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在使用Hermes Agent过程中观察到会话检索缓慢、全文搜索延迟明显或高频查询响应超时，则很可能是SQLite数据库查询未经过针对性优化。以下是解决此问题的步骤：
一、启用并分析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);
四、启用参数化查询并避免字符串拼接
参数化查询不仅防止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、将所有动态WHERE条件替换为占位符形式，例如将cursor.execute(f"SELECT * FROM sessions WHERE user_id = {user_id}")改为cursor.execute("SELECT * FROM sessions WHERE user_id = ?", (user_id,))。
3、在批量插入场景中统一使用executemany()配合元组列表，例如：cursor.executemany("INSERT INTO conversations VALUES (?, ?, ?, ?)", batch_data)。
五、调整数据库连接池配置以匹配查询负载
不合理的连接池设置会导致连接争抢或资源闲置，进而放大查询延迟。需根据并发量与硬件能力同步调优连接数、超时与回收策略。
1、在environments/default.yaml中定位database配置段，确认当前pool_size值是否超过CPU核心数的2倍。
2、将max_overflow设为不超过pool_size的50%，例如pool_size为10时，max_overflow应≤5。
3、设置pool_recycle为300（5分钟），避免长连接因数据库端超时被静默断开；同时将connect_timeout显式设为3秒，防止获取连接卡死。
