Claude CLI + Obsidian

What It Is

A local AI knowledge management stack pairing Obsidian (as a Zettelkasten vault) with a CLI agent that reads/writes notes, queries semantic memory via Dataview, and autonomously maintains bidirectional links. The agent treats the vault as its memory layer — creating, linking, and surfacing notes on behalf of the user.

Karpathy CLI Approach

The Karpathy pattern: vault as working directory → Claude reads/writes Markdown files directly. Tool access via ripgrep (search), glob, and Dataview HTTP queries. Three wiring options:

• Claude Code CLI — claude --dir ~/vault with project config pointing at vault root
• Custom Python agent — llm API calls with filesystem tools
• MCP server — Obsidian Local REST API plugin enables structured Dataview queries from CLI

Agentic Loop Pattern

Tools needed: vault_read, vault_search, vault_write, vault_glob, dataview_query, vault_link, vault_tag

Core Prompts

• System prompt: "You are a personal knowledge management agent. Your memory is an Obsidian vault. All notes are .md with YAML frontmatter. Prefer creating/updating notes over giving long answers. Link with wikilinks. Tag in frontmatter."
• Summarize & save: "summarize my notes on X, create a permanent note"
• Research: "I read an article about Y, save key takeaways to Inbox"
• Query: "what do I know about Z, find and link related notes"

Obsidian Vault Structure

Obsidian Plugins

Key Challenges & Gotchas

• Context window overflow — large vaults exceed LLM context. Use two-phase retrieve-then-reason with Dataview pre-filtering.
• Wikilink case sensitivity — APFS (macOS) is case-insensitive; ext4 (Linux) is sensitive. Use all-lowercase kebab-case filenames.
• Dataview index lag — queries may be stale if Obsidian is closed. Trigger refresh via Local REST API after bulk writes.
• Daily note conflicts — agent and user writing simultaneously clobber each other. Use separate memory/sessions/ folder for agent.
• CORS on Local REST API — if agent runs on different machine via SSH, tunnel or configure API auth.

Recommended Resources

What It Is

A CLI agent (Karpathy-style Python REPL loop + Claude API) that uses Obsidian as a persistent schema/context knowledge base, connects natively to Trino (federated SQL across S3/ADLS/GCS/Hive) and Snowflake (enterprise DW), translates natural language questions into self-verified optimized SQL, and returns human-readable results with full provenance.

Karpathy CLI Architecture

Python script REPL loop wrapping trino CLI + snow CLI + Obsidian file reads:

• System prompt: Defines persona (DB query expert), available tools (trino_query, snow_query, obsidian_search, validate_sql), behavior rules
• Tool layer: Python functions wrapping CLI commands — trino --server https://host:8443 --catalog aws -f query.sql
• Obsidian layer: obsidian_search(query) calls grep/Dataview API to find relevant schema docs
• Two backends: Agent decides whether to use Trino or Snowflake based on question topic

10 Core Tools

Agentic Loop

Trino Connector — Key Patterns

• Predicate pushdown: Include partition key filters (e.g., WHERE date = '2024-01-01') to leverage Trino's connector-level filter optimization
• Sampling: Use TABLESAMPLE (BERNOULLI(1)) for quick exploration before full analysis
• File formats: ORC (default, best compression), Parquet (widely compatible), Avro, JSON, CSV
• Auth: Certificate-based or service account — avoid passwords. LDAP, OAuth2, Kerberos for enterprise
• Trino → Snowflake: Native connector queries Snowflake directly; allows JOINing Snowflake dims with S3 facts in one SQL statement

Snowflake Connector — Key Patterns

• Dedicated warehouse: Agent uses a dedicated warehouse (e.g., COMPUTE_WH) with auto-suspend (60s) to avoid idle costs
• Key pair auth: More secure than password — store private key passphrase in env var or secrets manager
• Read-only role: GRANT USAGE + SELECT only — never INSERT/UPDATE/DELETE/SYSADMIN
• Micro-partitions: Queries benefit from predicates on clustered columns — align filters with clustering keys
• Result caching: Use identical query text for repeated exploration to hit Snowflake's query result cache

Efficient SQL Patterns

• Partition pushdown: Always include partition key predicates — without them, Trino scans all partitions
• Aggregation pushdown: Let Trino/Snowflake aggregate at the storage layer — never pull raw rows
• LIMIT rows early: Apply LIMIT 10000 immediately to reduce row volume before expensive operations
• JOIN ordering: Use smaller table as build side in hash joins; LEFT JOIN for dimension tables
• EXPLAIN first: Always run EXPLAIN before execution on large tables — reject if scan > 100GB or rows > 1B
• APPROX_DISTINCT: Use for high-cardinality counts to reduce payload

