AgriciDaniel/claude-obsidian

Layered Shell Architecture

Core Abstractions

• WikiEntry: Atomic markdown unit with YAML frontmatter (tags, creation date, confidence score) and body content linked via [[WikiLinks]]
• ResearchSession: Temporal execution context maintaining conversation history and incremental knowledge accumulation across API calls
• KnowledgeGraph: Directed graph abstraction representing vault topology, enabling traversal of prerequisite concepts during context window construction

Architectural Tradeoffs

• Shell vs. Runtime: Bash implementation minimizes dependencies but lacks structured concurrency; error handling relies on set -e rather than exception hierarchies
• File-Centric Storage: Direct markdown I/O eliminates database overhead but creates filesystem contention at scale (>10k notes)
• Eager Link Resolution: Immediate wikilink parsing on write ensures graph consistency but increases I/O latency compared to lazy indexing

The /autoresearch command implements an autonomous research agent loop within a shell environment, where Claude generates follow-up queries, evaluates knowledge gaps against the existing vault, and recursively expands the graph without human-in-the-loop intervention.

1. Karpathy Pattern Native Implementation: Unlike generic AI note-taking, this system specifically implements Andrej Karpathy's compounding wiki methodology—each research session begins by hydrating the LLM context with previously discovered related concepts, creating a self-reinforcing knowledge base that mimics human long-term research accumulation.
2. Shell-Based Context Persistence: Leverages POSIX file descriptors and named pipes for streaming context management between Claude API chunks, avoiding memory bloat in long-running research sessions typical of Python-based alternatives. Implements context_window_pruning() using semantic similarity to vault contents rather than naive token counting.
3. Obsidian-Native Bidirectional Linking: Automated generation of [[Backlinks]] sections via sed and awk parsers that maintain graph topology without Obsidian's JavaScript runtime, enabling compatibility with git-based vault synchronization and CI/CD pipelines.
4. Markdown-First Semantic Chunking: Implements hierarchical document splitting based on Obsidian header structure (# ## ###) rather than arbitrary token limits, preserving semantic coherence when retrieving context for the LLM.

Implementation Insight

# Core autoresearch loop pattern
autoresearch() {
  local topic="$1"
  local depth="${2:-3}"
  while [ $depth -gt 0 ]; do
    local context=$(build_context "$topic")
    local result=$(claude_api "$topic" "$context")
    vault_write "$result" --link-related
    topic=$(extract_followup "$result")
    ((depth--))
  done
}

Operational Metrics

Scalability Limitations

• Vault Size Constraints: Context building performs full-text grep across vault; performance degrades quadratically beyond ~5,000 markdown files due to linear scan patterns
• Concurrent Write Safety: Lacks distributed locking mechanisms; simultaneous /save operations on shared vaults risk write collisions
• Context Window Fragmentation: No vector embedding cache; repeated semantic similarity calculations for context pruning consume API tokens inefficiently

Bottleneck Analysis

The primary throughput constraint is not the shell implementation but the Claude API rate limits (40k tokens/min). However, the lack of connection pooling in shell-based HTTP clients (repeated curl invocations) adds ~200ms overhead per request compared to persistent HTTP/2 connections in Python/Node implementations.

Competitive Landscape

Production Adoption Patterns

• Research Scientists: Using /autoresearch for literature review compounding, maintaining domain-specific knowledge graphs across months of investigation
• Software Architects: Documenting system design decisions with traceable rationale via linked [[ADR]] (Architecture Decision Records) entries
• Technical Writers: Maintaining living documentation that auto-updates cross-references when API specifications change
• Investigative Journalists: Building entity-relationship graphs from interview transcripts using the wiki-linking automation
• Indie Hackers: Rapidly prototyping knowledge products by leveraging the shell interface for CI/CD integration (auto-generating docs from code commits)

Integration & Migration

Migration from existing PKM systems relies on Markdown export compatibility; the tool includes import_notion.sh and import_evernote.sh converters that normalize wikilinks. Integration points include Git hooks for automated /save operations on commit messages, and Alfred/Raycast workflows for quick-capture via the CLI interface.