Skip to main content
Glama

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.

CI License: MIT MCP Registry

Factum MCP Demo

Interactive docs — 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

Agent memory pain point

Factum mechanism

Can't tell "user said" from "LLM inferred"

5-level provenance + grammar-enforced model name on Extracted nodes

Stale memory used as current fact

Soft delete + cascade retraction via reverse dependency graph

Conflicting memories silently pick one

Ambiguous — refuses to answer rather than guess

Memory pollution (prompt injection)

Provenance chain makes contamination traceable and retractable

Enterprise can't let agents store sensitive data

Index-level permission filtering — no post-query leakage

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.

Related MCP server: xrad

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

Module

Status

Notes

factum-core (types, lexer, parser, serialize)

✅ Implemented

100% syntactic round-trip

factum-rt (store, query, arbitration, permissions, verifiers)

✅ Implemented

In-memory store (default) + RocksDB persistence (--features rocksdb); 5 column families, WriteBatch atomic writes

factum-mcp (JSON-RPC bridge)

✅ Protocol + handler

stdio transport verified end-to-end; HTTP transport not yet implemented (remote deployment requires custom wrapper)

factum-bench (benchmarks)

✅ Implemented

Syntax round-trip + token efficiency + query perf

factum-l (latent space projection)

❌ Not started

Research item — see ROADMAP.md

Wikidata/Mathlib corpus converters

❌ Not started

M2 milestone

Lean/Z3 verifiers

❌ Not started

Only Schema + DecimalRange verifiers implemented

Embedding-based semantic search

❌ Not started

Not on roadmap — consider using Mem0 alongside Factum

Memory consolidation/summarization

❌ Not started

Not on roadmap — consider using Letta alongside Factum

Inspector (visual debugger)

❌ Not started

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

Layer

What It Means

Status

Agent Read

Agent receives Factum-F as context via MCP — lower token overhead than verbose JSON

✅ Token efficiency measured (real o200k_base: canonical −62%, compact −53% vs JSON)

Agent Write

Agent generates Factum-F nodes — parse uniqueness guarantees one valid interpretation, error classes enable self-correction

✅ See authoring guide

Latent Reasoning

factum-l: encode Factum-F into continuous thought vector, reason in latent space, decode back for audit

🔬 Research item — not started, not blocking layers 1-2

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.

Format

Real tokens (5 nodes)

vs verbose JSON

What it includes

Factum canonical

238

−62%

Full 7-tuple: provenance + confidence + validity + permissions

Factum compact (JSON)

290

−53%

Same 7-tuple, JSON with numeric tags

Markdown

181

−71%

Assertion text only — no provenance, no confidence, no permissions

JSON (pretty)

623

baseline

Same 7-tuple metadata in verbose JSON encoding

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.

  2. 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

Format

How Factum Differs

RDF / JSON-LD

RDF triples carry no per-node provenance, confidence, or permissions. Factum makes these first-class and non-optional.

Markdown

Markdown has zero metadata. Factum trades human readability for machine verifiability.

JSON

JSON has no schema, no provenance, no temporal validity. Factum compact form uses JSON as transport but adds structure and audit chain.

Mem0 / Zep / Letta

These store and retrieve agent memory. Factum adds grammar-enforced provenance, cascade retraction, and conflict refusal. Complementary, not competitive.

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

Test Results

Run cargo test to see the current count. Tests cover: types, lexer, parser, serialization, morphemes, depth-limit/DoS protection, conformance vectors, store, query, arbitration, permission, verifier, subscription, MCP protocol/tools/handler, and benchmarks.

CI badge at the top of this README reflects the latest build status.

Security

  • Parser has a depth limit (128 levels) to prevent stack overflow DoS on adversarial input

  • Lexer has a token count limit (1M tokens) to prevent OOM

  • cargo-fuzz targets for parser, serialize round-trip, and lexer

  • gitleaks runs in CI to scan for leaked secrets

See SECURITY.md for vulnerability disclosure.

License

MIT

Trademark

"Factum" and the Factum-F language specification are project names. This MIT license covers code only; the specification may be governed by a separate process in the future.

Contributing

Contributions require DCO sign-off (git commit -s). See CONTRIBUTING.md.


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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      MCP server exposing a deterministic, local knowledge graph over stdio. Zero LLM calls in the bridge; answers are classified as Fact, Inference, or Unknown and persisted in redb (ACID, BLAKE3-hashed).
      10
      16
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides an MCP server for storing and querying knowledge as verifiable claims, enforcing evidence-backed assertions with exact quotes and refusing paraphrases or unsupported relations.
      Apache 2.0
    • A
      license
      B
      quality
      B
      maintenance
      Enables software agents to maintain a signed, evidence-aware local ledger of claims, with policy-gated proposals, conflict queries, and constitution-pinned access through an MCP stdio server.
      7
      3
      Apache 2.0