GitHub - GMaN1911/claude-cognitive: Working memory for Claude Code - persistent context and multi-instance coordination

Claude Cognitive

Working memory for Claude Code — persistent context and multi-instance coordination

The Problem

Claude Code is powerful but stateless. Every new instance:

Rediscovers your codebase from scratch
Hallucinates integrations that don't exist
Repeats debugging you already tried
Burns tokens re-reading unchanged files

With large codebases (50k+ lines), this becomes painful fast.

The Solution

Claude Cognitive gives Claude Code working memory through two complementary systems:

1. Context Router

Attention-based file injection with cognitive dynamics:

HOT (>0.8): Full file injection - active development
WARM (0.25-0.8): Headers only - background awareness
COLD (<0.25): Evicted from context

Files decay when not mentioned, activate on keywords, and co-activate with related files.

2. Pool Coordinator

Multi-instance state sharing for long-running sessions:

Automatic mode: Detects completions/blockers from conversation (every 5min)
Manual mode: Explicit pool blocks for critical coordination
Works with persistent sessions (days/weeks), not just short bursts

Results

Token Savings:

Cold start: 79% (120K → 25K chars)
Warm context: 70% (80K → 24K chars)
Focused work: 75% (60K → 15K chars)

Average: 64-95% depending on codebase size and work pattern.

Developer Experience:

✅ New instances productive in first message
✅ Zero hallucinated imports/integrations
✅ No duplicate work across 8+ concurrent instances
✅ Persistent memory across days-long sessions

Validated on:

1+ million line production codebase (3,200+ Python modules)
4-node distributed architecture
8 concurrent Claude Code instances
Multi-day persistent sessions

Quick Start

1. Install Scripts

# Clone to your home directory
cd ~
git clone https://github.com/GMaN1911/claude-cognitive.git .claude-cognitive

# Copy scripts
cp -r .claude-cognitive/scripts ~/.claude/scripts/

# Set up hooks (adds to existing config)
cat .claude-cognitive/hooks-config.json >> ~/.claude/settings.json

Note: The repo contains a .claude-dev/ directory for development/dogfooding purposes only. Do not copy this to your projects—it's not part of the user-facing installation. Use your own project-local .claude/ directory instead (see step 2).

2. Initialize Your Project

cd /path/to/your/project

# Create .claude directory
mkdir -p .claude/{systems,modules,integrations,pool}

