tgms

TGMS — 面向 Agent 的双时态图管理系统

一种时态图数据库，其查询接口专为大模型 Agent 构建—— 其答案还可以逐条主张地审计。

项目页面与博客： https://zxf-work.github.io/tgms/ · 论文： paper/main.pdf

大模型 Agent 恰好不擅长时态图分析所需的几件事：算术运算、标识符，以及只陈述证据所支持的内容。TGMS 的应对方式是从架构入手——不给模型任何机会去做这些事：

• 一个双时态属性图（有效时间 × 事务时间），能够区分演进（“边已结束”）和更正（“我们之前弄错了”），因此 Agent 可以回答*“我们在 3 月 1 日时相信什么？”*——最新状态快照和我们评估过的 RAG 配置都无法表达这个问题。双时态本身是继承而来，并非这里发明——它已有四十年的文献积累，写入了 SQL:2011 标准，也有围绕它构建的生产数据库。我们以其中最清晰的方案 XTDB 为基准：输入相同的操作流后，两个系统在 400 个探测点上对所信状态的判断完全一致；在以更正为主的写入场景中，TGMS 速度快 3.9–4.7×，磁盘占用少 23–27× (正面对比)；
• 由于在依据某个答案采取行动之后，信念仍可能被更正，TGMS 现在会告知你这种情况：tgms trace check 会根据事件日志检查已保存答案的依赖范围——无需重新计算，也无需锁定存储——并返回 FRESH / POSSIBLY_STALE / UNDECIDABLE；在关键的判断方向上保证可靠（绝不会将过时答案判为新鲜）。在两轮注入测试中共进行了 6,978 次试验：M4 测试（第 2 次运行，账户记录）中，447 个已变化答案没有出现任何误判为新鲜的情况；M5 carve-2 测试（28,044 次试验）中，1,852 个已变化答案也没有出现任何误判为新鲜的情况。而显而易见的廉价检查——“更正是否触及已存结果中的某一行？”——在 M4 的试验中有 47.4% 的情况下会得出错误结论；
• 现在，你想要保留而不只是检查的已保存结果，也能自行维护：tgms artifact register/check/refresh 会将其转换为带名称和代数编号的制品——刷新时只重新计算你指定的内容，旧代在磁盘上的字节保持不变；刷新还会向下传播一跳，更新任何基于该制品构建的其他内容，即使那些依赖项自身的范围从未被触及。在 M5 维护测试中测得：37,371 次试验中没有误判为新鲜，5,867 次传播决策中没有误判为安全（99.0% 的决策无需重新计算即可解决），并且 pinned-answer 豁免测试通过 600/600；
• 15 个经过验证的时序运算符（时间遵循路径上的可达性、δ-模体、快照差异、突发检测、区间连接、对边事件的分组聚合，以及信念日志本身）——具有类型约束、确定性、有界、受成本保护，并以工具形式开放（MCP 或进程内）；标识符必须来自解析器，算术运算必须使用 compute 运算符；
• 一个 Planner–Executor–Verifier 循环：LLM 仅负责规划和报告；计划会经过静态验证（包括一条使伪造标识符不可能出现的 grounding 规则，以及用于拒绝臆造结果路径的输出字段契约），再通过带内容寻址追踪的确定性方式执行；书面答案中的每一项主张都会根据生成它的追踪记录进行机器检查——包括截断污点，因此“基于不完整证据得出正确算术结果”也会被捕获；
• 一个专用原生存储引擎（Rust、PyO3）：双时态列式分段、时序 CSR 遍历索引、组提交，以及单写多读并发模式——每个边版本占用 24.6 字节；相比之下，相同的 1M 事件日志在 ClickHouse 上占用 78.4 字节，在 PostgreSQL 上占用 549.7 字节。

快速入门

pip install tgms
tgms demo

无需 GPU、API 密钥或下载数据集。tgms demo 会在临时目录中自行构建一个小型存储，并运行每个 TGMS 答案都遵循的流程：图当前认为的内容、修正生效前它认为的内容，以及支持这两项说法的追踪记录。从干净环境到获得第一个时间结果：不到 5 分钟。

