kg-capture

From knowledge-graph

Knowledge capture rules. ALWAYS ACTIVE during every session: CAPTURE IMMEDIATELY — not at session end. Context is freshest at discovery. The insight that took 20 min to discover takes 20 sec to record. BEFORE CREATING A NODE: ALWAYS kg_search first to check for existing similar nodes. Update existing nodes rather than creating duplicates. This is mandatory, not optional. CAPTURE TRIGGERS: - 10+ min debugging → save root cause pattern (not just the fix) - User corrected your approach → save the signal you missed (user level) - Same thing explained twice → save as reusable node - Undocumented dependency discovered → save as edge - Architectural decision made → save decision AND rationale in notes - Pattern from another project → generalize to user level - Found better approach after inefficient attempts → save best pattern immediately - Long streak of reads to clarify something → save key points now PROACTIVE CAPTURE: Do NOT wait to be asked. Save learnings as you discover them. User expects Claude to autonomously save important principles/patterns to the graph. Opportunity to learn is as important as completing the task. EDGE-FIRST THINKING: Before creating a node, ask "Can I express this as a relationship between existing things?" Edges are cheaper, reuse existing concepts, and survive compaction better (connected nodes score higher). COMPRESSION RULES: 1. Remove filler — no articles, hedging, unnecessary context 2. References over descriptions — "auth/" not "the auth module" 3. Structure over prose — edges over verbose nodes 4. Generalize after repetition — one pattern node beats three instance nodes 5. Headline test — gist reads like a newspaper headline NOTES vs GIST: Gist = compressed fact (always visible). Notes = rationale, "why", constraints (read on demand via kg_read with id). When a decision has context that matters later, put it in notes — preserved but out of the hot path. WHAT TO CAPTURE AT EACH LEVEL: - user (highest priority): user profile/expertise, meta-patterns, interaction preferences, cross-project principles - project: architecture decisions, non-obvious dependencies, debugging discoveries, conventions - skip: facts recoverable from code/docs (use touches/pointers instead)