Gemini Obsidian Extension

This is a powerful Gemini CLI extension that integrates your Obsidian Vault directly into your AI workflow. It transforms Gemini into a "Second Brain" assistant capable of reading, searching, connecting, and managing your notes.

Features

• 🧠 Semantic Search (RAG): Ask natural language questions about your notes. The extension indexes your vault using embeddings (via LanceDB) to find relevant context.
• 🕸️ Graph Traversal: Navigate your knowledge graph. Find backlinks ([[linked from]]) and outgoing links to surf your ideas.
• 🛠️ Link Repair: Audit broken wikilinks and make surgical in-note replacements without rewriting whole files.
• 📝 Smart Journaling: Fetch today's daily note or append logs to specific headings (e.g., ## Work Log) with timestamps.
• ⚡ Management: Create, move, rename notes, safely update YAML frontmatter in single or batch mode, and edit specific sections.
• 🔍 Fuzzy Search: Quickly find files by name or content.

Demo

Prerequisites

• Node.js: v18 or higher.
• Gemini CLI: The host application for this extension.
• Obsidian Vault: A local folder containing your markdown notes.

Installation

1. Install via Gemini CLI:

   gemini extensions install https://github.com/thoreinstein/gemini-obsidian

2. Install Native Dependencies: This extension requires native binaries for semantic search. You must run npm install inside the extension directory:

   cd ~/.gemini/extensions/gemini-obsidian && npm install

Configuration

The extension needs to know where your Obsidian vault is located.

Option 1: Environment Variable Set OBSIDIAN_VAULT_PATH in your shell profile:

export OBSIDIAN_VAULT_PATH="/Users/you/Documents/MyVault"

Option 2: Runtime Configuration The first time you use a tool, gemini will ask for your vault path and call obsidian_set_vault. The path must be an existing Obsidian vault (a folder containing .obsidian). It is cached in ~/.gemini-obsidian.config.json.

Tools always operate on the configured vault. They do not accept a per-call vault path.

Data Storage & Troubleshooting

• Vector Index: The semantic search index is stored locally in ~/.gemini-obsidian-lancedb.
• Module Not Found Error: If you see an error like Cannot find module '@lancedb/lancedb', it means the native dependencies were not installed. Run npm install in the extension directory as shown in the Installation section.
• Cache Reset: If you suspect the index is corrupted or want a fresh start, you can manually delete the ~/.gemini-obsidian-lancedb folder. The next time you run /obsidian:index or obsidian_rag_index, it will be recreated.
• Logs: If you encounter issues, check the extension logs. Since this runs as an MCP server, errors are typically output to stderr.

Indexing Performance Tuning

Warning

Initial semantic indexing can be time- and resource-intensive, especially on large vaults. For first-time indexing on larger vaults, prefer running indexing directly from the extension directory (outside an active Gemini chat session): node dist/index.js obsidian_rag_index

Initial Indexing Expectations

• Recommended threshold for one-time CLI indexing: vaults with roughly 500+ markdown files.
• CPU usage can stay high for the full indexing run (multiple cores active).
• In a real-world test with ~1000 files (957 notes), indexing produced 13,296 chunks and took about 11 minutes (11:01, ~374% CPU).

For large vaults, you can tune indexing throughput and chunk size with environment variables:

• GEMINI_OBSIDIAN_EMBED_BATCH_SIZE (default: 48): Number of chunks embedded per batch.
• GEMINI_OBSIDIAN_MIN_CHUNK_CHARS (default: 40): Skip very small chunks below this size.
• GEMINI_OBSIDIAN_MAX_CHUNK_CHARS (default: 1800): Split oversized paragraphs into smaller embedding-safe segments.
• GEMINI_OBSIDIAN_TARGET_CHUNK_CHARS (default: 700): Merge nearby short segments into larger chunks to reduce total embeddings.

Higher GEMINI_OBSIDIAN_TARGET_CHUNK_CHARS generally improves indexing speed by reducing chunk count, but can reduce retrieval granularity.

Example preset for very large vaults:

GEMINI_OBSIDIAN_EMBED_BATCH_SIZE=48 \
GEMINI_OBSIDIAN_TARGET_CHUNK_CHARS=900 \
GEMINI_OBSIDIAN_MIN_CHUNK_CHARS=60 \
node dist/index.js obsidian_rag_index

Commands

The extension comes with pre-configured slash commands for common workflows:

Command	Description
/obsidian:daily	Retrieve today's daily note, summarize tasks, and ask for updates.
/obsidian:recap	Harvest cross-workspace sessions and record into today's daily note using custom templates.
/obsidian:ask	Ask a question to your vault using RAG (e.g., /obsidian:ask "What did I learn about React?").
/obsidian:search	Fuzzy search for files by name or content.
/obsidian:index	Trigger a manual re-index of the vault for semantic search.

Available Tools

The following tools are exposed to the Gemini agent:

Retrieval & Search

• obsidian_rag_index: Index the vault for semantic search.
• obsidian_rag_query: Perform a semantic search query.
• obsidian_search_notes: Simple text/filename search.
• obsidian_list_notes: List files in a folder.
• obsidian_read_note: Read the full content of a note.

Graph & Connections

• obsidian_get_backlinks: Find all notes that link TO a specific note.
• obsidian_get_links: Find all notes linked FROM a specific note.
• obsidian_get_broken_links: Find wikilinks that point to missing notes.

Management & Journaling

• obsidian_set_vault: Set the default Obsidian vault path. Must be an existing Obsidian vault; saved for future sessions.
• obsidian_create_vault: Create a new Obsidian vault directory on disk, with optional desktop app registration.
• obsidian_create_note: Create a new markdown note.
• obsidian_append_note: Append text to the end of a note.
• obsidian_append_daily_log: Append text to a specific heading (e.g., "Log") in today's daily note with a timestamp.
• obsidian_move_note: Rename or move a note.
• obsidian_update_frontmatter: Safely update YAML frontmatter keys in single-key or batch mode.
• obsidian_replace_section: Replace the body of a heading without touching the rest of the file.
• obsidian_insert_at_heading: Insert content at the beginning or end of a heading section.
• obsidian_replace_in_note: Replace the first exact text match in a note for surgical inline edits.
• obsidian_get_daily_note: Get or create today's daily note.
• obsidian_harvest_cli_sessions: Scan and harvest Gemini CLI terminal sessions across all project workspaces, extracting user intents, topics, and key engineering milestones with support for custom template-driven daily logging and work recaps.

  Note on Session Formats: Scans standard JSONL session logs (session-*.jsonl). Legacy single-file .json sessions from older Gemini CLI versions are not scanned until migrated by opening them in current CLI versions.
  Privacy Notice: This tool aggregates user prompts across all terminal sessions on the specified date into the model context. Be mindful if sensitive tokens or credentials were pasted into CLI sessions during the day.

Skills

• obsidian-companion: Tool selection and vault workflow guidance.
• compound: Promote repeated project knowledge into durable global notes.
• moc-update: Suggest Maps of Content that should link to a newly created note.
• link-audit: Audit broken links, orphans, and cleanup opportunities.

Development

# Build changes
npm run build
# Type check
npm run type-check
# Run tests
npm test

License

ISC