System Audit

IDENTITY: Auditor.InventoryScanner. Run parallel checks across all package managers (brew,pip,npm,pnpm,node,git,softwareupdate) and compile a single structured update report. Law: NeverUpgradeSystemPip — it breaks macOS. WHENUSE: UserAsks{CheckUpdates,WhatsOutdated,AnythingNeedUpgrading,SystemMaintenance}. ESPECIALLY:AfterMajorHermesUpdate->PostUpdateVerification{PluginHealth+ToolHealth}. NoSkip:PostUpdateSmokeTests. REDFLAGS: SystemPipOutdated->FlagButLeaveAlone|nvmNotFound->ShellFunctionNotExecutable|pnpmCorepack->GlobalVersionMayNotMatter|GitHubRateLimited->UseBrewInfoFallback. RATIONALIZATIONS: UpgradeSystemPythonLibs->BreaksMacOS|SkipPostUpdateCheck->PluginMayBeBroken|JustShowRawLog->GroupIntoSections{NoAction,UpdateAvail,DontTouch}. QUICKREF: Scan{Homebrew{formulae+casks}->pip+pipx->npm+pnpm+yarn->node{LTS+latest}->KeyCLI{gh,bun,tmux,pnpm}->GitRepos->macOSSoftwareUpdate}->Compile{GroupBySection->NoteVersionDelta->FlagMajorVsMinor}->Verify{PluginHealth{hermes plugins list+hermes tools list}->GitPluginIntegrity->SmokeTestCriticalTools}.

Run this when the user asks a general "what's outdated" / "check for updates" / "anything need upgrading" question. Covers all package managers and common sources of updates on a macOS system.

Order of Checks

Run these in parallel where possible, then compile a single report.

1. Homebrew (formulae + casks)

brew outdated                  # formula updates
brew outdated --cask          # cask updates (GUI apps)

Check both. brew outdated auto-updates taps so you get current data.

2. pip / pipx

# System Python pip (be careful - upgrading system libs can break macOS)
python3 -m pip list --outdated --format=columns

# pipx-managed tools
pipx list 2>/dev/null

3. npm / pnpm / yarn

# Global npm packages
npm ls -g --depth=0

# pnpm version vs latest on npm
pnpm --version
npm view pnpm version

# yarn version vs latest on npm
yarn --version
npm view yarn version

4. Node.js version

node --version
# Check latest LTS:
curl -s https://nodejs.org/dist/index.json | python3 -c \
  "import sys,json; d=json.load(sys.stdin); lts=[v for v in d if v['lts']]; print(lts[0]['version'], lts[0]['lts'])"
# Check latest overall:
curl -s https://nodejs.org/dist/index.json | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(d[0]['version'])"

5. Key CLI tools

For each tool installed, check version vs latest release:

# gh CLI
gh --version
curl -sI https://github.com/cli/cli/releases/latest | grep -i location | sed 's/.*tag\///'

# bun
bun --version
curl -sI https://github.com/oven-sh/bun/releases/latest | grep -i location | sed 's/.*tag\///'

# tmux
tmux -V
curl -sI https://github.com/tmux/tmux/releases/latest | grep -i location | sed 's/.*tag\///'

# pnpm
pnpm --version
curl -sI https://github.com/pnpm/pnpm/releases/latest | grep -i location | sed 's/.*tag\///'

6. Cloned git repos

Find manually cloned repos and check if they're behind upstream:

find ~ -maxdepth 3 -name ".git" -type d 2>/dev/null | grep -v hermes-workspace | grep -v ".nvm" | head -20

For each: cd in, git remote -v, git fetch --dry-run, git log --oneline HEAD..origin/main (or master).

7. macOS system updates

softwareupdate --list

8. Mnemosyne Memory System

Check Mnemosyne health and dependency status:

# Quick status check
hermes memory              # shows plugin status, active provider

# Check installed version vs PyPI latest
~/.hermes/hermes-agent/venv/bin/pip3 show mnemosyne-memory 2>/dev/null | grep Version
# Compare with https://pypi.org/project/mnemosyne-memory/

# Key deps for full hybrid search (vector + FTS5 + importance):
# - mnemosyne-memory: core package (v3.1.0+)
# - fastembed: semantic embeddings (BAAI/bge-small-en-v1.5)
# - sqlite-vec: vector similarity search in SQLite
# Without fastembed+sqlite-vec, falls back to FTS5 keyword-only search.

To install/upgrade (skip llama-cpp-python — it builds from source on Intel Mac):

~/.hermes/hermes-agent/venv/bin/pip3 install mnemosyne-memory fastembed sqlite-vec

Post-install: A Hermes restart is required — the running agent process loads deps at startup, so newly installed packages won't be detected until restart.

Pitfall: pip install "mnemosyne-memory[all]" includes llama-cpp-python and ctransformers which build from source and hang on Intel Macs. Install core + fastembed + sqlite-vec individually instead.

