qst-memory

QST Memory Management v1.5 是专为 OpenClaw AI Agent 设计的智能记忆管理系统，通过创新的三层树状分类架构与混合搜索引擎，解决了大模型上下文窗口受限与 Token 消耗过高的痛点。该系统不仅提供了物理、计算、审计等多维度的分类体系，更融合了精确树搜索、几何邻域选择与 TF-IDF 语义相似度三种检索模式，使 Agent 能够在海量历史对话中快速定位关键信息。

在核心用法层面，用户可通过 CLI 工具执行多样化的记忆操作：利用 hybrid 模式进行智能检索，结合上下文感知与权重调整实现精准匹配；借助 auto_classify 功能自动推断内容所属分类与重要性等级（Critical/Important/Normal）；通过记忆衰减系统定期清理低价值记录，Critical 级记忆永久保留，Normal 级 30 天后自动删除。系统还支持 --dry-run 预览机制，确保清理操作安全可控。

该系统的显著优点体现在三个维度：首先是极致的 Token 效率，相比传统全量上下文注入，v1.5 版本可减少 70-90% 的 Token 消耗，同时将相关性提升至 95%；其次是灵活的分类体系，三层树状结构支持 34 个细分类别，配合几何邻域算法实现跨类别联想检索；最后是完整的本地隐私保护，所有数据存储于本地 Markdown 文件，无网络传输风险，采用 yaml.safe_load() 与 pathlib 等安全 API 防止代码注入与路径遍历攻击。

然而，作为 T3 来源的个人开源项目，其潜在局限性不容忽视：代码层面存在部分函数异常处理机制不完善的问题，且缺少 requirements.txt 依赖锁定文件；维护层面依赖个人开发者（ZhuangClaw），长期更新与社区支持存在不确定性；功能层面虽适合个人与轻量级场景，但缺乏高并发处理能力，不适用于分布式或多用户生产环境。

该系统最适合以下群体：需要构建个人知识库的 AI Agent 开发者、追求隐私安全的本地优先用户、以及希望优化 LLM 调用成本的技术爱好者。对于科研人员管理文献脉络、开发者维护项目上下文记忆、或智能客服系统归档历史对话等场景均有良好适配。

使用过程中需关注常规风险：数据层面建议定期备份 data/qst_memories.md 文件并设置 600 权限；操作层面执行 cleanup 前务必使用 --dry-run 预览，避免误删重要记忆；性能层面单文件存储架构在记忆条目超过万级时可能出现检索延迟，建议定期归档或分库管理。尽管安全评级为 A 级，但鉴于 T3 来源属性，建议在生产环境部署前进行完整的代码审计与容器化隔离测试。

QST Memory v1.5 綜合評估

核心用法

QST Memory 是一款專為 AI Agent 設計的本地記憶管理系統，採用三層樹狀分類結構（如 QST/Physics/FSCA、User/Identity）組織記憶片段。用戶可透過三種搜索模式檢索：

• Tree Search：精確匹配分類路徑，適合已知類別場景
• Selection Rule：基於幾何鄰居關係擴展搜索（如 QST_Physics ↔ QST_Computation）
• Semantic Search (v1.5)：結合 TF-IDF 餘弦相似度與上下文感知（自動關聯前3輪對話）

Hybrid Search 為預設模式，自動融合三種方法，兼顧精確度與召回率。

自動化功能

• 智能分類：輸入內容自動推薦分類（如「QST暗物質使用FSCA理論」→ QST_Physics_FSCA）
• 權重標記：關鍵詞觸發 Critical/Important/Normal 三級權重，影響記憶保留策略
• 記憶衰減：Normal 級 30 天自動清理、Important 級 365 天歸檔、Critical 級永久保留

顯著優點

1. 極致 Token 效率：官方數據顯示 v1.5 將每查詢 Token 從 v1.2 的 ~500 降至 ~200，降幅 60%，配合上下文剪枝可達 70-90% 省
2. 高相關性保障：TF-IDF + 上下文加權使相關率達 95%，避免傳統向量搜索的語義漂移
3. 零外部依賴：僅需 Python 標準庫 + PyYAML，無網路 API、無雲端洩漏風險
4. 靈活的組織結構：3 層分類深度兼顧粒度與可維護性，支援動態添加分類（需最小 3 次出現）
5. 完善的審計能力：內建統計面板（stats 命令）與乾運行模式（--dry-run），便於維運監控

潛在缺點與局限性

1. 語義理解邊界：TF-IDF 基於詞頻統計，對同義詞（如「ARM 芯片」vs「ARM 處理器」）與深層語義關聯的捕捉弱於現代 Embedding 模型
2. 中文分詞依賴：未整合 Jieba 等專業分詞器，連續文本的 TF-IDF 效果可能受影響
3. 並發寫入風險：當前版本無文件鎖機制，多 Agent 並發操作可能導致數據競爭（報告建議低優先級改進）
4. 分類冷啟動：自動分類準確度依賴既有樹結構與關鍵詞庫，冷啟動階段可能需要人工校準
5. 單機架構限制：記憶存儲於本地 Markdown 文件，無法原生支援分布式部署或跨設備同步

適合人群

| 場景 | 匹配度 |

|------|--------|

長期陪伴型 AI Agent（客服、教育、健康追蹤） | ⭐⭐⭐⭐⭐
高頻對話需成本控制（Token 敏感業務） | ⭐⭐⭐⭐⭐
隱私優先的本地部署（金融、醫療數據） | ⭐⭐⭐⭐⭐
需複雜知識圖譜推理（科研、法律） | ⭐⭐⭐☆☆
多模態記憶（圖片、音頻索引） | ⭐⭐☆☆☆

特別適合個人知識管理助手、垂直領域專家系統（如圖中 QST 物理計算框架）及高頻 API 調用需降本的商業場景。

常規風險

1. 數據持久化風險：雖有衰減系統，但 Critical 級記憶永久保留，長期累積可能導致文件膨脹，需定期人工審查
2. 分類維護成本：隨業務擴展，3 層分類結構可能面臨重構壓力，遷移既有記憶需腳本支援
3. 誤刪風險：Normal 級 30 天自動刪除無回收站機制，建議重要內容主動標記為 Important 以上
4. 依賴單點：雖然依賴極少，但 PyYAML 若出現新 CVE 需及時更新（當前掃描無已知漏洞）

結論

QST Memory v1.5 是工程導向、成本優先的記憶管理方案，以經典信息檢索技術（TF-IDF、BFS）換取確定性與低開銷，在 LLM 上下文窗口有限、API 計費敏感的當下具有明確價值。其 S 級安全評級與 T2 來源可信度（可信 GitHub 組織賬號）使其適合生產環境部署。對於追求極致語義理解或需雲端協作的場景，建議搭配向量數據庫作為補充層。