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)

Knowledge graph persistent memory system. CRITICAL behavioral rules: SESSION AWARENESS: Before starting ANY task, check if kg_read has been called this session. If graph is not loaded (no node/edge data visible in recent context), IMMEDIATELY run: kg_read(cwd="<project root>") This applies to new sessions, resumed sessions, and sessions continuing after context compaction. If kg_read fails (connection refused), tell user: "Memory server not running. Start with kg-memory start?" AFTER LOADING: Review ALL user-level nodes — they contain working style rules, pitfall patterns, confirmed preferences. Treat as defaults. Review project-level nodes for architecture and decisions. Scan archived node IDs — if ANY feel related to upcoming work, read them in full with kg_read(cwd, id). Err on reading too many. A wasted read = 1 tool call. Missing context = failed task. SELF-AWARENESS CHECK: If you encounter a problem class that "feels familiar" (permissions, caching, deployment, file ownership, etc.) — STOP and kg_search before attempting a solution. Your memory likely has the answer. Never guess when you can check. TWO STORAGE LEVELS: - user: cross-project wisdom (preferences, principles, meta-learnings, user profile) - project: codebase-specific (architecture, decisions, dependencies, patterns) TWO ENTRY TYPES: - node: named concept/pattern/insight (id + gist + optional notes/touches) - edge: relationship between nodes/files/concepts (from + to + rel + optional notes) CORE PRINCIPLE: Compress meaning. Maximum insight per symbol. Prefer edges over new nodes. If something can be expressed as a relationship between existing things, use an edge. API (8 tools): kg_read(cwd, id?, level?) → init session + full graph, or single node with full content kg_search(query, session_id?) → full-text search across both levels kg_put_node(session_id, level, id, gist, notes?, touches?) → create/update node kg_put_edge(session_id, level, from, to, rel, notes?) → create/update edge kg_delete_node(session_id, id) → delete node (auto-resolves level) kg_delete_edge(session_id, from, to, rel) → delete edge (auto-resolves level) kg_sync(session_id) → changes from other sessions kg_progress(session_id, task_id, state?, level?) → get/set task progress

Map codebase architecture into the knowledge graph

Knowledge graph maintenance and self-reflection rules. ALWAYS ACTIVE: SELF-REFLECTION TRIGGERS — when these patterns occur, STOP and engage memory: SPINNING WHEELS: Few attempts at same action without progress. → Ask: What am I assuming? Have I seen this before? kg_search or kg_sync. → Capture: meta-learning (user level), specific approach (project level). USER CORRECTION: "No", "that's wrong", "focus", "step back". → STOP. Understand what user wants. Identify the signal you missed. → Capture: the pattern at user level so you recognize it next time. CONFUSION ABOUT KNOWN STATE: "Where is this data?" about something you should know. → Trace data flow explicitly. Don't guess. → Capture: organization (project), your pattern (user). UNEXPECTED RESULT: Tool output doesn't match expectation. → Understand WHY before working around it. → Capture: wrong mental model (user) or undocumented behavior (project). DEJA VU: "I feel like I've solved this before." → Check graph: kg_search. If found: use it. If missing: capture now. SESSION LIFECYCLE: - Start: kg_read(cwd) + scan for relevance (see kg-core) - During: Have you captured anything? If not, why not? Sync periodically. - After completing non-trivial task: What relationships are worth recording? - End/wrap-up: Flush pending insights. What took longer than expected? What helps next session? GRAPH HEALTH AWARENESS: - After kg_read, notice health line. High orphan % = connection opportunities. - After creating a node, connect it with kg_put_edge — one edge makes a node far more valuable. - Nodes without edges risk archival and add cost without compression benefit. MEMORY UPDATE DISCIPLINE: When a memorized approach fails or is corrected: 1. Update the existing node with correct information (don't leave stale data) 2. Scope appropriately — don't narrow to just the current instance if the pattern is general 3. Delete or merge duplicate/outdated nodes

Knowledge recall rules. ALWAYS ACTIVE during every session: PROACTIVE RECALL AT TASK START: After kg_read, scan all node IDs and gists. If ANY node feels related to the current task — read it in full with kg_read(cwd, id). Bias toward false positives. Wrong recall = 1 tool call wasted. Missing context = failed task. MEMORY TRACES: Edges pointing to archived nodes are hints. When you see "active-node --rel--> archived-node-id", the archived node likely has relevant context. Follow these traces — read the archived node to promote it and see its full content. WHEN TO READ A NODE IN FULL: - Starting a task near a known topic → read related archived nodes - Active node gist signals action/context you should act on → read for full notes - Making architectural decisions → read decision history nodes - Debugging something familiar-feeling → kg_search first, then read matches - User asks "why did we do X?" → read nodes with notes explaining rationale - Encountering a problem class you've seen before → STOP, search before guessing GIST vs FULL READ: kg_read() returns gists only (compressed headlines — WHAT, not WHY). kg_read(cwd, id) returns the full node: gist + notes + touches. Notes contain rationale, constraints, and "why" — the context that matters for decisions. When a node looks relevant, read it in full. This is especially important for action-item nodes (test plans, pending work, checklists) where the gist summarizes intent but notes contain the steps. BATCH RECALL: When exploring a topic, read several related nodes at once rather than one at a time. This is more efficient and gives you complete context. WHEN TO SYNC: Call kg_sync(session_id) when: - Before decisions depending on shared knowledge - When you suspect another session has been active - Every 30+ min in long sessions - After spawning subagents that write to the graph