Factum

Factum — 面向 AI Agent 的可审计记忆

状态：v0.1.3 — 处于早期阶段，正在寻找早期合作伙伴。 核心的写入／查询／撤回流程已可运行。尚未达到生产就绪状态。架构决策仍可能变更。

交互式文档 — 包含语法解析动画、7 元组探索器、查询流程、令牌效率图表和 MCP 架构图。

Agent 写入的每条事实都必须附带来源信息。撤回某个来源时，所有派生自该来源的内容都会自动失效——即级联撤回。事实相互冲突时，Factum 会返回 Ambiguous，而不是猜测。

一种结构化知识语言（基于 S 表达式）、Rust 实现、stdio MCP 服务——可与 Claude Code、Cursor 及任何 MCP 客户端配合使用。

状态：v0.1.3，处于早期阶段。 核心的写入／查询／撤回流程已可运行；目前尚无语义搜索或记忆整合功能——Factum 处理的是经验证的结构化事实，而非对话上下文。最适用于对合规性敏感的 Agent、多 Agent 共享知识库，以及任何需要回答“Agent 为什么会相信 X”的场景。有关共享知识库模式，请参阅多 Agent 使用指南。

这与 Mem0 / Zep / Letta 有何不同？

Factum 独有： 语法强制要求来源信息 · 级联撤回 · 拒绝处理冲突。

Factum 目前尚不具备： 基于嵌入的语义检索 · 记忆整合 · HTTP 传输。

二者互补：Mem0/Letta 存储和检索上下文；Factum 存储可审计的结构化事实。它们可以通过 MCP 并行运行。

实际意义

Agent 记忆痛点	Factum 机制
无法区分“用户说的”和“大模型推断的”	5 级来源信息 + 对 Extracted 节点强制要求语法中包含模型名称
过时记忆被当作当前事实使用	软删除 + 通过反向依赖图进行级联撤回
冲突的记忆被悄悄择一采用	Ambiguous — 拒绝回答，而不是猜测
记忆污染（提示词注入）	来源链使污染可追踪、可撤回
企业无法允许 Agent 存储敏感数据	索引级权限过滤——不会发生查询后的数据泄露

学术背景： STALE 基准测试（2025 年）表明，即使是表现最佳的大模型 Agent，在判断自身记忆是否已过时方面的准确率也只有 55.2%——这证实了记忆过时仍是 Agent 系统中尚未解决的问题。

核心功能（已实现）

• 节点 7 元组：每个知识节点都包含 id、predicate、validity、provenance、confidence、authority 和 permissions，另有可选的 :note 用于提供人类可读的上下文
• 自动生成节点 ID：在 factum_insert 或 factum_assert 中将节点 ID 设为 "auto"，即可自动生成基于内容的 ID，无需手动管理 ID
• 5 级来源追溯：原文 / 摘要 / 提取 / 推导 / 断言——完整的审计链
• 语法强制要求模型引用：Extracted 节点必须包含模型及其版本——缺少时解析器会拒绝（这不是单纯的文档约定）
• 级联撤回：撤回上游来源时，推导节点会自动失效（通过 deps_rev 反向依赖图实现）；可配置节点数量上限，防止大型知识库中的级联失控
• 佐证检测：当第二个 Agent 断言相同事实时，factum_assert 会返回 corroborated（而非错误）——独立达成一致是多 Agent 协作中最有价值的信号
• 冲突裁决：LatestWins / HighestAuthority / Unanimous / WeightedVote——基于模式的分组可确保值冲突触发裁决；无法唯一解决时返回 Ambiguous
• 索引级权限：查询后无需过滤，防止聚合数据泄露
• 无损数值：所有数字均使用 Dec(i128, u8)，不会产生浮点误差
• MCP 桥接：JSON-RPC 2.0 工具/资源；已通过真实 MCP 客户端（Claude Code、Cursor）验证 stdio 传输

已实现与未实现的内容

