{"id":35893247,"url":"https://github.com/GMaN1911/claude-cognitive","last_synced_at":"2026-01-15T19:00:47.007Z","repository":{"id":331156011,"uuid":"1125502812","full_name":"GMaN1911/claude-cognitive","owner":"GMaN1911","description":"Working memory for Claude Code - persistent context and multi-instance coordination","archived":false,"fork":false,"pushed_at":"2026-01-13T03:08:33.000Z","size":550,"stargazers_count":405,"open_issues_count":0,"forks_count":32,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-01-13T05:51:20.127Z","etag":null,"topics":["claude-ai","claude-code","context-management","developer-tools","productivity","token-optimization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GMaN1911.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T21:05:15.000Z","updated_at":"2026-01-13T03:06:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GMaN1911/claude-cognitive","commit_stats":null,"previous_names":["gman1911/claude-cognitive"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/GMaN1911/claude-cognitive","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GMaN1911%2Fclaude-cognitive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GMaN1911%2Fclaude-cognitive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GMaN1911%2Fclaude-cognitive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GMaN1911%2Fclaude-cognitive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GMaN1911","download_url":"https://codeload.github.com/GMaN1911/claude-cognitive/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GMaN1911%2Fclaude-cognitive/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28465783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T18:56:24.589Z","status":"ssl_error","status_checked_at":"2026-01-15T18:56:23.992Z","response_time":62,"last_error":"SSL_read: (null) (tls_retry_write_records failure)","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-ai","claude-code","context-management","developer-tools","productivity","token-optimization"],"created_at":"2026-01-09T11:00:36.028Z","updated_at":"2026-01-15T19:00:47.000Z","avatar_url":"https://github.com/GMaN1911.png","language":"Python","funding_links":[],"categories":["Python","Tools \u0026 Utilities"],"sub_categories":[],"readme":"# Claude Cognitive\n\n\u003e Working memory for Claude Code — persistent context and multi-instance coordination\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Status: Production](https://img.shields.io/badge/Status-Production-green.svg)]()\n\n---\n\n## The Problem\n\nClaude Code is powerful but stateless. Every new instance:\n- **Rediscovers** your codebase from scratch\n- **Hallucinates** integrations that don't exist\n- **Repeats** debugging you already tried\n- **Burns tokens** re-reading unchanged files\n\nWith large codebases (50k+ lines), this becomes painful fast.\n\n---\n\n## The Solution\n\n**Claude Cognitive** gives Claude Code working memory through two complementary systems:\n\n### 1. Context Router\n**Attention-based file injection** with cognitive dynamics:\n- **HOT** (\u003e0.8): Full file injection - active development\n- **WARM** (0.25-0.8): Headers only - background awareness\n- **COLD** (\u003c0.25): Evicted from context\n\nFiles **decay** when not mentioned, **activate** on keywords, and **co-activate** with related files.\n\n### 2. Pool Coordinator\n**Multi-instance state sharing** for long-running sessions:\n- **Automatic mode**: Detects completions/blockers from conversation (every 5min)\n- **Manual mode**: Explicit `pool` blocks for critical coordination\n- Works with persistent sessions (days/weeks), not just short bursts\n\n---\n\n## Results\n\n**Token Savings:**\n- Cold start: **79%** (120K → 25K chars)\n- Warm context: **70%** (80K → 24K chars)\n- Focused work: **75%** (60K → 15K chars)\n\n**Average: 64-95% depending on codebase size and work pattern.**\n\n**Developer Experience:**\n- ✅ New instances productive in **first message**\n- ✅ Zero hallucinated imports/integrations\n- ✅ No duplicate work across 8+ concurrent instances\n- ✅ Persistent memory across days-long sessions\n\n**Validated on:**\n- 1+ million line production codebase (3,200+ Python modules)\n- 4-node distributed architecture\n- 8 concurrent Claude Code instances\n- Multi-day persistent sessions\n\n---\n\n## Quick Start\n\n### 1. Install Scripts\n\n```bash\n# Clone to your home directory\ncd ~\ngit clone https://github.com/GMaN1911/claude-cognitive.git .claude-cognitive\n\n# Copy scripts\ncp -r .claude-cognitive/scripts ~/.claude/scripts/\n\n# Set up hooks (adds to existing config)\ncat .claude-cognitive/hooks-config.json \u003e\u003e ~/.claude/settings.json\n```\n\n\u003e **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).\n\n### 2. Initialize Your Project\n\n```bash\ncd /path/to/your/project\n\n# Create .claude directory\nmkdir -p .claude/{systems,modules,integrations,pool}\n\n# Copy templates\ncp -r ~/.claude-cognitive/templates/* .claude/\n\n# Edit .claude/CLAUDE.md with your project info\n# Edit .claude/systems/*.md to describe your architecture\n```\n\n### 3. Set Instance ID\n\n```bash\n# Add to ~/.bashrc for persistence:\nexport CLAUDE_INSTANCE=A\n\n# Or per-terminal:\nexport CLAUDE_INSTANCE=B\n```\n\n### 4. Verify It's Working\n\n```bash\n# Start Claude Code\nclaude\n\n# First message - check for context injection:\n# Should see: \"ATTENTION STATE [Turn 1]\" with HOT/WARM/COLD counts\n\n# Query pool activity:\npython3 ~/.claude/scripts/pool-query.py --since 1h\n```\n\n### 5. Create Keywords Config (Required)\n\nCreate `.claude/keywords.json` in your project root:\n\n```bash\ncp ~/.claude-cognitive/templates/keywords.json.example .claude/keywords.json\n```\n\nEdit to match your project's documentation files and relevant keywords.\n\n**Full setup guide:** [SETUP.md](./SETUP.md)\n**Customization guide:** [CUSTOMIZATION.md](./CUSTOMIZATION.md)\n\n---\n\n## Project Configuration\n\nCreate `.claude/keywords.json` in your project root to define project-specific keywords:\n\n```json\n{\n  \"keywords\": {\n    \"path/to/doc.md\": [\"keyword1\", \"keyword2\", \"phrase to match\"]\n  },\n  \"co_activation\": {\n    \"path/to/doc.md\": [\"related/doc.md\"]\n  },\n  \"pinned\": [\"always/warm/file.md\"]\n}\n```\n\n**Keywords:** Map documentation files to trigger words. When any keyword appears in your prompt (case-insensitive), the file becomes HOT.\n\n**Co-activation:** When a file activates, related files get a score boost.\n\n**Pinned:** Files that should always be at least WARM.\n\nThe router checks for config in this order:\n1. `.claude/keywords.json` (project-local)\n2. `~/.claude/keywords.json` (global fallback)\n3. Empty defaults (no activation)\n\n---\n\n## How It Works\n\n### Context Router\n\n**Attention Dynamics:**\n```\nUser mentions \"orin\" in message\n    ↓\nsystems/orin.md → score = 1.0 (HOT)\n    ↓\nCo-activation:\n  integrations/pipe-to-orin.md → +0.35 (WARM)\n  modules/t3-telos.md → +0.35 (WARM)\n    ↓\nNext turn (no mention):\n  systems/orin.md → 1.0 × 0.85 decay = 0.85 (still HOT)\n    ↓\n3 turns later (no mention):\n  systems/orin.md → 0.85 × 0.85 × 0.85 = 0.61 (now WARM)\n```\n\n**Injection:**\n- HOT files: Full content injected\n- WARM files: First 25 lines (headers) injected\n- COLD files: Not injected (evicted)\n\n### Pool Coordinator\n\n**Automatic Mode:**\n```\nInstance A completes task\n    ↓\nAuto-detector finds: \"Successfully deployed PPE to Orin\"\n    ↓\nWrites pool entry:\n  action: completed\n  topic: PPE deployment to Orin\n  affects: orin_sensory_cortex/\n    ↓\nInstance B starts session\n    ↓\nPool loader shows:\n  \"[A] completed: PPE deployment to Orin\"\n    ↓\nInstance B avoids duplicate work\n```\n\n**Manual Mode:**\n````markdown\n```pool\nINSTANCE: A\nACTION: completed\nTOPIC: Fixed authentication bug\nSUMMARY: Resolved race condition in token refresh. Added mutex.\nAFFECTS: auth.py, session_handler.py\nBLOCKS: Session management refactor can proceed\n```\n````\n\n---\n\n## History Tracking (v1.1+)\n\n**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.\n\n### Why This Matters\n\nThe router always computed attention scores. Now they persist as queryable history:\n- **Replay development trajectories** - \"How did we stabilize the PPE last week?\"\n- **Identify neglected modules** - \"Which files got ignored during the sprint?\"\n- **Debug attention behavior** - \"Why didn't convergent.md activate when I mentioned convergence?\"\n\n### View History\n\n```bash\n# Last 20 turns\npython3 ~/.claude/scripts/history.py\n\n# Last 2 hours\npython3 ~/.claude/scripts/history.py --since 2h\n\n# Filter by file pattern\npython3 ~/.claude/scripts/history.py --file ppe\n\n# Show only tier transitions\npython3 ~/.claude/scripts/history.py --transitions\n\n# Summary statistics\npython3 ~/.claude/scripts/history.py --stats\n\n# Filter by instance\npython3 ~/.claude/scripts/history.py --instance A\n```\n\n### Example Output\n\n```\n============================================================\n  2025-12-31\n============================================================\n\n[18:43:21] Instance A | Turn 47\n  Query: refactor ppe routing tier collapse\n  🔥 HOT: ppe-anticipatory-coherence.md, t3-telos.md\n  🌡️  WARM: orin.md, pipeline.md\n  ⬆️  Promoted to HOT: ppe-anticipatory-coherence.md\n  ⬇️  Decayed to COLD: img-to-asus.md\n\n[19:22:35] Instance A | Turn 48\n  Query: what divergence dynamics?\n  🔥 HOT: divergent.md, t3-telos.md, cvmp-transformer.md\n  🌡️  WARM: pipeline.md, orin.md (+3 more)\n  ⬆️  Promoted to HOT: divergent.md\n```\n\n### Statistics View\n\n```bash\npython3 ~/.claude/scripts/history.py --stats --since 7d\n```\n\n```\n╔══════════════════════════════════════════════════════════════╗\n║                    ATTENTION STATISTICS                      ║\n╚══════════════════════════════════════════════════════════════╝\n\nTotal turns: 342\nTime range: 2025-12-24 to 2025-12-31\n\nInstances: {'A': 156, 'B': 98, 'default': 88}\n\nMost frequently HOT:\n   87 turns: pipeline.md\n   65 turns: t3-telos.md\n   43 turns: orin.md\n   38 turns: ppe-anticipatory-coherence.md\n   22 turns: divergent.md\n\nMost promoted to HOT:\n   23 times: ppe-anticipatory-coherence.md\n   18 times: divergent.md\n   12 times: convergent.md\n\nBusiest days:\n  2025-12-30: 156 turns\n  2025-12-29: 98 turns\n  2025-12-28: 88 turns\n\nAverage context size: 18,420 chars\n```\n\n### History Entry Structure\n\nEach turn logs:\n```json\n{\n  \"turn\": 47,\n  \"timestamp\": \"2025-12-31T18:43:21Z\",\n  \"instance_id\": \"A\",\n  \"prompt_keywords\": [\"refactor\", \"ppe\", \"routing\", \"tier\"],\n  \"activated\": [\"ppe-anticipatory-coherence.md\"],\n  \"hot\": [\"ppe-anticipatory-coherence.md\", \"t3-telos.md\"],\n  \"warm\": [\"orin.md\", \"pipeline.md\"],\n  \"cold_count\": 12,\n  \"transitions\": {\n    \"to_hot\": [\"ppe-anticipatory-coherence.md\"],\n    \"to_warm\": [\"orin.md\"],\n    \"to_cold\": [\"img-to-asus.md\"]\n  },\n  \"total_chars\": 18420\n}\n```\n\n**File:** `~/.claude/attention_history.jsonl` (append-only, one entry per turn)\n\n**Retention:** 30 days (configurable in `context-router-v2.py`)\n\n---\n\n## Architecture\n\n```\nclaude-cognitive/\n├── scripts/\n│   ├── context-router-v2.py      # Attention dynamics + history logging\n│   ├── history.py                # History viewer CLI (v1.1+)\n│   ├── pool-auto-update.py       # Continuous pool updates\n│   ├── pool-loader.py            # SessionStart injection\n│   ├── pool-extractor.py         # Stop hook extraction\n│   └── pool-query.py             # CLI query tool\n│\n├── templates/\n│   ├── CLAUDE.md                 # Project context template\n│   ├── systems/                  # Hardware/deployment\n│   ├── modules/                  # Core systems\n│   └── integrations/             # Cross-system communication\n│\n└── examples/\n    ├── small-project/            # Simple example\n    ├── monorepo/                 # Complex structure\n    └── mirrorbot-sanitized/      # Real-world 50k+ line example\n```\n\n**Hooks:**\n- `UserPromptSubmit`: Context router + pool auto-update\n- `SessionStart`: Pool loader\n- `Stop`: Pool extractor (manual blocks)\n\n**State Files:**\n- `.claude/attn_state.json` - Context router scores\n- `.claude/pool/instance_state.jsonl` - Pool entries\n\n**Strategy:** Project-local first, `~/.claude/` fallback (monorepo-friendly)\n\n---\n\n## Documentation\n\n### Concepts\n- [Attention Decay](./docs/concepts/attention-decay.md) - Why files fade\n- [Context Tiers](./docs/concepts/context-tiers.md) - HOT/WARM/COLD theory\n- [Pool Coordination](./docs/concepts/pool-coordination.md) - Multi-instance patterns\n- [Fractal Documentation](./docs/concepts/fractal-docs.md) - Infinite zoom strategy\n\n### Guides\n- [Getting Started](./docs/guides/getting-started.md) - First 15 minutes\n- [Large Codebases](./docs/guides/large-codebases.md) - 50k+ lines\n- [Team Setup](./docs/guides/team-setup.md) - Multiple developers\n- [Migration](./docs/guides/migration.md) - Adding to existing project\n\n### Reference\n- [Template Syntax](./docs/reference/template-syntax.md) - Markers and tags\n- [Pool Protocol](./docs/reference/pool-protocol.md) - Technical spec\n- [Token Budgets](./docs/reference/token-budgets.md) - Optimization guide\n\n---\n\n## Use Cases\n\n### Solo Developer - Large Codebase\n**Problem:** 50k+ line Python project, Claude forgets architecture between sessions\n\n**Solution:**\n- Context router keeps architecture docs HOT when mentioned\n- Token usage drops 79% (120K → 25K chars)\n- New sessions productive immediately\n\n### Team - Monorepo\n**Problem:** 4 developers, each running Claude in different terminals, duplicate work\n\n**Solution:**\n- Each dev sets `CLAUDE_INSTANCE=A/B/C/D`\n- Pool coordinator shares completions/blockers\n- Zero duplicate debugging\n\n### Long-Running Sessions\n**Problem:** Keep Claude open for days, it forgets what happened 2 days ago\n\n**Solution:**\n- Pool auto-updates write history continuously\n- Context router maintains attention across days\n- Temporal coherence preserved\n\n---\n\n## Enterprise\n\nNeed multi-team coordination, compliance features, or custom setup?\n\n**Contact:** gsutherland@mirrorethic.com\n\n**Services available:**\n- Custom implementation for your codebase\n- Team training and onboarding\n- Integration with existing tooling\n- Priority support and SLA\n\n---\n\n## Roadmap\n\n**v1.1 (Current - Production)**\n- ✅ Context router with attention dynamics\n- ✅ Pool coordinator (auto + manual)\n- ✅ Project-local strategy\n- ✅ CLI query tools\n- ✅ **Attention history tracking** (NEW in v1.1)\n- ✅ **History viewer CLI** (NEW in v1.1)\n\n**v1.2 (Next)**\n- [ ] Graph visualization of attention flow\n- [ ] Collision detection (multiple instances, same file HOT)\n- [ ] Nemotron compression for pool summaries\n- [ ] Semantic relevance (embeddings vs keywords)\n\n**v2.0 (Future)**\n- [ ] Conflict detection (multiple instances, same file)\n- [ ] Action confirmations (critical operations)\n- [ ] Integration with ES-AC learning (context preferences)\n- [ ] Oracle prediction (which files to pre-load)\n- [ ] Exploring integration with other AI coding assistants (Gemini CLI, Cursor, Aider)\n\n---\n\n## Credits\n\n**Built on production experience with:**\n- 1+ million lines of production Python code across 3,200+ modules\n- 4-node distributed architecture (Legion, Orin, ASUS, Pi5)\n- 8+ concurrent Claude Code instances in daily use\n\n**Created by:**\n- Garret Sutherland, [MirrorEthic LLC](https://mirrorethic.com)\n\n\n---\n\n## License\n\nMIT License - see [LICENSE](./LICENSE)\n\n**Use it, modify it, ship it.**\n\n---\n\n## Contributing\n\nIssues and PRs welcome!\n\n**Before submitting:**\n1. Check [existing issues](https://github.com/GMaN1911/claude-cognitive/issues)\n2. For features: Open issue first to discuss\n3. For bugs: Include context router + pool logs\n\n**Development:**\n```bash\n# Test locally\ncd ~/your-project\nexport CLAUDE_INSTANCE=TEST\nclaude\n\n# Check logs\ntail -f ~/.claude/context_injection.log\npython3 ~/.claude/scripts/pool-query.py --since 10m\n```\n\n---\n\n**Questions?** Open an [issue](https://github.com/GMaN1911/claude-cognitive/issues)\n\n**Updates?** Watch the [repo](https://github.com/GMaN1911/claude-cognitive) for releases\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGMaN1911%2Fclaude-cognitive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGMaN1911%2Fclaude-cognitive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGMaN1911%2Fclaude-cognitive/lists"}