Claim Ledger in claude-obsidian: Data Structure, Validation, and Evidence Tracking

The claim ledger in claude-obsidian is a JSON document stored at wiki/meta/ledgers/claim-ledger.json that records falsifiable statements, their risk classifications, assessment statuses, and supporting evidence to enable auditable knowledge management within Obsidian vaults.

The claude-obsidian project implements a rigorous knowledge management system that tracks the provenance and evaluation of claims extracted from vault content. At the center of this system is the claim ledger, which captures structured representations of verifiable assertions alongside their review metadata and evidentiary links. This ledger works in tandem with the source ledger to create a traceable chain of knowledge validation according to the schema defined in claude_obsidian/ledgers.py.

Core Data Fields in the Claim Ledger

Each claim entry uses a safe identifier prefixed with clm-, validated by the _safe_ledger_id function at line 44 of claude_obsidian/ledgers.py. The entry contains nine distinct fields that record the claim's content, context, and evidentiary support.

Falsifiable Statement and Risk Classification

The text field stores the actual falsifiable statement as a non-empty UTF-8 string, validated at lines 49-55. The risk field indicates potential impact as either normal or high (lines 55-58), which triggers additional validation requirements for high-risk entries.

Assessment Status and Confidence Levels

Reviewers record their judgment in the assessment field, which accepts one of five enumerated values: accepted, provisional, contested, unsupported, or deprecated (lines 59-62). The confidence field complements this assessment with levels of high, medium, low, or unknown (lines 61-64).

Vault Location Tracking

The location object specifies where the claim appears in the vault, containing:

• path: A canonical wiki file path starting with wiki/... (validated at lines 64-81)
• anchor: An optional reference to a heading or block ID using ^id format or heading text

Evidence Arrays and Temporal Metadata

The reviewed_at field stores an ISO date (validated at lines 30-34), while notes provides optional UTF-8 commentary (lines 46-50). Claims can reference superseded entries via supersedes (lines 51-53). Most critically, the evidence array links claims to sources, with each object containing:

• source_id: A safe source identifier with src-... prefix
• relation: One of supports, contradicts, or context
• locator: Optional human-readable location within the source

Validation Constraints and Business Rules

The validate_claim_ledger function (starting at line 101 in claude_obsidian/ledgers.py) enforces strict integrity constraints beyond basic schema validation.

Path and Anchor Verification

Location paths must be vault-relative wiki paths without absolute components or parent directory traversal (..). The _markdown_anchor_sets function verifies that anchors reference existing headings or block IDs within the target page.

Evidence Integrity Checks

Evidence objects must reference existing source IDs from the source ledger and use only allowed EVIDENCE_RELATIONS values. The system specifically validates that evidence links point to real sources rather than orphaned references.

High-Risk Claim Requirements

High-risk accepted claims face additional scrutiny. The _independent_group_count validation ensures these claims have at least two independent supporting sources. Additionally, accepted claims require at least one fresh active supporting source that predates the claim's review date, preventing circular or post-dated justifications.

Working with the Claim Ledger

The ledger follows the schema identifier defined by CLAIM_SCHEMA (line 22) and resides at the path specified by CLAIM_PATH (line 24). All timestamps use ISO-8601 UTC format, with a top-level generated_at field tracking ledger creation time.

Creating a Claim Entry

Here is a complete example of a valid claim ledger entry:

claim = {
    "schema": "claude-obsidian.claim-ledger.v1",
    "generated_at": "2026-08-28T12:00:00Z",
    "claims": {
        "clm-abc123def456": {
            "text": "Artificial intelligence can outperform humans in creative writing.",
            "risk": "high",
            "assessment": "accepted",
            "confidence": "high",
            "location": {
                "path": "wiki/ai/creative-writing.md",
                "anchor": "Artificial‑Intelligence‑Creativity"
            },
            "reviewed_at": "2026-08-27",
            "notes": "Multiple peer‑reviewed studies support this claim.",
            "supersedes": None,
            "evidence": [
                {
                    "source_id": "src-9f8e7d6c5b4a3",
                    "relation": "supports",
                    "locator": "Section 2.2"
                },
                {
                    "source_id": "src-1a2b3c4d5e6f7",
                    "relation": "supports",
                    "locator": None
                }
            ]
        }
    }
}

Validating Against the Source Ledger

To validate a claim ledger, pass it to validate_claim_ledger along with the source ledger:

from claude_obsidian.ledgers import validate_claim_ledger, empty_source_ledger

source_ledger = empty_source_ledger()
errors = validate_claim_ledger(claim, source_ledger)

if errors:
    for err in errors:
        print(f"{err['path']}: {err['message']}")
else:
    print("Claim ledger is valid.")

Summary

• The claim ledger in claude-obsidian resides at wiki/meta/ledgers/claim-ledger.json and stores falsifiable statements with full provenance tracking.
• Each claim uses a clm- prefixed ID and contains fields for text, risk level, assessment status, confidence, vault location, review date, and linked evidence.
• High-risk accepted claims require at least two independent supporting sources and one fresh active source predating the review date.
• The validate_claim_ledger function enforces constraints on path formats, anchor existence, evidence relations, and temporal consistency.
• All timestamps use ISO-8601 UTC format, with a top-level generated_at field tracking ledger creation time.

Frequently Asked Questions

What is the file path for the claim ledger in claude-obsidian?

The claim ledger is stored at wiki/meta/ledgers/claim-ledger.json within the Obsidian vault. This path is defined by the CLAIM_PATH constant in claude_obsidian/ledgers.py at line 24. The file uses JSON format with a schema version identifier specified by CLAIM_SCHEMA at line 22.

What are the valid assessment statuses for a claim?

According to the validation logic in claude_obsidian/ledgers.py (lines 59-62), the assessment field accepts five values: accepted (fully validated), provisional (pending further verification), contested (disputed by evidence), unsupported (lacking evidence), and deprecated (superseded by newer claims). Each status affects how the claim is treated during vault compilation and cross-referencing.

How does claude-obsidian validate evidence links in the claim ledger?

The validate_claim_ledger function checks that every source_id in the evidence array references an existing entry in the source ledger. Evidence must use one of the allowed EVIDENCE_RELATIONS values: supports, contradicts, or context. For high-risk accepted claims, the system additionally verifies that at least two independent sources provide support using the _independent_group_count validation implemented within the ledger validation logic.

Can a claim reference a specific location within an Obsidian note?

Yes. The location object contains a path field specifying the wiki file (e.g., wiki/ai/creative-writing.md) and an optional anchor field that references specific headings or block IDs. The validation function _markdown_anchor_sets verifies that these anchors exist in the target file, ensuring claims can be precisely located within the vault structure (validation logic at lines 64-81).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}