chore: bootstrap memory-os prototype

Consolidates the Knowledge OS stack into one repo so the studio can
evolve it as a single surface instead of three under-published packages.

Cloned in (current source, no .git/node_modules/dist):
  - packages/kernel/    from E:/AI/ai-loadout       (npm @mcptoolshop/ai-loadout@1.4.3)
  - packages/memories/  from E:/AI/claude-memories  (unpublished, README rewritten 2026-06-10)
  - packages/rules/     from E:/AI/claude-rules     (unpublished, README rewritten 2026-06-10)
  - apps/hook/          from ~/.claude/loadout-hook (mirror; live copy stays wired in settings.json)

Picker docs:
  - .claude/CLAUDE.md  source-of-truth rules + working conventions
  - ROADMAP.md         five-phase plan (workspace wiring -> CLI surface -> docs -> npm -> publish + retire upstream)

Reasoning for consolidation: memory/Feedback/feedback_consolidate_when_cant_juggle_repos.md
(decompose-by-secrets is correct for teams of N humans; operational visibility wins for solo + LLM-crew.)

PROTOTYPE state - upstream sources at E:/AI/{ai-loadout,claude-memories,claude-rules}
remain source-of-truth until Phase 5 retirement.

Author: mcp-tool-shop

.claude/CLAUDE.md

