Post-Session Processing System - User Guide

Overview

The Post-Session Processing system provides 100% reliable bookkeeping after agent sessions complete. Unlike agent-dependent state updates, this system runs independently in Python to ensure all insights are extracted and knowledge bases are updated regardless of agent compliance.

Key Benefits:

• 🎯 Reliable State Updates - Never miss session insights
• 🧠 Knowledge Extraction - Automatically capture patterns, decisions, and solutions
• 📊 Session Analytics - Track metrics and trends across sessions
• 🔄 Automatic Integration - Hooks trigger processing automatically

Architecture

Agent Session Completes
        ↓
Post-Session Hook Triggers
        ↓
Extract Insights from Transcript
        ↓
Update Knowledge Base (SQLite)
        ↓
Store Session Summary
        ↓
Append to Unified Messages
        ↓
Update Task Status

Quick Start

1. Process Latest Session (Automatic)

# Process most recent session automatically
python3 scripts/post-session-processor.py --auto

# Or use the hook
python3 hooks/post-session.py --manual --latest

2. Process Specific Session

# By session ID
python3 scripts/post-session-processor.py --session-id 20251222_143000

# By transcript file
python3 scripts/post-session-processor.py --transcript context-storage/session_20251222_143000.txt

3. Process with Task Tracking

# Associate with task ID
python3 scripts/post-session-processor.py --auto --task-id TASK-123

What Gets Extracted

1. Code Patterns

# Automatically detected:
- Function definitions (def name():)
- Class definitions (class Name:)
- Import statements
- Async/await patterns
- Decorators

2. Architecture Decisions

# Keywords trigger extraction:
- "decided to..."
- "chose X because Y..."
- "using X instead of Y..."
- "implementation uses..."

3. Gotchas & Warnings

# Warning patterns:
- ⚠️ prefix
- WARNING: prefix
- CAUTION: prefix
- Note: prefix
- Important: prefix

4. Error Solutions

# Error-solution pairs:
- Error: ... Solution: ...
- Exception: ... Fixed by: ...
- Failed: ... Resolved: ...

5. File Modifications

# File operations:
- Created: path/to/file
- Modified: path/to/file
- Deleted: path/to/file
- Writing to: path/to/file

Hook Integration

Automatic Triggering

The hook system automatically processes sessions when they complete:

# In your agent workflow
# Session completes → Hook triggers → Processing runs

Manual Hook Invocation

# Process latest session
python3 hooks/post-session.py --manual --latest

# Process specific session
python3 hooks/post-session.py --manual --session-id SESSION_ID

# Check hook status
python3 hooks/post-session.py --status

Hook Events

The system responds to two events:

1. session.complete - Automatic trigger when session ends
2. manual.invoke - Manual processing request

Output Files

1. Session Insights (.coditect/session-insights.json)

{
  "20251222_143000": {
    "session_id": "20251222_143000",
    "summary": "Session transcript...",
    "insights": {
      "patterns": [...],
      "decisions": [...],
      "gotchas": [...],
      "errors": [...],
      "file_modifications": [...]
    },
    "metrics": {
      "patterns_found": 15,
      "decisions_made": 3,
      "errors_solved": 2
    }
  }
}

2. Task Status (.coditect/task-status.json)

{
  "TASK-123": {
    "status": "completed",
    "updated_at": "2025-12-22T14:30:00Z",
    "insights_summary": {
      "patterns_found": 15,
      "decisions_made": 3,
      "files_modified": 8
    }
  }
}

3. Knowledge Base (ADR-118 Four-Tier)

SQLite databases with session_insights table in org.db (Tier 2):

CREATE TABLE session_insights (
    id INTEGER PRIMARY KEY,
    session_id TEXT NOT NULL,
    insight_type TEXT NOT NULL,
    content TEXT NOT NULL,
    confidence REAL,
    extracted_at TEXT NOT NULL
);

4. Unified Messages (context-storage/unified_messages.jsonl)

JSONL file with session insight summaries appended:

{"role": "system", "content": "Session insights: {...}", "timestamp": "...", "session_id": "..."}

Configuration

Edit config/post-session-config.json to customize:

Insight Extraction

{
  "insight_extraction": {
    "patterns": {
      "code_patterns": true,
      "architecture_decisions": true,
      "error_solutions": true,
      "gotchas_warnings": true
    },
    "min_confidence": 0.7
  }
}

Knowledge Base Updates

{
  "knowledge_base": {
    "auto_update": true,
    "deduplication": true,
    "batch_size": 100
  }
}

Session Summaries

