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

Capability	Skill	What it does
Capture	capture	Inbox → atomic note in under 30s. Smart extraction, never full dumps.
Typed memory	memory	Every fact has a type, confidence, TTL and provenance. Conflicts resolve, stale facts decay.
Retrieval	retrieval	Hybrid semantic search + the Iron Law of backlinks: a note that mentions an entity links back to it.
Consolidation	consolidate	The nightly "dream cycle": dedupe, backlink repair, contradiction detection, next-day priorities.
Reflection	reflect	A 5-stage pipeline that turns vault content into durable, connected knowledge.
Meetings	meetings	Ingest meeting notes with provenance, decisions and action items.
Signals	signal	Capture stray thoughts verbatim, with an ID — the original voice is the value.
Relationships	people-crm	A personal CRM as plain notes: people, companies, projects, interactions.
Health	health	Audit your vault: orphans, broken links, schema drift, index staleness.
Trackers	trackers	Track books, movies, series with a typed schema + INDEX.
Reference notes	reference	Author durable reference notes with standardized frontmatter.
Indexing	index	Maps of Content + a Tree Index that mirrors your growing knowledge graph.
Distillation	distill	Turn hard-won explorations into reusable skills.
Agents	agents	Delegate to isolated-context workers; enforce the credential boundary and context modes.

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

• brain CLI: one entry point for all bin/ scripts
• Upgrade & uninstall: brain upgrade / brain uninstall
• Versioned releases — SemVer + VERSION + git tags + CHANGELOG (v1.0.0)
• Documented architecture — ARCHITECTURE.md v2 + 8 ADRs
• 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.