# Intelligence Features Quick Start Guide
**Session Buddy's unique intelligence features**: Automatic knowledge capture and cross-project pattern sharing
**Time to get started**: 5 minutes
______________________________________________________________________
## 1. 💡 Automatic Insights Capture
### What It Does
Session Buddy automatically extracts educational insights from your conversations when you use the `★ Insight ─────` delimiter pattern.
### How to Use It
**Step 1: Write explanations in explanatory mode**
When you explain something to users (or when Claude explains something to you), mark key insights:
```markdown
You should use async/await for database operations.
`★ Insight ─────────────────────────────────────`
Always use async/await for database operations to prevent blocking the event loop and maintain responsiveness
`─────────────────────────────────────────────────`
This pattern ensures your application remains responsive during I/O operations.
```
**Step 2: Run checkpoints**
Session Buddy automatically extracts insights at two points:
```bash
# Checkpoint during work
/checkpoint
# End session
/end
```
**Step 3: Search your insights**
```bash
# Search for insights about async patterns
/session-buddy:search_insights "async database"
# View all captured insights
/session-buddy:search_insights "*"
# View statistics
/session-buddy:insights_statistics
```
### Example Workflow
```bash
# 1. Start your session
/start
# 2. Work normally, use ★ Insight delimiters for key points
# 3. Mid-work checkpoint (extracts insights)
/checkpoint
# 4. Continue working...
# 5. End session (extracts more insights, deduplicates)
/end
# 6. Next session: Search past insights
/session-buddy:search_insights "topic you're working on"
```
### Insight Capture Flow
```mermaid
flowchart TD
Start([Start Session]) --> Work[Work with Explanatory Mode]
Work --> Write[Write ★ Insight Delimiters]
Write --> Work
Work --> Checkpoint{Run Checkpoint?}
Checkpoint -->|Yes| Extract1[Extract Insights]
Checkpoint -->|No| Continue[Continue Work]
Continue --> Work
Extract1 --> Hash1[Calculate SHA-256]
Hash1 --> Dedupe1{Duplicate?}
Dedupe1 -->|No| Store1[Store with Embeddings]
Dedupe1 -->|Yes| Skip1[Skip Duplicate]
Store1 --> Work
Skip1 --> Work
Work --> End{End Session?}
End -->|Yes| Extract2[Extract Final Insights]
End -->|No| Work
Extract2 --> Hash2[Calculate SHA-256]
Hash2 --> Dedupe2{Duplicate?}
Dedupe2 -->|No| Store2[Store with Embeddings]
Dedupe2 -->|Yes| Skip2[Skip Duplicate]
Store2 --> Search[Available for Search]
Skip2 --> Search
Search --> Query[Query: search_insights]
Query --> Semantic[Semantic Search]
Semantic --> Results[Ranked Results]
style Start fill:#e1f5ff
style Work fill:#fff9c4
style Extract1 fill:#c8e6c9
style Extract2 fill:#c8e6c9
style Store1 fill:#b2dfdb
style Store2 fill:#b2dfdb
style Search fill:#ffccbc
style Results fill:#f8bbd9
```
Session Buddy captures insights when:
1. **You run `/checkpoint`**: Extracts insights from conversation so far
1. **You end session**: Extracts any new insights (duplicates are filtered out)
1. **Quality threshold**: Only captures insights with confidence ≥0.5 (configurable)
1. **Rate limiting**: Max 10 insights per checkpoint (configurable)
### Configuration
Edit `~/.claude/settings/session-buddy.yaml`:
```yaml
enable_insight_extraction: true # Enable/disable
insight_extraction_confidence_threshold: 0.5 # Minimum confidence
insight_extraction_max_per_checkpoint: 10 # Rate limiting
```
______________________________________________________________________
## 2. 🌐 Cross-Project Intelligence
### What It Does
Share knowledge across related projects with dependency-aware search and coordination.
### How to Use It
**Step 1: Create project groups**
```python
# In Claude Code, ask to create a project group
"I want to create a project group called 'microservices-app'
with projects: auth-service, user-service, api-gateway"
```
Or use the MCP tool directly:
```python
from session_buddy.multi_project_coordinator import ProjectGroup
group = ProjectGroup(
name="microservices-app",
projects=["auth-service", "user-service", "api-gateway"],
description="Authentication and user management microservices"
)
```
**Step 2: Define dependencies**
```python
from session_buddy.multi_project_coordinator import ProjectDependency
deps = [
ProjectDependency(
source_project="user-service",
target_project="auth-service",
dependency_type="uses",
description="User service depends on auth service"
),
ProjectDependency(
source_project="api-gateway",
target_project="user-service",
dependency_type="extends",
description="Gateway extends user service"
)
]
```
**Step 3: Search across projects**
```bash
# Search across all related projects
/session-buddy:search_across_projects "authentication pattern" "microservices-app"
# Get project insights
/session-buddy:get_project_insights ["auth-service", "user-service"]
```
### Cross-Project Dependency Visualization
```mermaid
graph TB
subgraph "Project Group: microservices-app"
Auth[Auth Service<br/>🔐 Authentication]
User[User Service<br/>👤 User Management]
Gateway[API Gateway<br/>🌐 Routing]
Payment[Payment Service<br/>💳 Transactions]
Notification[Notification Service<br/>📧 Messaging]
Audit[Audit Service<br/>📊 Logging]
end
%% Dependency relationships
User -.->|uses| Auth
Payment -.->|uses| Auth
Gateway -.->|extends| User
Notification -.->|extends| User
Audit -.->|references| Payment
Audit -.->|references| Gateway
%% Knowledge flow
Auth -.Knowledge Flow.-> User
Auth -.Knowledge Flow.-> Payment
User -.Knowledge Flow.-> Gateway
User -.Knowledge Flow.-> Notification
Payment -.Knowledge Flow.-> Audit
%% Styling
style Auth fill:#ffcdd2
style User fill:#f8bbd9
style Gateway fill:#e1bee7
style Payment fill:#d1c4e9
style Notification fill:#c5cae9
style Audit fill:#bbdefb
```
### Cross-Project Knowledge Sharing Flow
```mermaid
sequenceDiagram
participant Dev as Developer
participant Auth as Auth Service
participant Coord as Multi-Project<br/>Coordinator
participant User as User Service
participant Gateway as API Gateway
Note over Auth: Developer fixes auth bug
Dev->>Auth: Fix Authentication Issue
Auth->>Auth: Store Reflection
Note over Coord: Pattern Detected
Auth->>Coord: Share Pattern
Coord->>Coord: Check Dependencies
Note over Coord,User: "uses" relationship
Coord->>User: Propagate Solution
User->>User: Update Knowledge
Note over Coord,Gateway: "extends" relationship
Coord->>Gateway: Suggest Enhancement
Gateway->>Gateway: Apply Pattern
Note over Dev: Next session
Dev->>Coord: Search "authentication"
Coord-->>Dev: Ranked Results:
Coord-->>Dev: 1. Auth (source)
Coord-->>Dev: 2. User (uses)
Coord-->>Dev: 3. Gateway (extends)
```
### Example Use Cases
#### Use Case 1: Microservices Architecture
**Scenario**: You have 5 microservices that share authentication patterns.
**Setup**:
```python
# Create group
microservices = ProjectGroup(
name="api-platform",
projects=["auth-service", "user-service", "payment-service",
"notification-service", "audit-service"]
)
# Define dependencies
deps = [
ProjectDependency("user-service", "auth-service", "uses"),
ProjectDependency("payment-service", "auth-service", "uses"),
ProjectDependency("notification-service", "user-service", "extends"),
# ... more dependencies
]
```
**Benefit**: Fix an auth bug once, all dependent services learn about it automatically.
#### Use Case 2: Monorepo with Multiple Packages
**Scenario**: You have a monorepo with frontend, backend, shared packages.
**Setup**:
```python
monorepo = ProjectGroup(
name="web-app",
projects=["frontend", "backend", "shared-utils", "types"]
)
```
**Benefit**: API changes in backend automatically surface when working on frontend.
#### Use Case 3: Multi-Repo Related Projects
**Scenario**: Separate repos for client, server, and shared contracts.
**Setup**:
```python
distributed = ProjectGroup(
name="distributed-system",
projects=["client-app", "server-api", "shared-contracts"]
)
```
**Benefit**: Contract changes in shared-contracts alert both client and server teams.
### Dependency Types
- **`uses`**: Direct dependency (imports, API calls)
- **`extends`**: Enhancement or wrapper (adds functionality)
- **`references`**: Loose coupling (documentation, patterns)
- **`shares_code`**: Code sharing (common libraries, utilities)
______________________________________________________________________
## 3. 👥 Team Collaboration
### What It Does
Create teams for shared knowledge with collaborative filtering and voting.
### How to Use It
**Step 1: Create a team**
```python
from session_buddy.core.team_management import Team
team = Team(
team_id="platform-team",
name="Platform Team",
description="Backend platform development team",
owner_id="user-123"
)
```
**Step 2: Share knowledge**
When team members store reflections with `team_id`, they become searchable:
```bash
/session-buddy:store_reflection
content="Use Redis for session caching with 5-minute TTL"
team_id="platform-team"
tags=["caching", "redis", "performance"]
```
**Step 3: Search team knowledge**
```bash
# Search team reflections
/session-buddy:search_team_knowledge
query="caching strategies"
user_id="user-123"
team_id="platform-team"
```
**Step 4: Vote on quality**
```bash
# Upvote helpful reflections
/session-buddy:vote_on_reflection
reflection_id="abc-123"
user_id="user-123"
vote_delta=1 # Upvote
```
**Benefit**: High-quality reflections float to the top through community voting.
______________________________________________________________________
## 4. 🔍 Advanced Search Techniques
### Semantic Search
Find insights by meaning, not just keywords:
```bash
# Find insights about "async patterns" even if not exact match
/session-buddy:search_insights "concurrent database operations"
# Wildcard to see everything
/session-buddy:search_insights "*"
```
### Faceted Search
Combine filters for precise results:
```bash
# Search by file
/session-buddy:search_by_file "database.py"
# Search by concept with file context
/session-buddy:search_by_concept "error handling" "src/api/"
# Search errors only
/session-buddy:search_errors "database connection timeout"
# Temporal search
/session-buddy:search_temporal "last week insights about testing"
```
### Search Summary
Get aggregated insights without full result lists:
```bash
/session-buddy:search_summary "authentication"
# Returns:
# - Total count: 23 insights found
# - Top topics: JWT, session management, OAuth
# - Quality trends: Improving over time
# - No full result list (faster)
```
______________________________________________________________________
## 5. 📊 Analytics & Statistics
### Insights Statistics
View what's been captured:
```bash
/session-buddy:insights_statistics
```
Returns:
- Total insights captured
- Breakdown by type (pattern, architecture, best_practice, gotcha)
- Top topics
- Confidence score distribution
- Usage statistics (most referenced)
### Reflection Stats
```bash
/session-buddy:reflection_stats
```
Returns:
- Total reflections stored
- Projects with most reflections
- Search trends
- Database size and performance
### Team Statistics
```bash
/session-buddy:get_team_statistics
team_id="platform-team"
user_id="user-123"
```
Returns:
- Team member contributions
- Most voted reflections
- Activity trends
- Knowledge coverage
______________________________________________________________________
## 6. ⚙️ Configuration
### Feature Flags
Edit `~/.claude/settings/session-buddy.yaml`:
```yaml
# Insights capture
enable_insight_extraction: true
insight_extraction_confidence_threshold: 0.5 # 0.3-0.7
insight_extraction_max_per_checkpoint: 10 # Rate limiting
# Search settings
search_similarity_threshold: 0.7 # Semantic search threshold
search_max_results: 20 # Default results limit
```
### Environment Variables
```bash
# Disable insight extraction
export SESSION_BUDDY_ENABLE_INSIGHT_EXTRACTION="false"
# Custom database path
export SESSION_BUDDY_DATABASE_PATH="/custom/path/reflection.duckdb"
# Adjust confidence threshold
export SESSION_BUDDY_INSIGHT_CONFIDENCE="0.7"
```
______________________________________________________________________
## 7. 🎯 Best Practices
### Writing Better Insights
**DO** ✅:
- Be specific and actionable
- Include context and rationale
- Use concrete examples
- Mark truly valuable insights
```markdown
`★ Insight ─────────────────────────────────────`
Always validate user input at the API boundary, not just in business logic. This prevents invalid data from entering your system and provides clearer error messages to clients.
`─────────────────────────────────────────────────`
```
**DON'T** ❌:
- Mark every statement as an insight
- Capture trivial information
- Be vague or overly general
- Duplicate existing insights
```markdown
# Too trivial
`★ Insight ─────────────────────────────────────`
Use functions to organize code.
`─────────────────────────────────────────────────`
# Too vague
`★ Insight ─────────────────────────────────────`
Write good code.
`─────────────────────────────────────────────────`
```
### Organizing Projects
**DO** ✅:
- Group related projects meaningfully
- Define accurate dependencies
- Use descriptive project names
- Document relationships
**DON'T** ❌:
- Group unrelated projects together
- Create circular dependencies
- Use cryptic abbreviations
- Over-depend on other projects
### Team Collaboration
**DO** ✅:
- Vote on high-quality reflections
- Tag with relevant topics
- Share across teams appropriately
- Document team-specific knowledge
**DON'T** ❌:
- Spam with low-quality reflections
- Over-tag everything
- Share sensitive information publicly
- Duplicate existing team knowledge
______________________________________________________________________
## 8. 🐛 Troubleshooting
### Insights Not Being Captured
**Problem**: No insights appear after checkpoint/session_end
**Checks**:
1. **Verify feature is enabled**:
```bash
grep enable_insight_extraction ~/.claude/settings/session-buddy.yaml
```
1. **Check conversation has insights**:
- Look for `★ Insight ─────` delimiters
- Ensure proper formatting (exact delimiters required)
1. **Check confidence threshold**:
- Insights below threshold (default: 0.5) are filtered out
- Lower threshold temporarily: `export SESSION_BUDDY_INSIGHT_CONFIDENCE="0.3"`
1. **Check logs**:
```bash
tail -f ~/.claude/logs/session-buddy.log | grep -i insight
```
### Cross-Project Search Not Working
**Problem**: Results don't include related projects
**Checks**:
1. **Verify project group exists**:
```python
# Check in Python
from session_buddy.multi_project_coordinator import MultiProjectCoordinator
coordinator = MultiProjectCoordinator()
groups = await coordinator.list_project_groups()
```
1. **Check dependencies are defined**:
```python
deps = await coordinator.list_dependencies(
source_project="user-service"
)
```
1. **Verify projects share knowledge**:
- Ensure reflections are tagged with project names
- Check `search_insights` with `project="*"` (search all)
### Search Returns No Results
**Problem**: `search_insights` returns empty list
**Checks**:
1. **Wildcard search**:
```bash
/session-buddy:search_insights "*"
```
If this returns results, your data is there, just not matching your query.
1. **Lower threshold**:
```bash
/session-buddy:search_insights "your query" min_similarity=0.5
```
1. **Check database**:
```python
import duckdb
conn = duckdb.connect("~/.claude/data/reflection.duckdb")
result = conn.execute("SELECT COUNT(*) FROM default_reflections WHERE insight_type IS NOT NULL")
print(result.fetchone()) # Should be > 0
```
______________________________________________________________________
## 9. 📚 Further Reading
- **[Insights Capture & Deduplication](INSIGHTS_CAPTURE.md)** - Complete technical details
- **[MCP Tools Reference](../user/MCP_TOOLS_REFERENCE.md)** - All intelligence tools
<!-- - **[Claude Flow V2 Integration](../archive/implementation-plans/CLAUDE_FLOW_INTEGRATION_PLAN_V2.md)** - Future roadmap (file not found) -->
- **[Architecture Overview](../developer/ARCHITECTURE.md)** - System design
______________________________________________________________________
## 10. 🚀 Quick Reference
### Essential Commands
```bash
# Capture insights automatically
/checkpoint # Captures at mid-point
/end # Captures at end, deduplicates
# Search insights
/session-buddy:search_insights "topic" # Semantic search
/session-buddy:search_insights "*" # View all
/session-buddy:insights_statistics # View stats
# Cross-project
/session-buddy:create_project_group ... # Create group
/session-buddy:add_project_dependency ... # Add dependency
/session-buddy:search_across_projects "query" "group" # Search related
# Team
/session-buddy:create_team ... # Create team
/session-buddy:search_team_knowledge ... # Team search
/session-buddy:vote_on_reflection ... # Vote on quality
```
### Common Workflows
**New Feature Development**:
```bash
/start → Work with ★ Insight delimiters → /checkpoint →
Continue → /end → /search_insights "new feature"
```
**Bug Investigation**:
```bash
/search_errors "error message" → Review solutions →
/store_reflection "fix approach" → Vote on quality
```
**Multi-Project Coordination**:
```bash
/create_project_group → /add_project_dependency →
/search_across_projects "pattern" "group"
```
______________________________________________________________________
**Last Updated**: January 10, 2026
**Status**: Production Ready ✅
**Test Coverage**: 62/62 tests passing (100%)
