Skill: shahalay007/obsidian-librarian (version 0.2.7)

--- name: obsidian-librarian description: Obsidian second-brain and knowledge-base skill. Save any URL, article, tweet, or X post to your Obsidian vault as clean, categorized, wikilinked markdown. Two-pass Gemini pipeline handles structure, tags, and categories. Ask your whole vault anything with RAG, backed by a local JSON index or Supabase pgvector. URL fetch via Apify. Triggers on "save this", "save it", "save this url", research capture, vault search, or querying saved notes. version: 0.2.7 metadata: {"openclaw":{"primaryEnv":"GEMINI_API_KEY","requires":{"env":["GEMINI_API_KEY","OBSIDIAN_VAULT_PATH"],"bins":["python3","curl"]},"homepage":"https://github.com/openclaw/obsidian-librarian"}} --- # Obsidian Librarian A second brain for Obsidian, on autopilot. Drop any URL, article, tweet, X post, or pasted text into OpenClaw and it lands in your vault as a clean, categorized, wikilinked markdown note. Then ask your whole vault anything and get grounded answers with citations. Use this skill when the user wants OpenClaw to store text or a URL in the Obsidian vault as a cleaned, categorized markdown note, or to search and query notes they have already saved. Trigger shortcuts: - Treat `save this`, `save it`, `save this url`, and `save this link` as Obsidian-librarian requests when the same message contains a URL, pasted text, or quoted content to preserve. - Treat short follow-ups like `save it` as Obsidian-librarian requests when the immediately preceding user message provided the text or URL to store. - Treat phrases like `search my notes`, `search my vault`, `search Obsidian`, `what do my notes say about ...`, `ask my vault`, and `query my saved notes` as Obsidian-librarian requests that should run the RAG `ask` path. - If the message only says `save this` or `save it` with no actual content or URL available in context, do not guess; ask what should be saved. - If the intent is ambiguous between saving to the local filesystem versus saving to the knowledge vault, prefer the Obsidian vault when the content looks like a note, article, research snippet, or social post. The vault is mounted in the container at `/data/.openclaw/obsidian-vault`. Raw inputs are staged in `/data/.openclaw/obsidian-vault/_Inbox`, then processed into category folders. ## Environment Required: - `GEMINI_API_KEY`: Gemini API key used for both ingest and RAG answer generation. - `OBSIDIAN_VAULT_PATH`: Absolute path to the mounted Obsidian vault. Conditional: - `APIFY_API_KEY`: Required for URL ingestion. Optional: - `OBSIDIAN_INBOX_FOLDER`: Override the inbox folder name. Default: `_Inbox`. - `OBSIDIAN_GEMINI_MODEL`: Primary model override for librarian operations. - `GEMINI_MODEL`: Fallback model name when `OBSIDIAN_GEMINI_MODEL` is unset. - `OBSIDIAN_RAG_INDEX_PATH`: Override the local JSON RAG index path. - `SUPABASE_URL`: Enable Supabase-backed vector storage. - `SUPABASE_KEY`: Supabase API key for vector storage. - `EMBEDDING_MODEL`: Embedding model override. Default: `gemini-embedding-001`. - `EMBEDDING_DIMENSIONS`: Embedding size. Default: `384`. URL handling policy: - Always use Apify to read the URL first. - For `x.com` / `twitter.com` post URLs, use the dedicated Apify tweet actor. - If an X post contains linked URLs, follow those linked URLs through the same Apify-first path before falling back. - If direct URL reading fails, run a web-search fallback and stage the search-result snapshot instead. - If both stages fail, surface the full error back to OpenClaw instead of silently swallowing it. ## Supported Inputs - Pasted text - A local text/markdown file - A blog/article URL - An existing file already sitting in `_Inbox` - A natural-language question about the saved vault ## Workflow 1. Stage the raw source in `_Inbox/`. 2. Run Gemini pass 1 to clean and structure it into markdown. 3. Run Gemini pass 2 to choose category, tags, source attribution, and candidate wikilinks. 4. Scan existing vault notes for titles and aliases to resolve `[[wikilinks]]`. 5. Write the final note with YAML frontmatter into the chosen category folder. 6. Delete the `_Inbox` file only after the final note is written successfully. ## Ingest From Text File ```bash python3 {baseDir}/scripts/run_pipeline.py ingest --text-file /data/.openclaw/workspace/input.txt ``` ## Ingest From URL ```bash python3 {baseDir}/scripts/run_pipeline.py ingest --url "https://example.com/article" ``` ## Ingest An Existing Inbox File ```bash python3 {baseDir}/scripts/run_pipeline.py ingest --inbox-file /data/.openclaw/obsidian-vault/_Inbox/some-file.md ``` ## Ask The Vault (RAG) ```bash python3 {baseDir}/scripts/run_pipeline.py --vault-path /data/.openclaw/obsidian-vault ask "What do my notes say about AI agents?" --print-json ``` Optional flags: `--category <Category>`, `--threshold <float>` (default `0.65`), `--limit <N>` (default `5`). ## Reindex The Vault ```bash python3 {baseDir}/scripts/run_pipeline.py --vault-path /data/.openclaw/obsidian-vault reindex ``` Add `--file <path>` to re-embed a single note instead of the full vault. ## Notes - For long pasted text, prefer writing it to a temp file under `/data/.openclaw/workspace/` and using `ingest --text-file`. - Use `--title "Custom Title"` on `ingest` for an explicit note title override. - Use `--keep-inbox` only when debugging. Normal behavior is to clean up the staged source after success. - X status URLs preserve deterministic post metadata and captured post content instead of relying on a generic article-style rewrite. - The pipeline does forward-linking only in v1. Existing notes are not modified. - URL ingestion requires `APIFY_API_KEY` in the container environment. - RAG indexing runs after successful ingests. By default it uses a local JSON index; set `SUPABASE_URL` and `SUPABASE_KEY` to use Supabase pgvector instead (requires `EMBEDDING_DIMENSIONS=384` to match `sql/vault_chunks.sql`). - `SUPABASE_URL` must point at a Supabase-compatible API surface. All requests are issued against `/rest/v1/...`, so self-hosted PostgREST needs a gateway or reverse proxy that serves that prefix. - Before enabling Supabase, apply `sql/vault_chunks.sql` to the target database. It provisions the `vault_chunks` table, the HNSW index, and the `match_vault_chunks` RPC that the `ask` command calls.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)