数据存储层¶

📎 引用文件

本文引用的文件 - agent/src/memory/persistent.py - agent/src/memory/hierarchy.py - agent/src/memory/compression.py - agent/src/memory/lifecycle.py - agent/src/memory/search_index.py - agent/src/memory/semantic_links.py - agent/src/session/store.py

目录¶

简介
项目结构
核心组件
架构总览
详细组件分析
依赖关系分析
性能考量
故障排查指南
结论
附录

简介¶

本文件为 Vibe-Trading 的数据存储层提供系统化文档，覆盖多级存储架构（内存缓存、持久化存储与压缩策略）、分层记忆系统、数据生命周期管理与自动清理机制、数据库选型与索引优化、备份恢复与迁移策略、版本兼容性、存储性能监控与容量规划、扩展方案，以及典型场景（会话历史、研究结果、策略配置）的存储管理实践。

项目结构¶

数据存储层围绕“持久化记忆 + 可选增强能力”构建： - 持久化记忆：基于 Markdown 文件的跨会话记忆，支持元数据前导块、分类目录路由、全文检索与语义链接。 - 层级组织：按 memory_type 将条目路由到 category 子目录，提升扫描与搜索效率。 - 压缩归档：对长期未访问的条目进行分级压缩（原始→每日摘要→要点摘要），并保留原文件归档。 - 生命周期管理：质量评分、衰减、垃圾回收与容量控制。 - 全文检索：SQLite FTS5 倒排索引，支持 CJK 分词与片段高亮。 - 语义链接：BM25 相似度发现与 .relations.json 侧车文件维护。 - 会话存储：文件系统 JSON/JSONL 日志，用于会话、消息与执行尝试记录。

graph TB A["应用调用"] --> B["PersistentMemory 持久化记忆"] B --> C["MemoryHierarchy 分类目录路由"] B --> D["CompressionPipeline 三级压缩"] B --> E["MemorySearchIndex FTS5 索引"] B --> F["SemanticLinker 语义链接"] B --> G["MEMORY.md 轻量索引快照"] H["SessionStore 会话存储"] --> I["sessions/{id}/session.json"] H --> J["sessions/{id}/messages.jsonl"] H --> K["sessions/{id}/attempts/{attempt_id}/attempt.json"]

图表来源 - agent/src/memory/persistent.py:196-637 - agent/src/memory/hierarchy.py:34-436 - agent/src/memory/compression.py:160-353 - agent/src/memory/search_index.py:113-481 - agent/src/memory/semantic_links.py:158-372 - agent/src/session/store.py:16-259

章节来源 - agent/src/memory/persistent.py:196-637 - agent/src/memory/hierarchy.py:34-436 - agent/src/memory/compression.py:160-353 - agent/src/memory/lifecycle.py:71-421 - agent/src/memory/search_index.py:113-481 - agent/src/memory/semantic_links.py:158-372 - agent/src/session/store.py:16-259

核心组件¶

PersistentMemory：跨会话持久化记忆的核心入口，负责条目读写、去重、索引更新、与 FTS5/语义链接集成。
MemoryHierarchy：按 memory_type 路由到 category 子目录，支持扁平兼容、索引重建与范围裁剪。
CompressionPipeline：三级压缩（raw/daily/digest），基于 TF-IDF 句子打分与关键词提取，原子归档原文件。
MemoryLifecycle：质量评分、访问追踪、重要性衰减、垃圾回收（归档/删除）与压缩触发。
MemorySearchIndex：SQLite FTS5 全文检索索引，CJK 分词、片段高亮、批量重建与线程安全单例。
SemanticLinker：BM25 相似度计算与 .relations.json 侧车文件，支持显式 wikilink 引用解析。
SessionStore：文件系统存储会话、消息（追加日志）与执行尝试，具备容错读取与排序。

架构总览¶

存储层采用“文件为主、数据库为辅”的混合架构： - 主数据：Markdown 条目（含 frontmatter 元数据），通过分类目录组织，便于 O(类别规模) 级扫描与检索。 - 辅助索引：SQLite FTS5 倒排索引，提供 O(log n) 级别全文检索；若不可用则回退到本地 token 匹配。 - 语义关联：BM25 相似度生成 .relations.json 侧车文件，支持搜索结果扩展。 - 压缩与归档：按时间阈值触发压缩，原文件原子归档至 archive 目录，保障可恢复性。 - 生命周期：质量评分与访问计数驱动重要性衰减，GC 根据阈值归档或（可选）删除，并触发压缩。 - 会话存储：独立于记忆的 JSON/JSONL 日志，保证会话历史的可追加性与可回溯性。

