Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
77 lines (53 loc) · 2.4 KB

TROUBLESHOOTING.md

File metadata and controls

77 lines (53 loc) · 2.4 KB
Raw

Troubleshooting

Skills don't show up in Hermes

Skills load at session start. After ./setup, start a new Hermes session. Still missing?

  • Check they were installed: ls ~/.hermes/skills/brainstack/ (should list 13 directories, each with a SKILL.md).
  • If your Hermes home is elsewhere, re-run with it set: HERMES_HOME=/path/to/hermes ./setup.
  • Pre-existing skills named capture, memory, index, etc. can shadow the brainstack ones — rename or remove yours first.

brain: command not found

Setup symlinks the CLI into ~/.local/bin. Make sure that's on your PATH:

export PATH="$HOME/.local/bin:$PATH"   # add to your shell rc

Or call it directly: ~/.brainstack/bin/brain help.

The agent writes to the wrong vault

Everything reads BRAINSTACK_VAULT. Check ~/.brainstack/env.sh, fix the path, and source ~/.brainstack/env.sh. The skills also honor the vault path recorded there.

Search returns weak results

Without sentence-transformers, search falls back to keyword TF vectors — functional but coarser. Upgrade to real embeddings:

python3 -m venv ~/.brainstack/venv
~/.brainstack/venv/bin/pip install sentence-transformers
brain index --rebuild

(brain automatically prefers ~/.brainstack/venv when it exists.)

Also rebuild after large imports: the index doesn't watch the filesystem.

The dream cycle isn't running

  • crontab -l | grep dream-cycle — no line means cron install was skipped (--no-cron, or no crontab on the machine). Re-run ./setup or add the printed line manually.
  • Logs live at ~/.brainstack/dream-cycle.log.
  • On macOS, grant cron Full Disk Access if the vault is under ~/Documents.
  • Run it by hand any time: brain dream.

git push fails on brain sync

brain sync commits locally and only pushes if a remote exists — an offline push never fails the sync. Add a remote once:

cd "$BRAINSTACK_VAULT" && git remote add origin <url> && git push -u origin main

Vault health score is low

Run brain doctor and fix in the order it reports — broken links and Iron Law violations first, then orphans. The health skill can drive the fixes conversationally.

Upgrading / uninstalling

brain upgrade     # git pull + non-destructive re-setup
brain uninstall   # removes skills, engine, cron — never the vault

Something else? Open an issue: https://github.com/criptogus/brainstack/issues