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.
• DOMAIN BOUNDARIES AND IGNORANCE (IGNORANCE.md) — corpus-mined map of what the persona does and does not engage. Derived from 17 years of tag frequencies, explicit disclaimer language, and zero-frequency domain checks. Three tiers: hard-stop domains (music industry, parenting, romantic relationships, medical, legal, investing, sports, video games, celebrity, fashion — structurally absent from the corpus); impressionistic-only domains (current news, consumer tech comparisons, academic subfield debates, self-help, business strategy consulting — engage briefly from outside, name the limit); and characteristic non-attentions drawn from explicit corpus disclaimers.
• DARK KNOWLEDGE (DARK_KNOWLEDGE.md) — stealth competencies with substantive background that never surfaced in the public corpus: steel industry (grew up in Bhilai; prior: mini-mills vs. integrated steel economics); aerospace/controls engineering (Ph.D.-level; prior: autonomy hype confuses demo with deployment); semiconductor industry (consulting exposure; prior: CHIPS Act correct on stakes, wrong on mechanism — real action in advanced packaging, not sub-3nm bragging). Each domain specifies the opinionated prior so Sonnet's knowledge is filtered rather than ventriloquized.
• PERSONA-NATIVE REFUSAL GRAMMAR (REFUSAL_GRAMMAR.md) — 20 exit phrases across 5 types: clean hand-off (hard-stop domains), impressionistic hedge, reframe (redirect to adjacent corpus terrain), declared non-interest, anti-commodity move. The canonical template: "I don't follow music scenes closely — you'd get more value from someone embedded in that world." Designed to reduce both commodity-knowledge leakage and response length — explicit exits create natural stopping points that Sonnet otherwise fills.
• GUARDRAILS — five unconditional rules: temporal scope, professional distance, personal scope, persona integrity, dark-pattern-as-goal.

Persona evolution: three versions and what the experiments revealed

The soul document approach involves choices: what corpus to derive from, whether to use actual prose or AI-generated summaries, how many registers to model. vgr_zirp went through three deployed persona versions — and ran three controlled experiments to find out which worked best. The outcome was surprising.

The three versions

A fourth version (v4) was drafted in May 2026 after a diagnostic analysis of 35 public transcripts — it added explicit "operating assumptions" and "voice commitments" derived from failure patterns observed in the transcripts. v4 was never deployed; see below.

The three experiments

From v3 onward, the first turn of every conversation showed users both v3 and v2 responses side by side and asked them to choose the one that better matched their conversational goal. Choices were logged in D1 with session ID, the chosen/rejected version, and which column each voice appeared in.

What the experiments falsified

EXP003 produced a clean result and a set of falsified premises:

Premise: actual prose is better than paraphrase for voice derivation. v3 was derived from actual blog/Twitter/Quora/book text. v2 was derived from AI summaries of post summaries — a paraphrase-of-paraphrase chain. The bet was that reading real prose would produce a more authentic voice. Users disagreed. The paraphrase-derived persona won 55/45.

Premise: multi-register modeling improves conversational quality. v3 explicitly distinguished four registers with separate style descriptions. v2 has one undifferentiated register. The oracle operates in a single medium — a chat interface — and users appear to prefer the single-register voice for that context.

Premise: more source diversity → better persona. v3 added Twitter, Quora, and book corpora on top of the blog. v2 used only blog summaries. Broader source coverage didn't help.

The likely explanation: the paraphrase pipeline produces a distilled, averaged-out version of the voice — one that is more readable and internally consistent in short conversational turns than the raw-prose-derived v3. The idiosyncrasies that make vgr's actual prose compelling on the page may produce friction in a turn-by-turn chat format, where coherence and directness matter more than stylistic distinctiveness.

v4 was drafted on v3 assumptions before EXP003 concluded. It is currently deferred — the diagnostic findings that motivated it (overconfidence decay as sources thin, frame-refusing, leaving tensions unresolved) are likely still valid improvements, but they need to be applied on top of the v2 base, not v3.

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