sequenceDiagram participant App as "应用" participant PM as "PersistentMemory" participant MH as "MemoryHierarchy" participant CP as "CompressionPipeline" participant SI as "MemorySearchIndex" participant SL as "SemanticLinker" App->>PM : add(name, content, type) PM->>MH : route_entry(type, slug.md) MH-->>PM : path PM->>PM : 写入frontmatter+正文 PM->>SI : index_entry(id,title,desc,body) PM->>SL : discover_links & save_relations Note over PM,SL : 可选功能由配置开关控制

图表来源 - agent/src/memory/persistent.py:462-578 - agent/src/memory/hierarchy.py:70-90 - agent/src/memory/search_index.py:207-241 - agent/src/memory/semantic_links.py:179-230

详细组件分析¶

持久化记忆（PersistentMemory）¶

职责：条目增删改查、去重、索引更新、与 FTS5/语义链接集成。
关键设计：
去重：基于内容哈希的滑动窗口去重，避免重试或并发导致的重复写入。
索引：维护 MEMORY.md 作为轻量快照，限制行数以控制体积。
搜索：优先使用 FTS5，失败时回退到本地 token 加权匹配，并结合语义链接扩展结果。
锁定：跨进程写操作使用文件锁保护，避免竞争。
复杂度：
扫描：O(n) 遍历 .md 文件（启用层级后为 O(类别规模)）。
搜索：FTS5 近似 O(log n)，回退路径 O(n)。
错误处理：异常捕获与降级，确保可用性。

flowchart TD Start(["写入入口"]) --> Dedup{"是否重复?"} Dedup --> |是| ReturnNone["返回 None"] Dedup --> |否| Route["路由到分类目录"] Route --> Write["写入frontmatter+正文"] Write --> Index["更新FTS5索引"] Index --> Links["发现并保存语义链接"] Links --> End(["完成"])

图表来源 - agent/src/memory/persistent.py:440-578

章节来源 - agent/src/memory/persistent.py:196-637

层级目录（MemoryHierarchy）¶

职责：按 memory_type 路由到 category 子目录，支持扁平兼容、索引重建与查询范围裁剪。
关键点：
分类：user、feedback、project、reference。
恢复：自动修复无后缀的孤儿条目。
索引：生成 .hierarchy.yaml 统计与关键词，加速查询优先级排序。
迁移：将扁平条目迁移到对应分类目录。
复杂度：扫描 O(类别规模)，重建 O(n)。

classDiagram class MemoryHierarchy { +base_dir Path +route_entry(memory_type, filename) Path +scan_all() Path[] +scan_category(category) Path[] +rebuild_index(entries) void +prune_search_scope(query_tokens, category_filter) Path[] +migrate_flat_entry(file_path, memory_type) Path? }

图表来源 - agent/src/memory/hierarchy.py:34-436

章节来源 - agent/src/memory/hierarchy.py:34-436

压缩管道（CompressionPipeline）¶

职责：三级压缩（raw→daily→digest），原子归档原文件，估算信息保留率。
算法：
句子分割与 TF-IDF 打分，选取 top-k 句子并保留首尾句。
摘要阶段提取高频重要术语，生成要点列表。
触发条件：基于 last_accessed 的时间阈值。
安全性：先归档再压缩，失败不破坏原文件。

flowchart TD S(["开始"]) --> Check{"是否需要压缩?"} Check --> |否| End(["结束"]) Check --> |是| Archive["原子归档原文件"] Archive --> Level{"目标级别"} Level --> |daily| Daily["TF-IDF 关键句提取"] Level --> |digest| Digest["关键词要点摘要"] Daily --> Retention["估算保留率"] Digest --> Retention Retention --> End

图表来源 - agent/src/memory/compression.py:160-353

章节来源 - agent/src/memory/compression.py:160-353

生命周期管理（MemoryLifecycle）¶

