brainstack

A production-tested second brain for Hermes Agent: capture, typed
memory, retrieval, and nightly consolidation — 14 native skills, a small
Python engine, and one brain CLI. All Markdown, no SaaS, no telemetry.

Your agent captures notes, but nothing ever gets consolidated. Notes rot in
an inbox, memories are a flat dump of context, links break, and the "brain"
forgets what it knew last week. brainstack is the operating system that fixes
that: a proven pipeline where every conversation becomes a durable,
connected, retrievable memory.

Built and battle-tested in production over months of daily use with
Hermes Agent. MIT licensed.

Install (30 seconds)

git clone --single-branch --depth 1 https://github.com/criptogus/brainstack.git ~/brainstack && cd ~/brainstack && ./setup

That's it. The setup script:

1. Installs the 14 skills into ~/.hermes/skills/brainstack/ — Hermes loads
   them on the next session.
2. Scaffolds vault-template/ into your vault (or creates ~/brain-vault).
   Non-destructive: existing files are never overwritten.
3. Installs the engine to ~/.brainstack/ and links the brain CLI into
   ~/.local/bin.
4. Wires the nightly dream-cycle cron (skip with --no-cron).

Useful flags: --vault PATH · --no-cron · --dry-run ·
--embeddings (real semantic search via a local venv) · --version.

Requirements: Hermes Agent ·
Python 3.10+ · git · Obsidian optional (it's all plain Markdown).

Upgrade / remove: brain upgrade pulls the latest and re-installs;
brain uninstall removes everything except your vault.

Zero personal data. brainstack ships no content from anyone's real
vault. The templates are empty skeletons.

See it work

After setup, open a new Hermes session and just talk:

• "Process my inbox" → capture turns every PDF/article/clipping in
  00-Inbox/ into linked atomic notes.
• "Signal: ship beats perfect" → signal stores your thought verbatim,
  with an ID.
• "Ingest this meeting transcript" → meetings extracts decisions and
  action items with provenance.
• "What does the brain know about Acme?" → retrieval answers from the
  vault before touching any external API.
• "Run a health check" → health scores the vault and prioritizes fixes.

And from the shell, one entry point for the whole engine:

brain inbox            # process 00-Inbox into atomic notes
brain search "pricing" # hybrid semantic search
brain doctor           # scored vault health report
brain dream            # run the nightly consolidation now
brain sync             # git commit + push the vault
brain help             # everything else

The stack

Deep dives on every skill, with trigger phrases and how they chain:
docs/SKILLS.md.

Plus bin/ — the engine: memory compiler, semantic index/search,
dream-cycle runner, inbox processor, vault health checker, session
consolidator, decision logger — and a ready-made
vault-template/ with the folder skeleton (including the
00-Hermes/ operating layer: contexts, decisions, memory, workers), note
templates, and frontmatter schemas that make the whole thing work.

Why it works

Three layers, like a real brain:

REAL-TIME CAPTURE (during the conversation)
        │  every decision, correction, preference, insight
        ▼
NIGHTLY CONSOLIDATION (the dream cycle)
        │  dedupe, backlink repair, decay, contradiction detection
        ▼
CROSS-SESSION INTELLIGENCE (weekly)
        │  patterns → procedures → reusable skills
        ▼
              a brain that gets STRONGER over time

The details — typed memory schema, decay rules, the Iron Law of backlinks,
NOW.md, the Tree Index, the dream cycle — are documented in
ARCHITECTURE.md. It's the part you'll want to steal.

Requirements

• Hermes Agent (the skills are native
  Hermes skills with metadata.hermes frontmatter)
• Obsidian (or any Markdown folder - the system is plain files + git)
• Python 3.10+
• git (recommended for sync; optional otherwise)

Install as Agent Skills

Every skill is also in the standard Agent Skills format,
so you can install them individually with the standard CLI:

npx skills add criptogus/brainstack --all

Documentation

• docs/SKILLS.md — every skill in depth: pipeline, triggers, CLI mapping
• ARCHITECTURE.md — the brain: layers, agent architecture, schemas, rules, lifecycle
• AGENTS.md — the vault "operating agreement" template (drop into any vault)
• REPLICATION.md — replicate the system anywhere (the architecture travels; the knowledge does not)
• RELEASING.md — versioning and release procedure (SemVer + tags + changelog)
• docs/adr/ — architecture decision records (the why behind every structural choice)
• docs/TROUBLESHOOTING.md — skills not loading, cron, search, PATH
• docs/CONTRIBUTING.md — how to contribute

Troubleshooting (the short version)

• Skills missing? They load on the next Hermes session; check
  ~/.hermes/skills/brainstack/.
• brain not found? Put ~/.local/bin on your PATH.
• Weak search? Re-run ./setup --embeddings, then brain index --rebuild.

More in docs/TROUBLESHOOTING.md.

Roadmap

• [x] brain CLI: one entry point for all bin/ scripts
• [x] Upgrade & uninstall: brain upgrade / brain uninstall
• [x] Versioned releases — SemVer + VERSION + git tags + CHANGELOG (v1.0.0)
• [x] Documented architecture — ARCHITECTURE.md v2 + 8 ADRs
• [x] Replication playbook — docs/REPLICATION.md (new machine / new person / team)
• [ ] Hermes desktop plugin: sidebar pane for the Tree Index
• [ ] Cron pack: one command to wire the full nightly/weekly cron set

License

MIT — do anything you want, keep the attribution.

brainstack: give your Hermes a brain that doesn't forget.