Factum

Factum — Auditable Memory for AI Agents

Status: v0.1.3 — Early stage, seeking early collaborators.

Core write/query/retract pipeline works. Not production-ready. Architectural decisions are still open to change.

[Interactive docs](https://factum-project.github.io/factum/) — animated syntax parsing, 7-tuple explorer, query pipeline, token efficiency chart, and MCP architecture diagram.

Every fact an agent writes carries mandatory provenance. When a source is retracted, everything derived from it is invalidated automatically — cascade retraction. When facts conflict, Factum returns Ambiguous instead of guessing.

A structured knowledge language (S-expression based), Rust implementation, stdio MCP server — works with Claude Code, Cursor, and any MCP client.

Status: v0.1.3, early stage. Core write/query/retract pipeline works; no semantic search or memory consolidation yet — Factum handles verified structured facts, not conversation context. Best suited for compliance-sensitive agents, multi-agent shared knowledge bases, and anywhere "why did the agent believe X" needs an answer. See the multi-agent usage guide for shared knowledge base patterns.

How is this different from Mem0 / Zep / Letta?

Unique to Factum: grammar-enforced provenance · cascade retraction · conflict refusal.

Not (yet) in Factum: embedding-based semantic retrieval · memory consolidation · HTTP transport.

Complementary: Mem0/Letta store and retrieve context; Factum stores auditable structured facts. They can run side by side via MCP.

What this means in practice

Academic context: The STALE benchmark (2025) shows that even the best LLM agents achieve only 55.2% accuracy at detecting when their own memories are outdated — confirming that memory staleness is an unsolved problem in agent systems.

Key Features (Implemented)

• Node 7-tuple: Every knowledge node carries id, predicate, validity, provenance, confidence, authority, and permissions — plus optional :note for human-readable context
• Auto node IDs: Use "auto" as the node ID in factum_insert or factum_assert to auto-generate content-based IDs — no manual ID management
• 5-level provenance: Verbatim / Summary / Extracted / Derived / Asserted — full audit chain
• Grammar-enforced model reference: Extracted nodes MUST carry model + version — the parser rejects them if missing (not just a documentation convention)
• Cascade retraction: Derived nodes auto-invalidate when upstream sources are retracted (via deps_rev reverse dependency graph); configurable node limit prevents cascade explosion in large knowledge bases
• Corroboration detection: When a second agent asserts the same fact, factum_assert returns corroborated (not an error) — independent agreement is the most valuable multi-agent signal
• Conflict arbitration: LatestWins / HighestAuthority / Unanimous / WeightedVote — pattern-aware grouping ensures value conflicts trigger arbitration; returns Ambiguous when it cannot uniquely resolve
• Index-level permissions: No post-query filtering — prevents aggregate leakage
• Lossless numerics: All numbers use Dec(i128, u8) — zero floating-point error
• MCP bridge: JSON-RPC 2.0 tools/resources; stdio transport verified with real MCP clients (Claude Code, Cursor)

What's Implemented vs. What's Not

Quick Start

# 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

Use as an MCP server (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

See Getting Started with Factum MCP for the full guide.

Factum-F Syntax Example

; 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])

When n001 is retracted, n006 is automatically invalidated — the agent knows it can no longer trust the subsidiary relationship.

Three-Layer Architecture

A structured knowledge language underpins the memory layer — S-expression based for parse uniqueness, with Dec(i128, u8) for lossless numerics and mandatory model references for LLM self-auditing. Full design rationale in docs/design-rationale.md.

Token Efficiency — The LLM-Native Metric

TL;DR: Factum canonical form saves ~62% tokens vs verbose JSON with the same metadata. All numbers measured with real o200k_base (GPT-4o) tokenizer via tiktoken-rs.

Run cargo test -p factum-bench test_token_efficiency_real_tokenizer -- --nocapture to reproduce.

Key finding: The canonical S-expression form (238 tokens) is more token-efficient than the compact JSON form (290 tokens) — BPE tokenizers split JSON delimiters but merge S-expression parentheses. The form designed for correctness is also the most token-efficient.

Round-Trip Fidelity — What Exactly Is 100%?

1. Syntactic round-trip ✅ — parse(serialize(parse(x))) == parse(x). 100% and verified by the test suite + fuzzing. This is the trust foundation.

1. Semantic round-trip ❌ Not yet measured — requires factum-l (latent space projection, not implemented).

Morpheme Vocabulary — Current State

• Seed morphemes: 200+ across 9 kinds (Entity, Relation, Quantifier, Modal, Temporal, Status, Action, Attribute, Classification) — covering organizational, people, spatial, financial, product/project, version control, document/knowledge, agent memory, permission, and cause/effect domains
• Design target: 200–500 (to be loaded from morphemes.toml via build.rs)
• Status: Sufficient for agent memory use cases. morphemes.toml codegen is a future M2 item for external contributions.

Relationship to Other Formats

Project Structure

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 decisio