The Technology Behind vgr_zirp

vgr_zirp is a retrieval-augmented Q&A system that answers questions in Venkatesh Rao's intellectual voice, drawing on his published writing from 2007–2023. It is not a fine-tuned model — it retrieves relevant passages from the actual corpus and constructs answers grounded in that material. This page documents how it works.

The corpus

The system indexes three bodies of work:

The books corpus includes Tempo, Be Slightly Evil, Breaking Smart (season 1 essays + full 2015–2019 newsletter archive), Art of Gig (vols 1–3), Guerrilla Guide to Social Business (20 essays, 2011–2012), 1,699 Quora answers from 2010–2014, guest articles for Forbes/The Atlantic/Aeon, plus a 908-item bibliography of books, papers, and essays cited across the blog. Each book section and long-form Quora answer has a Haiku-generated 2–3 sentence summary; each bibliography item has a 3-sentence semantic summary — both used to improve title-query retrieval.

Embedding and retrieval

Chunking

Blog posts and book text are split into 512-token chunks with 64-token overlap. Each chunk is stored with metadata: source, date, author, title, series membership, and whether the post was collected into a book. Bibliography items are stored as single vectors (one per item, not chunked).

For both blog posts and book sections, the embedding text is prefixed with "Title: {title}\nSummary: {summary}\n\n" before the chunk body — ensuring that title and topic keywords are always present in the embedding vector even when they don't appear in the chunk body. The raw display text is unchanged; only the vector encoding receives the prefix.

In addition to body chunks, each blog post and each book section generates a dedicated summary vector (chunk_type: "post_summary" or "section_summary") that embeds only the title, summary, and tags. These give the retriever a clean, noise-free representation for title-based or high-level topic queries, which then surfaces the corresponding body chunks as sources.

Embedding model

Voyage AI voyage-3 — 1,024-dimensional dense vectors, cosine similarity. The same model is used for both document encoding (at index time) and query encoding (at query time), which is important for retrieval quality.

Vector indexes

Three Pinecone serverless indexes (AWS us-east-1):

Tier weighting

Retrieved chunks are scored by semantic similarity, then adjusted by a content-tier multiplier before merging across indexes. The tier order reflects editorial curation signal:

Up to 8 sources are passed to the language model as context.

The persona: deriving a soul document

The most distinctive part of vgr_zirp's architecture is the persona layer — a detailed structured document that captures the author's worldview, characteristic intellectual moves, voice patterns, and rhetorical style, used as the language model's system prompt.

Method

The persona was derived using a process we call the soul document approach, inspired by techniques in the AI character-building community for extracting stable personality representations from a text corpus.

Application to this project

The derivation script (derive_soul.py v2) uses AI-generated summaries of all 708 Venkat-authored posts as its corpus (vs. 90 post excerpts in v1), and uses the 15 empirically-derived topic clusters from the blog's tag co-occurrence graph as structural anchors for SOUL.md theme organization. The script calls Claude Sonnet with two prompts (~99K tokens each):

• plans/SOUL.md — 15 core intellectual themes (up from 13 in v1), full-corpus coverage, with signature vocabulary, known contradictions, characteristic intellectual moves, and strong positions (~26,000 words)
• plans/STYLE.md — sentence-level patterns, rhetorical structures, neologism introduction pattern, era-by-era voice evolution, a "Signature Formats" section on 2×2 matrices and aphorisms, and an explicit "what to avoid" section

A third constant, LEXICON_MD, is generated from the top 50 high-confidence terms in data/glossary_candidates.json — an AI-derived glossary of Venkat's coinages and redefinitions — providing precise, scannable definitions the model can draw on without retrieving a post.

All three documents are compiled into workers/oracle/persona.js (~62KB). The system prompt is assembled in workers/oracle/build-prompt.js, which imports from persona.js and is the single source of truth used by both the oracle Worker and the MCP Worker. It includes:

• ORACLE IDENTITY — factual answers to meta-questions the corpus can't answer: the etymology of "vgr_zirp" (Drew Austin tweet on ZIRP-era personality), full biography (born 1974 Jamshedpur; IIT Mumbai B.S. 1997; Michigan M.S./Ph.D. 1999/2004; Cornell postdoc 2004–06; Xerox Research Center Webster NY 2006–11; Sulekha.com 2000–01; Ribbonfarm founded 2007 while at Xerox), the Gervais Principle series, a technical self-description of the RAG pipeline, and a redirect rule for empty-archive queries ("ask the live vgr at venkateshrao.com").
• CORPUS MAP — a structured inventory of what is and isn't in the index: full publication lineage (Ribbonfarm → Breaking Smart S1 → Breaking Smart Newsletter → Contraptions rebrand sequence), alias table so the model recognizes variant names ("Ribbonfarm Studio" = 2019–2021 Contraptions era; "BS Newsletter" = the same 144-issue archive), and an explicit not-indexed list (post-2019 Contraptions, Refactor Camp talks, external publications).
• VOICE RULES — first person for Venkat's content, third person for guest contributors, bibliography items treated as recommended reading.
• CONVERSATIONAL REGISTER — turn-by-turn pacing rules: 2–4 sentences on turn 1, hard cap 3 paragraphs, questions only when there's a genuine hook in the user's phrasing, pop culture / metaphor / memetic-phrase instruction, concrete-anchor requirement.
• SOUL_MD + LEXICON_MD — full worldview and vocabulary.
• STYLE GUIDE — Signature Formats and What to Avoid sections from STYLE_MD.
• GUARDRAILS — four unconditional rules: temporal scope, professional distance, personal scope, persona integrity.

Inference

Each query follows this pipeline:

1. Embed query via Voyage voyage-3 (input_type="query")
2. Query all three Pinecone indexes in parallel (top-15 / top-12 / top-15 per index)
3. Normalize, tier-weight, and merge results; deduplicate by document ID
4. Select top 8 sources; build context block with labeled excerpts
5. Call Claude Sonnet (claude-sonnet-4-6) with cached persona system prompt, full prior-turn history (if any), and context block
6. Return answer + sources as JSON

A mode=sources query param stops after step 4, returning retrieval results without an LLM call. This is used for the semantic search interface.

Conversations are multi-turn: the Worker accepts a history array alongside the current query and passes the full prior-turn exchange to Claude as the messages array (up to 8 turns). The persona system prompt is always at position 0 and is prompt-cached; history is appended after it without displacing the cache anchor.

Cost

A typical (cached) query costs roughly $0.017 (1.7¢): ~12,161 cached system-prompt tokens × $0.30/M + ~2,200 non-cached context tokens × $3.00/M + ~450 output tokens × $15.00/M. The persona system prompt is cached via Anthropic's prompt caching API (5-minute TTL), cutting its cost from $0.036/query to $0.004/query on cache hits. A cold call (first in a 5-minute window) costs ~$0.059. The Voyage embedding call is negligible (~$0.000001/query).

Conversation features

Session actions

A persistent action bar below the chat input provides three operations:

Transcript sharing

After the turn limit (8 turns), the interface offers optional transcript submission. Submissions are stored in a Cloudflare D1 database and optionally published to a public transcript gallery.

Session tracking

On the first turn of each conversation (history.length === 0), the Worker fires a lightweight background ping that increments daily and lifetime session counters in KV. This gives a "sessions started" funnel metric independent of whether the conversation reaches the turn limit or whether a transcript is submitted.

Infrastructure

Limitations

• Temporal boundary: The corpus ends in 2023. vgr_zirp explicitly qualifies responses about post-2023 events and does not attempt to simulate post-corpus positions.
• Retrieval errors: Questions about niche topics with few matching chunks will produce answers that generalize from tangentially related material. The sources panel shows exactly what was retrieved.
• Author vs. archive: vgr_zirp speaks from the written record, not from Venkat's current views. Ideas that were explored and discarded, or positions since revised, remain in the corpus as-written.
• Hallucination risk: Claude Sonnet can generate plausible-sounding but incorrect attributions. When specific claims matter, follow the source links.

MCP access (public)

vgr_zirp is available as a public Model Context Protocol server — no account or API key required. Connect it to Claude Code or Claude Desktop and use the corpus directly from your AI client.

Endpoint: https://ribbonfarm.com/mcp

Claude Code

Run once in your terminal:

claude mcp add vgr-zirp --transport http https://ribbonfarm.com/mcp

Claude Desktop

Add to your claude_desktop_config.json:

{"mcpServers": {"vgr-zirp": {"type": "http", "url": "https://ribbonfarm.com/mcp"}}}

Session features

The MCP server has session awareness injected into answer text. On your first exchange you'll see a hello orienting you to the interface and its limits. Reminder nudges appear at exchanges 10 and 20; an alert fires at exchange 30 (the recommended coherence limit). All messages encourage saving transcripts locally to ./vgr_zirp_transcripts/ and optionally submitting to the ribbonfarm archive.

To resume a prior session: save the transcript with a ## Session Summary section at the end (the submit tool generates this automatically), then pass that section as prior_session on the first call of the new session. vgr_zirp will acknowledge the prior context in its hello. Usage is subject to the Terms of Use.

Changelog

Version history for vgr_zirp. Semantic versioning: MAJOR = corpus / model / retrieval changes; MINOR = new features, persona; PATCH = bug fixes.

Acknowledgments