Metadata-Version: 2.4
Name: memstack-skill-loader
Version: 4.15.1
Summary: MCP server that vector-indexes MemStack Pro skills for on-demand loading
Project-URL: Homepage, https://memstack.pro
Project-URL: Documentation, https://memstack.pro/docs
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: lancedb>=0.6.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: pyarrow>=14.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: aiohttp>=3.9
Provides-Extra: dev
Requires-Dist: setuptools>=68; extra == "dev"

# MemStack™ Skill Loader

**130 skills for Claude Code:** 86 free + 44 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 86 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 44 Pro skills (86 free + 44 Pro = 130 total). Then type `list skills` to verify.

> **The first start is slow, and that is normal.** On the very first run after installing or upgrading, the server builds the skill index before it answers anything. Nearly all of that time is a one-time download of the ~90 MB embedding model, so it tracks your network speed rather than the size of your skill library: indexing 86 skills itself takes about a second. On a fast connection the whole first start is around half a minute; on a slow one it is longer. **The server will look unresponsive for that time.** Let it finish. Every later start reuses the cached model and index and is not affected.

> To override the skills path, set `MEMSTACK_SKILLS_DIR=/path/to/your/memstack/skills`.

> See [Getting Started](https://memstack.pro/docs/getting-started) for detailed setup and [Skill Reference](https://memstack.pro/docs/skills) for the full skill catalog. If you hit issues, the [Troubleshooting](#troubleshooting) section below covers the common ones.

## Troubleshooting

**Nothing responds after a fresh install, and it does not seem to be failing either (during Step 4):** the first start builds the skill index before the server answers anything. Most of that is a one-time ~90 MB embedding-model download, not reading your skills, so the wait depends on your connection: around half a minute on a fast one, longer on a slow one. There is no progress output, so a working first start and a hung one look identical. Wait it out before changing anything. If it is still silent well past a few minutes, then treat it as the interpreter mismatch below. Later starts reuse the cached model and index and respond immediately.

**`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 130 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 and never leave your machine. Three small calls happen on their own at session start — license validation, a Pro-bundle version probe, and a PyPI update check — and every other outbound call is one you trigger ([Data and privacy](#data-and-privacy))
- **Pro skills auto-detected:** once activated, the Pro skills directory is added to your sources automatically, with no `config.json` edit
- **Auto-reindex on start:** skills stay current without manual rebuilds. Only startup ever rebuilds, never a search. The first start pays a one-time build dominated by the embedding-model download (see [Quick Start](#quick-start-5-minutes)); after that a rebuild happens in the background while the existing index keeps serving, so later starts are not delayed
- **Memory Engine:** an append-only, versioned fact store with query-time recall scoring — facts decay with age and decay more slowly the more they are recalled. Facts flow in from the diary's `## FACTS` block and are exposed to Claude through five `mem_*` tools (see [Available Tools](#available-tools))
- **Living memory at session start:** the SessionStart hook injects a compact, token-budgeted digest of the project's top recall-scored facts into context. It fails open — a missing, empty, or unreachable store never blocks startup
- **8-page localhost dashboard:** Overview, Skills Manager, Burn Report, Memory Browser (project-aware diary reader), Memory Inspector (read-only Memory Engine fact views), Agent Monitor, Referrals, and Settings

### Data and privacy

Outbound calls fall into two groups: the ones the loader makes on its own, and the ones you trigger. Both are listed in full.

**Automatic — these happen at session start without you asking:**

- **License validation** → POST to `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.
- **Pro bundle version probe** → GET to `admin.cwaffiliateinvestments.com/api/skills/pro-bundle/version`. Pro licenses only, at most once every 24 hours. Sends your license key as a bearer token and nothing else; it asks only whether a newer skill bundle exists.
- **Update check** → GET to `pypi.org/pypi/memstack-skill-loader/json`. At most once every 24 hours. Sends no payload at all — it reads the latest published version number so the loader can tell you an upgrade is available.

**Triggered by you — these never fire on their own:**

- **Pro skills download** → GET to `admin.cwaffiliateinvestments.com/api/skills/pro-bundle`, when you run `activate_license` or `refresh_pro_skills`, and when the version probe above finds a newer bundle. Sends your license key.
- **Agent Runner** → `api.anthropic.com`, only while you are running an agent. This is the one call that carries your actual work: the task you wrote and the contents of the files the agents read. It uses your own Anthropic API key, and nothing is sent unless you start an agent.
- **Referrals page** → POST to `memstack.pro/api/referrals/me`, only when you open that dashboard page. Sends your license key.
- **TokenStack proxy** → `api.anthropic.com`, only if you start the proxy yourself. It forwards your Claude Code traffic after compressing it, and is off unless you turn it on.

Outside the Agent Runner and the TokenStack proxy — both of which you start deliberately, and both of which talk to Anthropic rather than to us — **no code, file contents, file paths, usernames, project names, or prompts are ever sent.** The environment fields in license validation 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.10+
- [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()
```

### Memory Engine

The `mem_*` tools back a persistent, append-only fact store shared across sessions (see [How It Works](#how-it-works)).

- **`mem_store`** — Store a new immutable fact (subject, claim, provenance). Returns the fact id and its provenance tag.
- **`mem_correct`** — Correct a fact by superseding it with a new one. Corrections extend only from the live tip of a chain; correcting a superseded fact is refused and names the current tip.
- **`mem_recall`** — Recall live facts for a project, each rendered with an inline provenance tag `[method · source · recalled Nx]`. Each returned fact is logged as a recall. Optional full-text query or exact-subject filter.
- **`mem_inspect`** — Inspect a single fact and its full supersession chain (root → tip) with statuses, provenance, entities, and recall count.
- **`mem_stats`** — Fact-store statistics: totals by status (live/superseded/retracted), distinct subjects, and recall count. Optionally scoped to a project.

## Configuration

The `config.json` file controls where skills are loaded from:

```json
{
  "skill_sources": [
    {
      "type": "local",
      "path": "/path/to/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
}
```

`vector_db_path` sets where the skill index is stored. A relative value resolves against the canonical state root `~/.memstack`, not against the directory holding `config.json`, so the index lives in one place regardless of which directory a process is started from. An absolute or `~`-prefixed value is honored verbatim.

You never add Pro skills to `config.json` by hand: the loader adds that directory itself once a key is present. Run `activate_license` at least once regardless, because that is the step that validates your key and downloads the Pro skills. `MEMSTACK_PRO_LICENSE_KEY` is an optional override that supplies the key without storing it, and it takes precedence over the stored one, but on its own it downloads nothing.

Add entries to `skill_sources` to index skills from multiple directories:

```json
{
  "skill_sources": [
    {
      "type": "local",
      "path": "/path/to/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

### 4.15.1 (August 2026)

- **Fixed: activating a Pro license on a PyPI install downloaded the Pro skills and never indexed them.** The skills landed in `~/.memstack/pro-skills`, activation reported success, and the catalog still showed only the 86 free skills. Setting `MEMSTACK_PRO_LICENSE_KEY` was the only workaround. Both of the paths that decide whether to attach the Pro source now share one predicate.
- **Activation now takes effect immediately.** The reindex that follows an activation rebuilds with the Pro skills included, and the confirmation reports the post-activation count, so a restart is no longer needed.
- First-start timing in these docs was reworded: it is dominated by a one-time embedding-model download and therefore varies with network speed, rather than being the fixed "roughly a minute" previously quoted.

### 4.15.0 (August 2026)

- The skill index moved to the canonical state root, so a relative `vector_db_path` no longer depends on which directory the server happened to start in. **The first start after installing or upgrading rebuilds the index once**, nearly all of that time being a one-time embedding-model download. Later starts are unaffected.
- New index guard classifies the index as current, drift, stale, absent, or rebuilding, and reports that verdict at startup and in the dashboard. Only startup may rebuild on its own, so no search request ever blocks on one.
- Agent Runner git policy rewritten as an argv-level classifier, replacing a substring match that could not tell `git status` from `git push`.

### 4.10.0 to 4.14.1 (July 2026)

- Memory Engine: diary `## FACTS` ingestion, living-memory injection at session start, a read-only Memory Inspector dashboard page, and recall that ranks the whole live fact set rather than a window of it.
- Added the goal skill, bringing the public catalog to 130 skills (86 free + 44 Pro).
- Added the video-review Pro skill.
- Referrals page added to the dashboard.
- License validation now discloses its full payload in-product (see [Data and privacy](#data-and-privacy)).
- Packaging fix: `skill_descriptions.json` now ships in the wheel, so a pip install no longer falls back to empty dashboard descriptions.

### 4.0.0 to 4.9.0 (May to July 2026)

- Dashboard and Agent Runner: 3-agent orchestration (Manager, Builder, Reviewer) with per-agent model selection, context window monitoring, and token cost tracking.
- Session diary with markdown narratives, and safe git staging that keeps secrets and runtime data out of commits.
- TokenStack proxy compression, including AST compression of line-numbered Python.
- Memory Browser with project filtering and secret masking.
- Licensing hardened against transient network failures and machine mismatches.

## License

Proprietary. Part of MemStack™ Pro by CW Affiliate Investments LLC.
