Claude-Obsidian Product vs User Vault: Architecture and Setup Guide

The Claude-Obsidian product repository contains the immutable application code and skills you install, while the user vault is a separate directory where your personal knowledge files live and evolve through managed transactions.

Claude-Obsidian (AgriciDaniel/claude-obsidian) enforces a strict boundary between system code and user data. Understanding the distinction between the product (the cloned repository) and the user vault (your knowledge directory) is essential for safe operation and proper initialization.

What Is the Product Repository?

The product refers to the code you clone from GitHub. According to the source repository's README, "The checkout contains the product. It is not your knowledge vault" (README.md lines 95-98).

Key locations within the product include:

• claude_obsidian/ – Core Python modules implementing the system logic
• skills/ – Portable skill definitions invoked against your vault
• hooks/ – Git hooks and automation scripts
• scripts/ – CLI tools including claude-obsidian.py for vault operations
• templates/vault/ – Boilerplate files used when creating new vaults
• assets/ and tests/ – Static resources and test suites

The product lifecycle follows standard software releases. You update it via git pull, and it operates as an immutable engine that never writes directly to vault contents unless explicitly instructed through transaction bundles.

What Is the User Vault?

The user vault is your personal knowledge directory, initialized outside the product checkout (for example, at ~/Documents/MyKnowledgeVault). It contains:

• .claude-obsidian.json – Configuration file that marks the directory as a vault and stores metadata
• inbox/ – Landing zone for new, unprocessed notes
• .raw/ – Raw source copies of ingested documents
• wiki/ – Processed markdown knowledge base
• .vault-meta/ – Runtime state and transaction history
• .obsidian/ – Optional Obsidian app configuration folder

Unlike the product, the vault is mutable, user-owned, and version-controlled by you. All changes occur through recoverable transactions, creating an audit trail of how your knowledge evolves.

Trust Boundaries and Lifecycle Differences

The architectural separation creates distinct trust boundaries and lifecycle patterns:

Product (Immutable)

• Updated via Git; treated as external code that remains unchanged during operations
• Located via the repository path you specify when running claude --plugin-dir
• Only reads from vaults and writes back through approved, recoverable transaction bundles

User Vault (Mutable)

• The trusted data store that persists your knowledge across product updates
• Created and mutated through scripts/claude-obsidian.py operations
• Located via the .claude-obsidian.json marker file or explicit path arguments

This boundary ensures that cloning a new version of Claude-Obsidian cannot accidentally overwrite your notes, as the product code in claude_obsidian/ remains strictly separated from vault data.

Practical Initialization Workflow

To establish this separation in practice:

1. Clone the product (the code):

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

2. Initialize a separate vault (your data):

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"
python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" \
    --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

3. Operate on the vault, not the product:

cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian

The init command copies boilerplate files from templates/vault/ into your new vault directory and establishes the .claude-obsidian.json marker file that allows the product to locate and validate your vault.

Summary

• The product (AgriciDaniel/claude-obsidian) contains immutable Python modules, skills, and scripts in directories like claude_obsidian/ and skills/
• The user vault stores mutable knowledge in inbox/, .raw/, wiki/, and .vault-meta/ directories, marked by .claude-obsidian.json
• Trust boundary: The product reads from and writes to the vault only through explicit, recoverable transactions; it never modifies vault contents directly during normal operation
• Initialization: Use scripts/claude-obsidian.py init to create a vault outside the product directory, then run Claude Code against the vault path with --plugin-dir pointing to the product

Frequently Asked Questions

Can I store my vault inside the cloned claude-obsidian directory?

No. The README explicitly warns that the checkout contains the product and is not your knowledge vault. Storing vault data inside the product directory risks deletion during updates and violates the architectural trust boundary. Always initialize vaults in separate locations like ~/Documents/MyKnowledgeVault.

How does Claude-Obsidian locate my vault when I run commands?

The system uses the .claude-obsidian.json marker file. When you run operations from within a vault directory, or point to it via environment variables, the product searches upward through the directory tree for this configuration file. This locator file binds the immutable product code to your specific mutable data store.

What happens to my vault when I update the Claude-Obsidian product?

Nothing. Because the vault exists outside the product directory, updating the product via git pull leaves your knowledge base untouched. The product remains a separate, versioned codebase that merely operates on your vault through the CLI and transaction system.

Is the .obsidian folder in my vault the same as the product repository?

No. The .obsidian folder inside your user vault contains Obsidian.app-specific settings (themes, plugins, hotkeys) and is unrelated to the Claude-Obsidian product code. The product uses the vault's .claude-obsidian.json and .vault-meta/ for its own state management, while the skills/ and claude_obsidian/ directories remain strictly within the product repository.

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