How Claude-Obsidian Implements Local-First Knowledge Bases

Claude-Obsidian treats your knowledge base as a normal directory on your local machine, using explicit vault roots, non-destructive initialization workflows, and transaction-safe atomic mutations to ensure your Markdown files remain user-owned and editable outside the agent.

Claude-Obsidian is an open-source bridge between Claude and Obsidian that enforces strict local-first principles for managing knowledge bases. Unlike cloud-dependent tools that hide data in proprietary caches, this repository stores all content as plain Markdown, JSON, and source files in a regular directory structure you fully control. The system implements sophisticated safety mechanisms—including SHA-256 verified transaction bundles and atomic write journals—to prevent data loss while maintaining complete user ownership of files.

Explicit Vault Root Discovery

Claude-Obsidian locates your vault through an unambiguous, user-controlled resolution chain. The system searches for the vault root in the following priority order: an explicit --vault command-line flag, the CLAUDE_OBSIDIAN_VAULT environment variable, the nearest .claude-obsidian.json configuration file, or an unambiguous ancestor directory. If the selection remains ambiguous after these checks, the command aborts immediately to prevent accidental operations on the wrong directory. This logic is implemented in claude_obsidian/paths.py#L21-L30.

Non-Destructive Vault Operations

The tool provides two safe pathways for establishing a vault: initialization for fresh directories and adoption for existing Obsidian vaults.

Initialization vs. Adoption

Initialization creates a new vault from template files stored in templates/vault, generating the required ledger structure from scratch. Adoption migrates an existing Obsidian vault by copying over the necessary ledger files while preserving all pre-existing content. Both flows are implemented in claude_obsidian/vault_ops.py#L81-L104.

SHA-256 Plan Approval

Before any mutation occurs, the system constructs a transaction bundle that lists every expected file write along with its SHA-256 hash. You must review this plan and provide the exact hash via --approved-plan-sha256 before the tool applies any changes. This ensures you vet every file creation, modification, or copy before it touches your disk.

Transaction-Safe Mutations

All mutating operations in Claude-Obsidian use a durable transaction engine that guarantees atomicity and recoverability.

Atomic Bundles and Pre-Conditions

Every transaction bundle includes three critical components: a list of file writes with their intended SHA-256 hashes, pre-condition hashes to detect race conditions, and a persistent journal for rollback operations. The engine validates that current file hashes match expected pre-conditions before writing, preventing conflicts when multiple processes access the vault. This implementation resides in claude_obsidian/transaction.py#L41-L63 with journal management defined in claude_obsidian/transaction.py#L5-L12.

Reserved Paths and Process Locking

The transaction engine enforces reserved paths—specifically .vault-meta/*—to protect internal metadata from external modification. Additionally, the system guarantees that only one process can hold the mutation lock at any given time, serialized through the orchestrator pattern described in the project documentation. According to README.md#L76-L78, parallel agents cannot race the vault because workers only return drafts while a single orchestrator applies one vetted transaction at a time.

Local-First Guarantees

Claude-Obsidian enforces five specific technical guarantees that define its local-first architecture:

• User-Owned Files: The vault consists of plain Markdown, JSON, and source files that remain editable by the user outside the agent. The vault root is a regular directory with no hidden caches, as noted in README.md#L27-L35.

• No Implicit Network Egress: Network traffic only occurs when you explicitly invoke a skill that requires it, such as autoresearch. The README explicitly states that "Network egress is a separate, explicit decision" (README.md#L70-L72).

• Immutable Source Evidence: Original source files are copied into a content-addressed inbox/ directory and later into .raw/ ledgers before any summarization occurs. This preserves provenance even after synthesis, as described in README.md#L45-L48.

• Recoverable, Atomic Operations: Transaction bundles are validated against pre-conditions, written atomically per-file, and can be rolled back using the durable journal if conflicts occur, leveraging the rollback logic in claude_obsidian/transaction.py.

• Parallel Agent Safety: The orchestrator pattern ensures that only one mutation transaction executes at a time, preventing race conditions between concurrent agents working against the same vault.

Practical Vault Workflows

The following commands demonstrate how to interact with local-first knowledge bases using the CLI.

Initialize a brand-new vault with dry-run verification:

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"

# Preview the plan

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

# Apply the exact plan using the SHA from the preview

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyVault" \
  --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID" \
  --approved-plan-sha256 "<sha256-from-the-plan>" --apply

Adopt an existing Obsidian vault:

python3 scripts/claude-obsidian.py init "$HOME/ExistingVault" \
  --generated-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --operation-id "adopt-run" --adopt

Add a source file to the inbox and ingest:

cp paper.pdf "$HOME/Documents/MyVault/inbox/"
/claude-obsidian:wiki-ingest   # Creates ledgers and wiki pages from the source

Query the vault for facts:

/claude-obsidian:wiki-query "What is the main contribution of the paper in inbox/paper.pdf?"

Summary

• Claude-Obsidian resolves vault roots through an explicit priority chain (--vault flag, environment variable, config file, or ancestor directory) to ensure unambiguous targeting.
• All initialization and adoption operations require SHA-256 verified approval before applying changes, preventing accidental data loss.
• The transaction engine in claude_obsidian/transaction.py provides atomic writes, pre-condition validation, and rollback capabilities for every mutation.
• Your knowledge base remains a standard directory of Markdown and source files with no hidden caches, ensuring complete user ownership and portability.
• Network egress requires explicit skill invocation, keeping the core system strictly local unless you intentionally enable external operations.

Frequently Asked Questions

What makes Claude-Obsidian "local-first"?

Claude-Obsidian implements local-first principles by storing your entire knowledge base as plain Markdown, JSON, and source files in a regular directory that you own and can edit without the tool. The system uses explicit vault discovery, requires your approval before any file modifications via SHA-256 verified bundles, and maintains immutable source evidence in content-addressed directories—all without hidden caches or mandatory cloud synchronization.

How does the transaction bundle system prevent data loss?

The transaction bundle system prevents data loss by requiring pre-condition hash checks before any write operation, ensuring files have not changed since the plan was generated. Each bundle includes a durable journal that records every intended operation, allowing atomic per-file replacements and full rollback if conflicts occur. This means your vault never enters a partially updated state, and you can recover cleanly from interrupted operations.

Can I use Claude-Obsidian with an existing Obsidian vault?

Yes. The adoption workflow migrates existing Obsidian vaults by copying only the required ledger files while preserving all your current content. Use the --adopt flag when running the init command, and the system will safely integrate Claude-Obsidian's metadata structures without overwriting your existing notes or configuration.

How does the system handle concurrent modifications?

Claude-Obsidian prevents race conditions through a combination of pre-condition hashing and process serialization. The transaction engine validates that current file hashes match expected values before writing, and the orchestrator pattern ensures only one mutation transaction executes at a time across parallel agents. Workers return draft suggestions rather than direct modifications, with a single orchestrator applying vetted transactions to maintain vault consistency.

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