{
  "session_summary": {
    "max_length": 1000,
    "include_metrics": true,
    "include_transcript": false
  }
}

Query Extracted Insights

1. View Session Summary

import json

with open('.coditect/session-insights.json') as f:
    insights = json.load(f)

session = insights['20251222_143000']
print(f"Patterns: {len(session['insights']['patterns'])}")
print(f"Decisions: {len(session['insights']['decisions'])}")

2. Query Knowledge Base

import sqlite3

conn = sqlite3.connect('context-storage/org.db')  # ADR-118 Tier 2
cursor = conn.cursor()

# Get all patterns from session
cursor.execute("""
    SELECT content FROM session_insights
    WHERE session_id = ? AND insight_type = 'pattern'
""", ('20251222_143000',))

patterns = cursor.fetchall()

3. Check Task Status

import json

with open('.coditect/task-status.json') as f:
    tasks = json.load(f)

task = tasks['TASK-123']
print(f"Status: {task['status']}")
print(f"Files Modified: {task['insights_summary']['files_modified']}")

Advanced Usage

Batch Processing

# Process multiple sessions
for session in context-storage/session_*.txt; do
    python3 scripts/post-session-processor.py --transcript "$session"
done

Custom Transcript Location

# Process transcript from custom location
python3 scripts/post-session-processor.py \
    --transcript /path/to/transcript.txt \
    --session-id custom_session_id

Integration with CI/CD

# .github/workflows/post-session.yml
name: Post-Session Processing
on:
  workflow_dispatch:
    inputs:
      session_id:
        description: 'Session ID to process'
        required: true

jobs:
  process:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Process Session
        run: |
          python3 scripts/post-session-processor.py \
            --session-id ${{ inputs.session_id }}

Troubleshooting

Issue: No transcript found

# Check transcript location
ls -la context-storage/session_*.txt

# Verify session ID format
# Should be: session_YYYYMMDD_HHMMSS.txt

Issue: Knowledge base not updating

# Verify database exists (ADR-118 Tier 2)
ls -la context-storage/org.db

# Check permissions
chmod 644 context-storage/org.db

# Enable auto_update in config
# Set "auto_update": true in post-session-config.json

Issue: Hook not triggering

# Check hook status
python3 hooks/post-session.py --status

# Manually trigger hook
python3 hooks/post-session.py --manual --latest

# Verify hook configuration
cat config/post-session-config.json | grep -A 5 "hooks"

Best Practices

1. Regular Processing

Run post-session processing after every agent session:

# Add to your workflow
/session → Work completed → /cx → Post-session processing

2. Backup Before Processing

# Backup knowledge base before bulk processing (ADR-118)
cp context-storage/org.db context-storage/org.db.backup

3. Monitor Insights Quality

# Check confidence levels
python3 -c "
import json
with open('.coditect/session-insights.json') as f:
    insights = json.load(f)
    for session_id, data in insights.items():
        patterns = data['insights']['patterns']
        avg_conf = sum(p.get('confidence', 0) for p in patterns) / len(patterns) if patterns else 0
        print(f'{session_id}: avg confidence = {avg_conf:.2f}')
"

4. Clean Old Sessions

# Archive sessions older than 30 days
find context-storage -name "session_*.txt" -mtime +30 -exec mv {} archive/ \;

Performance

Processing Times

Session Size	Processing Time
Small (<1MB)	<1 second
Medium (1-5MB)	1-3 seconds
Large (5-10MB)	3-10 seconds

Optimization Tips

1. Enable async processing in config
2. Set transcript size limit to prevent OOM
3. Use batch processing for multiple sessions
4. Archive old sessions to reduce file scanning

Integration Examples

Example 1: Agent Workflow Integration

# In your agent code
async def complete_session(session_id, transcript):
    # Save transcript
    with open(f'context-storage/session_{session_id}.txt', 'w') as f:
        f.write(transcript)

    # Trigger post-session processing
    await run_hook('post-session', session_id=session_id)

Example 2: Task Management Integration

# Update task with insights
async def complete_task(task_id):
    # Process session with task tracking
    results = await process_session(
        transcript=get_transcript(),
        task_id=task_id
    )

    # Task status automatically updated
    return results

Support

Documentation:

• This guide (POST-SESSION-PROCESSING-GUIDE.md)
• MEMORY-MANAGEMENT-GUIDE.md
• COMPONENT-ACTIVATION-GUIDE.md

Scripts:

• scripts/post-session-processor.py - Main processor
• hooks/post-session.py - Hook integration

Configuration:

• config/post-session-config.json - Processing config

---

Last Updated: December 22, 2025 Version: 1.0.0 Status: Production Ready