{
  "markdown": "# mind-glaive\n\n**Eliminate context rot in Claude Code with intelligent memory, auto-learning hooks, and specialized subagents.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Status: Production Ready](https://img.shields.io/badge/Status-Production%20Ready-green.svg)]()\n[![GitHub: TheGlitchKing/mind-glaive](https://img.shields.io/badge/GitHub-TheGlitchKing%2Fmind--glaive-blue)](https://github.com/TheGlitchKing/mind-glaive)\n\n## Overview\n\n**mind-glaive** is a production-ready Claude Code plugin that solves the context rot problem through an intelligent, multi-layered architecture that:\n\n- **Captures** knowledge automatically via hooks\n- **Distills** it efficiently using local LLM summaries\n- **Indexes** it semantically through MCP servers\n- **Retrieves** it contextually at session start\n- **Maintains** it proactively with subagents\n- **Learns** from patterns and corrections\n\n## The Problem: Context Rot\n\nContext rot occurs when:\n- Knowledge evaporates between sessions\n- You repeat the same explanations to Claude\n- Verbose output pollutes conversations\n- Critical decisions are forgotten\n- Patterns aren't recognized\n\n**Result**: Wasted tokens, slower development, repeated mistakes.\n\n## The Solution: 8-Layer Architecture\n\n### Layer 1: Intelligent Memory Hierarchy\n- **Project Memory** (`.claude/CLAUDE.md`) - Auto-updated with session learnings\n- **Modular Rules** (`.claude/rules/`) - Domain-specific, glob-activated guidelines\n- **Context Archives** - Historical summaries for knowledge retrieval\n\n### Layer 2: Context-Preserving Hooks\n- **SessionEnd Hook** - Captures and distills session knowledge\n- **SessionStart Hook** - Injects relevant context automatically\n- **PreToolUse Hook** - Delegates verbose operations to subagents\n- **PostToolUse Hook** - Learns from repeated corrections\n\n### Layer 3: Specialized Subagent Fleet\n- **context-cleaner** - Identifies and removes stale memory\n- **test-runner** - Isolates verbose test output\n- **doc-miner** - Discovers undocumented patterns from codebase\n\n### Layer 4: Auto-Updating Slash Commands\n- `/context/status` - Show context health metrics\n- `/context/optimize` - Run maintenance and cleanup\n- `/learn/from-session` - Extract patterns from current session\n- `/resume/last-task` - Continue from previous session\n\n### Layer 5: MCP Servers for External Knowledge\n- **project-kb** - Queryable knowledge base (SQLite)\n- **codebase-rag** - Semantic search over your codebase (local embeddings)\n\n### Layer 6: Automated Maintenance Skills\n- **context-maintenance** - Weekly cleanup and optimization\n- **pattern-learning** - Auto-generates rules from corrections\n\n### Layer 7: Intelligence Amplification\n- **Pattern Detection** - Learns from 3+ repeated corrections\n- **Auto-Rule Generation** - Creates `.claude/rules/` from patterns\n- **Decision Tracking** - Maintains history of architectural choices\n\n### Layer 8: Plugin Packaging & Distribution\n- **One-Command Install** - `./install.sh --scope user`\n- **Project Templates** - full-stack, data-science, minimal\n- **Multi-Scope Support** - User-global or project-local\n- **Auto-Updates** - Version checking and upgrade path\n\n## Quick Start\n### Via Claude Code Marketplace (Easiest - Recommended!)\n**Add the marketplace - run this command OUTSIDE of claude code**\n```\nclaude plugin marketplace add TheGlitchKing/mind-glaive\n```\n\n**For each collaborator (once from within a claude session):**\n```\nclaude plugin install mind-glaive@mind-glaive-marketplace\n```\n\n**For each project (once):**\n```\n/mind-glaive/setup\n```\n\nThat's it! 🎉 Hooks are now active. Run:\n```\n/context/status\n```\n\n### Via NPM (project-level)\n\n> **v1 → v2 breaking change**: the `mind-glaive install --scope user` flow was removed. Installation is now handled automatically by either the Claude Code plugin marketplace or npm's postinstall. See [CHANGELOG.md](./CHANGELOG.md) for migration details.\n\n```bash\nnpm install --save-dev @theglitchking/mind-glaive\n```\n\nPostinstall writes `.claude/mind-glaive.json` (update policy: `nudge`) and registers a SessionStart update-check hook in `.claude/settings.json` (skipped if the marketplace plugin is already enabled in `~/.claude/settings.json`).\n\n### Update management\n\nEvery install ships with an update policy. Default is `nudge` — one-liner notification at session start when a newer version is available, no automatic changes.\n\n```bash\nmind-glaive status          # installed / latest / policy / hook state\nmind-glaive policy auto     # auto-update on session start\nmind-glaive policy nudge    # one-liner nudge only (default)\nmind-glaive policy off      # silent\nmind-glaive update          # update now\n```\n\nSlash-command parity: `/mind-glaive:status`, `/mind-glaive:policy <mode>`, `/mind-glaive:update`, `/mind-glaive:relink`.\n\n## Installation Methods\n\n### Method 1: Via Claude Code Marketplace (Recommended - No Terminal Needed!)\n\n**Step 1: Install the plugin** (once per person, any Claude Code session)\n\n```\n/plugin install TheGlitchKing/mind-glaive\n```\n\n**Step 2: Setup project** (once per project, in the project's Claude Code session)\n\n```\n/mind-glaive/setup\n```\n\n**Step 3: Enable the plugin**\n\n```\n/plugin enable mind-glaive\n```\n\n**That's it!** 🎉 Hooks are now active in your project.\n\n**Verify it works:**\n\n```\n/context/status\n```\n\n**Optional: Choose a template** (default is minimal)\n\n```\n/mind-glaive/setup full-stack\n/mind-glaive/setup data-science\n```\n\n---\n\n### Method 2: Direct Install from GitHub (For Power Users)\n\nClone and install manually for more control:\n\n```bash\n# Clone the repository\ngit clone https://github.com/TheGlitchKing/mind-glaive.git\ncd mind-glaive\n\n# Install globally (shared by all projects)\n./install.sh --scope user --template full-stack\n\n# Or install for current project only\ncd /path/to/your/project\n/path/to/mind-glaive/install.sh --scope project --template minimal\n\n# Then enable the plugin\n/plugin enable mind-glaive\n/welcome\n```\n\n---\n\n### Method 3: Migrating from Marketplace to Direct Install\n\nIf you already installed via marketplace but want direct control:\n\n```bash\n# Keep the plugin installed\n# Just run the installer in your project\n/path/to/mind-glaive/install.sh --scope project --template minimal\n\n# Verify hooks are active\n/plugin enable mind-glaive\n/context/status\n```\n\n---\n\n### For Teams: Installing for All Collaborators\n\n**Have each team member do this (once per person):**\n\n```\n1. /plugin install TheGlitchKing/mind-glaive\n```\n\n**Then in the shared project, have one person do this (once per project):**\n\n```\n2. /mind-glaive/setup\n```\n\n**Commit `.claude/` to git so other team members pick up the config:**\n\n```bash\ngit add .claude/\ngit commit -m \"chore: initialize mind-glaive for project\"\ngit push\n```\n\n**Other team members just need to:**\n\n```\n1. /plugin install TheGlitchKing/mind-glaive\n2. git pull (to get .claude/ with hooks.json)\n3. /plugin enable mind-glaive\n4. /context/status (verify it's working)\n```\n\n---\n\n## ⚠️ IMPORTANT: .gitignore Configuration\n\nMind-glaive creates local files that should **NOT** be committed to your repository. Add this to your `.gitignore`:\n\n```gitignore\n# mind-glaive local context (keep out of version control)\n.claude/CLAUDE.md\n.claude/archives/\n.claude/context/\n```\n\n**What to commit (shared with team):**\n```gitignore\n.claude/hooks.json          # ✅ DO commit - shared hook config\n.claude/rules/              # ✅ DO commit - shared rules\n.claude/commands/           # ✅ DO commit - shared commands\n.claude/agents/             # ✅ DO commit - shared agents\n.claude/skills/             # ✅ DO commit - shared skills\n```\n\n**What NOT to commit (local only):**\n```gitignore\n.claude/CLAUDE.md           # ❌ Local context, changes per session\n.claude/archives/           # ❌ Historical data, local summaries\n.claude/context/            # ❌ Session-specific context\n.claude/scripts/            # ❌ Generated scripts (auto-created)\n```\n\n**Why?** Each team member's `CLAUDE.md` reflects their own session history and learnings. Sharing these would cause conflicts and lose individual context. The hook config and rules are meant to be shared; the context is personal.\n\n**Recommended .gitignore entry:**\n```gitignore\n# mind-glaive - keep local context out of version control\n.claude/CLAUDE.md\n.claude/archives/\n.claude/context/\n.claude/scripts/\n```\n\n---\n\n## Updates & Maintenance\n\n### Automatic Updates\n\nIf you installed via the Claude Code marketplace, the plugin **automatically checks for updates at startup**:\n\n- ✅ New versions install automatically\n- 📢 You'll see a notification suggesting you restart Claude Code\n- 🔄 Just restart to apply the latest features and fixes\n\n### Manual Updates\n\nTo manually update to the latest version:\n\n**Via Marketplace:**\n```\n/plugin uninstall mind-glaive@mind-glaive-marketplace\n/plugin install mind-glaive\n```\n\n**Via Direct Install:**\n```bash\ncd mind-glaive\ngit pull origin main\n./install.sh --scope user --template full-stack\n```\n\n### What's New\n\nCheck the [GitHub releases](https://github.com/TheGlitchKing/mind-glaive/releases) for what's included in each version:\n\n- New features and improvements\n- Bug fixes\n- New hook capabilities (e.g., PreCompact hook for context preservation during compaction)\n- Enhanced documentation\n\n### Breaking Changes\n\nWe follow semantic versioning (MAJOR.MINOR.PATCH). Breaking changes only occur in major version updates and are documented in release notes.\n\n**Current Version**: 1.0.0 ✅\n\n## Project Templates\n\nChoose a template during installation:\n\n### Full-Stack\nOptimized for web applications with backend/frontend/database patterns.\n```bash\n./install.sh --template full-stack\n```\n\n### Data Science\nConfigured for notebooks, experiments, and model training.\n```bash\n./install.sh --template data-science\n```\n\n### Minimal\nLightweight setup for small projects or learning.\n```bash\n./install.sh --template minimal\n```\n\n## How It Works\n\n### Automatic Knowledge Capture (SessionEnd Hook)\n```bash\n# When you end a session, the hook runs:\n1. Analyzes session transcript\n2. Extracts key decisions, patterns, learnings\n3. Updates CLAUDE.md automatically\n4. Archives to knowledge base\n```\n\n### Smart Context Injection (SessionStart Hook)\n```bash\n# When you start a new session:\n1. Checks current git branch\n2. Loads branch-specific context\n3. Injects recently modified file rules\n4. Adds relevant historical decisions\n```\n\n### Verbose Output Isolation (PreToolUse Hook)\n```bash\n# Before running noisy commands:\n1. Detects verbose operations (tests, logs, builds)\n2. Delegates to isolated subagent\n3. Receives only summarized results\n4. Main context stays clean\n```\n\n## Configuration\n\n### Settings File (`.claude/settings.json`)\n```json\n{\n  \"hooks\": {\n    \"SessionEnd\": [...],\n    \"SessionStart\": [...],\n    \"PreToolUse\": [...]\n  }\n}\n```\n\n### Project Memory (`.claude/CLAUDE.md`)\n```markdown\n---\nlast_updated: 2026-01-09T15:30:00Z\nsession_count: 47\nauto_maintenance: enabled\n---\n\n# Project Context\n\n## Current Focus\n- Working on: User authentication\n- Blocked by: Database migration pending\n\n## Critical Decisions\n- 2026-01-08: Chose PostgreSQL RLS over app-level auth\n\n## Common Patterns\n- Always use asyncpg not psycopg2\n- API endpoints must include rate limiting\n```\n\n### Modular Rules (`.claude/rules/`)\n```\n.claude/rules/\n├── backend/\n│   ├── api-standards.md      # Applied to backend/app/api/**\n│   └── database-patterns.md  # Applied to backend/migrations/**\n└── frontend/\n    └── component-structure.md # Applied to frontend/src/components/**\n```\n\n## Success Metrics\n\nTrack context health with `/context/status`:\n\n| Metric | Target | Description |\n|--------|--------|-------------|\n| Avg context size | < 50KB | Per session memory usage |\n| Repeated clarifications | < 2/session | Knowledge retention |\n| Knowledge retention | > 90% | Cross-session recall |\n| Sessions using history | > 70% | Context reuse rate |\n| Manual searches | < 5/week | Auto-retrieval success |\n\n## Architecture Principles\n\n1. **Privacy-First**: Local LLM (Ollama) for summaries, no external API calls required\n2. **Opt-In Intelligence**: Start minimal, learn over time\n3. **Transparent Operations**: All hooks show what they're doing\n4. **Clean Uninstall**: Remove cleanly without data loss\n5. **Version Control Friendly**: Project configs in `.claude/`, user configs in `~/.claude/`\n\n## Documentation\n\n- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Deep dive into system design\n- **[INSTALLATION.md](INSTALLATION.md)** - Detailed installation guide\n- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Contributing and development\n- **[ROADMAP.md](ROADMAP.md)** - Implementation timeline\n- **[DISTRIBUTION.md](DISTRIBUTION.md)** - Marketplace strategy\n- **[docs/](docs/)** - Layer-by-layer documentation\n\n## Requirements\n\n### Minimum\n- Claude Code v1.0+\n- Python 3.9+\n- Git 2.0+\n- Bash (for hooks)\n\n### Recommended\n- Ollama (for local LLM summaries, privacy-first)\n- 10GB disk space (for knowledge base + embeddings)\n\n### Optional\n- Docker (for MCP server isolation)\n- PostgreSQL (for advanced knowledge graphs)\n\n## Development Status\n\n- [x] Architecture design\n- [x] Documentation structure\n- [ ] Layer 1: Memory Hierarchy\n- [ ] Layer 2: Hooks System\n- [ ] Layer 3: Subagents\n- [ ] Layer 4: Slash Commands\n- [ ] Layer 5: MCP Servers\n- [ ] Layer 6: Skills\n- [ ] Layer 7: Intelligence\n- [ ] Layer 8: Distribution\n- [ ] v1.0.0 Release\n\n## Contributing\n\nContributions welcome! See [DEVELOPMENT.md](DEVELOPMENT.md) for guidelines.\n\n1. Fork the repository\n2. Create feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit changes (`git commit -m 'Add amazing feature'`)\n4. Push to branch (`git push origin feature/amazing-feature`)\n5. Open Pull Request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: https://github.com/yourusername/context-preservation-system/issues\n- **Discussions**: https://github.com/yourusername/context-preservation-system/discussions\n- **Email**: your-email@example.com\n\n## Acknowledgments\n\nInspired by the Claude Code community's need for better context management.\n\nBuilt with:\n- Claude Code (Anthropic)\n- Ollama (local LLM)\n- Python + Bash\n\n## Roadmap\n\n### v1.0.0 (Target: February 2026)\n- Core 8-layer system\n- 3 project templates\n- Full documentation\n- Installer + tests\n\n### v1.1.0 (Target: March 2026)\n- Web dashboard for knowledge base\n- Visual context health monitoring\n- Team sync features\n\n### v2.0.0 (Target: Q2 2026)\n- Cloud backup/sync (optional)\n- Advanced pattern recognition\n- Cross-project knowledge sharing\n\n---\n\n**Star this repo if it helps you eliminate context rot!** ⭐\n",
  "bytes": 14602,
  "sha": "ec51df7967f8c0fe7465a8de3e05f6cd0a19bac5d3d3a8562fa59dea7bbbcbf0",
  "repo_slug": "theglitchking/mind-glaive",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_theglitchking_mind_glaive_mind_glaive_4d64ba99/readme"
}