准备好使用自己的图数据、运行原生测试套件、启动 MCP 服务，或让 Agent 接入真实 LLM 时，请参阅下方的完整设置——本快速入门刻意设计为最精简的第一步，而不是对操作界面的全面介绍。

接下来的步骤，按大多数人的需求顺序排列： 使用自己的时序图数据 · 通过 MCP 将 TGMS 提供给 Agent · 审计答案 · 维护派生结果 · 跨版本可依赖的内容 · 即将推出的内容

效果如何？

三个不同的问题，三个不同的答案。我们会报告这三项结果，因为第三项最不尽如人意。

1. Agent 层是否优于其他方案？ 开发集划分测试（CollegeMsg，开源模型在本地通过一块 24 GB GPU 提供服务。“答案准确率”是归一化的类型化答案准确率——对计数和数值严格评分，区间答案在 IoU ≥ 0.5 时计为正确。完整凭证随论文和 benchmarks/results-v1/ 中的评估记录一同发布）：

汇总答案准确率，Qwen2.5-14B	TGMS	向量 RAG	静态图 RAG	文本转 Cypher
所有任务类型	0.41	0.09	0.05	0.18
修正探测（“截至 tt…”）	0.67	0.00	0.00	0.00

• 相比静态图 RAG：高 36 个百分点，配对自助法 95% CI [0.18, 0.59]
• 验证器故障注入：注入的 500 条虚假声明全部检出，0 条误报；在冻结的测试中，启用门控时生成的 199 个答案中有 0 个包含无依据的声明（未启用时为 220 个中的 21 个）——覆盖率为 199/282，因此其中一部分是通过拒绝作答换来的
• 在基线保持平稳的情况下，准确率会随着规划器能力提升：Qwen2.5 7B / 14B / 32B fp16 分别为 13.8% / 34.0% / 62.8%；32B 的修正探测准确率达到 100%

2. 引擎是否有竞争力？ 六个系统回答同一组包含 13 个查询的注册表——TGMS 原生引擎、TGMS-on-DuckDB、PostgreSQL、ClickHouse、Neo4j、Memgraph——每个单元格都经过哈希验证后才计时：

查询类型	TGMS 原生引擎	最佳其他系统
时序可达性，200k	14.7 ms	3.9–7.3 s（Memgraph、Neo4j）
闭合三角形 δ-motif，200k	28.7 ms	2.1–5.5 s（Memgraph、Neo4j）
分组聚合，200k	14.5 ms	32.6 ms（ClickHouse）
按身份查询实体历史，200k	0.1 ms	0.3 ms（PostgreSQL）
整个时间窗口内的分桶计数，10M	84.7 ms	37.9 ms（ClickHouse）

最后一行是我们无法追平的项目：在 1M 和 10M 两种规模下，ClickHouse 在整个时间窗口聚合方面都快 2.2 倍；这是查询形态本身的固定差距，而不是随规模增长的差距。经过三轮性能分析，该差距从 12 倍缩小到 2.2 倍，每轮都发现问题出在我们自己的实现，而不是工作负载。单次延迟数据在不同日期复测时的波动约为 ±20%，所有引用数据的地方都已注明这一点。

在 10M 个事件的规模下，完整查询套件运行时的峰值 RSS 为 1.76 GB；16 个并发读取者的吞吐量是单个读取者的 10.2 倍；实时写入者对这些读取者的单查询延迟影响为 0–3%。 3. 它能回答人们实际会问的问题吗？ 这是最诚实的问题，现在也有了续篇。110 个问题由一些人编写，他们看过两个公共数据集的通俗描述，却从未看过算子列表。其中，94 个问题可以用固定的 15 算子目录表达——研究预注册时，这个数字是 10 个。在 LDBC SNB 的 41 个读取模板中，3 个成功执行——这是算子执行轴（计划是否能编译、加载、通过准入并实际运行），门槛低于更严格的 ECQR 结果契约轴；后者的结果是 41 个中有 7 个。这个数字连续 8 次检查都没有变化，因为 38 个未命中的问题中，有 35 个需要带标签的多路模式匹配：这是一个被有意推迟的设计决策，而不是缺少算子。

