{
  "markdown": "# Claude_Meister\n\n**Intelligence Runtime for Claude Code**\n\nClaude_Meister is a lightweight runtime layer that makes Claude Code smarter, cheaper, and faster — without changing how you use it. It installs in under two minutes and works silently in the background from that point on.\n\n---\n\n## New in v2: `meister` — cross-tool conversation memory\n\nThe same conversation memory, available from Claude Code, Cursor, Codex, Aider, or your shell. Captures every turn into a repo-local `.repo_memory/conversation.jsonl`, then surfaces it back with **layered retrieval** — so recall costs ~50 tokens, not 5,000.\n\n**30-second demo:**\n\n```bash\n# One-time install (makes the `meister` command globally available)\ngit clone https://github.com/Mintsolester/claude-meister\ncd claude-meister && pip install -e .\n\n# Wire the capture hooks + statusLine + SessionStart injection\nmeister install-hooks\n\n# ...work in Claude Code as usual. Hooks silently capture every turn,\n# and the new session footer shows live capture state in real time.\n\n# Next day, in any repo:\n$ meister last\nLast 1 session(s) in ~/your-repo:\n\n  s_1715692800  2026-05-14 18:42  events=12  tools=[Edit:5,Bash:3,Read:4]\n                files: db/repository.py, tests/test_repo.py\n                title: fix the dedup bug in batch_insert_personas\n\n# Find a past session by topic:\n$ meister recall \"auth middleware\"\n# Drill in:\n$ meister show s_1715692800\n\n# Verify everything works on your machine:\n$ meister test\n```\n\n**Why this is different from CLAUDE.md or built-in memory:**\n\n- **Platform-agnostic.** Same `.repo_memory/` works whether you used Claude Code, Cursor, or a shell-only client. Your memory follows the repo, not the tool.\n- **Layered retrieval (L0 → L1 → L2).** Default recall returns one-line session titles. Drill in only when you need the detail. The recall cost stays bounded as your history grows.\n- **Repo-local.** The log lives in `your-repo/.repo_memory/`. Commit it, gitignore it, sync it with the repo — your call.\n- **Zero embedding install.** Pure TF-IDF over events. No vector DB, no model download, no daemon. ~400 LOC. Upgrade to embedded recall later via the MCP server if you want.\n- **Fails open.** Capture hooks swallow all errors. They never block your tool calls.\n\nFull reference: [`docs/MEISTER_CLI.md`](docs/MEISTER_CLI.md).\n\n---\n\n## Before / After\n\n| Scenario | Without Claude_Meister | With Claude_Meister | Difference |\n|---|---|---|---|\n| Typo fix — tokens loaded into context | ~1,400 (full CLAUDE.md always loaded) | ~847 (slim baseline only) | **-40% context overhead** |\n| Typo fix — extra runtime cost | 0 (paid full CLAUDE.md cost regardless) | 0 (LIGHT mode, runtime skipped entirely) | Same task, cheaper |\n| Moderate refactor — context | 1,400 (no routing, same cost every time) | 847 + ~800 (targeted context loaded) | Only loads what's needed |\n| Complex feature — memory | Manual, no scoring, often too much retrieved | Scored, ranked, 500-token cap enforced | Controlled, relevant memory |\n| Architectural task — finding tools | Manual directory search, minutes | `tool_loader.py` ranked matches, seconds | Seconds vs. minutes |\n\n> **What is a \"token\"?** A token is roughly 3/4 of a word. Claude Code has a \"context window\" (a limit on how much text it can consider at once). Every token loaded costs money and uses up that window. Claude_Meister keeps that number low.\n\n---\n\n## Table of Contents\n\n1. [Why Claude_Meister?](#why-claude_meister)\n2. [Quick Start](#quick-start)\n3. [Plugin Install and Distribution](#plugin-install-and-distribution)\n4. [Detailed Installation Guide](#detailed-installation-guide)\n5. [How It Works](#how-it-works)\n6. [Example Walkthroughs](#example-walkthroughs)\n7. [Configuration](#configuration)\n8. [Commands Reference](#commands-reference)\n9. [Updating](#updating)\n10. [Uninstalling](#uninstalling)\n11. [Troubleshooting](#troubleshooting)\n12. [FAQ](#faq)\n13. [Contributing](#contributing)\n14. [License & Credits](#license--credits)\n\n---\n\n## Why Claude_Meister?\n\n### The Problem\n\nClaude Code loads its instruction file (`~/.claude/CLAUDE.md`) at the start of every single conversation — a typo fix and a full architectural redesign both pay the same context cost. There is no built-in way to load only what a task actually needs.\n\nOn top of that:\n- Memory must be managed manually. There is no built-in way to score, rank, or cap retrieved memories.\n- Finding the right tool script in a large project requires manual search.\n- Nothing tracks which mode Claude is operating in or whether the context spend was worthwhile.\n\n### The Solution\n\nClaude_Meister installs three things:\n\n1. **Runtime engine** (`~/.claude_runtime/`) — a set of behavioral documents and controller scripts. The router reads your task, classifies its complexity, and loads only the context that complexity warrants.\n2. **Memory server** (`~/.claude_memory/`) — an MCP (Model Context Protocol — a standard way for tools to communicate with Claude Code) server that stores, scores, and retrieves memories automatically.\n3. **Wiki knowledge base** (`~/.claude_wiki/`) — optional offline documentation that Claude can query without an internet connection.\n\nYour `~/.claude/CLAUDE.md` gets a small block appended that teaches Claude how to invoke the runtime. That is the only change to any file you already have.\n\n### Results\n\nRunning `python install.py --stats` shows your own data:\n\n```\nClaude_Meister Usage Report (last 30 days)\n-------------------------------------------\nTasks logged:           47\nMode distribution:      LIGHT 62% | STANDARD 30% | DEEP 8%\nAvg memory tokens:      287 / 500 cap\nTasks with memory:      14 (30%)\nTasks skipping runtime: 29 (62%)  <-- saved ~600 tokens each\n\nEstimated savings:      ~17,400 tokens saved by LIGHT mode skipping runtime\n```\n\n---\n\n## Quick Start\n\nIf you are comfortable with the command line and just want to get started:\n\n```bash\n# 1. Clone the repo\ngit clone https://github.com/Mintsolester/claude-meister.git\ncd claude-meister\n\n# 2. Run the installer\npython install.py --full\n\n# 3. Verify everything installed correctly\npython install.py --verify\n```\n\nThen restart Claude Code. That is it.\n\nNot sure what any of those commands mean? Read the [Detailed Installation Guide](#detailed-installation-guide) below — it walks through every step with screenshots and expected output.\n\n---\n\n## Plugin Install and Distribution\n\nIf you want to use Claude_Meister as a plugin through Claude Code marketplaces:\n\n```bash\n# 1. Add this repository as a marketplace\nclaude plugin marketplace add Mintsolester/claude-meister\n\n# 2. Install the plugin from this marketplace\nclaude plugin install claude-meister@claude-meister-marketplace\n```\n\nFor local plugin development and testing without marketplace install:\n\n```bash\nclaude --plugin-dir ./plugins/claude-meister\n```\n\nBefore publishing plugin changes, run validation locally:\n\n```bash\nclaude plugin validate .\nclaude plugin validate plugins/claude-meister\n```\n\nFor official public listing, submit the plugin using Claude.ai or Console plugin submission forms.\n\n---\n\n## Detailed Installation Guide\n\n### What You Need First (Prerequisites)\n\nBefore installing Claude_Meister, you need three things on your computer. Here is how to check each one.\n\n#### 1. Python 3.8 or newer\n\n**What is Python?** Python is a programming language. Claude_Meister is written in Python, so Python must be installed to run it.\n\nOpen a terminal:\n- **Windows:** Press `Win + R`, type `cmd`, press Enter\n- **macOS:** Press `Cmd + Space`, type `Terminal`, press Enter\n- **Linux / WSL:** Open your terminal application\n\nType this and press Enter:\n\n```\npython --version\n```\n\nYou should see something like:\n\n```\nPython 3.11.4\n```\n\nAs long as the number is 3.8 or higher, you are good. If you see `Python 2.x` or an error, [download Python from python.org](https://www.python.org/downloads/) and install it. On macOS/Linux you may need `python3 --version` instead.\n\n> **If you see an error:** Python is not installed or not on your PATH (the list of places your computer looks for programs). Download it from python.org and run the installer. On Windows, check \"Add Python to PATH\" during installation.\n\n#### 2. Two Python packages: `mcp` and `fastmcp`\n\nThese packages enable the memory server. Install them by running:\n\n```\npip install mcp fastmcp\n```\n\nExpected output (abbreviated):\n\n```\nCollecting mcp\n  Downloading mcp-...\nCollecting fastmcp\n  Downloading fastmcp-...\nSuccessfully installed mcp-... fastmcp-...\n```\n\n> **If pip is not found:** Try `pip3 install mcp fastmcp` on macOS/Linux. On Windows, try `python -m pip install mcp fastmcp`.\n\n#### 3. Claude Code CLI\n\nClaude_Meister registers its memory server with Claude Code during installation. The `claude` command must be available.\n\nTest it:\n\n```\nclaude --version\n```\n\nExpected output:\n\n```\nclaude/1.x.x\n```\n\nIf you see an error, install Claude Code from [claude.ai/code](https://claude.ai/code) and follow its setup instructions before continuing.\n\n---\n\n### Step-by-Step Installation\n\n#### Step 1: Get the files\n\nIf you have Git installed:\n\n```bash\ngit clone https://github.com/Mintsolester/claude-meister.git\ncd claude-meister\n```\n\nIf you do not have Git, download the ZIP from the GitHub page, unzip it, and open a terminal in that folder.\n\n#### Step 2: Run the installer\n\n```bash\npython install.py --full\n```\n\nThe installer will work through these stages. Here is what to expect:\n\n```\nClaude_Meister Installer\n========================\n[1/7] Checking Python version...          OK  (Python 3.11.4)\n[2/7] Checking dependencies (mcp, fastmcp)... OK\n[3/7] Installing runtime engine to ~/.claude_runtime/...  OK\n[4/7] Installing memory server to ~/.claude_memory/...    OK\n[5/7] Installing wiki knowledge base to ~/.claude_wiki/... OK\n[6/7] Updating ~/.claude/CLAUDE.md...     OK  (block appended)\n[7/7] Registering MCP memory server...    OK  (registered as \"memory\")\n\nInstallation complete. Restart Claude Code to activate.\n```\n\n> **If you see \"Claude Code not found\" at step 7:** Make sure `claude --version` works in your terminal, then re-run the installer. The `claude mcp add` command requires the CLI to be on your PATH.\n\n> **If you see \"Permission denied\":** On macOS/Linux, you may need to prefix with `sudo`. On Windows, run Command Prompt as Administrator.\n\n> **If you see a message about an existing installation:** The installer will ask whether to update, do a clean reinstall, or abort. Choose \"update\" to preserve your memories and logs.\n\n#### Step 3: Verify the installation\n\n```bash\npython install.py --verify\n```\n\nExpected output:\n\n```\nVerification Results\n====================\nRuntime engine:      PASS  (~/.claude_runtime/ present, 4 core files found)\nMemory server:       PASS  (~/.claude_memory/ present, index.json OK)\nWiki knowledge base: PASS  (~/.claude_wiki/ present, index.md found)\nCLAUDE.md block:     PASS  (markers found, paths correctly substituted)\nMCP registration:    PASS  (\"memory\" server registered with Claude Code)\n\nAll checks passed. You are ready to go.\n```\n\nIf any check shows FAIL, see the [Troubleshooting](#troubleshooting) section for that specific failure.\n\n#### Step 4: Restart Claude Code\n\nClose all Claude Code windows and reopen. The memory server only becomes available to Claude after a fresh session start.\n\n#### Step 5: Your first interaction\n\nOpen Claude Code in any project and type something. Nothing looks different — Claude_Meister works silently. Behind the scenes, your task has been classified, the right amount of context was loaded, and Claude is operating in the appropriate mode.\n\nTo confirm it is running, ask Claude directly:\n\n```\nWhat mode are you operating in right now?\n```\n\nClaude will respond with something like:\n\n```\nLIGHT mode — this is a simple question, so I'm not loading the full runtime. \nNo extra context cost.\n```\n\n---\n\n## How It Works\n\n### The Three Modes\n\nEvery conversation starts with a silent classification step. Claude reads your request, determines its complexity, and selects one of three operating modes:\n\n| Mode | When it activates | What gets loaded | Memory | Response style |\n|---|---|---|---|---|\n| **LIGHT** | Trivial / Simple tasks | Nothing beyond CLAUDE.md baseline | Skipped | Under 200 words |\n| **STANDARD** | Moderate tasks | `context_router.md` + targeted files | Retrieve only (500-token cap) | Proportional |\n| **DEEP** | Complex / Architectural | Full router + all relevant files | Retrieve + store + evolve | Thorough |\n\n**LIGHT mode is the key innovation.** Most interactions — quick edits, questions, small fixes — are simple. LIGHT mode ensures these never pay extra context cost. The runtime files stay on disk, unread.\n\n### Architecture Diagram\n\n```\nYour message\n     │\n     ▼\n┌─────────────────────────────────┐\n│  CLAUDE.md baseline             │  ← Always loaded (slim)\n│  (Mode selector instructions)   │\n└─────────────────┬───────────────┘\n                  │\n         Classify complexity\n                  │\n         ┌────────┴────────┐\n         │                 │\n    LIGHT / SIMPLE    MODERATE or higher\n         │                 │\n         ▼                 ▼\n   Direct response   Read context_router.md\n                          │\n                    Load targeted context\n                          │\n                    Retrieve memories (≤500 tok)\n                          │\n                    Discover tools if needed\n                          │\n                     Execute + respond\n```\n\n### The Memory System\n\n**What is it?** The memory system gives Claude a long-term memory that persists across sessions. When you work on a project today, key facts are stored. Tomorrow, they are retrieved automatically.\n\n**How memories are scored:**\n\nEach memory gets a composite score when retrieved:\n\n```\nscore = (relevance × 0.4 + recency × 0.25 + frequency × 0.15 + success_rate × 0.2)\n        × (1 − decay_factor)\n```\n\nOnly the highest-scoring memories within the 500-token budget are passed to Claude. This keeps context lean while ensuring the most useful memories surface.\n\n**Storage location:** `~/.claude_memory/` — one JSON file per memory entry, plus `index.json` for fast lookup.\n\n**Memory tools available to Claude:**\n\n| Tool | What it does |\n|---|---|\n| `memory_retrieve` | Query memories by keyword + project, returns scored results |\n| `memory_store` | Save a new memory with metadata |\n| `memory_evolve` | Update an existing memory when new evidence arrives |\n| `memory_debate` | Compare contradictory memories, keep the stronger one |\n| `memory_cleanup` | Remove stale or low-scoring entries |\n| `memory_status` | Report memory system health and stats |\n\n### Runtime File Locations\n\nAfter installation, files live here:\n\n```\n~/.claude_runtime/\n├── configs/\n│   └── runtime_config.json      # Your configuration\n├── controllers/\n│   ├── tool_loader.py            # Discovers tools by keyword\n│   ├── usage_logger.py           # Logs task stats\n│   ├── memory_controller.py      # Direct memory access (no MCP needed)\n│   └── mcp_router.py             # Routes memory queries\n├── core/\n│   ├── context_router.md         # Main routing logic\n│   ├── mode_selector.md          # Mode classification rules\n│   ├── skill_router.md           # Skill discovery\n│   └── token_budget.md           # Budget enforcement rules\n├── hooks/                        # Event hooks\n├── injector/                     # Context injection\n└── logs/\n    └── runtime_usage.json        # Usage history\n\n~/.claude_memory/\n├── index.json                    # Fast-lookup index\n└── server/                       # MCP server modules\n\n~/.claude_wiki/                   # Offline documentation\n```\n\n---\n\n## Example Walkthroughs\n\n### Walkthrough 1: \"Fix a typo\"\n\n**Your message:** `There's a typo in line 42 of README.md — \"recieve\" should be \"receive\"`\n\n**Internal flow:**\n\n```\n1. Classify: Trivial (single word, single file)\n2. Mode selected: LIGHT\n3. Context loaded: CLAUDE.md baseline only (~847 tokens)\n4. Memory: skipped\n5. Tools: skipped\n6. Action: read line 42, apply fix\n```\n\n**Response:** Claude opens the file, fixes the typo, confirms the change. No extra context was loaded. Token cost: minimal.\n\n**What Claude says if you ask:** `\"LIGHT mode — trivial fix, zero runtime overhead.\"`\n\n---\n\n### Walkthrough 2: \"Refactor the auth module\"\n\n**Your message:** `The auth module is getting messy. Refactor it to separate concerns — auth logic, token handling, and session management should be in their own files.`\n\n**Internal flow:**\n\n```\n1. Classify: Complex (multi-file, architectural judgment needed)\n2. Mode selected: DEEP\n3. Context loaded: CLAUDE.md baseline + context_router.md + relevant architecture files\n4. Memory: retrieve memories tagged \"auth\" or this project (scored, ≤500 tokens)\n5. Tools: tool_loader.py scans for any existing auth-related scripts\n6. Plan: break into subtasks, propose file structure\n7. Execute: read current module, write three new files, update imports\n```\n\n**Response:** Claude reads the existing module, retrieves any prior context about the project's conventions, proposes the new structure, and executes each file change with explanation.\n\n**After the session:** The refactoring approach is stored as a memory, scored for relevance and success. Next time you ask about auth, it surfaces automatically.\n\n---\n\n### Walkthrough 3: \"Continue what we did yesterday\"\n\n**Your message:** `Let's continue the database migration we started yesterday.`\n\n**Internal flow:**\n\n```\n1. Classify: Moderate (continuation task, memory keyword detected: \"yesterday\")\n2. Mode selected: STANDARD\n3. Context loaded: CLAUDE.md baseline + context_router.md\n4. Memory: retrieve — keywords \"database migration\" + current repo\n   Scores: migration_plan.json (0.91), schema_notes.json (0.78), unrelated (0.32 — excluded)\n   Total retrieved: 312 tokens (within 500-token cap)\n5. Claude reads the retrieved memories\n6. Responds with full context of what was done and what comes next\n```\n\n**Response:** Claude accurately recalls the migration plan, the tables already processed, and the next step — without you having to re-explain anything.\n\n**What makes this work:** The 0.32-scored memory was excluded because it scored below the relevance threshold. Only the two high-confidence memories were included, keeping context tight.\n\n---\n\n## Configuration\n\nYour configuration lives at `~/.claude_runtime/configs/runtime_config.json`. After installation it looks like this (paths shown for each platform):\n\n```json\n{\n  \"version\": \"1.0\",\n  \"runtime_path\": \"C:/Users/yourname/.claude_runtime\",\n  \"memory_root\": \"C:/Users/yourname/.claude_memory\",\n  \"memory_server_modules\": \"C:/Users/yourname/.claude_memory/server\",\n  \"tools_dirs\": [],\n  \"wiki_path\": \"\",\n  \"defaults\": {\n    \"memory_max_tokens\": 500,\n    \"mode\": \"STANDARD\",\n    \"log_usage\": true\n  }\n}\n```\n\n> On macOS/Linux, paths use `/home/yourname/` or `/Users/yourname/` instead of `C:/Users/yourname/`. The installer fills these in automatically.\n\n### Field Reference\n\n| Field | Type | What it does |\n|---|---|---|\n| `version` | string | Config schema version. Do not change. |\n| `runtime_path` | string | Where the runtime engine is installed. Auto-set by installer. |\n| `memory_root` | string | Root directory for the memory system. Auto-set by installer. |\n| `memory_server_modules` | string | Path to MCP server code. Auto-derived from `memory_root`. |\n| `tools_dirs` | list of strings | Directories Claude searches when looking for tool scripts. |\n| `wiki_path` | string | Path to an additional wiki directory (if you have one). |\n| `defaults.memory_max_tokens` | integer | Maximum tokens the memory system can inject per session. Default: 500. |\n| `defaults.mode` | string | Default mode if classification is ambiguous. Options: `LIGHT`, `STANDARD`, `DEEP`. |\n| `defaults.log_usage` | boolean | Whether to log task usage to `runtime_usage.json`. Default: true. |\n\n### Adding Your Own Tool Directories\n\nIf you have a `tools/` folder in your project, add it to `tools_dirs` so Claude can discover scripts by keyword:\n\n```json\n{\n  \"tools_dirs\": [\n    \"/home/yourname/my-project/tools\",\n    \"/home/yourname/shared-scripts\"\n  ]\n}\n```\n\nAfter saving, Claude can run:\n\n```\npython ~/.claude_runtime/controllers/tool_loader.py --query \"scrape\"\n```\n\nAnd get back a ranked list of matching scripts from your directories.\n\n### Adding a Wiki Knowledge Base\n\nIf you have a folder of Markdown documentation you want Claude to query:\n\n```json\n{\n  \"wiki_path\": \"/home/yourname/my-notes/wiki\"\n}\n```\n\nThe wiki system expects an `index.md` file in that directory. Claude will use the index to find relevant pages before reading them.\n\n### Adjusting the Memory Budget\n\nTo increase the token cap for memory retrieval (useful for complex projects with rich history):\n\n```json\n{\n  \"defaults\": {\n    \"memory_max_tokens\": 800\n  }\n}\n```\n\nKeep in mind that higher budgets mean more context used per session. The default of 500 is calibrated to balance recall quality against cost.\n\n### Disabling Usage Logging\n\n```json\n{\n  \"defaults\": {\n    \"log_usage\": false\n  }\n}\n```\n\nThis stops writes to `runtime_usage.json`. The `--stats` command will have no data to show.\n\n---\n\n## Commands Reference\n\n### Installer Commands (`python install.py`)\n\nRun these from the `claude-meister` directory you cloned.\n\n| Flag | What it does |\n|---|---|\n| `--full` | Full installation: runtime engine + memory server + wiki knowledge base |\n| `--runtime-only` | Install the runtime engine only (skips memory and wiki) |\n| `--memory-only` | Install the memory server only |\n| `--wiki-only` | Install the wiki knowledge base only |\n| `--no-wiki` | Full install minus the wiki (runtime + memory) |\n| `--update` | Update an existing installation (preserves memories, config, and logs) |\n| `--uninstall` | Remove everything (prompts before deleting memories) |\n| `--verify` | Run post-install health checks and report what passed/failed |\n| `--stats` | Show usage dashboard for the last 30 days |\n\n**Examples:**\n\n```bash\n# First-time install, everything\npython install.py --full\n\n# Install without wiki (faster, smaller)\npython install.py --no-wiki\n\n# Check if everything is healthy\npython install.py --verify\n\n# View your usage stats\npython install.py --stats\n\n# Update after pulling new version\npython install.py --update\n\n# Remove Claude_Meister completely\npython install.py --uninstall\n```\n\n### Controller Commands\n\nThese scripts live in `~/.claude_runtime/controllers/` after installation. Claude calls them automatically, but you can also run them directly.\n\n#### `tool_loader.py` — Discover tools by keyword\n\n```bash\n# Find tools matching a keyword\npython ~/.claude_runtime/controllers/tool_loader.py --query \"scrape\"\n\n# Scan a specific directory instead of config dirs\npython ~/.claude_runtime/controllers/tool_loader.py --query \"api\" --scan-dir /path/to/tools\n\n# List all tools without filtering\npython ~/.claude_runtime/controllers/tool_loader.py --all\n```\n\nExample output:\n\n```json\n[\n  {\"name\": \"scrape_single_site\", \"path\": \"/path/to/tools/scrape_single_site.py\",\n   \"description\": \"Fetch and parse a single web page\", \"match_score\": 1.0},\n  {\"name\": \"scrape_batch\", \"path\": \"/path/to/tools/scrape_batch.py\",\n   \"description\": \"Batch scrape multiple URLs\", \"match_score\": 0.5}\n]\n```\n\n#### `usage_logger.py` — Log task usage and view stats\n\n```bash\n# Log a completed task\npython ~/.claude_runtime/controllers/usage_logger.py \\\n  --mode STANDARD \\\n  --tools-used \"tool_loader.py,advisor.py\" \\\n  --memory-tokens 312 \\\n  --task-summary \"Refactored auth module\"\n\n# View usage stats\npython ~/.claude_runtime/controllers/usage_logger.py --stats\n```\n\n#### `memory_controller.py` — Direct memory access (no MCP required)\n\n```bash\n# Query memories directly (useful for debugging)\npython ~/.claude_runtime/controllers/memory_controller.py --query \"auth\" --repo my-project\n```\n\n---\n\n## Updating\n\nWhen a new version of Claude_Meister is released:\n\n```bash\n# Pull the latest code\ngit pull\n\n# Run the updater\npython install.py --update\n```\n\n**What the updater preserves:**\n- `~/.claude_runtime/logs/runtime_usage.json` — your usage history\n- `~/.claude_runtime/configs/runtime_config.json` — your configuration (if you have edited it)\n- All stored memories in `~/.claude_memory/`\n\n**What the updater overwrites:**\n- All core behavioral documents (`context_router.md`, `mode_selector.md`, etc.)\n- All controller scripts (`tool_loader.py`, `usage_logger.py`, etc.)\n- All MCP server modules\n- All template-derived files (re-substituted with your current home directory)\n\n**What this means in practice:** Your memories, config customizations, and usage logs survive an update. The brains of the system get refreshed with the latest version.\n\n---\n\n## Uninstalling\n\n```bash\npython install.py --uninstall\n```\n\nThe uninstaller does the following, in order:\n\n1. Removes the Claude_Meister block from `~/.claude/CLAUDE.md` — your content outside the markers is untouched.\n2. Unregisters the memory server: runs `claude mcp remove memory`.\n3. **Asks you** whether to keep your stored memories (default: yes, keep them).\n4. Deletes `~/.claude_runtime/`.\n5. Optionally deletes `~/.claude_memory/server/` — the server code. Your actual memory data at `~/.claude_memory/` is kept by default.\n\nAfter uninstalling, Claude Code returns to its default behavior. Your `CLAUDE.md` is left in the state it was in before Claude_Meister appended its block.\n\n---\n\n## Troubleshooting\n\n### Installation Issues\n\n#### \"Python not found\" or \"python is not recognized\"\n\nPython is not on your PATH. Fix:\n- **Windows:** Re-run the Python installer from python.org and check \"Add Python to PATH\". Then open a fresh terminal.\n- **macOS:** Try `python3 --version`. If that works, use `python3 install.py --full` throughout.\n- **Linux:** Run `sudo apt install python3` (Debian/Ubuntu) or the equivalent for your distro.\n\n#### \"No module named mcp\" or \"No module named fastmcp\"\n\nThe packages are not installed. Run:\n\n```bash\npip install mcp fastmcp\n```\n\nIf you have multiple Python versions, make sure you are installing into the same Python that runs `install.py`. Use:\n\n```bash\npython -m pip install mcp fastmcp\n```\n\n#### \"Claude Code not found\"\n\nThe `claude` CLI is not installed or not on PATH. Install Claude Code from [claude.ai/code](https://claude.ai/code), then open a fresh terminal and retry.\n\n#### \"Permission denied\" writing to home directory\n\n- **macOS/Linux:** Run `ls -la ~` to check ownership. If you do not own your home directory, contact your system administrator.\n- **Windows:** Run Command Prompt as Administrator.\n\n#### \"Existing installation detected\"\n\nThe installer found a previous installation. You have three options:\n- **Update** — recommended. Preserves all your data.\n- **Clean install** — deletes everything and starts fresh. You will lose stored memories.\n- **Abort** — does nothing.\n\n#### \"Incomplete install detected\"\n\nThe installer found a partial previous install (directory exists but config is missing). It will run a clean installation automatically.\n\n#### OneDrive-redirected home directory (Windows)\n\nIf your home directory is inside OneDrive (e.g. `C:/Users/yourname/OneDrive/...`), the installer will warn you. OneDrive sync can cause file locking issues. You can set the `USERPROFILE` environment variable to a local directory, or proceed and watch for any sync conflicts.\n\n---\n\n### Runtime Issues\n\n#### Mode classification seems wrong\n\nClaude is classifying a simple task as DEEP, or a complex task as LIGHT. This is usually a prompt phrasing issue. Add explicit context:\n\n- For a simple task: \"Quick fix:\" at the start of your message signals simple.\n- For a complex task: \"Architecture question:\" signals DEEP.\n\n#### `context_router.md` cannot be found\n\nThe runtime path in `runtime_config.json` does not match where the files actually are. Run:\n\n```bash\npython install.py --verify\n```\n\nIf the runtime engine check fails, run `python install.py --runtime-only` to reinstall the engine.\n\n#### `runtime_config.json` shows bad JSON error\n\nThe config file was corrupted (e.g., you made an edit with a syntax error). The runtime falls back to defaults automatically. To fix:\n\n1. Open `~/.claude_runtime/configs/runtime_config.json` in a text editor.\n2. Validate it at [jsonlint.com](https://jsonlint.com).\n3. Fix any errors and save.\n\n#### Usage stats show 0 entries\n\nEither `log_usage` is set to `false` in your config, or you have not used Claude Code since installing. Check your config:\n\n```bash\npython install.py --stats\n```\n\nIf stats are empty after confirmed use, check that `~/.claude_runtime/logs/runtime_usage.json` exists and is writable.\n\n---\n\n### Memory Issues\n\n#### Memories are not being retrieved\n\nFirst, confirm the MCP server is registered:\n\n```bash\nclaude mcp list\n```\n\nYou should see `memory` in the output. If not, re-run:\n\n```bash\npython install.py --memory-only\n```\n\nThen restart Claude Code. MCP tools only become available after a fresh session.\n\n#### \"memory\" name conflict during registration\n\nIf you already have an MCP server named \"memory\", the installer will ask: replace it, rename the new one, or skip. Replacing is usually correct unless you have a different memory server you depend on.\n\n#### Wrong Python version running the memory server\n\nIf `mcp` is installed under Python 3.11 but the memory server launches with Python 3.8, the import will fail. The installer tries to detect the correct Python, but on machines with multiple versions you may need to confirm:\n\n```bash\nwhich python  # macOS/Linux\nwhere python  # Windows\n```\n\nMake sure this is the Python where you ran `pip install mcp fastmcp`.\n\n#### `index.json` corrupted\n\nIf you see an error about `index.json` being invalid JSON, the memory system will return empty results and log a warning. Fix:\n\n```bash\n# Back up the corrupted index\ncp ~/.claude_memory/index.json ~/.claude_memory/index.json.bak\n\n# Delete and let the system rebuild it\nrm ~/.claude_memory/index.json\n```\n\nThe index will be rebuilt on the next memory store operation. Existing memory files are unaffected.\n\n---\n\n### Platform-Specific Issues\n\n#### Windows: Encoding errors (\"charmap codec can't encode\")\n\nThis is a Windows console encoding issue. Fix by setting the environment variable before running:\n\n```cmd\nset PYTHONIOENCODING=utf-8\npython install.py --full\n```\n\nOr run in Windows Terminal (which uses UTF-8 by default) instead of the legacy Command Prompt.\n\n#### Windows: Path length errors\n\nWindows has a 260-character path limit by default. If you installed deep in a nested directory, this can trigger errors. Fix:\n1. Move the `claude-meister` folder closer to the root: `C:/claude-meister/`\n2. Or enable long paths in Windows: search \"Enable Win32 long paths\" in Group Policy Editor.\n\n#### macOS: \"Cannot be opened because the developer cannot be verified\"\n\nGatekeeper is blocking the scripts. Run:\n\n```bash\nxattr -d com.apple.quarantine install.py\n```\n\nOr right-click `install.py` in Finder, choose Open, then confirm you want to open it.\n\n#### macOS: System Python vs Homebrew Python\n\nmacOS ships with Python 3 but it may be an older version. If you installed a newer Python via Homebrew, use `python3` explicitly:\n\n```bash\npython3 install.py --full\n```\n\nCheck which Python has your packages:\n\n```bash\npython3 -c \"import mcp; print('OK')\"\n```\n\n#### Linux: Locale errors\n\nIf you see locale-related errors, set:\n\n```bash\nexport PYTHONIOENCODING=utf-8\npython install.py --full\n```\n\n#### WSL (Windows Subsystem for Linux)\n\nClaude_Meister detects WSL automatically and uses Linux-style paths. Important: your Claude Code installation must also be running inside WSL (not the Windows-side Claude Code) for the MCP registration to work. Mixed WSL/Windows setups are not supported.\n\n---\n\n### The Nuclear Option\n\nIf nothing works and you want a completely clean slate:\n\n```bash\n# Uninstall via installer if it runs\npython install.py --uninstall\n\n# Manual removal if installer won't run\nrm -rf ~/.claude_runtime\nrm -rf ~/.claude_memory/server   # Keep ~/.claude_memory/ itself if you want your memories\n\n# On Windows (run in PowerShell):\nRemove-Item -Recurse -Force \"$env:USERPROFILE\\.claude_runtime\"\nRemove-Item -Recurse -Force \"$env:USERPROFILE\\.claude_memory\\server\"\n\n# Remove the block from CLAUDE.md manually\n# Open ~/.claude/CLAUDE.md and delete everything between:\n# === Claude_Meister Runtime ===\n# and\n# === End Claude_Meister Runtime ===\n\n# Unregister the MCP server\nclaude mcp remove memory\n```\n\nAfter this, reinstall from scratch with `python install.py --full`.\n\n---\n\n## FAQ\n\n**Does Claude_Meister send any data anywhere?**\n\nNo. Everything runs locally. The memory server runs on your machine via stdio (standard input/output — a local communication channel, not a network). No data leaves your computer.\n\n**Does it call any external APIs?**\n\nNo. Claude_Meister has no API keys and makes no outbound network requests. It is purely local file operations and subprocess calls.\n\n**Will it slow Claude Code down?**\n\nNo. In LIGHT mode (the majority of interactions), the runtime is not loaded at all — there is zero overhead. In STANDARD and DEEP modes, reading a few local Markdown files adds milliseconds.\n\n**Will it conflict with my existing CLAUDE.md?**\n\nNo. The installer appends a clearly marked block to your existing CLAUDE.md. Everything outside the markers is untouched. When you uninstall, the block is removed and your file is restored to its previous state.\n\n**Can I use this on multiple machines?**\n\nYes. Install it on each machine separately. Memories are local to each machine — they do not sync automatically. If you want to share memories, you can copy `~/.claude_memory/` between machines.\n\n**What if I update Claude Code — will Claude_Meister break?**\n\nThe memory server registration should persist across Claude Code updates. If the `claude` CLI changes how it handles MCP servers, run `python install.py --verify` to check, and `python install.py --update` to re-register if needed.\n\n**Does it work with Claude's paid tiers?**\n\nYes. Claude_Meister reduces the tokens Claude Code loads per session. This benefits all tiers — fewer tokens means lower cost and more context available for your actual work.\n\n**Can I contribute to or modify the behavioral documents?**\n\nYes — they are plain Markdown files in `~/.claude_runtime/core/`. Edit them freely. Note that running `python install.py --update` will overwrite them with the latest versions from the repo. Keep a backup or fork the repo if you want permanent customizations.\n\n---\n\n## Contributing\n\n### Reporting Bugs\n\nOpen an issue on GitHub with:\n1. Your OS and Python version (`python --version`)\n2. The full error message (copy-paste, do not screenshot)\n3. The output of `python install.py --verify`\n4. What you expected to happen vs. what actually happened\n\n### Requesting Features\n\nOpen an issue with the label `enhancement`. Describe:\n1. The problem you are trying to solve (not just the feature you want)\n2. How you currently work around it\n3. What success looks like\n\n### Development Setup\n\n```bash\ngit clone https://github.com/Mintsolester/claude-meister.git\ncd claude-meister\n\n# Install test dependencies\npip install pytest\n\n# Run the test suite\npytest tests/ -v\n```\n\nThe test suite covers all 8 installer modules, the memory server, the controller scripts, and the verification system. All tests must pass before opening a pull request.\n\n**Project structure:**\n\n```\ninstall.py          # Entry point — orchestrates all installer modules\ninstaller/          # 8 installer modules (paths, runtime, memory, wiki,\n                    #   claude_md, mcp, verify, + __init__)\nruntime/            # Files that get installed to ~/.claude_runtime/\nmemory/             # Files that get installed to ~/.claude_memory/\nwiki/               # Files that get installed to ~/.claude_wiki/\ntemplates/          # Template files with {{PLACEHOLDER}} tokens\ntests/              # Full test suite\ndocs/               # Architecture and design documentation\nDEVIATIONS.md       # Audit trail of deliberate plan deviations\n```\n\n---\n\n## License & Credits\n\n**License:** MIT — see [LICENSE](LICENSE) for full text.\n\n**Author:** Mintsolester\n\n**Built on:**\n- [Claude Code](https://claude.ai/code) — the AI coding assistant this runtime extends\n- [FastMCP](https://github.com/jlowin/fastmcp) — the framework powering the memory MCP server\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io) — the standard that enables Claude Code to call external tools\n\n---\n\n*Claude_Meister is not affiliated with Anthropic. It is an independent project that extends Claude Code's behavior using its public plugin interfaces.*\n",
  "bytes": 36608,
  "sha": "f303bcb11d785c43613e2a531eb94f754423dc829bed94023f751bbc105f80ff",
  "repo_slug": "mintsolester/claude-meister",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_mintsolester_claude_meister_claude_meist_10321bcf/readme"
}