# FlowState-QMD

> 仓库地址：https://github.com/amanning3390/flowstate-qmd
> 作者/组织：amanning3390
> 成熟度：beta
> 分析日期：2026-04-15

## 一句话总结
一个面向编码 agent 的预见性 memory 层，将本地 markdown 文档转化为共享项目记忆，支持 anticipatory context prefetching 和 hybrid search。

## 项目定位与架构
FlowState-QMD 解决的是编码 agent（Codex、Claude、Cursor 等）的上下文获取效率问题——不是等 agent 被动搜索，而是主动预取相关文档到 `~/.cache/qmd/intuition.json`（anticipatory memory）。

三层 memory 架构：Durable Knowledge（indexed markdown collections）→ Working Memory（FlowState anticipatory cache）→ Context Overlays（人工添加的语义摘要）。

技术栈本地优先：Bun runtime + SQLite (FTS5 + sqlite-vec) + node-llama-cpp (Qwen3 models)。检索 pipeline 结合 BM25 全文搜索 + vector similarity + reciprocal rank fusion + 可选 LLM reranking。通过 MCP server（stdio/HTTP）暴露工具：`fetch_anticipatory_context`、`query`、`get`、`multi_get`、`status`。

## 关键技术特性
- **Anticipatory Memory**：主动预取设计文档、changelog、migration notes、RFC、ADR 等到 cache，agent 优先访问
- **Hybrid Search**：BM25 + vector similarity + reciprocal rank fusion + LLM reranking
- **Local-first**：零外部依赖，SQLite + sqlite-vec + local GGUF models
- **Hardware profiles**：Standard（Qwen3 embedding + reranker，16GB+ RAM）和 Lite（~1.2GB VRAM，<8GB）
- **Idempotency**：0.90 cosine threshold 语义去重，多 agent 索引相同内容时标注而非复制
- **Multi-target bootstrap**：`qmd init --target all` 支持 Hermes、Claude Code、Codex、Gemini CLI、Kiro、VS Code 等

## 设计亮点与创新
"Anticipatory memory"概念是核心创新——与传统 RAG 的"query then retrieve"不同，FlowState 预测 agent 需要什么并提前准备。agent skill 中 tool 使用优先级设计也很精巧：anticipatory context first → queries → exact document retrieval。telemetry 持久化（cache hits/misses/refresh latency）支持性能优化迭代。

## 局限性与风险
结果质量依赖 markdown 知识源的质量和覆盖度。anticipatory memory 需要活跃 session 日志。初次 model-backed 搜索有 warmup 延迟。collection 操作（add、embed、update）故意设计为手动——对大量文档场景可能不够高效。

## 与生态系统的关联
作为 memory 工具与 hindsight（长期 semantic/graph/temporal memory）和 honcho-self-hosted（对话 memory backend）形成互补——QMD 专注文档知识，hindsight 专注学习型记忆，honcho 专注对话历史。通过 MCP 协议可集成到任何支持 MCP 的 agent。