职责：质量评分、访问追踪、重要性衰减、垃圾回收与压缩触发。
关键点：
强化学习风格的质量更新，事件驱动 delta。
衰减公式结合访问频率与最近访问时间。
GC 阈值决定归档或删除（默认仅归档），并记录 gc.log。
非 dry_run 时触发压缩周期，更新 frontmatter 中的 compression_level。
复杂度：GC 扫描 O(n)，压缩按需触发。

flowchart TD Start(["运行GC"]) --> Scan["扫描所有条目"] Scan --> Age{"是否满足最小年龄?"} Age --> |否| Next["下一个条目"] Age --> |是| Imp["计算重要性"] Imp --> Threshold{"低于阈值?"} Threshold --> |是| Action{"归档/删除"} Threshold --> |否| Next Action --> Compress{"是否启用压缩?"} Compress --> |是| Apply["应用压缩并写回"] Compress --> |否| Next Apply --> Next Next --> Done(["完成"])

图表来源 - agent/src/memory/lifecycle.py:183-273

章节来源 - agent/src/memory/lifecycle.py:71-421

全文检索（MemorySearchIndex）¶

职责：SQLite FTS5 倒排索引，支持 CJK 分词、片段高亮、批量重建与线程安全单例。
关键点：
CJK 文本展开为 unigram + bigram，提升匹配效果。
查询清洗防止注入，返回 snippet 高亮。
自动重建：首次空搜索且磁盘存在条目时触发全量重建。
复杂度：索引插入 O(1)，搜索近似 O(log n)。

sequenceDiagram participant PM as "PersistentMemory" participant SI as "MemorySearchIndex" PM->>SI : index_entry(id,title,desc,body) SI->>SI : _prepare_cjk(text) SI->>SI : INSERT OR REPLACE memories Note over SI : 触发器同步到 FTS5 PM->>SI : search(query) SI->>SI : _sanitize_fts_query(query) SI-->>PM : MemoryMatch[]

图表来源 - agent/src/memory/search_index.py:207-302 - agent/src/memory/persistent.py:358-438

章节来源 - agent/src/memory/search_index.py:113-481 - agent/src/memory/persistent.py:358-438

语义链接（SemanticLinker）¶

职责：BM25 相似度发现与 .relations.json 侧车文件维护，解析显式 wikilink 引用。
关键点：
IDF 与 BM25 打分，过滤低分链接并限制出度。
原子写入 relations 文件，崩溃安全。
支持 [[hex-id]] 形式的显式引用解析。
复杂度：单次发现 O(m)（候选数），IDF 预计算一次。

classDiagram class SemanticLinker { +discover_links(entry_title, entry_tokens, all_entries_data, top_k) (filename,score)[] +save_relations(entry_path, links) void +load_relations(entry_path) (filename,score)[] +resolve_wikilinks(body) string[] +get_relation_path(entry_path) Path +remove_relations(entry_path) void }

图表来源 - agent/src/memory/semantic_links.py:158-372

章节来源 - agent/src/memory/semantic_links.py:158-372

会话存储（SessionStore）¶

职责：文件系统存储会话、消息（追加日志）与执行尝试，具备容错读取与排序。
关键点：
目录结构清晰，每个会话独立目录。
消息采用 JSONL 追加日志，fsync 保证落盘。
读取时跳过损坏行，保证整体可用性。
复杂度：写入 O(1) 追加，读取 O(n) 扫描。

graph LR A["SessionStore"] --> B["sessions/{id}/session.json"] A --> C["sessions/{id}/messages.jsonl"] A --> D["sessions/{id}/attempts/{attempt_id}/attempt.json"]

图表来源 - agent/src/session/store.py:16-259

章节来源 - agent/src/session/store.py:16-259

依赖关系分析¶

模块耦合：
PersistentMemory 依赖 Hierarchy、SearchIndex、SemanticLinker，形成“主存储 + 增强能力”的组合。
Lifecycle 依赖 PersistentMemory 与 CompressionPipeline，实现生命周期闭环。
SearchIndex 与 SemanticLinker 通过配置开关解耦，降低默认开销。
外部依赖：
SQLite FTS5 作为可选增强，不可用时自动降级。
文件系统锁（fcntl）在类 Unix 平台提供写互斥。
潜在循环：
通过延迟导入避免循环依赖（如 lifecycle 中延迟加载 compression）。

graph TB PM["PersistentMemory"] --> MH["MemoryHierarchy"] PM --> SI["MemorySearchIndex"] PM --> SL["SemanticLinker"] LC["MemoryLifecycle"] --> PM LC --> CP["CompressionPipeline"]

