IntegrationsOpenClaw
Session Start Context Injection
Planned automatic context injection at session start using session:start events and --profile auto for intelligent memory retrieval.
Session Start Context Injection
Forward-compatible feature. The session:start event is not yet implemented in OpenClaw. The hook handler includes a ready-made handler that will activate automatically when OpenClaw adds this event. The design below describes intended behavior.
For current session context, use clawvault wake manually or rely on the gateway:startup hook for context death detection.
When OpenClaw adds session:start, the ClawVault hook will automatically inject relevant context at the beginning of new sessions.
Planned Behavior
When OpenClaw fires a session:start event, the hook will:
- Context Analysis: Analyze current situation and available memories
- Profile Selection: Determine appropriate context profile (
auto,planning,incident, etc.) - Memory Retrieval: Retrieve relevant memories using graph-aware search
- Context Injection: Inject formatted context into session start
Profile Auto Selection
The --profile auto mode intelligently chooses the best context profile based on environmental cues:
Detection Signals
| Signal | Profile | Rationale |
|---|---|---|
| Recent context death | incident | Need recovery-focused context |
| Time since last session > 8 hours | handoff | Need transition context |
| Active projects with recent updates | planning | Need strategic context |
| High-priority items in inbox | incident | Need action-oriented context |
| Normal continuation | default | Standard balanced context |
Profile Characteristics
Default Profile
- Balanced mix of recent memories
- General context without bias
- 3-5 key memories across categories
Planning Profile
- Strategic and goal-oriented memories
- Project status and roadmaps
- Decision history and lessons learned
Incident Profile
- Recent urgent items and blockers
- Error logs and troubleshooting context
- Recovery procedures and contacts
Handoff Profile
- Session transition information
- Incomplete tasks and next steps
- Continuity markers and progress updates
Context Injection Format
Injected context follows a consistent, parseable format:
Standard Injection
# Session Context (Auto-Selected: Default Profile)
## Recent Memories
- **Decision:** [[database-choice]] - Chose Postgres over SQLite for concurrency
- **Lesson:** [[context-death-recovery]] - Checkpoint frequently during heavy work
- **Project:** [[clawvault-docs]] - Documentation sprint in progress
## Active Items
- [ ] Finish OpenClaw integration documentation
- [ ] Test context injection with new hook
- [ ] Review PR feedback on memory graph
## Key Relationships
- **[[pedro]]** - Project lead, daily standup at 9 AM
- **[[justin-dukes]]** - Client contact for Hale Pet Door
*Context generated: 2024-01-15 15:30:42 | Profile: default | Memories: 8*Incident Profile Injection
# Session Context (Auto-Selected: Incident Profile)
## Urgent Items
- **BLOCKER:** API keys expired for production deployment
- **ERROR:** Memory graph rebuild failed, needs investigation
- **DEADLINE:** Client demo tomorrow at 2 PM
## Recent Problems
- [[production-outage-2024-01-14]] - Database connection issues resolved
- [[api-rate-limiting]] - Temporary workaround in place
## Recovery Resources
- [[emergency-contacts]] - On-call rotation and escalation
- [[deployment-rollback]] - Standard rollback procedures
*Context generated: 2024-01-15 15:30:42 | Profile: incident | Memories: 12*Handoff Profile Injection
# Session Context (Auto-Selected: Handoff Profile)
## Previous Session Summary
- **Ended:** 8 hours ago (2024-01-15 07:30)
- **Working on:** ClawVault documentation improvements
- **Completed:** Commands section, repair-session docs
- **In progress:** OpenClaw integration guides
## Next Steps
1. Finish auto-checkpoint documentation
2. Create advanced usage examples
3. Build and test documentation site
## Handoff Notes
- "Good progress on docs, integration section next"
- "Examples need more real-world scenarios"
- "Consider adding troubleshooting flowcharts"
*Context generated: 2024-01-15 15:30:42 | Profile: handoff | Memories: 6*Configuration
Context injection is controlled by hardcoded constants in the hook handler (handler.js). A clawvault config command for runtime tuning is planned for a future release.
Current tuning constants in handler.js:
| Constant | Value | Purpose |
|---|---|---|
MAX_CONTEXT_RESULTS | 4 | Max vault memories injected |
MAX_CONTEXT_PROMPT_LENGTH | 500 | Max chars of user prompt sent to search |
MAX_CONTEXT_SNIPPET_LENGTH | 220 | Max chars per memory snippet |
MAX_RECAP_RESULTS | 6 | Max session recap messages |
MAX_RECAP_SNIPPET_LENGTH | 220 | Max chars per recap message |
To adjust, edit the constants directly in your hook's handler.js.
Memory Selection Algorithm
The context injection uses ClawVault's graph-aware search:
Stage 1: Candidate Collection
- Recent memories (last 7 days)
- High-priority items (decisions, urgent tasks)
- Frequently referenced entities
- Graph neighbors of current focus
Stage 2: Profile Filtering
- Default: Balanced representation across categories
- Planning: Emphasize goals, projects, strategic decisions
- Incident: Prioritize problems, blockers, urgent items
- Handoff: Focus on continuity, next steps, progress
Stage 3: Relevance Scoring
- Recency weight (newer = higher score)
- Priority weight (urgent = higher score)
- Graph centrality (well-connected = higher score)
- Profile match (aligned with profile = higher score)
Stage 4: Selection and Formatting
- Top N memories selected (configurable limit)
- Formatted with consistent structure
- Wiki-links preserved for navigation
Integration Examples
Normal Day Start
Session Start Conditions:
- Last session: 12 hours ago
- No urgent items
- Ongoing projects active
Auto-Selected Profile: handoff
Context: Recent progress + next steps + project statusCrisis Response
Session Start Conditions:
- Production alerts detected
- High-priority items in inbox
- Recent error logs
Auto-Selected Profile: incident
Context: Problems + blockers + emergency proceduresStrategic Planning
Session Start Conditions:
- Monday morning session
- Goals review scheduled
- Multiple projects updating
Auto-Selected Profile: planning
Context: Goals + project status + strategic decisionsTroubleshooting
Context Not Appearing
Symptoms:
- New sessions start without context injection
- Agent has no awareness of previous work
Diagnosis:
# Check hook registration
openclaw hooks list
# Test context generation manually
clawvault context --profile auto "session start"
# Check vault accessibility
clawvault doctorSolutions:
# Reinstall hook
clawhub install clawvault
# Use wake command as workaround
clawvault wakeWrong Profile Selection
Test profile selection manually:
clawvault context --profile incident "production issue"
clawvault context --profile planning "roadmap review"
clawvault context --profile handoff "resuming work"Context Generation Too Slow
Edit MAX_CONTEXT_RESULTS and MAX_RECAP_RESULTS constants in handler.js to reduce injection size.
Manual Context Injection
You can trigger context injection manually:
Test Profile Selection
# See what profile would be auto-selected
clawvault context --profile auto --explain "session start"Manual Profile Override
# Force specific profile
clawvault context --profile incident "production problem"
# Use in session start
clawvault context --profile handoff "resuming work"Test Without Hook
# Use wake command directly (includes context retrieval)
clawvault wakeBest Practices
- Let auto-selection work - it learns from your patterns
- Maintain good memory hygiene - clean, categorized memories improve selection
- Use wiki-links liberally - improves graph-aware retrieval
- Monitor injection performance - adjust timeouts if needed
Manual context control is useful for:
- Demos/presentations - ensure specific context appears
- Deep work sessions - focus context on single project
- Crisis situations - force incident profile when auto-detection misses
- Strategic sessions - force planning profile for goal work
Integration with Other Features
Checkpoint Recovery
- Context injection includes recent checkpoint data
- Combines with auto-checkpoint for seamless continuity
- Handoff profile emphasizes checkpoint content
Context Death Detection
- Death detection triggers incident profile selection
- Recovery context injected alongside normal context
- Provides comprehensive restart information
Memory Graph
- Graph-aware search improves context relevance
- Entity relationships inform memory selection
- Wiki-links in context maintain graph connectivity
Performance Characteristics
| Vault Size | Context Generation Time | Memory Count |
|---|---|---|
| Small (<100 files) | 50-200ms | 5-8 memories |
| Medium (100-500 files) | 200-500ms | 6-10 memories |
| Large (500-1000 files) | 500ms-1s | 8-12 memories |
| Very Large (1000+ files) | 1-3s | 10-15 memories |
Timeout protection ensures session start never blocks longer than configured limit (default: 3 seconds).