@@ -0,0 +1,57 @@
+# memory-os — project instructions
+
+## What this is
+
+**memory-os is the Knowledge OS for the studio**, consolidated into one repo so it can evolve as a single surface. It folds together three previously-separate npm packages:
+
+| Was | Now lives at | Role |
+|---|---|---|
+| `@mcptoolshop/ai-loadout` | `packages/kernel/` | Dispatch table, matching, resolver, runtime |
+| `@mcptoolshop/claude-memories` | `packages/memories/` | MEMORY.md parser + index/validate/stats |
+| `@mcptoolshop/claude-rules` | `packages/rules/` | CLAUDE.md parser + split/analyze/stats |
+
+Plus the runtime pointer-injection hook earned in the 2026-06-10 session:
+
+| Was | Now lives at | Role |
+|---|---|---|
+| `~/.claude/loadout-hook/` | `apps/hook/` | UserPromptSubmit hook — injects pointer lines to relevant memory entries |
+
+## Status — PROTOTYPE (2026-06-10)
+
+This is a **prototype consolidation**, not a finished product. Expect 1–2 months of work to reach shippable state. Pick up via `ROADMAP.md` at the repo root.
+
+## Source-of-truth rule (load-bearing)
+
+Until memory-os reaches first-shippable, the **upstream source-of-truth** still lives at:
+
+- `E:/AI/ai-loadout/` (kernel — npm `@mcptoolshop/ai-loadout@1.4.3`, the only one published)
+- `E:/AI/claude-memories/` (memories — local-only, README rewritten 2026-06-10 to admit not-on-npm)
+- `E:/AI/claude-rules/` (rules — local-only, README rewritten 2026-06-10 to admit not-on-npm)
+- `~/.claude/loadout-hook/` (hook — wired into `~/.claude/settings.json`, runs every UserPromptSubmit)
+
+**Do not edit the three upstream source repos from inside memory-os.** Edits inside memory-os stay inside memory-os until the explicit retirement step in `ROADMAP.md` (Phase 5).
+
+**The live hook** at `~/.claude/loadout-hook/` is what's actually running in every session. `apps/hook/` here is a mirror for refactor work. If you change the hook contract, update both — and the wired path in `~/.claude/settings.json`.
+
+## Why this consolidation
+
+The "three small packages, one kernel + two adapters" design is architecturally clean (decompose-by-secrets, Parnas 1972) but operationally broken for the studio's solo + LLM-crew shape. Multi-repo work fragments Claude context across sessions, lets unpublished adapters rot (only kernel was published), and forces serial advancement when one-repo work could be parallel-within-session. Full reasoning: `C:/Users/mikey/.claude/projects/F--AI/memory/Feedback/feedback_consolidate_when_cant_juggle_repos.md`.
+
+## Working rules
+
+- **Read `ROADMAP.md` first.** It's the dispatch table for this repo.
+- **Read the global rules** at `C:/Users/mikey/.claude/CLAUDE.md` and the workspace rules at `E:/AI/.claude/CLAUDE.md` — they apply here too.
+- **Read the canonical memory store** at `C:/Users/mikey/.claude/projects/F--AI/memory/MEMORY.md` before any Write/Edit (enforced by hook).
+- The `loadout-hook` from session 2026-06-10 is live — it injects pointer lines on every prompt. Use them; don't paraphrase from the summaries.
+- Workflow standards apply: any new pipeline/script/SKILL.md needs the six-standards compliance block (`workflow_standards.md`).
+
+## Standards compliance — repo bootstrap
+
+This repo is a prototype clone-in, not a workflow. The six-standards rule applies to workflows authored INSIDE this repo (CI pipelines, swarm dispatchers, multi-step builds), not to the bootstrap itself.
+
+## Quick orientation
+
+- `packages/kernel/` — published as `@mcptoolshop/ai-loadout@1.4.3`. Stable API surface (`matchLoadout`, `planLoad`, `resolveLoadout`, `recordLoad`). Don't break this.
+- `packages/memories/` — CLI `claude-memories` (installed globally from this directory's upstream). Commands: `analyze`, `index`, `validate`, `stats`, `health`.
+- `packages/rules/` — CLI `claude-rules` (installed globally from upstream). Commands: `analyze`, `split`, `validate`, `stats`, `init-signals`.
+- `apps/hook/` — Node project, single mjs entrypoint, depends on `@mcptoolshop/ai-loadout` (npm). When Phase 1 lands, swap to a workspace dep on `packages/kernel`.

.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+coverage/
+.nyc_output/
+.turbo/
+.cache/
+*.log
+.DS_Store
+Thumbs.db
+.env
+.env.local
+*.tsbuildinfo

README.md

@@ -0,0 +1,33 @@
+# memory-os
+
+> **Prototype, 2026-06-10.** Consolidated Knowledge OS for the studio — folds `ai-loadout` (kernel) + `claude-memories` (MEMORY.md adapter) + `claude-rules` (CLAUDE.md adapter) + the runtime UserPromptSubmit pointer-injection hook into a single repo. Not yet wired as workspaces, not yet published, not yet on a remote.
+
+## Pickers start here
+
+- Read [`.claude/CLAUDE.md`](.claude/CLAUDE.md) — project instructions and source-of-truth rules
+- Read [`ROADMAP.md`](ROADMAP.md) — five-phase consolidation plan, ~1–2 months of session work
+- Then dive in
+
+## Layout
+
+```
+memory-os/
+├── packages/
+│   ├── kernel/       # was @mcptoolshop/ai-loadout (npm 1.4.3 — only one published)
+│   ├── memories/     # was @mcptoolshop/claude-memories (unpublished)
+│   └── rules/        # was @mcptoolshop/claude-rules (unpublished)
+├── apps/
+│   └── hook/         # mirror of ~/.claude/loadout-hook/ (the LIVE one)
+├── .claude/
+│   └── CLAUDE.md
+├── ROADMAP.md
+└── README.md
+```
+
+## Why consolidate
+
+Decompose-by-secrets (Parnas 1972) was the clean answer for a team of N humans. The studio runs 1 human + LLM crew — multi-repo work fragments Claude context across sessions and lets unpublished adapters rot. One named umbrella repo serves the operator. Full reasoning: `memory/Feedback/feedback_consolidate_when_cant_juggle_repos.md` in the canonical memory store.
+
+## License
+
+MIT (matches all three upstream sources).

ROADMAP.md

@@ -0,0 +1,90 @@
+# memory-os — ROADMAP
+
+> Estimated horizon: **1–2 months** of session work to reach shippable.
+> Picker: whoever opens the next session in this tree. Read `.claude/CLAUDE.md` first.
+
+## Phase 0 — Initial bootstrap (DONE, this commit)
+
+- [x] Clone in the three upstream sources (`ai-loadout`, `claude-memories`, `claude-rules`) under `packages/`
+- [x] Clone in the runtime hook under `apps/hook/`
+- [x] Drop CLAUDE.md and this ROADMAP for the next picker
+- [x] `git init` + initial commit (no remote yet — that's Phase 5)
+
+Out of scope for the bootstrap: no workspace wiring, no shared tests, no docs site, no remote, no publish.
+
+## Phase 1 — Workspace wiring (1 session)
+
+Goal: make the four trees install + build + test under one root.
+
+- [ ] Root `package.json` with `workspaces: ["packages/*", "apps/*"]`
+- [ ] One root `tsconfig.base.json` extended by each package
+- [ ] Each package keeps its own `package.json`, but versions follow the root version
+- [ ] `apps/hook` swaps its `@mcptoolshop/ai-loadout` dep for `"@memory-os/kernel": "workspace:*"`
+- [ ] `npm ci` at the root produces a working install; `npm run build --workspaces` builds all four
+- [ ] Each package's existing test suite still runs (`npm test --workspaces`)
+
+Gate: green build at root, all existing tests pass, hook still injects when invoked with stdin JSON.
+
+## Phase 2 — Unified CLI surface (1–2 sessions)
+
+Goal: one `memory-os` binary that wraps the three CLI surfaces.
+
+- [ ] New `packages/cli/` with `bin: { "memory-os": "..." }`
+- [ ] Subcommands:
+  - `memory-os memories <index|validate|stats|health>` — wraps `packages/memories/`
+  - `memory-os rules <analyze|split|validate|stats>` — wraps `packages/rules/`
+  - `memory-os resolve|explain|usage|dead|overlaps|budget|validate` — wraps `packages/kernel/`
+  - `memory-os hook test` — drives `apps/hook` with a sample prompt
+- [ ] Old binaries (`claude-memories`, `claude-rules`, `ai-loadout`) get thin shim binaries that delegate + emit a deprecation warning for one minor release
+- [ ] `--help` is complete and accurate (Hard Gate C of shipcheck)
+
+Gate: shipcheck `init` + `audit` runs cleanly on the new CLI; hard gates A–D green.
+
+## Phase 3 — Docs + landing (1 session)
+
+Goal: one Starlight handbook + one landing page covers the whole layer.
+
+- [ ] `site/` at the root, Astro + Starlight (use the `handbook` skill)
+- [ ] Sections: Kernel, Memories, Rules, Runtime hook, Migration from the three legacy packages
+- [ ] Single landing page replaces the three separate `mcp-tool-shop-org.github.io/{ai-loadout,claude-memories,claude-rules}/` pages
+- [ ] CNAME + GitHub Pages wiring (Phase 5 dependency — actual deploy after publish)
+
+## Phase 4 — npm + GitHub bootstrap (1 session)
+
+Goal: reserve the name on npm, set up Trusted Publishing, create the GitHub repo.
+
+- [ ] Reserve `@mcptoolshop/memory-os` via the `npm-placeholder` skill (v0.0.0 placeholder + OIDC config)
+- [ ] Create `mcp-tool-shop-org/memory-os` on GitHub (private at first; flip to public at Phase 5 publish)
+- [ ] Add remote, push the initial bootstrap commit + Phases 1–3 commits
+- [ ] CI workflow: lint + test on push (per workflow-standards.md — paths-gated, ubuntu-latest, concurrency block)
+
+## Phase 5 — First real publish + upstream retirement (1 session)
+
+Goal: ship `@mcptoolshop/memory-os@1.0.0`, retire the three upstream repos.
+
+- [ ] Shipcheck full audit (`memory/shipcheck.md`)
+- [ ] Run translations BEFORE publish (per the release-ordering rule in global CLAUDE.md)
+- [ ] `npm publish` via Trusted Publishing
+- [ ] `gh release create v1.0.0`
+- [ ] Cut over `~/.claude/settings.json` hook command from `node ~/.claude/loadout-hook/loadout-hook.mjs` to `npx @mcptoolshop/memory-os hook` (or equivalent)
+- [ ] Deprecate the three upstream npm names (only `ai-loadout` is published; npm-deprecate that one with a pointer to memory-os)
+- [ ] Archive the three upstream local repos at `E:/AI/{ai-loadout,claude-memories,claude-rules}/` — move to `E:/DEEP_MEMORY/retired/` with a README explaining where they went
+- [ ] Delete `~/.claude/loadout-hook/` once the npx-based hook is verified working
+
+Gate: shipcheck 31/31, CI green, hook works through `npx @mcptoolshop/memory-os hook`, no broken pointer chains anywhere in the studio.
+
+## Out of scope (for now)
+
+- Replacing the kernel's matching algorithm with embeddings — separate research project; possibly a `memory-os/research/` tree later
+- Multi-rig sync of `~/.ai-loadout/index.json` — out of scope until there's a second rig
+- Web UI for browsing the dispatch table — nice-to-have, not in the critical path
+
+## Open questions (for the director)
+
+- Naming: keep `memory-os` or rebrand at Phase 4? (Sister names in the studio: Game Foundry OS, Research OS, Testing OS — pattern is consistent.)
+- Should the kernel CLI surface (`ai-loadout resolve`, etc.) be preserved verbatim under `memory-os resolve`, or restructured? Verbatim = lower migration cost; restructured = chance to fix any ergonomics warts.
+- License — three sources are all MIT, root stays MIT?
+
+## When this is done
+
+When all five phases pass, this file is the source-of-truth for "what shipped"; flip it to a CHANGELOG-style retrospective and start the next iteration.

apps/hook/loadout-hook.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// UserPromptSubmit hook — inject pointers (not payloads) to relevant memory entries.
+//
+// Design (FIXED — see kickoff 2026-06-10):
+//   • Read ~/.ai-loadout/index.json (refreshed by the freshness ritual in CLAUDE.md)
+//   • matchLoadout(prompt, index) against it
+//   • Emit AT MOST 5 entries as one-line pointers: "- <id> — <summary> → <path>"
+//   • Total additionalContext kept ≤ ~200 tokens
+//   • Below-threshold match  emit nothing (silent)
+//   • Always-record loaded events to ~/.ai-loadout/usage.jsonl
+//
+// Off-switch: AI_LOADOUT_HOOK=off  no-op exit 0.
+// Latency budget: < 500 ms cold. Never blocks.
+
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+if (process.env.AI_LOADOUT_HOOK === 'off') {
+  process.exit(0);
+}
+
+const HOME = homedir();
+const INDEX_PATH = resolve(HOME, '.ai-loadout', 'index.json');
+const USAGE_PATH = resolve(HOME, '.ai-loadout', 'usage.jsonl');
+const MAX_ENTRIES = 5;
+const MAX_LINE_CHARS = 180;
+
+function readStdinSync() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function safeExit(code) {
+  try { process.exit(code); } catch { /* ignore */ }
+}
+
+function clip(s, n) {
+  if (!s) return '';
+  s = String(s);
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1).trimEnd() + '…';
+}
+
+async function main() {
+  if (!existsSync(INDEX_PATH)) { safeExit(0); return; }
+
+  const stdin = readStdinSync();
+  let payload;
+  try { payload = JSON.parse(stdin); } catch { safeExit(0); return; }
+  const prompt = (payload.prompt || payload.user_prompt || payload.message || '').toString();
+  if (!prompt.trim()) { safeExit(0); return; }
+
+  let index;
+  try { index = JSON.parse(readFileSync(INDEX_PATH, 'utf8')); } catch { safeExit(0); return; }
+
+  let matchLoadout;
+  try {
+    ({ matchLoadout } = await import('@mcptoolshop/ai-loadout'));
+  } catch {
+    safeExit(0); return;
+  }
+
+  let results;
+  try { results = matchLoadout(prompt, index); } catch { safeExit(0); return; }
+  const top = (results || []).filter(r => r && r.entry && r.entry.priority !== 'manual').slice(0, MAX_ENTRIES);
+  if (top.length === 0) { safeExit(0); return; }
+
+  const lines = top.map(r => {
+    const id  = r.entry.id || '(unnamed)';
+    const sum = r.entry.summary || '';
+    const pth = r.entry.path || '';
+    return clip(`- ${id} — ${sum} → ${pth}`, MAX_LINE_CHARS);
+  });
+
+  const additionalContext =
+    '[loadout-hook] Memory entries relevant to this prompt (open the file pointer before acting, do not paraphrase from the summary):\n' +
+    lines.join('\n');
+
+  // Record usage (best-effort; never block)
+  try {
+    if (!existsSync(dirname(USAGE_PATH))) mkdirSync(dirname(USAGE_PATH), { recursive: true });
+    const ts = new Date().toISOString();
+    const taskHash = (payload.prompt_id || payload.session_id || '').toString().slice(0, 12) || ts.replace(/[-:.TZ]/g, '').slice(0, 14);
+    const events = top.map(r => JSON.stringify({
+      timestamp: ts,
+      taskHash,
+      entryId: r.entry.id,
+      trigger: 'UserPromptSubmit',
+      mode: r.mode || 'lazy',
+      tokensEst: r.entry.tokens_est || 0
+    })).join('\n') + '\n';
+    appendFileSync(USAGE_PATH, events, 'utf8');
+  } catch { /* swallow */ }
+
+  process.stdout.write(JSON.stringify({
+    suppressOutput: true,
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext
+    }
+  }));
+  safeExit(0);
+}
+
+main().catch(() => safeExit(0));