Obsidian Schema Knowledge Base

Each schema note has YAML frontmatter: type: table-schema, catalog, schema, partitionKeys, clusterKeys, rowEstimate, lastUpdated. Dataview queries find tables related to any topic.

Query Self-Verification

• Run EXPLAIN on generated SQL before executing — verify table names, column references, row estimates, no Cartesian products
• Cross-reference column names with Obsidian schema docs — catch typos before execution
• Check JOIN key types match (string vs int vs date) — type mismatch causes silent wrong results
• Validate WHERE predicates: no invalid date ranges, no comparisons on non-comparable types
• Spot-check results against Obsidian sample data for semantic correctness

Security & Auth

Required Tools

Key Challenges

• Schema drift: Tables change but Obsidian docs go stale — agent should detect inconsistencies on describe and flag
• Vault size: Large vaults (10k+ notes) can't fit in context — use Dataview to dynamically filter per question
• SQL dialect differences: Trino uses HiveQL derivatives; Snowflake uses its own dialect — agent must route correctly
• Snowflake warehouse cold start: ~60s wake-up cost if suspended — warn about this
• Query cost: Snowflake charges per credit — always run EXPLAIN first and warn about expensive queries

What It Is

Claude conducts deep web research, synthesizes findings into atomic markdown notes, and automatically links them into a growing Obsidian knowledge graph. Every research session feeds a compounding graph — future queries leverage prior work so research on related topics auto-surfaces old notes.

Karpathy CLI Approach

Terminal-first, no GUI automation of Obsidian — just direct file I/O on .md files. Claude operates as the agent brain; Obsidian is the viewer/output:

• claude --dir ~/vault — vault as working directory
• WebSearch + WebFetch built-in (no MCP needed) — Claude issues searches, reads top results
• Optional: Brave Search MCP for higher-quality results with free API key

Agentic Loop

Loop terminates when: question answered, Claude signals diminishing returns, or user interrupts. Subagents can run parallel research branches.

Core Prompts

• Research system: "Always cite sources with [Source](URL). Create one note per concept (atomic). Always link to related notes with wikilinks. If note exists, extend it — don't duplicate."
• Deep research: Issue search → read 2-3 source pages → write atomic note → link to related notes → add #Sources block
• Note synthesis: Review last 5 inbox notes, identify top 3 concepts, create synthesis note connecting all items
• Link discovery: Run Dataview for orphaned notes, search web for how orphaned concept relates to other topics
• Session resume: Read session-log.md, summarize last thread, suggest next searches

Obsidian Vault Structure

Session Persistence

A session-log.md at vault root records: current research question, what was searched, what was found, what remains open, suggested next steps. Updated at end of each session. On startup, Claude reads it first.

Git commits provide full history — git log can reconstruct past research threads. The vault becomes a fully versioned, queryable knowledge base.

Source Tracking

