memstack-skill-loader 4.5.1__tar.gz → 4.7.0__tar.gz

{memstack_skill_loader-4.5.1/src/memstack_skill_loader.egg-info → memstack_skill_loader-4.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memstack-skill-loader
-Version: 4.5.1
+Version: 4.7.0
 Summary: MCP server that vector-indexes MemStack Pro skills for on-demand loading
 Requires-Python: >=3.10
 Requires-Dist: mcp>=1.0.0

memstack_skill_loader-4.7.0/README.md

@@ -0,0 +1,218 @@
+# MemStack™ Skill Loader
+
+**128 skills for Claude Code:** 85 free + 43 Pro exclusive. Vector-indexed so CC loads only the skill it needs, saving your context window.
+
+## Quick Start (5 minutes)
+
+MemStack installs in two parts: the **skills** (via the Claude Code plugin marketplace) and the **engine** (this loader, via PyPI). You need both. Every command below is labeled **(in Claude Code)** or **(in terminal)** — running one in the wrong place is the most common setup mistake.
+
+**Step 1 — Install the free skills · (in Claude Code):**
+```
+/plugin marketplace add cwinvestments/memstack
+/plugin install memstack@cwinvestments-memstack
+```
+Run both commands. This unlocks the 85 free skills right away.
+
+> **SSH error?** ("Host key verification failed" on a fresh server that's never used GitHub over SSH.)
+> **Default fix · (in terminal)** — rewrite GitHub to HTTPS, then retry Step 1:
+> ```bash
+> git config --global url."https://github.com/".insteadOf "git@github.com:"
+> ```
+> **Backup fix · (in terminal)** — add GitHub's host key, then retry Step 1:
+> ```bash
+> mkdir -p ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
+> ```
+
+**Step 2 — Install the engine · (in terminal):**
+
+Windows:
+```bash
+pip install memstack-skill-loader
+```
+
+Linux / Mac — use the explicit interpreter (the same one you register in Step 3):
+```bash
+/usr/bin/python3 -m pip install memstack-skill-loader --break-system-packages
+```
+Find yours with `which python3` and substitute it if it isn't `/usr/bin/python3`. The `--break-system-packages` flag is required on newer externally-managed Python. No pip for that interpreter? Run `sudo apt install python3-pip` first (Debian/Ubuntu).
+
+**Step 3 — Register the MCP server · (in terminal):** register against the **same interpreter you installed onto in Step 2.**
+
+Windows:
+```bash
+claude mcp add --scope user memstack-skills -- python -m memstack_skill_loader
+```
+
+Linux / Mac:
+```bash
+claude mcp add --scope user memstack-skills -- /usr/bin/python3 -m memstack_skill_loader
+```
+If this doesn't match Step 2's interpreter, the server won't launch (you'll see a "failed to reconnect" error and `activate_license` will be missing).
+
+**Step 4 — Activate your license · (in Claude Code, after a full restart):** fully quit and reopen Claude Code first so it picks up the new MCP server, then run:
+```
+activate_license(key="your-key", email="you@example.com")
+```
+Use `key="free"` for the free tier, or your Pro key from [memstack.pro](https://memstack.pro) to unlock all 43 Pro skills (85 free + 43 Pro = 128 total). Then type `list skills` to verify.
+
+> To override the skills path, set `MEMSTACK_SKILLS_DIR=/path/to/your/memstack/skills`.
+
+> See [QUICKSTART.md](QUICKSTART.md) for detailed setup, [QUICK-REFERENCE.md](QUICK-REFERENCE.md) for the full skill catalog, and [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if you hit issues.
+
+## Troubleshooting
+
+**`error: externally-managed-environment` (during Step 2)** — pip refuses to install on a system-managed Python. Add `--break-system-packages` · (in terminal):
+```bash
+/usr/bin/python3 -m pip install memstack-skill-loader --break-system-packages
+```
+
+**Plugin clone fails: "Host key verification failed" (during Step 1)** — a fresh server that's never connected to GitHub over SSH. **Default fix · (in terminal):** `git config --global url."https://github.com/".insteadOf "git@github.com:"` then retry Step 1. **Backup fix · (in terminal):** `mkdir -p ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts` then retry Step 1.
+
+**`activate_license` not found, or MCP "failed to reconnect (-32000)"** — the loader was installed onto a **different Python interpreter** than the one Claude Code launches (the classic bare-`python` mismatch on Linux/Mac). Check · (in terminal):
+```bash
+/usr/bin/python3 -c "import memstack_skill_loader; print('ok')"
+```
+If it prints `ok`, make sure Step 3 registered that exact path, then fully restart Claude Code. If it errors with `ModuleNotFoundError`, reinstall onto the explicit interpreter and re-register against that same path · (in terminal):
+```bash
+/usr/bin/python3 -m pip install memstack-skill-loader --break-system-packages
+claude mcp add --scope user memstack-skills -- /usr/bin/python3 -m memstack_skill_loader
+```
+Then fully restart Claude Code. Rule of thumb: whatever interpreter you `import`-check as `ok` is the path that must appear in your `claude mcp add` command.
+
+**`No module named pip` (during Step 2)** — that interpreter ships without pip (common on minimal Debian/Ubuntu server images). Install it, then retry the Step 2 install · (in terminal):
+```bash
+sudo apt install python3-pip
+```
+
+## How It Works
+
+MCP server that vector-indexes all 128 MemStack™ skills so Claude Code can call `find_skill("deploy to Railway")` and load **only** the relevant skill on demand, instead of all skills consuming context window.
+
+- **No Anthropic API key required:** skill search and indexing run locally — the only outbound network call is license validation, which contacts the MemStack license server on session start ([Data and privacy](#data-and-privacy))
+- **Pro skills auto-detected:** set your license key and they appear automatically
+- **Auto-reindex on start:** skills stay current without manual rebuilds
+
+### Data and privacy
+
+License validation is the loader's only outbound network call. On session start it POSTs to the MemStack license server (`admin.cwaffiliateinvestments.com/api/licenses/validate`) with:
+
+- your **license key**
+- a **machine ID** — a stable, hashed fingerprint that binds the license to your machine
+- your **email**, if you provided one at activation
+- your **environment** — OS name, Python version, and MemStack loader version
+
+That is the complete payload. **No code, file contents, file paths, usernames, project names, or prompts are ever sent.** The environment fields exist only so platform-specific breakage (for example, a bug that affects only Linux) is visible to us in aggregate.
+
+### Environment Variable Override
+
+Set `MEMSTACK_SKILLS_DIR` to override the skills path in `config.json`:
+
+```bash
+export MEMSTACK_SKILLS_DIR=/path/to/your/memstack/skills
+```
+
+## Stack
+
+- Python 3.12+
+- [MCP SDK](https://pypi.org/project/mcp/) (stdio transport)
+- [LanceDB](https://lancedb.com/) (vector storage, zero external dependencies)
+- [sentence-transformers](https://www.sbert.net/) with `all-MiniLM-L6-v2` (384-dim local embeddings)
+
+## Available Tools
+
+### `find_skill`
+Search skills by describing what you need. Returns the most relevant skill(s) with full instructions.
+
+```
+find_skill(query="deploy to Railway", top_k=3)
+```
+
+### `list_skills`
+Browse the full skill catalog with names and descriptions.
+
+```
+list_skills()
+```
+
+### `get_skill`
+Load a specific skill by exact name.
+
+```
+get_skill(name="railway deploy")
+```
+
+### `reindex_skills`
+Rebuild the vector index after adding or modifying skills.
+
+```
+reindex_skills()
+```
+
+## Configuration
+
+The `config.json` file controls where skills are loaded from:
+
+```json
+{
+  "skill_sources": [
+    {
+      "type": "local",
+      "path": "C:\\Projects\\memstack\\skills",
+      "pattern": "**/SKILL.md",
+      "label": "MemStack"
+    }
+  ],
+  "embedding_model": "all-MiniLM-L6-v2",
+  "default_top_k": 3,
+  "vector_db_path": "./vectors",
+  "auto_reindex_on_start": true
+}
+```
+
+Pro skills are **auto-detected** when `MEMSTACK_PRO_LICENSE_KEY` is set, no need to add them to `config.json`.
+
+Add entries to `skill_sources` to index skills from multiple directories:
+
+```json
+{
+  "skill_sources": [
+    {
+      "type": "local",
+      "path": "C:\\Projects\\memstack\\skills",
+      "pattern": "**/SKILL.md",
+      "label": "MemStack"
+    },
+    {
+      "type": "local",
+      "path": "/home/user/custom-skills",
+      "pattern": "*.md",
+      "label": "My Custom Skills"
+    }
+  ]
+}
+```
+
+The `pattern` field controls how skills are discovered:
+- `**/SKILL.md`: Subdirectory structure (e.g., `category/skill-name/SKILL.md`)
+- `*.md`: Flat directory (each `.md` file is a skill)
+
+## Release Notes
+
+### v4.0.0 (May 2026)
+
+- Dashboard: 6-page localhost dashboard (Overview, Skills Manager, Burn Report, Memory Browser, Agent Monitor, Settings)
+- Agent Runner: 3-agent orchestration (Manager/Builder/Reviewer) with per-agent model selection
+- 17 MCP tools
+- 127 skills (84 free + 43 Pro)
+- Real-time context window monitoring per agent
+- Session diary with AI-authored markdown narratives
+- Safe git staging (prevents accidental commits of secrets/runtime data)
+- Task completion notifications (browser, tab flash, audio)
+- Token usage tracking with estimated costs
+- TokenStack™ proxy integration (~35-40% token savings)
+
+**[v3.4.0](https://github.com/cwinvestments/memstack-skill-loader/releases/tag/v3.4.0)**: 100 Skills Milestone (18 new Pro skills, auto-detection, display name fixes)
+
+## License
+
+Proprietary. Part of MemStack™ Pro by CW Affiliate Investments LLC.

{memstack_skill_loader-4.5.1 → memstack_skill_loader-4.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "memstack-skill-loader"
-version = "4.5.1"
+version = "4.7.0"
 description = "MCP server that vector-indexes MemStack Pro skills for on-demand loading"
 requires-python = ">=3.10"
 dependencies = [

{memstack_skill_loader-4.5.1 → memstack_skill_loader-4.7.0}/src/memstack_skill_loader/__init__.py

@@ -1,3 +1,3 @@
 """MemStack Skill Loader — MCP server for semantic skill search."""
 
-__version__ = "4.5.1"
+__version__ = "4.7.0"

{memstack_skill_loader-4.5.1 → memstack_skill_loader-4.7.0}/src/memstack_skill_loader/categories.py

@@ -12,7 +12,8 @@ CATEGORY_MAP = {
     "quill": "Business", "scan": "Business", "governor": "Business",
     "client-onboarding": "Business", "contract-template": "Business", "financial-model": "Business",
     "freelancer-toolkit": "Business", "invoice-generator": "Business", "scope-of-work": "Business",
-    "sop-builder": "Business", "proposal-writer": "Business",
+    "sop-builder": "Business", "proposal-writer": "Business", "gdpr": "Business",
+    "licensing": "Business",
     # Content
     "humanize": "Content", "blog-post": "Content", "email-sequence": "Content",
     "landing-page-copy": "Content", "newsletter": "Content", "product-description": "Content",
@@ -26,7 +27,7 @@ CATEGORY_MAP = {
     "forge": "Development", "shard": "Development",
     "state": "Development", "work": "Development", "verify": "Development",
     "project": "Development", "familiar": "Development", "api-designer": "Development",
-    "code-reviewer": "Development", "database-architect": "Development", "migration-planner": "Development",
+    "code-reviewer": "Development", "migration-planner": "Development",
     "performance-audit": "Development", "refactor-planner": "Development", "test-writer": "Development",
     "changelog-generator": "Development", "mentor": "Development", "webapp-testing": "Development",
     # Core
@@ -45,20 +46,46 @@ CATEGORY_MAP = {
     "user-story-generator": "Product", "mvp-scoper": "Product", "roadmap-builder": "Product",
     "feedback-analyzer": "Product",
     # Security
-    "advanced-security": "Security", "env-manager-pro": "Security",
     "api-audit": "Security", "csp-headers": "Security", "dependency-audit": "Security",
     "owasp-top10": "Security", "owasp-top-10": "Security",
     "rls-checker": "Security", "rls-guardian": "Security",
-    "secrets-scanner": "Security",
-    # Pro skills (for backfill matching)
-    "api-docs": "Core", "branching": "Core", "consolidate": "Core", "context-db": "Core",
-    "multi-agent": "Development", "codebase-index": "Development", "doc-index": "Development",
-    "diagram-generator": "Development", "browser-use": "Development", "session-restore": "Core",
-    "drift-detection": "Security", "mcp-builder": "Development", "claude-api-helper": "Development",
-    "test-generator": "Development", "log-analyzer": "Development",
-    "performance-profiler": "Development", "dependency-auditor": "Security",
-    "git-worktrees": "Development", "error-handler": "Development", "web-scraper": "Automation",
-    "hooks-integration": "Development",
+    "secrets-scanner": "Security", "git-guard": "Security",
+    # ── Pro-exclusive skills (43) — CANONICAL category map ─────────────────
+    # Must cover every slug in PRO_EXCLUSIVE_SKILLS (license.py) exactly; no Pro
+    # slug may fall through to "Other". Enforced by scripts/check_skill_drift.py
+    # (Check C / F-3). Core = MemStack's own session/memory/agent/efficiency
+    # meta-skills ONLY; anything that operates on the user's code/docs is
+    # Development, not Core.
+    # Core (9)
+    "burn": "Core", "checkpoint": "Core", "consolidate": "Core",
+    "context-db": "Core", "council": "Core", "governor-pro": "Core",
+    "model-router": "Core", "multi-agent": "Core", "session-restore": "Core",
+    # Development (21)
+    "api-docs": "Development", "api-load-tester": "Development",
+    "branching": "Development", "claude-api-helper": "Development",
+    "codebase-index": "Development", "database-architect": "Development",
+    "database-migration": "Development", "developer-growth-analysis": "Development",
+    "diagram-generator": "Development", "doc-index": "Development",
+    "drift-detection": "Development", "error-handler": "Development",
+    "frontend-design": "Development", "git-worktrees": "Development",
+    "log-analyzer": "Development", "mcp-builder": "Development",
+    "nextjs-conventions": "Development", "performance-profiler": "Development",
+    "python-conventions": "Development", "rag-builder": "Development",
+    "test-generator": "Development",
+    # Security (4)
+    "advanced-security": "Security", "config-audit": "Security",
+    "dependency-auditor": "Security", "env-manager-pro": "Security",
+    # Automation (4)
+    "browser-use": "Automation", "hooks-integration": "Automation",
+    "video-pipeline": "Automation", "web-scraper": "Automation",
+    # Business (2)
+    "meeting-insights-analyzer": "Business", "us-privacy-compliance": "Business",
+    # Content (1)
+    "social-media": "Content",
+    # Deployment (1)
+    "ios-app-store": "Deployment",
+    # Marketing (1)
+    "gtm-validator": "Marketing",
 }
 
 

{memstack_skill_loader-4.5.1 → memstack_skill_loader-4.7.0}/src/memstack_skill_loader/dashboard.html

@@ -1564,6 +1564,10 @@
       <div class="card">
         <div class="value stat-green" id="ts-avg-savings">-</div>
         <div class="label">Avg Savings</div>
+        <div id="ts-code-read" style="display:none;font-size:0.62rem;color:#6e7681;margin-top:0.35rem;line-height:1.3">
+          <span id="ts-code-read-text"></span>
+          <span id="ts-code-read-info" style="cursor:help;border-bottom:1px dotted #6e7681">&#9432;</span>
+        </div>
       </div>
       <div class="card">
         <div class="value" style="color:#58a6ff" id="ts-requests">-</div>
@@ -5216,6 +5220,21 @@ async function loadTokenStackSavings() {
     avgEl.textContent = (d.avg_savings_pct || 0).toFixed(1) + '%';
     reqEl.textContent = fmt(d.total_requests || 0);
 
+    // Secondary, clearly-subordinate stat: all-time p95 of the AST-fired
+    // (code-read) slice. Hidden unless the slice is big enough to be meaningful.
+    const crEl = document.getElementById('ts-code-read');
+    const crText = document.getElementById('ts-code-read-text');
+    const crInfo = document.getElementById('ts-code-read-info');
+    if (d.code_read_display_pct != null && (d.code_read_sample_size || 0) >= 50) {
+      crText.textContent = 'up to ~' + d.code_read_display_pct + '% on code-heavy reads';
+      crInfo.title = 'Code-heavy = requests where AST truncation fires (file reads of '
+        + 'source code). p95 of that slice (n=' + fmt(d.code_read_sample_size)
+        + ') — not the typical case.';
+      crEl.style.display = '';
+    } else {
+      crEl.style.display = 'none';
+    }
+
     const labels = {free: 'Free', ast: 'AST', json: 'JSON', log: 'Log', path: 'Path',
                     system: 'System Prompt', dedup: 'Conversation Dedup', markdown: 'Markdown'};
     const order = ['free', 'ast', 'json', 'log', 'path', 'system', 'dedup', 'markdown'];
@@ -5230,6 +5249,8 @@ async function loadTokenStackSavings() {
     savedEl.textContent = '-';
     avgEl.textContent = '-';
     reqEl.textContent = '-';
+    const crEl = document.getElementById('ts-code-read');
+    if (crEl) crEl.style.display = 'none';
     tbody.innerHTML = '<tr><td colspan="2"><span class="empty-state">No compression data yet. Start the dashboard with --with-proxy.</span></td></tr>';
   }
 }

{memstack_skill_loader-4.5.1 → memstack_skill_loader-4.7.0}/src/memstack_skill_loader/dashboard.py

@@ -30,7 +30,11 @@ from . import agent_runner
 import subprocess
 from .skill_config import load_skill_config, save_skill_config, toggle_skill, set_mode, SkillConfig
 from .stats import DB_PATH, get_dashboard_data, get_project_details, get_skill_fire_counts, get_burn_report_data, get_api_costs
-from .proxy.stats_tracker import get_tokenstack_stats, get_lifetime_avg_savings
+from .proxy.stats_tracker import (
+    get_tokenstack_stats,
+    get_lifetime_avg_savings,
+    get_code_read_savings,
+)
 
 _HTML_PATH = Path(__file__).parent / "dashboard.html"
 _LAST_WORKDIR_FILE = Path.home() / ".memstack" / "agent-runner" / "last-workdir.txt"
@@ -795,6 +799,10 @@ class _Handler(BaseHTTPRequestHandler):
                 rng = "all"
             try:
                 data = get_tokenstack_stats(rng)
+                # All-time code-read (AST-fired) p95 capability stat. Merged here
+                # rather than inside the range-scoped aggregate so it stays a
+                # stable claim independent of the selected time window.
+                data.update(get_code_read_savings())
             except Exception as exc:
                 data = {"error": str(exc)}
             body = json.dumps(data).encode()

{memstack_skill_loader-4.5.1 → memstack_skill_loader-4.7.0}/src/memstack_skill_loader/license.py

@@ -9,6 +9,7 @@ import hmac as hmac_mod
 import json
 import math
 import os
+import platform
 import socket
 import sys
 import threading
@@ -406,6 +407,50 @@ def save_license_key(key: str) -> None:
 # ---------------------------------------------------------------------------
 
 
+def _environment_info() -> dict[str, str | None]:
+    """Coarse environment info attached to every license-validation POST.
+
+    Purpose: let us see which OS / Python / loader versions our users run, so a
+    bug that silently breaks one platform (e.g. the hooks bug that killed skill
+    auto-loading on Linux/macOS) is visible in aggregate.
+
+    Collects ONLY three fields: OS name, running Python version, installed
+    loader version. It deliberately sends NO hostname, username, file path,
+    project name, or any identifier beyond the machine_id already in the
+    payload. Each field is detected independently and fail-safe: any failure
+    yields ``None`` (JSON null), never an exception — environment detection
+    must NEVER be able to fail a license validation.
+
+    ``plugin_version`` is intentionally absent. The Claude Code skills-bundle
+    plugin is a separate marketplace artifact; its version lives in
+    ``.claude-plugin/plugin.json`` inside Claude Code's plugin cache. This
+    loader's MCP server is registered standalone
+    (``claude mcp add ... python -m memstack_skill_loader``), so the process
+    never receives ``CLAUDE_PLUGIN_ROOT`` or any handle to that cache, and the
+    two artifacts share no version coupling. There is no reliable value to
+    send, so the field is omitted rather than guessed.
+    """
+    info: dict[str, str | None] = {"os": None, "python_version": None, "loader_version": None}
+
+    try:
+        info["os"] = platform.system() or None
+    except Exception:
+        pass
+
+    try:
+        info["python_version"] = platform.python_version()
+    except Exception:
+        pass
+
+    try:
+        from importlib.metadata import version as _pkg_version
+        info["loader_version"] = _pkg_version("memstack-skill-loader")
+    except Exception:
+        pass
+
+    return info
+
+
 async def validate_license(
     license_key: str | None = None,
     email: str | None = None,
@@ -644,9 +689,10 @@ async def _validate_locked(key: str, email: str | None) -> LicenseStatus:
             return cached_status
 
     # --- build request body ---
-    body_payload: dict[str, str] = {"license_key": key, "machine_id": _machine_id()}
+    body_payload: dict[str, str | None] = {"license_key": key, "machine_id": _machine_id()}
     if email:
         body_payload["email"] = email
+    body_payload.update(_environment_info())  # os / python_version / loader_version (fail-safe)
 
     # --- always call API on session start ---
     try:
@@ -710,7 +756,8 @@ def refresh_license_cache(key: str, timeout: float = HTTP_TIMEOUT) -> LicenseSta
     Returns the new LicenseStatus on success, or None if the server is unreachable
     or returns an error. All network exceptions are caught internally.
     """
-    body_payload: dict[str, str] = {"license_key": key, "machine_id": _machine_id()}
+    body_payload: dict[str, str | None] = {"license_key": key, "machine_id": _machine_id()}
+    body_payload.update(_environment_info())  # os / python_version / loader_version (fail-safe)
     # Uses VALIDATE_URL directly via httpx — not routed through ANTHROPIC_BASE_URL (Anthropic SDK only).
     try:
         with httpx.Client(timeout=timeout) as client:

{memstack_skill_loader-4.5.1 → memstack_skill_loader-4.7.0}/src/memstack_skill_loader/proxy/body_parser.py

@@ -154,8 +154,31 @@ def parse_and_compress(body_dict: dict, tier: str = "free", force_pro: bool = Fa
             _diag.body_transform("dedup", dedup_saved,
                                  note="(cross-message repeated-block removal)")
 
+    # Body-level transforms (system-prompt compression + conversation dedup) remove
+    # tokens from content that is already inside total_compressed (the post-block
+    # forwarded text), but they run *after* total_compressed was tallied in the
+    # message loop. Credit their savings in savings_pct by computing it against the
+    # reduced "forwarded" size — but DO NOT mutate total_compressed itself: the
+    # stored compressed_tokens must stay a BLOCK-ONLY base so historical (backfilled)
+    # and new rows share exactly one convention. The read path (get_tokenstack_stats
+    # / get_proxy_stats) reconstructs the body-inclusive tokens-saved total from this
+    # same block-only base plus the dedup/system columns, so the headline % and the
+    # absolute token count stay consistent. The removals are disjoint from the
+    # block-transform deltas (sequential) and from each other, so no double-count;
+    # clamp >=0 for the rare sub-threshold case. total_original stays block-scope —
+    # folding the system prompt's original size into the denominator is
+    # unreproducible by the column-only backfill (sys_orig is not stored) and would
+    # dilute the headline. See scripts/verify_metric_fix.py for the live-data proof.
+    body_saved = 0
+    if pro:
+        if sys_t is not None and sys_t.enabled:
+            body_saved += savings.get(sys_t.stat_key, 0)
+        if dedup_t is not None and dedup_t.enabled:
+            body_saved += savings.get(dedup_t.stat_key, 0)
+    forwarded = max(0, total_compressed - body_saved)
+
     if total_original > 0:
-        savings_pct = round((1 - total_compressed / total_original) * 100, 1)
+        savings_pct = round((1 - forwarded / total_original) * 100, 1)
     else:
         savings_pct = 0.0