![\"npm](\"https://img.shields.io/npm/v/memory-os?style=flat-square&color=222\")
\n![\"License:](\"https://img.shields.io/badge/license-MIT-222?style=flat-square\"){kind=icon}
\n![\"Node\"](\"https://img.shields.io/badge/node-%3E%3D20-222?style=flat-square\"){kind=icon}
\n![\"MCP](\"https://img.shields.io/badge/MCP-compatible-222?style=flat-square\"){kind=icon}
\n\nYour Claude Code setup has 45 things that could be better. This finds them in 2 seconds.\n
\n\n\n
Open-source context engineering scanner for Claude Code
\n\nScores your Claude Code setup across 45 check layers and 3 dimensions. Returns adaptive reports with Context Engineering pattern mapping, prioritized fixes with time estimates, and an HTML dashboard. Free tools run locally with zero network calls. Paid tools unlock progress tracking, context analysis, conversation import, and AI-powered upgrades.\n\n---\n\n## Install\n\n### One command setup\n\n```bash\nnpx @iwo-szapar/second-brain-health-check setup\n```\n\nInteractive onboarding (~2 minutes):\n1. Asks for your API key (or skip for free tier)\n2. Configures the MCP server in Claude Code\n3. Asks about your role, experience, and goals\n4. Runs the first health check and opens the dashboard\n\n### Manual MCP setup\n\n```bash\nclaude mcp add second-brain-health-check -- npx @iwo-szapar/second-brain-health-check\n```\n\nThen ask Claude: \"Run a health check on my project.\"\n\n---\n\n## Tools\n\n### Free Tools\n\nNo API key required. Run locally, zero network calls.\n\n#### `check_health`\n\nFull 45-layer scan across setup quality, usage activity, and AI fluency. Adapts the report to your brain's maturity level.\n\n```\n> Run a health check\n\n> Check my setup health in quick mode\n\n> Run health check in Spanish\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `path` | current directory | Path to project root |\n| `mode` | `full` | `full` (45 layers), `quick` (~100ms detection only), `manifest` (full + YAML output) |\n| `language` | `en` | `en`, `es`, `de`, `fr`, `pl`, `pt`, `ja`, `ko`, `zh`, `it`, `nl`, `ru`, `tr`, `ar` |\n| `workspace_type` | -- | `solo`, `team`, `enterprise` |\n| `use_case` | -- | `development`, `content`, `operations`, `research`, `mixed` |\n\n#### `get_fix_suggestions`\n\nPrioritized action plan for your weakest area. Each fix includes a time estimate and point value.\n\n```\n> What should I fix first in my setup?\n\n> Give me fix suggestions focused on setup quality\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `path` | current directory | Path to project root |\n| `focus` | `auto` | `auto` (picks weakest), `setup`, `usage`, `fluency` |\n| `language` | `en` | Same as check_health |\n\n#### `generate_dashboard`\n\nSelf-contained HTML dashboard with score visualizations, CE radar chart, and guided fixes. Opens in your browser.\n\n```\n> Generate a health check dashboard\n\n> Generate dashboard and save to ~/reports/brain.html\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `path` | current directory | Path to project root |\n| `output` | `health-check-report.html` | Output file path |\n\n#### `generate_pdf`\n\nPDF report via headless Chrome. Requires Chrome or Chromium installed.\n\n```\n> Generate a PDF health check report\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `project_path` | *(required)* | Absolute path to project |\n\n---\n\n### Paid Tools\n\nRequire an API key. Set `SBF_TOKEN` in your environment or run `setup` to configure.\n\n#### `weekly_pulse`\n\nTrack progress over time. Shows score deltas, CE pattern trends, streak detection, and targeted suggestions.\n\n```\n> Show my weekly pulse\n\n> Show my progress over the last 30 days\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `period` | `since_last` | `since_last`, `7d`, `30d` |\n| `path` | current directory | Path to project root |\n\n#### `context_pressure`\n\nAnalyze how much of your 200K token context window is consumed by fixed overhead -- CLAUDE.md, MEMORY.md, knowledge files, MCP definitions, skills, hooks, and settings.\n\n```\n> Check my context pressure\n\n> How much of my context window am I using?\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `path` | current directory | Path to project root |\n\n#### `audit_config`\n\nAudit your configuration for dead references, conflicts, security issues, unused items, and performance problems.\n\n```\n> Audit my config\n\n> Run a security audit on my setup\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `path` | current directory | Path to project root |\n| `check_categories` | all 5 | `references`, `conflicts`, `security`, `unused`, `performance` |\n\n**What each category checks:**\n- **references** -- Dead file paths in CLAUDE.md, missing hook scripts\n- **conflicts** -- Duplicate CLAUDE.md files, overlapping MCP servers, unmatched hooks\n- **security** -- `.env` in `.gitignore`, API key patterns in config files, wildcard permissions\n- **unused** -- Skills with zero invocations in session logs\n- **performance** -- Oversized CLAUDE.md (>300 lines), MEMORY.md (>180 lines), too many MCP tools (>30)\n\n#### `import_context`\n\nImport conversation history from ChatGPT or Claude exports into organized memory files. Scan first to preview, then import to create files.\n\n```\n> Scan my ChatGPT export at ~/Downloads/conversations.json\n\n> Import my ChatGPT conversations, only coding-related ones from 2025\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `source_type` | *(required)* | `chatgpt_export` (conversations.json) or `claude_export` (directory) |\n| `source_path` | *(required)* | Path to export file or directory |\n| `mode` | `scan` | `scan` (preview only) or `import` (write files) |\n| `output_dir` | `memory/imported/` | Where to write imported files |\n| `max_conversations` | unlimited | Limit conversations processed |\n| `min_messages` | `3` | Skip short conversations |\n| `date_after` | -- | ISO date filter (e.g. `2024-01-01`) |\n| `date_before` | -- | ISO date filter |\n| `categories` | all | `coding`, `writing`, `research`, `planning`, `data`, `creative`, `operations` |\n| `merge_existing` | `false` | When true, writes to `memory/semantic/` instead |\n| `language` | `en` | Output language |\n\n#### `upgrade_brain`\n\nIdentify missing and outdated files in your setup and generate personalized upgrades. Runs health check and inventory locally, then calls the Factory API for template matching and personalization. Requires `UPGRADE_BRAIN_API_KEY`.\n\n```\n> Upgrade my brain\n\n> Show me what files I'm missing (dry run)\n\n> Upgrade brain, high impact only\n```\n\nParameters:\n\n| Parameter | Default | Options |\n|:----------|:--------|:--------|\n| `path` | current directory | Path to project root |\n| `high_only` | `false` | Only show HIGH impact files |\n| `category` | all | `agent`, `skill`, `memory`, `config`, `docs` |\n| `dry_run` | `false` | Preview the diff without applying |\n\n---\n\n## CLI\n\n```bash\n# First-time setup (interactive)\nnpx @iwo-szapar/second-brain-health-check setup\n\n# Run health check (prints report + opens dashboard)\nnpx @iwo-szapar/second-brain-health-check\n\n# Scan a specific directory\nnpx @iwo-szapar/second-brain-health-check /path/to/project\n\n# Text report only (no browser)\nnpx @iwo-szapar/second-brain-health-check --no-open\n\n# Generate PDF report\nnpx @iwo-szapar/second-brain-health-check --pdf\n```\n\n---\n\n## What It Measures\n\nThree dimensions. 45 check layers. ~459 raw points, normalized to /100 each.\n\n```\nSETUP QUALITY 32 layers ~284 pts\nA (85%+) | B (70%+) | C (50%+) | D (30%+) | F (<30%)\n\nUSAGE ACTIVITY 7 layers ~125 pts\nActive (85%+) | Growing (70%+) | Starting (50%+) | Dormant (30%+) | Empty (<30%)\n\nAI FLUENCY 6 layers ~60 pts\nExpert (85%+) | Proficient (70%+) | Developing (50%+) | Beginner (30%+) | Novice (<30%)\n```\n\n### Adaptive Reports\n\nReports shift based on brain maturity:\n\n| Brain State | Condition | Report Style |\n|:--|:--|:--|\n| **Empty** | No CLAUDE.md | 3-step getting-started guide (~20 min) |\n| **Minimal** | Small CLAUDE.md, no .claude/ | Growth mode: top 3 fixes, celebrates what exists |\n| **Basic** | CLAUDE.md + .claude/ | Growth mode |\n| **Structured** | Has skills or hooks or memory | Full report with all dimensions |\n| **Configured** | Has skills + hooks + memory | Full report with CE patterns |\n\n### Context Engineering Patterns\n\nAll 45 layers map to 7 CE patterns:\n\n| Pattern | What It Measures |\n|:--------|:-----------------|\n| Progressive Disclosure | CLAUDE.md layering, knowledge files, settings hierarchy |\n| Knowledge Files as RAM | Knowledge base architecture, directory structure |\n| Hooks as Guardrails | PreToolUse/PostToolUse hooks, rules system |\n| Three-Layer Memory | Episodic/semantic separation, session logs |\n| Compound Learning | Review loops, compound evidence, workflow maturity |\n| Self-Correction | Health infra, memory evolution, cross-references |\n| Context Surfaces | MCP servers, plugins, interaction config, context pressure |\n\n---\n\n## HTML Dashboard\n\n\n![\"Dashboard](\"assets/dashboard-score-panel.png\")
\n
\n![\"Dashboard](\"assets/dashboard-ce-patterns.png\")
\n
\n![\"Dashboard](\"assets/dashboard-setup-quality.png\")
\n
\n\n[MemoryOS](https://www.iwoszapar.com/memory-os) by [Iwo Szapar](https://www.iwoszapar.com). MIT License.\n\n
\n","readmeFilename":"README.md"}