Compilation Rules

• Group into sections: "No action needed" / "Updates available" / "Don't touch"
• For "Don't touch", explain why (e.g. system Python libs break macOS)
• For "Updates available", note the version delta
• Flag major version jumps vs minor patches
• If a tool's installed version matches latest, say so

Pitfalls

• System Python pip is deliberately old (21.x). Upgrading it or setuptools/wheel via pip can break macOS tools. Flag but recommend leaving alone unless something is actually broken.
• nvm is a shell function, not an executable — which nvm fails. Use NVM_DIR="$HOME/.nvm" or the nvm function if sourced.
• pnpm installed via corepack: the global version is controlled by corepack. Projects pin their own version via packageManager in package.json. Upgrading the global pnpm may have no practical effect.
• git fetch --dry-run fetches new refs but doesn't update HEAD — check origin/main vs HEAD after a real fetch.
• Some GitHub API calls (api.github.com/repos/.../releases/latest) may be rate-limited without authentication.
• ffmpeg version tags on GitHub don't use standard SemVer — check brew info ffmpeg for the version delta instead.
• Pip-installed plugins get wiped on venv recreation. If hermes update or a profile migration recreates the venv, packages installed via pip (not declared in requirements.txt) vanish. Known casualties: rtk-hermes (RTK command rewriting plugin), mnemosyne-memory (memory provider). After ANY venv recreation, run pip3 show rtk-hermes mnemosyne-memory and reinstall missing packages. Git-installed plugins in ~/.hermes/plugins/ are NOT affected — they survive venv changes.
• plugins.enabled can become a stringified JSON string. If set via hermes config set, the YAML value may become enabled: '["list","of","plugins"]' (a string) instead of a proper YAML list. The plugin loader may not parse this correctly. Fix: rewrite as a proper YAML list using Python yaml.dump. Always verify with grep -A 20 "^plugins:" config.yaml — the enabled list should show - item lines, not a single quoted string.
• mnemosyne-memory[all] builds llama-cpp-python from source which hangs on Intel Macs (>120s). Install core + key extras individually instead: pip install mnemosyne-memory fastembed sqlite-vec.

Example Output Structure

**No action needed — up to date:**
- gh v2.92.0 ✓
- bun v1.3.13 ✓

**Updates available:**
- ffmpeg: 8.1_1 → 8.1.1 (brew)
- macOS Sequoia 15.7.7 (system, requires restart)

**Don't touch:**
- System pip (21.2.4 → 26.0.1 available - upgrading breaks macOS)

Post-Update Verification

After upgrading anything, there are two follow-ups the user may want:

1. Plugin & Tool Health Check

Verify Hermes plugins and toolsets are still loaded and functional:

hermes plugins list       # check all plugins show "enabled"
hermes tools list          # check built-in and plugin toolsets show ✓ enabled
hermes memory              # check mnemosyne plugin is "installed ✓" and "active"

Critical: check pip-installed plugins survive venv changes:

# These get wiped if the venv was recreated during update
~/.hermes/hermes-agent/venv/bin/pip3 show rtk-hermes 2>&1
~/.hermes/hermes-agent/venv/bin/pip3 show mnemosyne-memory 2>&1
# If "not found", reinstall immediately

For git-installed plugins, verify the repo is intact:

ls $HERMES_HOME/plugins/<name>    # dir exists
cd $HERMES_HOME/plugins/<name> && git log --oneline -1   # git history intact

If any show as "not enabled" after an update, re-enable with:

hermes plugins enable <name>

2. Show What Changed in an Update

When the user asks "what changed from the version we had" for a git-pulled plugin or repo:

# If you know the OLD commit (e.g. from reflog or the previous tag):
cd <repo-path> && git log <old-ref>..HEAD --oneline --no-decorate

# If plugin has a plugin.yaml with version:
head -5 plugin.yaml   # check current version
git tag | tail -5     # see tags for changelog reference
git log --oneline <prev-tag>..HEAD   # changes between tags

# Alternative: find the previous state from reflog:
git reflog --date=iso | head -5      # shows when last pull/clone happened

Group the output by version/release (e.g., "v0.10.0 — key change, v0.10.1 — fix X") so the user gets a readable summary, not a raw log dump.

3. Smoke Test Critical Tools

For non-Hermes upgrades (brew formulas, etc.), do a quick sanity check:

<tool> --version         # confirm new version
<tool> --help            # basic invocation still works

Cross-reference against Hermes plugin dependencies — if the upgraded tool is used by any plugin, check the plugin's tool listing still shows ✓ enabled.

Reference Files

• references/post-update-sweep-checklist.md — quick parallel checklist for post-update verification, known recovery commands, and symptom→cause table.
• references/runtime-diagnostics.md — macOS runtime diagnostics: CPU hog identification, memory pressure checks, process tree tracing, daemon management. Use when the user says "my Mac is hot", "what's running", or "something is slow".