Eidolon Search

基于 FTS5 的 AI Agent 记忆搜索方案。仅需对 Markdown 文件索引一次，即可实现 90%+ 的 token 节省。

快速开始

1. 索引记忆文件（仅需一次）

python3 scripts/build-index.py  

示例：

python3 scripts/build-index.py ./memory ./memory.db

该命令将在指定目录（递归）下所有 .md 文件构建一个 SQLite 数据库，并使用 FTS5 创建全文索引。

2. 搜索

python3 scripts/search.py  [limit] [db_path]

示例：

python3 scripts/search.py "Physical AI roadmap" 5
python3 scripts/search.py "project timeline" 10 ./memory.db

默认 limit 值为 10；默认 db_path 为 ./memory.db。

输出：匹配的文本片段（snippet），包含对应文件路径及相关性得分。

3. 文件变更后重新索引

再次运行 build-index.py 即可。该脚本将从头重建索引（速度快，典型工作区耗时 <1 秒）。

适用场景

• 记忆搜索：在大量日常笔记或记忆文件中查找特定信息
• 上下文 token 受限：一次性读取全部文件会超出模型上下文长度限制
• 高频重复搜索：索引一次，多次查询
• 大型工作区：包含 10+ 个 Markdown 文件，总大小 >50KB

不适用场景

• 单个小型文件（<5KB）：直接读取即可
• 需要语义/语义层面的搜索：FTS5 仅支持关键词匹配
• 更多已知限制请参阅 references/QUALITY.md

Agent 搜索技巧

FTS5 基于关键词匹配。可通过以下方式提升搜索效果：

• 使用具体术语：例如用 "Jetson Orin"，而非 "hardware plans"
• 使用 OR 连接同义词：例如 "car OR vehicle OR automobile"
• 使用英文双引号包裹短语：如 "Physical AI"
• 若首次查询无结果，建议尝试多个不同查询
• 根据结果中的文件路径，按需读取完整上下文

性能基准测试

• Token 节省率：90%+（实测值为 93–98.9%）
• 查询速度：快 15 倍（实测值为 10–20 倍）
• 详细数据请参阅 references/PERFORMANCE.md

可自行运行基准测试：

python3 scripts/benchmark-recall.py    # Recall@5、Recall@10
python3 scripts/benchmark-cache.py     # 热缓存 vs 冷缓存

数据库 Schema

CREATE VIRTUAL TABLE memory_fts USING fts5(path, content);

支持直接 SQL 查询：

sqlite3 memory.db "SELECT path, snippet(memory_fts, 1, '', '', '...', 32) FROM memory_fts WHERE memory_fts MATCH 'query' ORDER BY rank LIMIT 5;"