# Copy templates
cp -r ~/.claude-cognitive/templates/* .claude/

# Edit .claude/CLAUDE.md with your project info
# Edit .claude/systems/*.md to describe your architecture

3. Set Instance ID

# Add to ~/.bashrc for persistence:
export CLAUDE_INSTANCE=A

# Or per-terminal:
export CLAUDE_INSTANCE=B

4. Verify It's Working

# Start Claude Code
claude

# First message - check for context injection:
# Should see: "ATTENTION STATE [Turn 1]" with HOT/WARM/COLD counts

# Query pool activity:
python3 ~/.claude/scripts/pool-query.py --since 1h

5. Create Keywords Config (Required)

Create .claude/keywords.json in your project root:

cp ~/.claude-cognitive/templates/keywords.json.example .claude/keywords.json

Edit to match your project's documentation files and relevant keywords.

Full setup guide: SETUP.md Customization guide: CUSTOMIZATION.md

Project Configuration

Create .claude/keywords.json in your project root to define project-specific keywords:

{
  "keywords": {
    "path/to/doc.md": ["keyword1", "keyword2", "phrase to match"]
  },
  "co_activation": {
    "path/to/doc.md": ["related/doc.md"]
  },
  "pinned": ["always/warm/file.md"]
}

Keywords: Map documentation files to trigger words. When any keyword appears in your prompt (case-insensitive), the file becomes HOT.

Co-activation: When a file activates, related files get a score boost.

Pinned: Files that should always be at least WARM.

The router checks for config in this order:

.claude/keywords.json (project-local)
~/.claude/keywords.json (global fallback)
Empty defaults (no activation)

How It Works

Context Router

Attention Dynamics:

User mentions "orin" in message
    ↓
systems/orin.md → score = 1.0 (HOT)
    ↓
Co-activation:
  integrations/pipe-to-orin.md → +0.35 (WARM)
  modules/t3-telos.md → +0.35 (WARM)
    ↓
Next turn (no mention):
  systems/orin.md → 1.0 × 0.85 decay = 0.85 (still HOT)
    ↓
3 turns later (no mention):
  systems/orin.md → 0.85 × 0.85 × 0.85 = 0.61 (now WARM)

Injection:

HOT files: Full content injected
WARM files: First 25 lines (headers) injected
COLD files: Not injected (evicted)

Pool Coordinator

Automatic Mode:

Instance A completes task
    ↓
Auto-detector finds: "Successfully deployed PPE to Orin"
    ↓
Writes pool entry:
  action: completed
  topic: PPE deployment to Orin
  affects: orin_sensory_cortex/
    ↓
Instance B starts session
    ↓
Pool loader shows:
  "[A] completed: PPE deployment to Orin"
    ↓
Instance B avoids duplicate work

Manual Mode:

```pool
INSTANCE: A
ACTION: completed
TOPIC: Fixed authentication bug
SUMMARY: Resolved race condition in token refresh. Added mutex.
AFFECTS: auth.py, session_handler.py
BLOCKS: Session management refactor can proceed
```

History Tracking (v1.1+)

Claude Cognitive now remembers its own attention. Every turn is logged with structured data showing which files were HOT/WARM/COLD and how they transitioned between tiers.

Why This Matters

The router always computed attention scores. Now they persist as queryable history:

Replay development trajectories - "How did we stabilize the PPE last week?"
Identify neglected modules - "Which files got ignored during the sprint?"
Debug attention behavior - "Why didn't convergent.md activate when I mentioned convergence?"

View History

# Last 20 turns
python3 ~/.claude/scripts/history.py

# Last 2 hours
python3 ~/.claude/scripts/history.py --since 2h

# Filter by file pattern
python3 ~/.claude/scripts/history.py --file ppe

# Show only tier transitions
python3 ~/.claude/scripts/history.py --transitions

# Summary statistics
python3 ~/.claude/scripts/history.py --stats

# Filter by instance
python3 ~/.claude/scripts/history.py --instance A

Example Output

============================================================
  2025-12-31
============================================================

[18:43:21] Instance A | Turn 47
  Query: refactor ppe routing tier collapse
  🔥 HOT: ppe-anticipatory-coherence.md, t3-telos.md
  🌡️  WARM: orin.md, pipeline.md
  ⬆️  Promoted to HOT: ppe-anticipatory-coherence.md
  ⬇️  Decayed to COLD: img-to-asus.md

[19:22:35] Instance A | Turn 48
  Query: what divergence dynamics?
  🔥 HOT: divergent.md, t3-telos.md, cvmp-transformer.md
  🌡️  WARM: pipeline.md, orin.md (+3 more)
  ⬆️  Promoted to HOT: divergent.md

Statistics View

python3 ~/.claude/scripts/history.py --stats --since 7d

╔══════════════════════════════════════════════════════════════╗
║                    ATTENTION STATISTICS                      ║
╚══════════════════════════════════════════════════════════════╝

Total turns: 342
Time range: 2025-12-24 to 2025-12-31

Instances: {'A': 156, 'B': 98, 'default': 88}

Most frequently HOT:
   87 turns: pipeline.md
   65 turns: t3-telos.md
   43 turns: orin.md
   38 turns: ppe-anticipatory-coherence.md
   22 turns: divergent.md

Most promoted to HOT:
   23 times: ppe-anticipatory-coherence.md
   18 times: divergent.md
   12 times: convergent.md

Busiest days:
  2025-12-30: 156 turns
  2025-12-29: 98 turns
  2025-12-28: 88 turns

Average context size: 18,420 chars

History Entry Structure

Each turn logs:

{
  "turn": 47,
  "timestamp": "2025-12-31T18:43:21Z",
  "instance_id": "A",
  "prompt_keywords": ["refactor", "ppe", "routing", "tier"],
  "activated": ["ppe-anticipatory-coherence.md"],
  "hot": ["ppe-anticipatory-coherence.md", "t3-telos.md"],
  "warm": ["orin.md", "pipeline.md"],
  "cold_count": 12,
  "transitions": {
    "to_hot": ["ppe-anticipatory-coherence.md"],
    "to_warm": ["orin.md"],
    "to_cold": ["img-to-asus.md"]
  },
  "total_chars": 18420
}

File: ~/.claude/attention_history.jsonl (append-only, one entry per turn)

Retention: 30 days (configurable in context-router-v2.py)

Architecture

claude-cognitive/
├── scripts/
│   ├── context-router-v2.py      # Attention dynamics + history logging
│   ├── history.py                # History viewer CLI (v1.1+)
│   ├── pool-auto-update.py       # Continuous pool updates
│   ├── pool-loader.py            # SessionStart injection
│   ├── pool-extractor.py         # Stop hook extraction
│   └── pool-query.py             # CLI query tool
│
├── templates/
│   ├── CLAUDE.md                 # Project context template
│   ├── systems/                  # Hardware/deployment
│   ├── modules/                  # Core systems
│   └── integrations/             # Cross-system communication
│
└── examples/
    ├── small-project/            # Simple example
    ├── monorepo/                 # Complex structure
    └── mirrorbot-sanitized/      # Real-world 50k+ line example

Hooks:

UserPromptSubmit: Context router + pool auto-update
SessionStart: Pool loader
Stop: Pool extractor (manual blocks)

State Files:

.claude/attn_state.json - Context router scores
.claude/pool/instance_state.jsonl - Pool entries

Strategy: Project-local first, ~/.claude/ fallback (monorepo-friendly)

Documentation

Concepts

Attention Decay - Why files fade
Context Tiers - HOT/WARM/COLD theory
Pool Coordination - Multi-instance patterns
Fractal Documentation - Infinite zoom strategy

Guides

Getting Started - First 15 minutes
Large Codebases - 50k+ lines
Team Setup - Multiple developers
Migration - Adding to existing project

Reference

Template Syntax - Markers and tags
Pool Protocol - Technical spec
Token Budgets - Optimization guide

Use Cases

Solo Developer - Large Codebase

Problem: 50k+ line Python project, Claude forgets architecture between sessions

Solution:

Context router keeps architecture docs HOT when mentioned
Token usage drops 79% (120K → 25K chars)
New sessions productive immediately

Team - Monorepo

Problem: 4 developers, each running Claude in different terminals, duplicate work

Solution:

Each dev sets CLAUDE_INSTANCE=A/B/C/D
Pool coordinator shares completions/blockers
Zero duplicate debugging

Long-Running Sessions

Problem: Keep Claude open for days, it forgets what happened 2 days ago

Solution:

Pool auto-updates write history continuously
Context router maintains attention across days
Temporal coherence preserved

Enterprise

Need multi-team coordination, compliance features, or custom setup?

Contact: gsutherland@mirrorethic.com

Services available:

Custom implementation for your codebase
Team training and onboarding
Integration with existing tooling
Priority support and SLA

Roadmap

v1.1 (Current - Production)

✅ Context router with attention dynamics
✅ Pool coordinator (auto + manual)
✅ Project-local strategy
✅ CLI query tools
✅ Attention history tracking (NEW in v1.1)
✅ History viewer CLI (NEW in v1.1)

v1.2 (Next)

Graph visualization of attention flow
Collision detection (multiple instances, same file HOT)
Nemotron compression for pool summaries
Semantic relevance (embeddings vs keywords)

v2.0 (Future)

Conflict detection (multiple instances, same file)
Action confirmations (critical operations)
Integration with ES-AC learning (context preferences)
Oracle prediction (which files to pre-load)
Exploring integration with other AI coding assistants (Gemini CLI, Cursor, Aider)

Credits

Built on production experience with:

1+ million lines of production Python code across 3,200+ modules
4-node distributed architecture (Legion, Orin, ASUS, Pi5)
8+ concurrent Claude Code instances in daily use

Created by:

Garret Sutherland, MirrorEthic LLC

License

MIT License - see LICENSE

Use it, modify it, ship it.

Contributing

Issues and PRs welcome!

Before submitting:

Check existing issues
For features: Open issue first to discuss
For bugs: Include context router + pool logs

Development:

# Test locally
cd ~/your-project
export CLAUDE_INSTANCE=TEST
claude

# Check logs
tail -f ~/.claude/context_injection.log
python3 ~/.claude/scripts/pool-query.py --since 10m

Questions? Open an issue

Updates? Watch the repo for releases