richfrem/obsidian-query-agent

Dependencies

Requires Python 3.8+ and pyyaml.

pip install -r requirements.txt

---

Obsidian Query Agent

Status: Active Author: Richard Fremmerlid Domain: Obsidian Wiki Engine

Purpose

Progressive-disclosure query interface for the Obsidian LLM wiki. Returns the cheapest useful answer first: a 1-5 sentence RLM summary. The caller can then request bullets, then the full wiki node — expanding context only as needed.

Progressive Disclosure Levels

| Level | Content | Cost | |:------|:--------|:-----| | summary | 1-5 sentence distilled answer | ~50 tokens | | bullets | 6-10 key idea bullets | ~150 tokens | | full | Complete wiki node + wikilinks | ~800 tokens | | raw | Original source file content | variable |

Usage

Quick summary (default)

python ./scripts/query_wiki.py --wiki-root /path/to/wiki-root "authentication flow"

Bullet-level detail

python ./scripts/query_wiki.py --wiki-root /path/to/wiki-root "authentication flow" --level bullets

Full wiki node

python ./scripts/query_wiki.py --wiki-root /path/to/wiki-root "authentication flow" --level full

File result back into wiki (Karpathy's "outputs always add back" loop)

python ./scripts/query_wiki.py --wiki-root /path/to/wiki-root "rlm design" \
    --level full --save-as my-rlm-research

Use specific vector DB profile for Phase 2

python ./scripts/query_wiki.py --wiki-root /path/to/wiki-root "attention mechanism" \
    --vdb-profile research

Use shared .agent/learning/ RLM cache

python ./scripts/query_wiki.py --wiki-root /path/to/wiki-root "auth flow" \
    --rlm-cache-dir /path/to/project/.agent/learning/rlm_wiki_cache

List all indexed concepts

python ./scripts/query_wiki.py --wiki-root /path/to/wiki-root --list

JSON output (for programmatic use / agent pipelines)

python ./scripts/query_wiki.py --wiki-root /path/to/wiki-root "api design" --json

Search Strategy (3-Phase)

Phase 1 — Slug/token match (O(1), always runs):

1. Exact concept slug match
2. Slug is a prefix/substring of a concept name
3. Shared word-token overlap (e.g. "auth" matches "authentication-flow")

Phase 2 — Vector DB semantic search (O(log N), requires vector-db installed):

• Calls vector-db plugin's query.py as a subprocess
• Resolves vector DB config from .agent/learning/vector_profiles.json
• Default profile: wiki (override with --vdb-profile)
• Maps semantic results back to concept slugs via meta/agent-memory.json
• Gracefully skipped if vector-db is not installed

Phase 3 — Full-text keyword scan (O(N), always available):

• Grep-style scan of wiki/*.md content as final fallback

--save-as: Filing Results Back Into the Wiki

Karpathy's key insight: "I end up filing the outputs back into the wiki to enhance it."

The --save-as flag writes the query result as a new wiki node:

wiki/{concept-slug}.md  ← new concept page derived from the query result

The saved node includes:

• YAML frontmatter with query_derived: true and derived_from attribution
• Original content at the requested disclosure level
• ## See Also link back to the source concept

This means every query session can grow the wiki, not just read from it.

When to Use

• Any time you need fast context about a concept in the wiki
• Before reading a full raw source file (use summary first)
• When /wiki-ingest has been run and nodes are populated
• As a pre-flight check before expensive agent operations

Related Scripts

• query_wiki.py — progressive-disclosure query engine
• raw_manifest.py — WikiSourceConfig for path resolution
• audit.py — reports missing or stale nodes