oGMemory 架构
oGMemory 是面向 Agent 的上下文生命周期引擎。它贯穿 Agent 循环的关键边界，管理什么进入上下文窗口、什么被持久化、什么被压缩归档，以及什么能够在后续会话中被重新召回。
架构总览
oGMemory 的核心设计是把上下文当作有生命周期的数据来管理，而不是只把它当作向量检索文本。系统分为接入层、服务编排层、写入链路、读取链路、ContextFS、会话层和异步索引层。
ContextFS 是上层统一的上下文存储抽象。它可以落到 AGFS，也可以落到 DB-first 存储。DB-first 在这里指用数据库表直接承载语义节点、内容、摘要、概览、关系和元数据，是对 AGFS 主存储形态的平替；上层的抽取、写入策略、检索和压缩流程不需要感知底层到底是 AGFS 还是 DB-first。
Agent / Plugin
|
| HTTP REST / Python SDK
v
+--------------------------------------------------+
| HTTP API |
| 生命周期入口、认证、RequestContext 构建 |
+-------------------------+------------------------+
|
v
+--------------------------------------------------+
| MemoryService |
| compose / after_turn / compact / dispose |
+-------------------------+------------------------+
|
+-----------------+-----------------+
| |
v v
+-------------------+ +-------------------+
| 写入链路 | | 读取链路 |
| 抽取 -> 策略路由 | | 意图 -> L0/L1/L2 |
| -> 原子写入 | | -> 评分 -> 组装 |
+---------+---------+ +---------+---------+
| |
+-----------------+-----------------+
|
v
+--------------------------------------------------+
| ContextFS |
| 语义节点、内容、摘要、概览、关系、元数据 |
+-------------------------+------------------------+
|
+-----------------+-----------------+
| |
v v
+-------------------+ +-------------------+
| 会话层 | | 异步索引层 |
| SessionBuffer | | OutboxWorker |
| Archive / Compact | | L0/L1/L2 Index |
+-------------------+ +-------------------+
|
v
+--------------------------------------------------+
| 存储后端 |
| AGFS / DB-first + Vector DB |
+--------------------------------------------------+写入数据流
一条对话信息从 Agent 轮次结束到可检索，经过以下路径：
Agent 轮次结束
|
v
after_turn
|
v
增量抽取
|
v
CandidateMemory[]
|
v
PolicyRouter
按上下文类型选择写入策略
|
v
ContextWriter
原子写入 ContextFS
底层可落 AGFS，也可落 DB-first
|
v
OutboxEvent
|
v
Index Worker
生成 L0 / L1 / L2 向量索引写入链路关注四件事：
| 目标 | 说明 |
|---|---|
| 抽取 | 从对话中识别 profile、preference、event、skill 等候选上下文 |
| 路由 | 根据上下文类型选择 merge、aggregate 或 append 写入策略 |
| 持久化 | 通过 ContextFS 写入主存储；底层可以是 AGFS 目录文件，也可以是 DB-first 数据库表 |
| 索引 | 写入完成后通过 Outbox 后台生成 L0/L1/L2 向量索引 |
读取数据流
一次用户查询从进入 oGMemory 到注入 Agent 上下文，经过以下路径：
用户查询
|
v
compose
|
v
意图识别与查询规划
|
v
L0 / L1 / L2 混合向量搜索
|
v
L0 / L1 命中作为目录入口
|
v
层次展开到 L2 内容
|
v
回源 ContextFS 读取内容
底层 AGFS / DB-first 对读取链路透明
|
v
排序、去重、预算控制
|
v
组装为可注入上下文读取链路不只做单层 top-k 搜索。oGMemory 同时索引摘要、概览和完整内容：
| 层级 | 内容 | 作用 |
|---|---|---|
| L0 | 短摘要 | 快速定位主题，作为目录路标 |
| L1 | 结构化概览 | 判断相关性和内容范围 |
| L2 | 完整内容 | 提供最终可注入的详细证据 |
这种分层检索方式可以减少长文本 embedding 信号稀释带来的漏召回。L0/L1 负责定位，L2 负责提供完整信息。
无论主存储采用 AGFS 还是 DB-first，读取链路都通过 ContextFS 回源读取内容；Vector DB 只负责候选召回和排序所需的索引视图。
生命周期模型
oGMemory 按 Agent 运行阶段组织上下文能力。每个阶段只处理适合该阶段的事情，避免把所有逻辑塞进一次检索或一次抽取里。
| 阶段 | 时机 | 主要入口 | 作用 |
|---|---|---|---|
| ① 消息到达 | Agent 推理前 | compose | 解析当前问题，预取候选上下文 |
| ② 推理准备 | 组装上下文窗口 | compose | 注入 profile、归档历史、会话状态和检索证据 |
| ③ 工具使用 | 工具调用前后 | tool usage collector | 收集工具调用统计，为后续抽取和观测提供输入 |
| ④ 轮次结束 | Agent 完成一轮后 | after_turn | 累积新消息，达到阈值后抽取并写入长期记忆 |
| ⑤ 压缩管理 | 上下文接近上限或显式 compact | prepare_compaction / compact | 抽取未处理内容，归档会话，返回压缩摘要 |
| ⑥ 会话关闭 | 会话结束 | dispose | 刷新剩余消息，清理活跃 session |
生命周期中的上下文流转
对话消息
-> SessionBuffer
-> 增量抽取
-> ContextFS 节点
(AGFS 或 DB-first 主存储)
-> Outbox 异步索引
-> 分层检索
-> compose 注入
-> compact / dispose 归档上下文类型
oGMemory 按信息语义区分上下文类型。不同类型有不同的生命周期、写入策略和作用域。
| 类型 | 作用 | 写入方式 | 典型作用域 |
|---|---|---|---|
| profile | 用户稳定身份信息，如姓名、职业、地点 | 合并 | user |
| preference | 用户偏好，如编码风格、工具偏好 | 按主题合并 | user |
| entity | 人、项目、组织、地点等实体事实 | 按实体合并 | user |
| event | 有时间边界的历史事件 | 追加写入 | user |
| case | Agent 解决问题的案例和经验 | 追加写入 | agent |
| pattern | 从交互中观察到的行为模式 | 按主题合并 | user |
| skill | Agent 可复用的工作流程和技能 | 按技能合并 | agent |
| tool | 工具使用经验、参数建议和失败模式 | 按工具合并 | agent |
这些类型由 YAML Schema 声明。Schema 决定抽取字段、owner scope、目录模板和写入模式，因此用户可以新增自定义上下文类型并且不需要改动主流程。