核心用法
midos-memory-cascade 是一套为 AI Agent 设计的分层记忆路由系统。开发者通过 query() 发起查询时，系统会按 T0→T4 的优先级逐级检索：T0（内存字典 <1ms）→ T1（JSON 文件 <5ms）→ T2（SQLite <5ms）→ T3（SQLite 全文索引 <1ms）→ T4（Grep 回退 ~3s）。每层的置信度阈值决定是否继续下探，命中即返回。写入时 store() 根据数据类型自动选择持久化层级：session 状态进内存、结构化配置存 JSON、知识库内容入 SQLite 并建立全文索引。
系统内置 evolve() 自学习机制：累计 20 次以上查询后，分析查询签名（前 3 词）的命中分布。若某签名在固定层级命中率超 80%，则生成 shortcut 直接跳转；若某层级整体命中率低于 5%，则标记 skip 避免空转。学习结果持久化到 cascade_stats.json，下次启动自动加载。
显著优点
延迟优化显著：热数据 T0 命中亚毫秒响应，相比单层存储的恒定全量扫描，长尾查询成本降低 2-3 个数量级。
零依赖轻量：核心层无外部依赖，纯 Python 标准库即可运行，避免供应链攻击面。
自学习进化：无需人工调参，系统根据实际 workload 自动收敛到最优路由策略。
渐进式集成：支持纯文档协议模式（零代码）和完整引擎模式，团队可按需采纳米级功能。
生态扩展性：接入 MidOS 完整生态后，T3 层可扩展至 670K 向量的 LanceDB 语义检索，并配备 GEPA 质量评分和自动升级流水线。
潜在缺点与局限性
冷启动惩罚：首次查询无历史 shortcut 时，必须走完完整级联，T4 层 Grep 扫描大目录可能耗时 3 秒以上。
学习门槛：5 层架构 + 置信度阈值 + shortcut 机制的概念密度高，团队需要理解分层设计哲学才能正确配置数据类型路由。
签名哈希冲突：shortcut 基于查询前 3 词归一化签名，语义相近但表述不同的查询可能无法复用 shortcut。
SQLite 规模瓶颈：T2/T3 层依赖本地 SQLite，单库 22K+ 行后 FTS 性能可能衰减，超大规模场景需接入 LanceDB 等向量扩展。
生态锁定：完整功能（语义搜索、MCP 工具暴露、质量评分）需绑定 MidOS 付费生态（$20/月），独立模式仅保留 80% 核心能力。
适合的目标群体
- 构建复杂 Agent 的开发者：需要处理会话状态、项目知识、跨会话记忆三类数据的长期运行 Agent。
- 延迟敏感型应用：客服、实时交互等场景，要求热查询 <10ms 响应。
- 本地优先/隐私优先团队：希望数据驻留本地，拒绝云同步的合规敏感项目。
- MidOS 生态用户：已使用 MidOS 200+ skills 的开发者，可获得无缝集成体验。
使用风险
性能风险：T4 Grep 回退在超大代码库（百万行级）可能超时，建议设置查询超时熔断或限制搜索目录范围。
数据持久化风险：T0 session 状态默认非持久化，Agent 重启即丢失关键上下文，生产环境需显式配置 durability 参数。
shortcut 漂移：业务逻辑变化后，历史 shortcut 可能指向错误层级，需定期手动触发 evolve() 或配置定时任务重建。
stats 文件损坏：cascade_stats.json 若被意外篡改，可能导致路由决策异常，建议纳入版本控制或配置备份策略。
多实例一致性问题：分布式部署时，各实例独立维护 shortcut 状态，缺乏全局共识机制，可能出现路由策略分歧。