模块	状态	备注
factum-core（类型、词法分析器、解析器、序列化）	✅ 已实现	100% 语法往返
factum-rt（存储、查询、裁决、权限、验证器）	✅ 已实现	内存存储（默认）+ RocksDB 持久化（--features rocksdb）；5 个列族，WriteBatch 原子写入
factum-mcp（JSON-RPC 桥接）	✅ 协议 + 处理器	已端到端验证 stdio 传输；尚未实现 HTTP 传输（远程部署需要自定义封装）
factum-bench（基准测试）	✅ 已实现	语法往返 + Token 效率 + 查询性能
factum-l（潜在空间投影）	❌ 尚未开始	研究项目——参见 ROADMAP.md
Wikidata/Mathlib 语料转换器	❌ 尚未开始	M2 里程碑
Lean/Z3 验证器	❌ 尚未开始	目前仅实现了 Schema 和 DecimalRange 验证器
基于嵌入的语义搜索	❌ 尚未开始	不在路线图中——可考虑将 Mem0 与 Factum 搭配使用
记忆整合/摘要	❌ 尚未开始	不在路线图中——可考虑将 Letta 与 Factum 搭配使用
Inspector（可视化调试器）	❌ 尚未开始

快速开始

# Build
cargo build

# Run tests
cargo test

# Run demo
cargo run -p factum-demo

# Build with RocksDB persistence backend
cargo build --features rocksdb
cargo test --features rocksdb

# Build MCP server with RocksDB persistence
cargo build --release -p factum-mcp --features rocksdb --bin factum-mcp-server

# Fuzz (requires nightly)
cargo +nightly fuzz run fuzz_parser -- -max_total_time=600

用作 MCP 服务（Claude Code / Cursor）

# Build the MCP server binary (in-memory, default)
cargo build --release -p factum-mcp --bin factum-mcp-server

# Or build with RocksDB persistence (survives restarts)
cargo build --release -p factum-mcp --features rocksdb --bin factum-mcp-server

# Register with Claude Code (in-memory)
claude mcp add --transport stdio --scope local factum -- "$(pwd)/target/release/factum-mcp-server"

# Register with Claude Code (persistent — recommended for agent memory)
claude mcp add --transport stdio --scope local factum -- \
  "$(pwd)/target/release/factum-mcp-server" --db-path ~/.factum/store

# Verify connection
claude mcp get factum

完整指南请参阅Factum MCP 入门指南。

Factum-F 语法示例

; Acme Corp knowledge graph
(node n001
  :pred (instance-of @ACME-CORP organization)
  :conf 0.99 :auth 0.95 :perm public
  :src (asserted "wikidata"))

