claude-obsidian

claude-obsidian is a self-organizing AI second brain designed for use with Obsidian and Claude Code. It acts as an autonomous knowledge engine that ingests sources, extracts entities and concepts, maintains cross-references, and manages a persistent wiki vault.

Key capabilities include:

• Auto-organization: Creates entities, concepts, and cross-references.
• Vault Maintenance: Performs 8-category linting (orphans, dead links, gaps, etc.).
• Session Memory: Uses a hot cache to persist context between conversations.
• Autonomous Research: Supports 3-round web research with gap-filling.
• Methodology Support: First-class support for LYT, PARA, and Zettelkasten.
• Multi-writer Safety: Uses per-file advisory locking (v1.7+).

DragonScale is a set of four opt-in mechanisms designed to organize and research your Obsidian vault:

1. Fold Operator (Mechanism 1): Provided via skills/wiki-fold/. It is an extractive, structurally idempotent operator that supports dry-runs.
2. Deterministic Page Addresses (Mechanism 2): Uses scripts/allocate-address.sh to assign addresses following the address: c-NNNNNN convention.
3. Semantic Tiling Lint (Mechanism 3): Uses scripts/tiling-check.py and local ollama embeddings to identify duplicate or semantically similar pages.
4. Boundary-First Autoresearch (Mechanism 4): Uses scripts/boundary-score.py to identify high-value research targets from the wikilink graph when no topic is provided to /autoresearch.

By default, claude-obsidian runs entirely on your local machine. It does not collect, transmit, or store personal data, and contains no telemetry or usage tracking.

What stays local by default:

• Ingesting sources, answering queries, linting, and updating the hot cache.
• All wiki content in the wiki/ directory (plain Markdown).
• The /wiki-retrieve BM25 index.
• Ollama-based reranking (runs on localhost).

The claude-obsidian project utilizes the LLM Wiki Pattern, which focuses on building persistent, compounding knowledge bases. Unlike standard RAG (Retrieval-Augmented Generation) which retrieves isolated chunks, this pattern pre-compiles synthesis and maintains cross-references.

Key components include:

• Compounding Knowledge: Every ingestion enriches existing pages rather than just adding new data.
• Hot Cache: A mechanism (typically a ~500-word file) that captures recent context so new sessions can start with full context at minimal token cost.
• Human-AI Workflow: Obsidian acts as the IDE (visualizing the graph and curation), while Claude acts as the programmer (writing and maintaining the wiki content).

The vault contains several key navigation files to help you understand the knowledge structure:

• [[Wiki Map]]: A visual Fibonacci graph of all wiki pages.
• [[index]]: The master catalog containing all pages organized by type.
• [[overview]]: An executive summary of the entire vault's contents.
• [[LLM Wiki Pattern]]: Documentation on the architectural pattern used to build the vault.
• [[Wiki vs RAG]]: Explains the advantages of a wiki-based approach over standard RAG at human scale.
• [[dashboard]]: A live view of vault statistics using Dataview queries (requires the Obsidian Dataview plugin).

DragonScale is a memory-layer design for LLM wiki vaults. It governs how a wiki grows, compacts, addresses its pages, and checks for duplicates. It is not a search, planning, or reasoning algorithm, but a structural framework that shapes what information an LLM surfaces and in what order.

The architecture is built on four core mechanisms:

1. Fold Operator: A hierarchical rollup mechanism that produces meta-pages (summaries) of batches of ingested content.
2. Deterministic Page Addresses: A system for assigning stable, unique identifiers to pages.
3. Semantic Tiling Lint: An embedding-based deduplication check to ensure one concept lives in exactly one canonical page.
4. Boundary-First Autoresearch: An agent attention mechanism (planned for Phase 4) that weights attention toward frontier pages.

The vault is organized into three distinct layers:

1. .raw/ (Layer 1): Immutable source documents (articles, transcripts, etc.). Never modify these files.
2. wiki/ (Layer 2): The LLM-generated knowledge base. This is where you (and the AI) create, update, and organize content. It includes subfolders like entities/, concepts/, domains/, and questions/.
3. WIKI.md (Layer 3): The reference schema and rules for the system.

Core Rules:

• Use Wikilinks ([[Page Name]]) instead of file paths.
• Maintain Atomic notes (one concept per page).
• Every wiki page must have frontmatter.
• Update, don't duplicate: If a page exists, update it rather than creating a new one.

The claude-obsidian project utilizes the LLM Wiki Pattern to ensure knowledge compounds over time. Unlike standard AI chats or traditional RAG (Retrieval-Augmented Generation) systems that re-derive insights from scratch for every query, this pattern treats the wiki as pre-compiled knowledge.

Key Advantages

• Synthesis vs. Retrieval: Instead of just retrieving raw document chunks, the system integrates new sources by updating entity pages, flagging contradictions, and strengthening cross-references.
• Reduced Token Usage: By using a compact wiki (index + hot cache) instead of full document searches, you can significantly reduce token consumption (e.g., up to 95% in practical use cases).
• Automated Maintenance: The LLM handles the tedious bookkeeping of updating cross-references and summaries, preventing the 'knowledge decay' common in human-maintained wikis.

The wiki-mode skill supports four distinct organizational philosophies:

1. LYT (Linking Your Thinking): Focuses on Maps of Content (MOCs). Files are stored in wiki/mocs/ (hubs) and wiki/notes/ (atomic notes).
2. PARA (Tiago Forte): Organizes by actionability. Uses wiki/projects/, wiki/areas/, wiki/resources/, and wiki/archives/.
3. Zettelkasten (Niklas Luhmann): Uses atomic notes with unique timestamped IDs (e.g., wiki/20260528120000123456-slug.md) and no subdirectories.
4. Generic (Default): The v1.6/v1.7 behavior. Uses wiki/sources/, wiki/entities/, wiki/concepts/, and wiki/sessions/.

Use the feature matrix to evaluate claude-obsidian against other projects in the ecosystem.

Key Strengths of claude-obsidian:

• Hot cache: A unique session context mechanism.
• Canvas skill: Provides a visual layer (unlike other LLM Wiki projects).
• Marketplace install: Offers a polished installation experience.
• /save conversation: Unique ability to file chat sessions as wiki pages.

Known Gaps (Current Limitations):

• No delta tracking (re-ingests everything on every compile).
• No URL ingestion (requires manual copy-paste).
• No auto-commit (vault changes are not automatically versioned).
• No multi-depth query.
• No vision/image input support.