模块由三个相互独立、无循环依赖的子包组成:
- memory/:以 PersistentMemory(persistent.py)为核心,将每条记忆持久化为带 YAML frontmatter 的 .md 文件,维护 MEMORY.md 索引;通过 hierarchy.py 按类型路由到子目录,compression.py 在 GC 时降级 body,search_index.py 基于 SQLite FTS5 做关键词检索并回退到本地 token 匹配,semantic_links.py 用 BM25 发现条目间关联;lifecycle.py 的 MemoryLifecycle 在 PersistentMemory 之上叠加 Ebbinghaus 衰减、访问计数、reinforcement 事件与容量回收,所有写操作经 memory_lock(POSIX fcntl.flock / Windows msvcrt)串行化。
- entities/:纯数据层,models.py 定义 Entity/Instrument/Security/Fund/Bond 等 frozen dataclass,并在 __post_init__ 中集中校验货币、日期、枚举取值与业务约束;cashflow.py 提供 CashFlowSeries 作为与 bar 引擎解耦的现金流分析序列;ingest.py 负责外部 CSV/JSON 到这些模型的装载。
- governance/:ledger.py 实现哈希链式 JSONL 追加账本,每条记录包含 seq/prev_record_hash/record_hash,写入前对整条链做 O(n) 校验并 fsync 落盘,支持分段归档(rotate_if_needed)与离线导出/验证(build_export/verify_export);manifest.py 对系统提示、技能、工具注册表与关键包版本计算确定性指纹,diff_manifests 输出两次运行的差异。
依赖方向单向:memory 仅读 src.config.accessor 开关并可选调用 search_index/semantic_links;entities 零外部依赖;governance 不依赖 agent 其他模块,仅被 src/live/audit.py 消费。