(node n004
  :pred (shareholder-major @ACME-CORP @FOUNDER-1 0.73 :since #date(2001-03-15))
  :conf 0.85 :auth 0.8 :perm confidential
  :src (extracted "doc002" [100 200] (model "claude-sonnet-4" "2025-01")))

(node n006
  :pred (subsidiary-of @ACME-SUB @ACME-CORP :since #date(2001-03-15))
  :src (derived n001 "rule-subsidiary-merge")
  :deps [n001])

撤回 n001 时，n006 会自动失效，Agent 因此知道不能再信任该从属关系。

三层架构

层级	含义	状态
Agent 读取	Agent 通过 MCP 接收 Factum-F 作为上下文——相比冗长的 JSON，Token 开销更低	✅ 已测量 Token 效率（基于真实 o200k_base：规范格式比 JSON 减少 62%，紧凑格式比 JSON 减少 53%）
Agent 写入	Agent 生成 Factum-F 节点——解析唯一性保证只有一种有效解释，错误类别支持自我纠正	✅ 参见编写指南
潜在推理	factum-l：将 Factum-F 编码为连续思维向量，在潜在空间中推理，再解码回来以供审计	🔬 研究项目——尚未开始，不会阻碍第 1–2 层

结构化知识语言为记忆层提供支撑——它基于 S 表达式，以确保解析唯一性；使用 Dec(i128, u8) 实现无损数值，并强制要求模型引用，以便大模型进行自我审计。完整的设计依据请参阅 docs/design-rationale.md。

Token 效率——面向大模型的度量指标

简而言之：与包含相同元数据的冗长 JSON 相比，Factum 规范形式可节省约 62% 的 token。所有数字均使用 tiktoken-rs 和真实的 o200k_base（GPT-4o）分词器测得。

格式	实际 token 数（5 个节点）	相较冗长 JSON	包含内容
Factum 规范形式	238	−62%	完整的 7 元组：来源 + 置信度 + 有效性 + 权限
Factum 紧凑形式（JSON）	290	−53%	相同的 7 元组，使用数字标签的 JSON
Markdown	181	−71%	仅断言文本——没有来源、置信度或权限
JSON（美化格式）	623	基准	使用冗长 JSON 编码的相同 7 元组元数据

运行 cargo test -p factum-bench test_token_efficiency_real_tokenizer -- --nocapture 即可复现。

关键发现：规范的 S 表达式形式（238 个 token）比紧凑 JSON 形式（290 个 token）更节省 token——BPE 分词器会拆分 JSON 分隔符，却会合并 S 表达式的括号。为保证正确性而设计的形式，也是最节省 token 的形式。

往返保真度——100% 指什么？

1. 语法往返 ✅ — parse(serialize(parse(x))) == parse(x)。已通过测试套件和模糊测试验证，达到 100%。 这是信任的基础。

2. 语义往返 ❌ 尚未测量——需要 factum-l（潜在空间投影，目前尚未实现）。

语素词汇——当前状态

• 种子语素：涵盖 9 种类型（Entity、Relation、Quantifier、Modal、Temporal、Status、Action、Attribute、Classification）的 200 多个语素——覆盖组织、人员、空间、财务、产品/项目、版本控制、文档/知识、Agent 记忆、权限以及因果关系等领域
• 设计目标：200–500 个（通过 build.rs 从 morphemes.toml 加载）
• 状态：足以满足 Agent 记忆用例。morphemes.toml 代码生成是未来 M2 阶段面向外部贡献的工作项。

与其他格式的关系

格式	Factum 的不同之处
RDF / JSON-LD	RDF 三元组不包含逐节点的来源、置信度或权限。Factum 将这些设为一等且必需的信息。
Markdown	Markdown 没有任何元数据。Factum 以牺牲可读性为代价，换取机器可验证性。
JSON	JSON 没有架构、来源或时间有效性。Factum 紧凑形式使用 JSON 作为传输格式，但增加了结构和审计链。
Mem0 / Zep / Letta	这些工具用于存储和检索 Agent 记忆。Factum 增加了语法强制的来源信息、级联撤回和冲突拒绝机制。二者互为补充，并非竞争关系。

项目结构

factum/
├── crates/
│   ├── factum-core/     # Data model, lexer, parser, serialization
│   ├── factum-rt/       # Runtime: store (InMemory + RocksDB), query, arbitration, permissions, verifiers
│   ├── factum-mcp/      # MCP bridge: JSON-RPC tools/resources, stdio transport
│   ├── factum-bench/    # Benchmarks: round-trip, token efficiency, query perf
│   └── factum-demo/     # End-to-end demonstration
├── fuzz/              # cargo-fuzz targets (parser, serialize round-trip, lexer)
├── spec/              # Conformance test vectors (JSON, language-agnostic)
├── docs/site/         # Interactive visualization (GitHub Pages)
├── .github/workflows/ # CI: test + fuzz + gitleaks + Pages deploy
├── Cargo.toml         # Workspace root
├── ROADMAP.md         # What's planned and in what order
├── SECURITY.md        # Vulnerability disclosure
├── CONTRIBUTING.md    # How to contribute
├── CHANGELOG.md       # Version history
├── docs/design-rationale.md     # Why each architectural decision was made
├── docs/authoring-for-llms.md   # LLM guide for generating Factum-F
└── docs/getting-started-mcp.md  # MCP setup guide (Claude Code / Cursor)

测试结果

运行 cargo test 查看当前数量。测试涵盖：类型、词法分析器、解析器、序列化、语素、深度限制/DoS 防护、一致性测试向量、存储、查询、仲裁、权限、验证器、订阅、MCP 协议/工具/处理程序以及基准测试。

本 README 顶部的 CI 徽章反映最新的构建状态。

安全

• 解析器设有深度限制（128 层），以防止恶意输入导致栈溢出 DoS
• 词法分析器设有令牌数量限制（100 万个令牌），以防止内存耗尽
• 为解析器、序列化往返和词法分析器设置了 cargo-fuzz 目标
• CI 中运行 gitleaks，扫描泄露的机密信息

漏洞披露请参阅 SECURITY.md。

许可证

MIT

商标

“Factum”和 Factum-F 语言规范是项目名称。本 MIT 许可证仅涵盖代码；未来规范可能采用单独的治理流程。

贡献

贡献者必须通过 DCO 签署（git commit -s）。请参阅 CONTRIBUTING.md。

---

• MCP Registry 名称：mcp-name: io.github.factum-project/factum