这个被推迟的决策如今已落地。TGIR 是一种包含 12 个原语的组合式时序图 IR，现在可将整个 15 算子目录作为字节完全相同的叶节点运行，还能将某些问题形态——包括带标签的多路模式匹配——编译为由这些原语构成的链。两条轴的预测都在构建 TGIR 之前做出，并在测量首行数据之前冻结，最终变化与预测完全一致：LDBC 算子执行覆盖率从 3 → 24（共 41 个），独立问题覆盖率从 94 → 102（共 110 个）；在完整的 52 行预测中，实际交付数／预测数为 29/29（51 行可评分数据为 28/28——冻结时按名称排除了一行，因为其标准语料中没有需要查找的更正），超额交付 0 项，未命中 0 项。

存储层依然出色，但实际支持范围仍比“24 个中的 41 个”听起来要窄。此仓库中没有 LDBC SNB 数据集。 21 行 LDBC 数据针对手工构建的测试样例执行，该样例包含 LDBC 的标签、关系类型和多跳拓扑，规模小到评审者可以在一个屏幕上读完（scripts/build_ldbc_fixture.py）；它证明计划可以编译、加载、通过准入并执行，但不代表任何规模能力。独立问题轴是在真实数据（bitcoin-otc、CollegeMsg）上测量的，也是准入／成本保护机制声明有意义的地方。两种测量工具都在仓库中（scripts/independent_questions.py、scripts/ldbc_fit.py），几秒钟即可重新运行；每项交付的能力都根据构建前做出的预测进行评分——实际交付数／预测数已依次达到 14/30、4/7、10/13、14/16、15/15、4/8、5/5、4/5 和 29/29。5/5 和 4/5 是首批按问题而非整体做出的预测；TGIR 的 29/29 则是首个逐行预测，且在测量任何一行之前就已做出，覆盖整个范围并实现零未命中。

运算符可以表达什么

共有 15 个运算符——其中 14 个自 D-044 以来未变，因为自 v0.4.0 以来的大部分扩展都发生在它们内部，由上文的研究逐个问题驱动。最新的扩展则发生在它们底层：TGIR 是一个包含 12 个基本操作的组合式时序图 IR，现在将整个运算符集作为字节完全一致的叶节点运行——语义相同、附带摘要回执，并且可通过 TGIR_PLAN_PATH=off 关闭——此外，还会将某些问题形式（主要是带标签的多路模式匹配）编译为由这些基本操作组成的链。TGIR 计划还不是面向用户的查询语言：目前没有可直接编写计划的公开语法，而以下 15 个运算符仍是 Agent（或你）调用的完整接口。改变的是调用底层发生的事情，其相关数据记录在可按字节复现的 benchmarks/tgir-v1/measured.yaml 中。

原有的 15 个运算符：

能力	所在位置	可回答的问题
分组聚合	aggregate_events	按时间桶、rel_type、端点或端点标签统计数量和不同值数量
算术	compute	对行求均值／中位数；对两个标量求比值／差值／百分比——绝不交由大模型处理
类型化属性	aggregate_events	对边属性应用谓词并求最小值／最大值／均值；只有 JSON 类型匹配的值才会参与计算
集合运算	compute、aggregate_events	对 uid 列表求交集／差集／并集、进行群组预过滤，以及使用无向和互惠对模式
行算术与连接	compute	derive 添加一个计算列；join 按两侧都唯一的键对齐两个分组结果
有序序列	aggregate_events	计算连续事件之间的最长间隔、给定时间跨度内最繁忙的滑动窗口，以及在间隔不超过阈值的情况下最长的连续时段
日历单位	aggregate_events	按一天中的小时、一周中的星期几或一年中的月份分组；UTC 固定偏移量由参数指定，而非使用默认值
信念日志	version_history	哪些信念被修订以及何时修订——这是唯一读取更正记录而非其派生状态的运算符

以上每一项都经过验证，与运算符本身使用同一个暴力枚举预言机，并且都在推出它们的会话中完成了测量。尚未支持的内容也逐个问题记录在 scripts/independent_questions.py 和 scripts/ldbc_fit.py 的重新审计表中——二者的 report 都会输出当前受阻能力列表。

完整设置（从源码开始）

以下所有步骤都会从检出代码构建 TGMS，而非使用 PyPI wheel：真实数据集加载器、本地引擎测试套件、MCP 服务，以及连接到实际大模型的 Agent 循环。

