Claims

A claim is the atomic unit of knowledge in TruthKeeper. Every fact your AI learns is stored as a claim with full provenance, verification state, and dependency tracking.

Claim Structure

Every claim contains:

{
  "id": "clm_abc123def456",
  "content": "The PaymentService validates credit cards before charging",
  "state": "SUPPORTED",
  "confidence": 0.92,
  "evidence": [
    {
      "source": "file://src/services/payment.py:42-67",
      "type": "CODE",
      "excerpt": "def process_payment(self, card):\n    if not self.validate_card(card):\n        raise InvalidCardError()"
    }
  ],
  "dependencies": [
    {
      "target": "file://src/services/payment.py",
      "type": "HARD"
    }
  ],
  "metadata": {
    "tags": ["payment", "validation"],
    "created_by": "claude-code-agent"
  },
  "created_at": "2026-01-21T10:00:00Z",
  "updated_at": "2026-01-21T10:05:00Z",
  "verified_at": "2026-01-21T10:05:00Z"
}

Claim States

Claims flow through a well-defined state machine. The current state tells you how much to trust the claim.

State Transitions

                    ┌─────────────┐
                    │  HYPOTHESIS │
                    └──────┬──────┘
                           │
              verification │
                           ▼
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │  SUPPORTED   │  │  CONTESTED   │  │   OUTDATED   │
  └──────┬───────┘  └──────┬───────┘  └──────────────┘
         │                 │                 ▲
  source │                 │ human           │
  change │                 │ review          │
         ▼                 ▼                 │
  ┌──────────────┐  ┌──────────────┐         │
  │    STALE     │  │PENDING_REVIEW│─────────┘
  └──────┬───────┘  └──────────────┘
         │
         │ reverification
         ▼
  ┌──────────────┐
  │  SUPPORTED   │ (or OUTDATED)
  └──────────────┘

Confidence Scoring

The confidence score (0.0 to 1.0) indicates how strongly the evidence supports the claim. It's calculated using a weighted formula:

confidence = (
    0.4 * minicheck_score +    # Natural language inference
    0.2 * authority_score +    # Source trustworthiness
    0.3 * agreement_score +    # Cross-source corroboration
    0.1 * recency_score        # How recent the evidence is
)

Confidence Thresholds

Evidence

Evidence links claims to their sources. Each piece of evidence includes:

• source: URI pointing to the evidence (file://, http://, git://)
• type: Classification of the evidence source
• excerpt: Relevant snippet from the source
• confidence: How strongly this evidence supports the claim

Evidence Types

Bi-temporal Versioning

Claims support bi-temporal queries, allowing you to ask:

• What was known at time T? - Query belief state at any point
• When did we learn X? - Find when knowledge was acquired
• What changed between T1 and T2? - Audit trail for compliance

# What did we believe about authentication on Jan 1st?
claims = await client.search_claims(
    query="authentication",
    as_of=datetime(2026, 1, 1)
)

# Get full history of a claim
history = await client.get_claim_history(claim_id)
for version in history:
    print(f"{version.valid_from}: {version.state} ({version.confidence})")

Best Practices

Writing Good Claims

• Be specific: “UserService.authenticate() validates passwords using bcrypt” vs “UserService handles auth”
• Include context: Reference specific files, functions, or line numbers
• Avoid opinions: Claims should be verifiable facts
• Set appropriate dependencies: Use HARD for critical relationships

Managing Claims at Scale

• Use tags for organization: ["auth", "payment", "api"]
• Set up source watchers for automatic staleness detection
• Configure blast radius thresholds for human review
• Export regularly to JSONL for backup and version control

Next Steps

• Dependencies - How claims relate to sources
• Verification - How claims are verified
• API Reference - Create and manage claims