Claude Cognitive Files

✅ v1.2.0 - Phase 1 Complete: Usage Tracking

Status: Stable Release Date: 2026-01-12 Branch: main

---

🎯 Phase 1 Complete

This release marks the completion of Phase 1: Usage Tracking from the v1.2 Intelligence Roadmap.

The foundation is now in place for data-driven context routing optimization. The system can observe which injected files Claude actually uses, measure their usefulness, and prepare for learning-based improvements in future phases.

---

✨ What's New

Usage Tracking System (Production Ready)

Core capability: Measure which documentation Claude actually uses vs what gets injected.

:::python
# After each conversation turn:
{
  "injected": ["auth.md", "database.md", "api.md"],  # What we sent
  "accessed": ["auth.md", "database.md"],            # What Claude read
  "usefulness_scores": {
    "auth.md": 0.85,      # High value (accessed 85% of time)
    "database.md": 0.72,  # Good value (accessed 72% of time)
    "api.md": 0.15        # Low value (rarely accessed)
  }
}

Why this matters: We finally have objective measurement of documentation effectiveness. No more guessing which files are valuable.

Features

1. File Access Monitoring

• Tracks: Which .claude/*.md files are injected into context
• Measures: Which files Claude actually reads (via tool calls)
• Calculates: Usefulness score = accessed / injected (0.0 to 1.0)
• Stores: .claude/usage_stats.json, .claude/usage_history.jsonl

2. Ralph Loop Learning Pattern

• Observe: Collect usage data over multiple turns
• Measure: Calculate usefulness scores per file
• Learn: Auto-adjust keyword weights after 50 turns
• Refine: Improved context routing based on real usage

3. Keyword Weight Learning

• Starts: All keywords weighted 1.0 (default)
• Learns: High-usefulness files get weights > 1.0
• Adjusts: Low-usefulness files get weights < 1.0
• Applies: Learned weights used in attention calculation
• Persists: .claude/keyword_weights.json

4. Integration with context-router-v2.py

• Injection logging: Automatically records injected files
• Weight loading: Applies learned weights to attention scores
• Graceful fallback: Works without tracker if not installed
• Zero overhead: Tracking happens post-response (non-blocking)

---

📊 How It Works

The Ralph Loop

Turn 1-50:  Observation Mode
           ↓ (collect usage data)
           ↓
Turn 51:    Calculate usefulness scores
           ↓ (identify high/low value files)
           ↓
Turn 52+:   Apply learned weights
           ↓ (prioritize valuable files)
           ↓
Turn 100:   Recalculate and adjust
           ↓ (continuous learning)
           ↓
Repeat...

Result: Context routing improves over time based on actual usage.

Example Learning Outcome

Before learning (turns 1-50):

:::python
# All keywords equal weight
keywords = {
  "auth": ["systems/auth.md"],       # weight: 1.0
  "database": ["systems/db.md"],     # weight: 1.0
  "api": ["modules/api-docs.md"]     # weight: 1.0
}

After learning (turn 51+):

:::python
# Weights adjusted based on usefulness
keywords = {
  "auth": ["systems/auth.md"],       # weight: 1.5 (high usefulness)
  "database": ["systems/db.md"],     # weight: 1.2 (good usefulness)
  "api": ["modules/api-docs.md"]     # weight: 0.5 (low usefulness)
}

Impact: "auth" gets 50% more attention, "api" gets 50% less → better context quality.

---

🚀 Installation

Step 1: Update to v1.2.0

:::bash
cd ~/claude-cognitive-package
git checkout main
git pull origin main

Step 2: Install Stop Hook

:::bash
python3 scripts/add-usage-tracking-hook.py

This adds usage-track-stop.py to your ~/.claude/settings.json stop hooks.

Step 3: Verify Installation

:::bash
# Check hook is registered
cat ~/.claude/settings.json | grep usage-track-stop

# Should show:
# "stop": ["python3 /path/to/scripts/usage-track-stop.py"]

Step 4: Use Claude Code Normally

The tracker works automatically: - During conversation: No overhead (tracking deferred) - After conversation: Usage analysis runs in stop hook - After 50 turns: Automatic weight learning kicks in

Step 5: Check Results

:::bash
# View usage statistics
cat .claude/usage_stats.json

# View history
tail -10 .claude/usage_history.jsonl

# View learned weights
cat .claude/keyword_weights.json

---

📚 Documentation

• CHANGELOG.md - What's new in v1.2.0
• README.md - Quick start guide
• .claude/modules/usage-tracker.md - Usage tracker design (850+ lines)
• V1.2_INTELLIGENCE_ROADMAP.md - Complete 4-phase roadmap
• RALPH_LOOP_INSIGHTS.md - Design philosophy (700+ lines)

---

🎯 Roadmap Status

Phase	Status	Description
Phase 1: Usage Tracking	✅ Complete (v1.2.0)	Measure file usefulness, learn weights
Phase 2: Embeddings	🔄 Skipped	Moving to hologram auto-discovery
Phase 3: Intelligent Agents	🔜 Planned (v2.x)	Foraging + doc refiner agents
Phase 4: Self-Learning	🔜 Planned (v2.x)	Full autonomous maintenance

---

🚀 What's Next: v2.0 Hologram Integration

Phase 2 has been skipped in favor of a better approach: hologram-cognitive.

Why Skip Embeddings?

The original Phase 2 plan: - Use embeddings to find semantic relationships - Still requires manual seed configuration - High computational cost - Limited relationship discovery

The hologram approach: - ✅ Auto-discovers relationships (no manual config) - ✅ 20x more relationships found (1,881 vs ~100) - ✅ 100% accuracy (no false positives) - ✅ Zero configuration required - ✅ Self-healing (adapts to file changes)

v2.0.0-rc Available Now! 🚀

v2.0 Release Candidate introduces hologram-cognitive integration:

• Auto-discovered DAG relationships replace manual keywords.json
• Edge-weighted injection with physics-based prioritization
• Hub governance prevents meta-docs from dominating budget
• Learning-ready architecture for Phase 4

Branch: github.com/GMaN1911/claude-cognitive/tree/v2.0

Status: Dogfooding in progress (Week 1-2), stable release expected Week 4

Migration Path

Current users (v1.x): 1. Stay on v1.2.0 (stable, keywords.json-based) 2. Monitor v2.0 dogfooding progress 3. Migrate to v2.0 when it's finalized (Week 4+)

Early adopters: 1. Switch to v2.0 branch now 2. Follow Migration Guide 3. Provide feedback during dogfooding

---

🔧 Technical Details

Files Added

• scripts/usage_tracker.py - Core tracking logic (Ralph Loop implementation)
• scripts/usage-track-stop.py - Stop hook integration
• scripts/add-usage-tracking-hook.py - Hook installer utility

Files Modified

• scripts/context-router-v2.py - Added usage tracker integration, learned weight loading
• ~/.claude/settings.json - Stop hook registration (via installer)

Generated Files (Auto-created)

• .claude/usage_stats.json - Current usefulness scores per file
• .claude/usage_history.jsonl - Historical usage data per turn
• .claude/keyword_weights.json - Learned weights (after turn 50+)

---

🐛 Known Limitations

Observation Period

• Requires 50 turns before weight learning activates
• Early turns use default weights (all 1.0)
• Learning improves gradually over time

Edge Cases

• Large codebases: May need more turns for accurate learning
• Rare topics: Files used infrequently may be underweighted
• Context shifts: Major project changes may require weight reset

Mitigation: These are inherent to learning-based systems. Phase 4 (v2.x) will add more sophisticated learning.

---

💡 Design Philosophy: Ralph Loop

This release embodies the Ralph Loop pattern:

Iterate → Measure → Learn → Refine → Repeat

Not: - ❌ Build perfect system upfront - ❌ Guess what users need - ❌ Hard-code all the rules

Instead: - ✅ Build foundation with measurement - ✅ Observe real usage patterns - ✅ Learn from objective data - ✅ Refine based on evidence - ✅ Iterate continuously

Result: System that improves itself over time based on actual usage, not assumptions.

---

🙏 Credits

Created by: Garret Sutherland (@GMaN1911) Pattern: Ralph Loop (iterate-measure-learn-refine) Foundation for: v2.0 hologram integration (Phase 4)

---

🔗 Links

• Repository: github.com/GMaN1911/claude-cognitive
• v2.0 Branch: github.com/GMaN1911/claude-cognitive/tree/v2.0
• v2.0.0-rc Release: Latest pre-release
• Issues: github.com/GMaN1911/claude-cognitive/issues
• Discussions: github.com/GMaN1911/claude-cognitive/discussions

---

📅 Timeline

Milestone	Date	Status
v1.1.2	2026-01-08	Pre-release (development preview)
v1.2.0	2026-01-12	✅ Stable (Phase 1 complete)
v2.0.0-rc	2026-01-12	Pre-release (dogfooding)
v2.0.0	Week 4	Planned (hologram stable)

---

🚀 Get Started

Option A: Stay on v1.2.0 (Stable)

:::bash
cd ~/claude-cognitive-package
git checkout main
git pull origin main
python3 scripts/add-usage-tracking-hook.py

Option B: Try v2.0.0-rc (Early Adopter)

:::bash
cd ~/claude-cognitive-package
git checkout v2.0
git pull origin v2.0

# Follow migration guide
open https://github.com/GMaN1911/claude-cognitive/blob/v2.0/docs/MIGRATION_GUIDE.md

---

💬 Feedback

• Bug reports: GitHub Issues
• Feature requests: GitHub Discussions
• Questions: GitHub Discussions

For v2.0 feedback: See v2.0.0-rc release

---

v1.2.0 marks Phase 1 completion. v2.0 introduces the next paradigm shift. Choose your path! 🚀