feat: transform reflect into universal project knowledge base (v1.0.0) - #10
Merged
Conversation
Sessions are the richest source of knowledge — every decision, preference, pattern, and correction flows through them. This change broadens reflect from "coding agent session memory" to "persistent, compounding knowledge base for any repo." Key changes: - qmd is now required (auto-installed via npm/bun in reflect init) - Triage agent extracts ALL knowledge (decisions, preferences, patterns, brand, business, architecture — not just 4 hardcoded categories) - Wiki categories are dynamic — triage can create new categories on the fly - Committed index.md regenerated after every ingest - Automatic qmd re-indexing (update + embed) after every ingest - Skill no longer injects context.md — agents query qmd directly - Session-start hook signals ingest only (no context generation) - New seed categories: Patterns & Conventions, Preferences - Version bump to 1.0.0 https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC
Re-syncs .claude/skills/reflect/ with the updated source files from skill/SKILL.md and hooks/session-start.sh. Also picks up the entire-search agent installed by `entire enable --agent claude-code` during reflect init. https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC Entire-Checkpoint: 4ecb34b81a12
reflect init was only registering the qmd collection without generating embeddings for existing pages. This meant first-time qmd query would warn "100% of documents need embeddings" and fall back to BM25 only. Now init detects existing pages and runs qmd update + qmd embed to seed vectors, giving users full hybrid search immediately after setup. https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC Entire-Checkpoint: bdd0e5492e95
qmd ships first-class agentic features that reflect was underusing: - Structured output flags (--json, --files, --csv, --md, --xml) - Threshold filtering (--min-score, --all) - Full document retrieval (qmd get --full) - Batch fetch (qmd multi-get with glob patterns) - Dedicated AI skill (qmd skill install) - MCP server (qmd mcp) for stdio tool calls Changes: - skill/SKILL.md: promote agentic query patterns as the primary interface. Show --json / --files / --min-score / --full / -n examples for every query type (query / search / vsearch / get / multi-get). Point agents to the installed qmd skill and the MCP server option. - skill/agents/keeper.md: qmd is now the first rung of the evidence ladder. Keeper queries the indexed wiki before falling back to raw Entire sessions or git. Fast, structured retrieval first. - lib/init.py: reflect init now runs `qmd skill install --yes` so the qmd skill is available alongside reflect's skill out of the box. - lib/search.py: fix latent bug — qmd uses -n for result limit, not --limit. Also bump the query timeout to 60s for first-run llama.cpp compilation. https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC Entire-Checkpoint: b2a5adf63dd2
Re-syncs .claude/agents/keeper.md and .claude/skills/reflect/SKILL.md with the updated sources (qmd-first evidence ladder, agentic flag patterns). Gitignores tool-managed installation output so `reflect init` stays idempotent without polluting the working tree: - .agents/ installed by `qmd skill install --yes` - .claude/skills/qmd symlink created by qmd skill install - .reflect/.last_run generated freshness state - .reflect/context.md generated briefing (legacy path) https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC Entire-Checkpoint: 9c595bc9b42d
During ingest testing on a headless machine, qmd embed was timing out after 120 seconds with no visible progress. Turned out two things: 1. qmd defaults to gpu: "auto" which picks Vulkan when the prebuilt is present. On machines without Vulkan drivers (common in sandboxes and CI), this fails with "The prebuilt binary is not compatible with the current system" and falls back to compiling llama.cpp from source — which then ALSO fails because Vulkan SDK isn't installed. Users need QMD_LLAMA_GPU=false to force CPU. 2. qmd embed was running under capture_output=True so users saw no progress indicators during the 2-5 minute CPU embedding phase. Changes to lib/ingest.py _qmd_reindex: - Split update (fast, 60s timeout) from embed (slow, 900s timeout) - Stream embed stdout/stderr to user's terminal so progress is visible - On failure, print a helpful hint about QMD_LLAMA_GPU=false - Tell user when embedding starts so the delay isn't silent Changes to lib/init.py: - Document QMD_LLAMA_GPU in the _install_qmd docstring https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC Entire-Checkpoint: c960454549ca
The 7 existing pages were built with the v0 triage prompt which only extracted 4 hardcoded categories (decisions/gotchas/open-work/pitfalls). Wiping them so the next ingest can rebuild the knowledge base with the new v1.0.0 triage which extracts ALL knowledge types and proposes dynamic categories. Also removes .reflect/.last_run so the next ingest runs in "initial seed" mode (full history) instead of "incremental" mode. https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC Entire-Checkpoint: a835bc7b84e5
Output of running reflect ingest with the new v1.0.0 universal triage prompt against the reflect repo's full session + git history. Captures 36 active pages across 6 categories, including the dynamic categories (guides/, patterns/) that the triage agent proposed without them being in format.yaml. Categories produced: - decisions/ (7) — design decisions made this session and earlier - gotchas/ (8) — friction we hit (vulkan, bash hang, stop hook, etc.) - guides/ (7) — how-to docs (created dynamically, not in format.yaml) - open-work/ (6) — unfinished items including the embed-still-running - patterns/ (4) — reusable techniques (qmd query types, archiving) - pitfalls/ (4) — don't-do rules (concurrent qmd, --limit vs -n bug) Highlights of what the broader triage caught that the old 4-category prompt would have missed: - Vulkan/CPU prebuilt precedence issue and the QMD_LLAMA_GPU=false fix - Bash wrapper process hang when piping background tasks through tail - Concurrent qmd processes triggering duplicate llama.cpp builds - The --limit vs -n flag bug we found and fixed in lib/search.py - Sessions-as-source-of-truth and no-injection-model design decisions This commit demonstrates Karpathy's compounding wiki vision: every session teaches the next one. Future sessions querying qmd will get this accumulated knowledge instead of rediscovering it. Note: qmd embed is still running in background (downloading the embedding model). Once it completes, the wiki will be searchable via hybrid BM25 + vector queries. Until then, BM25 search works. https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC Entire-Checkpoint: 01fb74b4ff0c
Implements Strategy A from the branch-management discussion: the wiki is project memory and should not fork along feature branches. Running 'reflect ingest' on a non-default branch now prints a warning suggesting the user merge to main first, then ingest there. Why this matters: - Branch-local wikis create knowledge silos (pages on branch A don't appear on branch B) - Wiki merge conflicts (especially in index.md) every time a feature branch merges - qmd index doesn't auto-rebuild on branch switch, so search results go stale - Entire CLI checkpoints are stored globally (not per-branch), so ingesting on main can still see conversations from any branch Implementation: - lib/ingest.py: _get_current_branch() and _get_default_branch() helpers. Default branch detected via 'git symbolic-ref refs/remotes/origin/HEAD' with fallback to main/master/trunk. - lib/ingest.py: cmd_ingest now warns at the top when current_branch != default_branch (and --force not set). Doesn't block — just informs. - reflect (CLI): added --force flag with documented branch policy in the help epilog. - SPEC.md: new "Branch Policy" subsection under Git Conventions. - skill/SKILL.md: branch policy documented under the Ingest command so agents understand the recommended workflow. The recommended workflow is now: 1. Develop on feature branches (sessions accumulate in Entire CLI) 2. Merge feature branch into main 3. On main: reflect ingest (canonical wiki update) https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC Entire-Checkpoint: 8d8b19292e59
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sessions are the richest source of knowledge — every decision, preference,
pattern, and correction flows through them. This change broadens reflect
from "coding agent session memory" to "persistent, compounding knowledge
base for any repo."
Key changes:
brand, business, architecture — not just 4 hardcoded categories)
https://claude.ai/code/session_01CDvDjvBftTryk5teGVB5QC