Hooks & Session Intelligence

On This Page

• Overview
• Session Startup Cheatsheet
• Knowledge Capture Pipeline
• Knowledge Importance Tiers
• Knowledge Queue Format
• Session Close Hook
• DA Bridge Auto-Detection
• Knowledge Maintenance
• Skill Knowledge Pipeline
• Configuration
• Troubleshooting

Overview

AgentUX configures three Claude Code hooks that work together to create an intelligent session loop:

All hooks are configured in the project-level .claude/settings.json and run automatically. They are additive to any user-level hooks in ~/.claude/settings.json.

Session Startup Cheatsheet

Every new session and every /clear command displays a compact cheatsheet covering:

• GraphRAG Tools — Top 5 tools for verifying UE APIs before guessing
• Critical Gotchas — The 5 most common mistakes (mesh RC, viewport position, float/real, BeginPlay, PIE delay)
• Path Rules — Full UObject paths, component paths, subobject paths
• Error Codes — Standard JSON-RPC error codes and their meanings
• Knowledge Capture Mandate — When to record learnings (see below)
• Neo4j Status — Live health check with 2-second timeout

The cheatsheet is injected into Claude's context, ensuring every session starts with essential knowledge regardless of conversation history.

Script: .claude/hooks/agentux-cheatsheet.py

Knowledge Capture Pipeline

AgentUX implements a continuous learning loop that captures session discoveries and makes them available to future sessions:

Session Start                    During Session                   Session End
     |                                |                                |
  Cheatsheet                   Claude discovers               SessionEnd hook
  (includes capture mandate)   API quirk or workaround        reads queue file
     |                                |                                |
  Claude sees:                 Appends to                     Parses entries
  "RECORD when..."             .claude/knowledge-queue.md     MERGEs into Neo4j
     |                         (with importance tier)          (with importance tier)
  Primed to capture            Queue accumulates              Clears queue
                               entries during session         on success
                                                                       |
                                                              Periodic: /knowledge-maintenance
                                                              prunes by tier (see below)

Knowledge Importance Tiers

Every piece of captured knowledge is classified with an importance tier that controls how aggressively the maintenance system can prune it. This prevents long-running sessions from treating hard-won debugging knowledge as “self-evident.”

When Claude captures knowledge, it assigns a tier based on how the knowledge was acquired. Users can override: saying “never forget this” or “this is critical” automatically sets the tier to never-forget. If the importance field is omitted, it defaults to life-experience.

Capture Criteria

Claude is instructed to RECORD when:

• API behavior differs from documentation or reasonable expectation
• A call failed and the fix was non-obvious
• Parameter name/type is case-sensitive, version-dependent, or misleading
• Specific call ordering is required (A must happen before B)
• Silent failure: input accepted, no error, but output was wrong
• When in doubt, RECORD — the maintenance skill prunes later

Claude is instructed to SKIP when:

• Routine API usage that worked on first try
• Information already documented
• Temporary debugging steps or one-off investigations
• User preferences or project-specific configuration

Knowledge Queue Format

Claude appends entries to .claude/knowledge-queue.md during sessions. Each entry follows this format:

## pattern: Descriptive Name
category: Blueprint API
handler: editor.blueprint
importance: life-experience
description: When creating variables, UE 5.7.4 returns "real" instead of "float" for the type field.
```
var_type = result.get("type", "").lower()
assert var_type in ("float", "real")  # Accept both
```

For handler-specific gotchas:

## gotcha: Mesh Component Path
handler: staticmesh
importance: hard-won
description: Direct property set on StaticMeshComponent doesn't trigger render proxy
correct: Use editor.rc.call with SetStaticMesh function instead

The importance field is optional (defaults to life-experience). Valid values: quick-tip, life-experience, hard-won, never-forget.

The queue file includes the full capture criteria as HTML comments at the top. Entries are appended below the marker line.

Session Close Hook

When a session ends (via /exit, /clear, or terminal close), the SessionEnd hook:

1. Reads .claude/knowledge-queue.md
2. Strips HTML comments (template examples are inside comments)
3. Parses ## pattern: and ## gotcha: entries
4. MERGEs each entry into Neo4j as TestPattern or TestGotcha nodes (with importance tier)
5. Clears the queue file on success (preserves header/criteria)

Graceful Failure

• Neo4j offline: Queue is preserved for the next session. No data is lost.
• Empty queue: Hook exits silently (no output, no errors).
• Invalid entries: Skipped individually; valid entries still ingested.
• Always exits 0: Never blocks session termination.

Script: .claude/hooks/agentux-session-close.py

DA Bridge Auto-Detection

When you paste output from Epic's Developer Assistant (or any AI assistant with UE instructions), AgentUX automatically detects it and suggests the DA Bridge skill.

How It Works

The UserPromptSubmit hook scores each prompt against 7 indicators:

Threshold: 3 or more indicators triggers detection. This prevents false positives on normal prompts while catching genuine DA output.

On detection, Claude receives: "Use the DA Bridge skill to parse and execute this: /skill da-bridge"

Script: .claude/hooks/agentux-da-detect.py

Knowledge Maintenance

Over time, the knowledge base accumulates entries that may overlap, become stale, or contradict updated code. The /knowledge-maintenance skill handles cleanup with tier-aware pruning:

Six Pruning Checks

Grace Period

Maintenance never deletes on the first pass. Instead it uses a two-session grace period:

1. First run: Entry is marked as marked-for-pruning with a timestamp. Not deleted.
2. Next run: If still marked, the entry is deleted. If it survived re-review, the mark is cleared.

Demotions (e.g., life-experience to quick-tip) follow the same two-session pattern. Escalations (promoting an entry to a higher tier) are always immediate.

The skill defaults to dry-run mode — it reports what it would do without making changes. Confirm to apply.

Recurring Schedule

The startup hook automatically triggers maintenance when 24+ hours have elapsed. You can also run it manually or on a loop:

/knowledge-maintenance          # Manual run
/loop 24h /knowledge-maintenance  # Recurring

Skill Knowledge Pipeline

AgentUX skills use a GraphRAG-backed knowledge architecture. Instead of storing all domain knowledge in static files, skills are slim stubs that query the Neo4j knowledge graph for relevant concepts on demand.

Architecture

How It Works

1. Claude triggers a skill via keyword detection (e.g., “lighting” triggers lighting-fundamentals)
2. The slim stub loads — Claude sees the skill identity, interaction checkpoints, and execution steps
3. For domain knowledge, Claude queries get_skill_knowledge with the task-relevant terms
4. Neo4j returns self-contained concept nodes — each one is independently actionable
5. Claude loads only what’s relevant, not the entire skill’s knowledge base

Example Queries

get_skill_knowledge(skill_name="lighting-fundamentals")              # All concepts for a skill
get_skill_knowledge(query="Lumen indoor lighting")                    # Cross-skill search
get_skill_knowledge(skill_name="lighting-fundamentals", topic="pattern")  # Just patterns
get_skill_knowledge(query="shadow cascade", topic="anti-pattern")     # Pitfalls about shadows

Concept Types

Each SkillKnowledge node is one of six concept types:

• Pattern — Named setup recipes with step-by-step instructions and bundled pitfalls
• Anti-pattern — Common mistakes with explanations and correct approaches
• Identity — What the skill covers and doesn’t cover
• Query — GraphRAG queries to verify UE API details before acting
• Escalation — When to hand off to a related skill
• Output — Deliverable templates and naming conventions

Graceful Degradation

If Neo4j is unavailable, skills still provide their identity, interaction checkpoints, and execution steps. Claude falls back to training knowledge for domain concepts and notes the limitation to the user.

Extending Skills

Adding knowledge to a skill means adding Neo4j nodes, not editing files. Run migrate_skills_to_graphrag.py after updating SKILL.md content, or create SkillKnowledge nodes directly via Cypher. Skills are now open-ended knowledge domains with no file size limit.

Configuration

All hooks are configured in .claude/settings.json (project-level):

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/agentux-cheatsheet.py\"" }]
    }],
    "SessionEnd": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/agentux-session-close.py\"" }]
    }],
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "python \"$CLAUDE_PROJECT_DIR/.claude/hooks/agentux-da-detect.py\"" }]
    }]
  }
}

Customizing

• Disable a hook: Remove its entry from settings.json
• SessionEnd timeout: Set CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 for longer Neo4j ingest
• Neo4j credentials: Hooks read from GraphRAG/config.yaml automatically

Troubleshooting

Cheatsheet not appearing

• Verify .claude/settings.json exists in the project root (not user home)
• Run manually: python .claude/hooks/agentux-cheatsheet.py
• Check for Python errors (encoding issues on Windows are handled by the UTF-8 wrapper)

Knowledge queue not clearing

• Check Neo4j is running: python neo4j_check.py
• Entries persist when Neo4j is offline — they will be processed next session
• Run the ingest manually: python Scripts/import_test_knowledge.py

DA detection false positives

• The threshold (3 indicators) can be raised by editing THRESHOLD in agentux-da-detect.py
• Prompts under 100 characters are never checked

"can't open file" error in subdirectory

• If you see can't open file '.claude/hooks/agentux-*.py': No such file or directory, your hook commands are using relative paths
• Fix: Change all hook commands in .claude/settings.json to use $CLAUDE_PROJECT_DIR: python "$CLAUDE_PROJECT_DIR/.claude/hooks/agentux-cheatsheet.py"
• This ensures hooks resolve correctly regardless of which directory Claude Code is working in

Hook not firing

• Type /hooks in Claude Code to verify hooks are loaded
• Project-level settings.json must be valid JSON
• Python must be on PATH