apps/hook/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "loadout-hook",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "UserPromptSubmit hook that injects pointers to relevant memory entries from ~/.ai-loadout/index.json",
+  "main": "loadout-hook.mjs",
+  "scripts": {
+    "test": "node loadout-hook.mjs"
+  },
+  "dependencies": {
+    "@mcptoolshop/ai-loadout": "^1.4.3"
+  }
+}

apps/hook/smoke-test.ps1

@@ -0,0 +1,36 @@
+$ErrorActionPreference = 'Continue'
+$hook = 'C:/Users/mikey/.claude/loadout-hook/loadout-hook.mjs'
+
+$prompts = @(
+  @{ label = '1. GAME prompt (Star Freight visual canon)';
+     payload = @{ prompt = 'I want to update the Star Freight visual canon — the Renna identity packet needs a new portrait variant. Open the right canon paths and the workflow profile.' } },
+  @{ label = '2. TOOL prompt (shipcheck a repo before publish)';
+     payload = @{ prompt = 'Run shipcheck audit on the role-os repo before npm publish — full treatment afterwards if it passes.' } },
+  @{ label = '3. GENERIC prompt (mundane filesystem)';
+     payload = @{ prompt = 'list the files in the current directory' } }
+)
+
+foreach ($p in $prompts) {
+  Write-Output ('=' * 78)
+  Write-Output $p.label
+  Write-Output ('=' * 78)
+  $body = $p.payload | ConvertTo-Json -Compress
+  $start = [System.Diagnostics.Stopwatch]::StartNew()
+  $out = $body | & node $hook 2>$null
+  $start.Stop()
+  $ms = $start.ElapsedMilliseconds
+  if (-not $out -or $out.Trim().Length -eq 0) {
+    Write-Output "(silent — no pointer injection)"
+  } else {
+    try {
+      $parsed = $out | ConvertFrom-Json
+      $ctx = $parsed.hookSpecificOutput.additionalContext
+      Write-Output $ctx
+    } catch {
+      Write-Output "RAW OUTPUT: $out"
+    }
+  }
+  Write-Output ""
+  Write-Output ("latency: {0} ms" -f $ms)
+  Write-Output ""
+}