Grounded Facts

What is a grounded fact?

Regular remember() stores content as a semantic memory — searchable by vector similarity and keyword, recalled when relevant. That is the right default for most things: decisions, how-to guides, error fixes, session learnings.

A grounded fact goes further. When you pass domain, MemoryLayer also extracts formal triples (subject → predicate → object) from the content and loads them into a Z3-backed knowledge graph. Those triples become provable axioms:verify() can then split any prose into individual claims and check each one against the graph, returning one of:

• grounded — confirmed against a formal axiom
• refuted — actively disproved (the claim contradicts a stored fact)
• unsupported — the domain has no opinion; it was never taught this

The difference between unsupported and refutedis critical. An LLM that hasn't seen something just guesses. A grounded domain that has seen the opposite fact will flag it as a contradiction — turning a silent hallucination into a visible failure.

When to use it

Use the domain flag for facts that must stay true as the project evolves:

• Architecture invariants — "HNSW index is always reconstructable from the embeddings table"
• Pricing and tier rules — "Pro is $19/mo, 5,000 calls; Pro+ is $49/mo, 10,000 calls"
• Security boundaries — "fs_read blocks ~/.ssh and cloud credential directories"
• API contracts — "the /license/validate JWT expires in 15 minutes"
• Design principles — component patterns, token rules, spacing invariants
• Key decisions — "we use SQLite, not Postgres; the choice was deliberate"

Grounding with remember()

Pass domain alongside your content. MemoryLayer stores the memory normally and extracts triples into the named domain. Usepromote_immediately: true to skip the warmup phase and force-promote to Z3 axioms right away — best for authoritative, curated facts you are certain about.

// Ground a pricing rule
remember({
  content: "Pro tier costs $19/month and allows 5,000 calls/month. Pro+ costs $49/month and allows 10,000 calls/month.",
  domain: "pricing",
  promote_immediately: true,
  tags: ["rule", "constraint"],
  priority: 9,
  namespace: "my-project"
})

// Ground an architecture invariant
remember({
  content: "The HNSW index is always reconstructable from the embeddings table. Never treat it as durable state.",
  domain: "architecture",
  promote_immediately: true,
  tags: ["arch", "constraint"],
  priority: 10,
  namespace: "my-project"
})

Without promote_immediately, triples warm up naturally through repeated confirmation — safe for content you are less certain about, where you want the graph to build confidence before treating facts as axioms.

Grounding with code(ingest)

When ingesting a repository, pass domain to also ground the prose sections (markdown and text files) into a formal domain. Code bodies (functions, classes) are never loaded into a domain — only curated prose, since raw source code produces noise, not facts.

// Ingest docs/ directory — grounds all .md files into the "architecture" domain
code({
  action: "ingest",
  path: "/path/to/project/docs",
  domain: "architecture",
  ground_immediately: true,
  namespace: "my-project"
})

// Ingest the full repo (code symbols only; prose in docs/ grounded separately)
code({
  action: "ingest",
  path: "/path/to/project",
  namespace: "my-project"
})

Verifying claims

Once facts are grounded, verify() becomes a hallucination gate. It splits the input text into individual claims and checks each against the loaded domain. Run it before stating facts in a response, before writing code that depends on a constraint, or after recall to confirm retrieved content is still accurate.

// Check a claim against the pricing domain
verify({
  text: "Pro users get 10,000 calls per month and pay $19/mo.",
  domain: "pricing"
})

// Returns per-claim verdicts:
// { claim: "Pro users get 10,000 calls per month", verdict: "refuted", ... }
// { claim: "Pro users pay $19/mo", verdict: "grounded", ... }

// Verify architecture claims before making a change
verify({
  text: "The HNSW index persists across restarts and does not need to be rebuilt.",
  domain: "architecture"
})
// Returns: { verdict: "refuted" } — catches the wrong assumption before it becomes a bug

The hook system runs verify() automatically at session end (Stop hook) on any factual claims made during the turn. You can also call it explicitly any time you are about to state something as fact.

Managing domains

The domain tool manages formal domain state — load, inspect, and export your knowledge graphs.

// Load a domain before querying it
domain({ action: "load", name: "architecture" })

// Check what domains are loaded and their axiom counts
domain({ action: "status" })

// Export a domain's axioms for review or backup
domain({ action: "export", name: "pricing" })

Proving specific triples

For a single, precise relational question — "does A call B?", "is X a Y?" — useprove() instead of verify(). It runs a focused Z3 proof for one triple and returns proven,refuted, or unsupported with a proof certificate.

prove({
  subject: "Pro tier",
  predicate: "monthlyLimit",
  object: "5000",
  domain: "pricing"
})
// { proven: true, confidence: 1.0, certificate: "..." }

Recommended workflow

A practical pattern for a new project:

// 1. Set namespace
memorylayer namespace set my-project

// 2. Ingest code (symbols) + prose (grounded into architecture domain)
code({ action: "ingest", path: ".", namespace: "my-project" })
code({ action: "ingest", path: "./docs", domain: "architecture",
       ground_immediately: true, namespace: "my-project" })

// 3. Ground key invariants manually
remember({
  content: "Free tier: 1,000 calls/mo. Pro: 5,000 calls/mo ($19). Pro+: 10,000/mo ($49).",
  domain: "pricing",
  promote_immediately: true,
  tags: ["rule", "constraint"],
  priority: 10,
  namespace: "my-project"
})

// 4. Before any claim about these facts, verify
verify({ text: "Free users get 500 calls per month.", domain: "pricing" })
// → refuted (catches the wrong number before it ships)