# macOS note: if this repo sits in an iCloud-synced folder, keep the venv
# outside it (iCloud sets the hidden flag on .pth files and Python 3.12+
# silently skips them):  export UV_PROJECT_ENVIRONMENT=$HOME/.venvs/tgms
uv sync --extra agent
make test                     # 271 tests: property, oracle, metamorphic, e2e

# build a real store + task suite (downloads CollegeMsg from SNAP)
make data-collegemsg suite-collegemsg

# call one verified operator — no LLM needed
uv run tgms call temporal_reachability \
  '{"src": "n9", "window": {"t_a": 1082040961000000, "t_b": 1088000000000000}}' \
  --store stores/collegemsg

# verifier acceptance experiment (deterministic, no LLM)
uv run tgms eval c2 --store stores/collegemsg \
  --suite stores/suite-collegemsg/suite.json --mutants 500

使用任何兼容 OpenAI 的大模型端点（例如 vllm serve Qwen/Qwen2.5-7B-Instruct）：

uv run tgms ask "How many nodes can n9 reach between ... and ...?" \
  --store stores/collegemsg --model openai/Qwen/Qwen2.5-7B-Instruct \
  --api-base http://localhost:8000/v1 --html trace.html   # auditable trace page

bash scripts/run_webapp.sh    # interactive guided demo at localhost:8080

接口

接口	入口点	用途
Python 库	tgms.open(...)、Agent(store, model=…).ask(…)	研究代码、笔记本
MCP 服务	tgms serve --store PATH	将经过验证的工具箱交给任何支持 MCP 的 Agent
CLI	tgms demo/ingest/synth/tasks/call/ask/bench/memory/eval/trace	可复现性
Trace 查看器	tgms ask … --html trace.html	提问 → 回答 → 审计证据（静态、自包含的 HTML）
新鲜度检查	tgms trace check record.json --store PATH	这个答案还新吗？——对照事件日志返回 FRESH／POSSIBLY_STALE／UNDECIDABLE，不重新计算
演示 GUI	tgms webapp …／scripts/run_webapp.sh	引导式体验：运算符 → Agent → 篡改演示 → 时间旅行 → 新鲜度检查

正确性

每个操作符都通过独立的暴力穷举判定器进行验证（每个操作符测试 500 个随机案例；两个后端在 tgms/temporal/ 中的行覆盖率为 97%），并通过变形属性验证——差异组合和双时态不可变性：任何固定在过去信念状态的结果，在后续更正前后都逐字节一致。同一套测试未经修改即可在两个后端上运行，这正是原生引擎的完整验收依据：它必须满足 DuckDB 所遵循的同一套由人维护的真实基准。

TGMS_TEST_BACKEND=native make test    # same tests, native engine

写入路径通过随机的断言／撤回／更正交错操作进行属性测试；只追加事件日志重放到任一后端后，都会得到相同的存储摘要。流程规则在 CI 中强制执行，不是建议：测试和判定器绝不能与其评判的实现提交在同一个提交中；项目网站上引用的每个数字都会在构建时从 docs/site_facts.json 解析，因此过时的数据会导致构建失败，而不是留待评审时发现。请参阅 CONTRIBUTING.md。

目录结构

tgms/core       clock, bi-temporal data model, error taxonomy
tgms/storage    StorageAdapter ABC, native + DuckDB backends, event log, TCSR index
tgms/temporal   operator algebra O1–O15 + brute-force oracle
tgms/tools      tool schemas, MCP server / ToolRouter, trace viewer, demo GUI
tgms/agent      plan IR, planner, executor, verifier, reporter, memory
tgms/data       dataset loaders (SHA-256 pinned) + synthetic generator
tgms/eval       task suites, baselines, matrix harness, metrics, fault injection
crates/         the native engine: bi-temporal segments, TCSR, motif kernel

数据集绝不随项目打包：加载器会从源站（SNAP）下载数据，并固定 SHA-256 清单。有关设计、定位、测量结果和路线图，请参阅 docs/eval/。

许可证

Apache-2.0 — 请参阅 LICENSE。请通过 CITATION.cff 引用。

---

_{mcp-name: io.github.zxf-work/tgms}