图表来源 - agent/src/memory/persistent.py:196-637 - agent/src/memory/lifecycle.py:71-421

章节来源 - agent/src/memory/persistent.py:196-637 - agent/src/memory/lifecycle.py:71-421

性能考量¶

搜索性能：
启用 FTS5 时，搜索近似 O(log n)，显著提升大规模记忆检索速度。
未启用 FTS5 时，回退到本地 token 匹配，适合小规模场景。
写入性能：
文件锁保护写互斥，避免竞争；Windows 下直接允许写入。
原子写入（临时文件 + rename）减少损坏风险。
压缩与归档：
仅在达到时间阈值时触发，避免频繁 IO。
归档原文件确保可恢复，压缩过程失败不影响原数据。
容量规划：
限制索引行数与条目正文长度，控制内存与磁盘占用。
GC 阈值与最大条目数控制总体规模。
监控建议：
观察 gc.log 与 MEMORY.md 大小变化。
监控 SQLite WAL 状态与 FTS5 可用情况。
跟踪压缩前后文件大小与信息保留率。

故障排查指南¶

写入冲突：
检查文件锁是否超时，确认多进程并发写入场景。
FTS5 不可用：
查看初始化日志，确认 SQLite 编译选项是否包含 FTS5。
若不可用，系统将自动回退到本地 token 匹配。
压缩失败：
检查 archive 目录权限与磁盘空间。
关注压缩异常日志，必要时回滚原文件。
语义链接异常：
校验 .relations.json 格式与版本，确保解析兼容。
会话数据损坏：
读取 JSONL 时跳过损坏行，定位问题行号并修复。

章节来源 - agent/src/memory/persistent.py:42-73 - agent/src/memory/search_index.py:147-173 - agent/src/memory/compression.py:258-291 - agent/src/memory/semantic_links.py:282-305 - agent/src/session/store.py:164-193

结论¶

Vibe-Trading 的数据存储层以文件为核心，辅以 SQLite FTS5 与语义链接增强，实现了高效、可扩展且可恢复的记忆与会话存储体系。通过层级目录、压缩归档与生命周期管理，系统在性能与容量之间取得平衡，并提供灵活的配置开关以适应不同部署环境。

附录¶

数据库选型与表结构¶

数据库：SQLite（FTS5 虚拟表用于全文检索）。
表结构：
memories：id、title、description、keywords、body。
memories_fts：FTS5 虚拟表，映射到 memories 内容。
索引优化：
FTS5 MATCH 查询，snippet 高亮。
CJK 文本展开为 unigram + bigram，提升匹配召回。

章节来源 - agent/src/memory/search_index.py:147-196 - agent/src/memory/search_index.py:357-407

备份恢复与迁移策略¶

备份：
记忆目录整体复制，包括 archive 目录与原文件。
SQLite 数据库文件（WAL 模式）需同时备份主库与 WAL 文件。
恢复：
恢复记忆目录与数据库文件，重启服务即可。
若 FTS5 不可用，首次搜索将自动重建索引。
迁移：
扁平条目迁移到分类目录，保持文件名不变。
无后缀条目自动修复为 .md 后缀。

章节来源 - agent/src/memory/hierarchy.py:92-143 - agent/src/memory/hierarchy.py:381-436 - agent/src/memory/search_index.py:304-355

版本兼容性¶

语义链接版本：.relations.json 包含 version 字段，解析时校验版本。
压缩级别：frontmatter 中 compression_level 字段标识当前压缩级别。
降级策略：FTS5 不可用时自动回退到本地 token 匹配。

章节来源 - agent/src/memory/semantic_links.py:54-56 - agent/src/memory/semantic_links.py:303-305 - agent/src/memory/persistent.py:257-258 - agent/src/memory/search_index.py:160-173

典型数据存储场景¶

会话历史：
使用 SessionStore 存储会话元数据与消息日志，支持追加与回溯。
研究结果：
使用 PersistentMemory 存储研究笔记与结论，配合 FTS5 快速检索。
策略配置：
使用分类目录（如 project）组织策略相关记忆，便于按类型管理。

章节来源 - agent/src/session/store.py:16-259 - agent/src/memory/persistent.py:196-637 - agent/src/memory/hierarchy.py:19-21

← 数据处理管道数据流设计 →