• Inline citation: Every factual claim ends with [Source](https://...)
• Frontmatter: source: https://... and sources: [...] in YAML
• Source block: Notes end with # Sources block listing all URLs
• Provenance: Note's created date + git commit history = full provenance trail

Key Plugins

Key Challenges

• Duplicate notes: Instruct Claude to always search vault first before creating a new note
• Wikilink breakage: Rename handling via Obsidian's internal link index; use stable lowercase filenames
• Dataview slowness: On 10k+ vaults, use limit clause and cache queries
• Agent drift: Set max session length; reference session-log.md explicitly to keep on track
• Research quality degradation: Summarize and git-commit every 10 searches to prevent drift

What It Is

An AI-powered codebase exploration and documentation system. Claude reads local codebases, traces execution paths, maps dependencies, explains architecture, and auto-generates interconnected documentation within an Obsidian vault — turning a codebase into a searchable, navigable knowledge graph with ADRs, inline explanations, and architectural overviews.

Karpathy CLI Approach

Vault as working directory → Claude Code operates on local repo → generated docs written to Obsidian vault at docs/vault/:

• Claude Code Explore subagent: Read-only traversal, designed for large codebases
• Custom SKILL.md: Drives exploration loop with structured prompts
• Vault output: docs/vault/{project-name}/ — can be separate git repo or subdirectory
• Git history: git log/blame/show enrich understanding of decisions and evolution

Agentic Loop — Tools

Core Prompts

• Architecture explanation: "Identify layers, key abstractions, data flow, entry/exit points. Cite file paths and line numbers."
• Dependency tracing: "Trace dependency chain — what it depends on, what depends on it. Identify circular dependencies."
• Code review: "Design patterns, bugs, performance, conventions, error handling. Rate severity × confidence."
• ADR generation: "Generate Architecture Decision Record. Base on git history analysis and code structure."
• Git enrichment: "Who were primary authors? Major evolution points? Long-standing TODOs/FIXMEs?"

Obsidian Vault Structure

Large Codebase Strategies

• Hierarchical summarization: Explore module-by-module, summarize each, then synthesize at higher levels
• Targeted exploration: Only read files relevant to query — never full repo at once
• ctags TAGS file: Pre-generated, checked into repo — O(1) symbol-to-file lookup
• Tree-sitter CLI: Optional but dramatically improves structural understanding
• Exploration budget: Max 50 files read, max 5 subdirectories traversed per query

Key Plugins

Key Challenges

• Context overflow: Never read entire repo — always scope by directory or import graph
• Stale docs: Regenerate periodically; include last-analyzed date; Dataview flags stale (>30 days)
• Wikilink breakage: Always write .md before linking to it; use lowercase kebab filenames
• Monorepo variants: One vault per package with root vault linking all sub-vaults

What It Is

Claude ingests meeting content (raw notes, Zoom/Teams/Otter transcripts, or audio via Whisper), extracts decisions, action items with owners and deadlines, and writes them into Obsidian as a linked task graph. Every meeting becomes a living knowledge graph node — tasks surface automatically, owners are explicit, deadlines tracked via Dataview.

Karpathy CLI Approach

Pipeline: transcript file → shell script strips formatting/timestamps → Claude extracts structured JSON → Obsidian writes markdown notes:

• Raw text: claude --print < meeting-notes.txt
• Transcript formats: Zoom VTT, Teams TXT, Otter TXT/XLSX, Google Meet VTT — strip with sed/awk before processing
• Audio: Whisper.cpp (local, CPU-friendly) → transcript.txt → Claude → Obsidian

Structured Output Schema

Claude outputs ONLY valid JSON in this exact schema:

{
  "meeting_title": "string",
  "meeting_date": "YYYY-MM-DD",
  "attendees": ["name1", "name2"],
  "summary": "2-3 sentence executive summary",
  "decisions": [{ "id": "DEC-1", "decision": "...", "owner": "..." }],
  "action_items": [{
    "id": "ACT-1",
    "description": "starts with verb",
    "owner": "full name",
    "deadline": "YYYY-MM-DD or null",
    "priority": "high|medium|low",
    "status": "open"
  }]
}

Obsidian Vault Structure

Every task note has frontmatter: id, owner, deadline, priority, status, meeting_source and links back to the originating meeting.

Cross-Linking Graph

• Meeting → Task: Task file path in meeting frontmatter; task links back via meeting_source
• Meeting → Person: Attendee list in frontmatter; each person note has meetings: [...]
• Meeting → Project: Topics/projects in frontmatter; project note has meetings: [...]
• Task → Project: project: [[Project Name]] in task frontmatter

Dataview Queries for Task Tracking

Required Tools

Key Challenges

• Noisy transcripts: Auto-generated transcripts have hallucinated words, speaker confusion. Always review action item extraction.
• Context window limits: Very long meetings (>2 hours) chunk by 30-min segments, then merge outputs
• Owner name disambiguation: "John", "John from engineering", "JS" all same person — deduplicate
• Deadline inference: "next Tuesday" → meeting date + 7 days; complex verbal references need manual correction
• Action items without owners: Flag as orphaned tasks for meeting organizer assignment

What It Is

A self-contained AI writing pipeline where Claude operates as a persistent agent over an Obsidian vault, reading accumulated notes and context to draft documents — emails, reports, blog posts, documentation, presentations — in a consistent authorial voice. The vault acts as both knowledge base and drafting workspace.

Karpathy CLI Approach

Claude CLI + Obsidian MCP server via Local REST API plugin:

• Read: Fetch relevant notes from vault (by topic, folder, or search) → Claude analyzes context packet (typically 5–15 notes)
• Draft: Generate content using Templater template → write to vault/drafts/
• Review: Show draft to user or auto-evaluate against criteria
• Edit: Iterate draft in place
• Commit: Git commit draft → promote to vault/writing/final/ when approved

Core Prompts

• Drafting from context: "Read notes on [TOPIC]. Draft a [DOCUMENT TYPE] synthesizing this context. Maintain [STYLE]. Output to vault/drafts/[date]-[slug].md."
• Style matching: "Analyze writing style of [voice samples]. Apply: [specific traits]. Match sentence length, paragraph structure, formality."
• Tone adaptation: "Audience is [AUDIENCE]. Adjust: more formal/informal, technical/plain-language, persuasive/informative."
• Outline expansion: "Expand each section of [outline-file.md] into full prose. Keep flowing, avoid bullet fragmentation."

Voice / Style Learning

Claude learns writing patterns by reading 3–5 representative documents from vault/style/ or vault/writing/final/:

• Average sentence length, paragraph structure, vocabulary level
• Passive vs active voice, bullet frequency, formality
• Store summary in vault/notes/meta/authorial-voice.md — Claude reads it at every session start
• After edits, save feedback as a note: what changed, why, what to maintain → compounding improvement

Writing Types & Turnaround

Obsidian Vault Structure

Required Tools

Key Challenges

• MCP connection fragility: Local REST API plugin must be running in Obsidian — if closed, connection fails
• Context window limits: Can't read entire vault — discipline to load only relevant context notes
• Voice matching is approximate: Claude extracts patterns but subtle personal voice needs periodic correction/feedback
• Export to DOCX/PDF: Requires Pandoc/Marp CLI — not built-in

What It Is

Claude Code runs as a headless BI analyst loop — on demand or on a schedule, it executes SQL against Trino/Snowflake, performs trend analysis, anomaly detection, and forecasting, then writes rich Obsidian notes with tables, trend indicators, inline charts, and Dataview queries — creating a living BI dashboard that's browsable, searchable, and annotatable.

Agentic Loop — 9 Steps

Core Prompts

• Trend analysis: "Query last N days of metric_column grouped by group_by. Return Markdown table with trend arrows + 7-day moving average. Write Obsidian note with Mermaid line chart."
• Anomaly detection: "Compute z-score vs mean/stddev. Flag rows where |z| > 2.5. Write alert note at vault/alerts/ if anomalies found."
• Forecast: "Using last 90 days of metric data, perform 14-day linear trend forecast. Overlay on chart. Write note with confidence intervals."
• Data storytelling: "Latest 30-day results from vault/metrics/. Write narrative briefing: headline findings → drill-down → flag anything needing attention → next steps."

Chart Rendering — 6-Tier Strategy

Anomaly Detection Methods

• Z-score: (value - mean) / stddev over 30-day rolling window. Flag if |z| > 2.5.
• IQR: Flag values outside Q1 - 1.5×IQR and Q3 + 1.5×IQR. Better for skewed distributions.
• % change: Flag if today's value deviates >X% from 7-day or 30-day moving average.
• Seasonality-adjusted: Compare against same-day-of-week rolling average to avoid false alerts on weekly cycles.
• MA crossover: Short-window MA crosses long-window MA = classic trend change signal.

Alert suppression: after firing, suppress repeats for 24h (same metric) to avoid alert fatigue.

12 Common Business Metrics

Cron Schedules

Required Tools

Key Challenges

• Vault growth: Implement retention policy — archive notes >12 months to separate vault
• Trino timeouts: Set CLI timeout (120s); prefer pre-aggregated tables; log and retry once
• Snowflake credits: Use QUERY RESULT CACHE; prefer batch aggregation over ad-hoc per metric
• Alert fatigue: Seasonality-adjust thresholds; implement cooldown; require consecutive breaches
• No live refresh: Dataview re-runs on note open; use Auto Refresh plugin or Templater journal creation

What It Is

Claude reads papers (PDF), articles (URLs), and books; generates structured summaries; extracts key concepts; creates flashcards and Socratic questions; and writes them into Obsidian organized by topic. An SRS plugin (SM-2 or FSRS algorithm) schedules flashcard reviews and tracks retention — a closed-loop learning system where AI both ingests knowledge and generates review material.

Agentic Loop — 7 Steps

Flashcard Formats

Spaced Repetition Algorithms

Review cycles: limit new cards/day (20–30) to avoid overwhelm. Review all due cards before adding new ones.

Obsidian Vault Structure

Frontmatter Schema

type: source|concept|flashcard
source-type: paper|article|book|video
title:
author:
date:
subject:
summary: (for sources)
concepts: [tag1, tag2]
read: false  (sources)
review-count: 0
last-review:
next-review:
rating: 0  (SM-2 ease × 100)
interval: 1  (days)
source-url:

Dataview Queries

• Due today: TABLE WHERE next-review <= date(today) AND type = "flashcard"
• Overdue: TABLE WHERE next-review < date(today)
• Retention stats: TABLE avg(rating), count() GROUP BY subject
• By subject: TABLE key, value FROM "concepts" WHERE subject = "ml"

Key Plugins

Key Challenges

• Flashcard quality: AI-generated cards can be superficial — always review before scheduling
• Long papers: Process in chunks (abstract+intro, methods, results, conclusion) — then merge
• SRS plugin quality: Community plugins vary — test multiple; check recent commit activity
• Review overwhelm: Start strict (10–15 new cards/day); quality over quantity
• Math notation: Use LaTeX in Obsidian (native support); cloze cards work well for formulas