yepyhun/Brainstack

Brainstack

Hermes-native local-first donor-grounded

Brainstack gives Hermes a memory model instead of a memory blob.

It is a composite MemoryProvider for persistent agents: profile memory, session continuity, temporal graph truth, and corpus retrieval under one memory owner inside Hermes.

It is built from three proven memory lines, then adapted into a Hermes-native kernel:

• Hindsight gives bounded continuity and after-turn learning.
• Graphiti gives temporal graph truth, relations, and conflict handling.
• MemPalace gives large-corpus retrieval and packed evidence recall.

Brainstack's job is not to copy those projects loosely. Its job is to keep their useful invariants, put them behind one Hermes memory owner, and make every important memory decision inspectable.

The installer also carries the Hermes integration path Brainstack needs for stateful conversation. It keeps runtime ownership in Hermes while installing the memory seam, doctor checks, and optional compatibility support required by the kernel.

Optional bonus: this repo also includes a Hermes Proactive Extension under extensions/hermes_proactive/. It is not part of the Brainstack memory kernel. The wizard can install it only when explicitly requested, so operators can decide whether they want heartbeat/PulseProducer/Evolver-style proactivity on top of Brainstack. Brainstack provides the memory projection SDK; Hermes owns the runtime behavior. The extension itself uses stdlib plus Brainstack; it can read Evolver health signals, but it does not silently install Evolver or its dependencies.

The promise is simple:

• better long-horizon memory for always-on Hermes agents
• less prompt sludge from blind transcript stuffing
• cleaner truth handling when preferences, facts, and large recalled bodies need different treatment
• one wizard path from fresh Hermes clone to memory-aware, Gateway-ready runtime

This repo is for people building serious Hermes-based second-brain systems. It is not trying to pretend that transcript search, vector recall, and profile tables are the same job.

Core foundation

Brainstack's foundation stays donor-grounded:

Additional patterns also shape current code:

• Hermes-LCM for bounded transcript evidence fallback

How a query flows through Brainstack

User query
   |
   v
Risk + intent check
   |
   +--> profile recall      -> preferences, identity, stable user facts
   +--> continuity recall   -> recent session state, pending context
   +--> graph recall        -> current facts, relations, temporal truth
   +--> corpus recall       -> larger external knowledge and packed evidence
   +--> transcript fallback -> only bounded raw evidence when needed
   |
   v
Control plane packs the smallest useful evidence set
   |
   v
Hermes answers
   |
   v
After-turn learning updates the right shelf, not one giant memory blob

In plain language:

• Brainstack first decides what kind of question this is.
• Then it pulls from the right shelves instead of dumping everything into the prompt.
• Hermes gets a small, purpose-built evidence packet.
• After the answer, the new information is written back to the right place.

Why Brainstack exists

Most agent memory stacks fail in predictable ways:

• they flatten profile, transcript, graph, and corpus into one blob
• they overwrite old facts instead of tracking change over time
• they split memory ownership across multiple subsystems that quietly disagree with each other
• they solve recall by stuffing more and more text back into the prompt

Brainstack takes the opposite approach:

• one live memory owner
• clear separation of responsibilities
• bounded evidence instead of transcript abuse
• temporal truth handled explicitly, not as an afterthought

Transcript is evidence. Graph is truth. Corpus is corpus. Profile is profile. That sounds obvious, but most agent memory systems blur those lines. Brainstack keeps them separate so Hermes can answer with less noise and less accidental false confidence.

What Brainstack is trying to do

• be one of the strongest practical local-first memory stacks for always-on Hermes agents
• combine temporal continuity, graph truth, and corpus retrieval in one system
• keep memory ownership inside Brainstack instead of letting three half-systems fight each other
• stay useful in real deployed runs, not just in architecture diagrams

Current status

• runs inside Hermes-Agent as a direct MemoryProvider plugin
• augments Hermes through the native explicit-memory seam instead of replacing builtin user/profile writes
• keeps memory ownership in Brainstack while storage is split by responsibility
• uses SQLite for shell, session, profile, transcript, and lexical fallback state
• supports embedded Kuzu for L2 graph truth and reports explicitly if it is unavailable
• supports embedded Chroma for L3 semantic corpus retrieval and reports explicitly if it is unavailable
• proves explicit capture with receipt-backed writes instead of trusting an assistant saying "saved"
• ships a public-safe regression corpus for memory correctness without private Discord or canary data
• emits evidence traces showing what entered the packet, what was dropped, and why
• keeps runtime handoff read-only from Brainstack's side; scheduling, execution, approval, and provider behavior remain Hermes/runtime responsibilities

Quickstart

Dry-run compatibility check:

python install_into_hermes.py /path/to/hermes-agent --enable --doctor --dry-run --runtime docker

Real install:

python install_into_hermes.py /path/to/hermes-agent --enable --doctor --runtime docker

Local non-Docker install:

python install_into_hermes.py /path/to/hermes-agent --enable --doctor --runtime local

After install, run the doctor and confirm that Brainstack is the active memory provider.

For profile isolation, supported config shapes, and the optional proactive extension state paths, see Install And Profile Isolation.

Donor boundaries

The donor base is important, but the product value is the integration boundary: Hermes sees one memory kernel, while Brainstack keeps the underlying jobs separate.

That boundary matters:

• donors provide proven memory semantics
• Brainstack adapts them into Hermes-native shelves and contracts
• Hermes remains the runtime owner for scheduling, tools, approval, and provider behavior
• transcript fallback stays bounded raw evidence, not a second memory engine

What Brainstack adds on top

Using the donors directly would still leave a lot of hard integration work in the host.

Brainstack adds the parts that make the system usable in a real Hermes agent instead of only looking good in a diagram:

• one live memory owner inside Hermes
• explicit shelf separation instead of a flat memory blob
• current truth, historical truth, and conflict state kept distinct
• bounded packing discipline so recall helps the turn instead of flooding it
• host-aware install, doctor, and boundary tooling so the memory layer can actually survive real runtime drift
• public proof fixtures and evidence traces so regressions can be checked without private data

Current runtime architecture

Brainstack routes memory into five shelves instead of a flat memory blob:

Under those shelves, storage is split by responsibility:

On top of the shelves, Brainstack uses owner-first evidence assembly:

• high-stakes questions should not bluff from memory alone
• explicit profile questions should prefer compact native or mirrored profile recall
• temporal and explanatory questions should expand continuity and graph evidence
• transcript recall stays bounded and session-scoped
• graph recall keeps current truth, historical truth, inferred links, and conflicts separate instead of flattening them together

What is already working

This repo is no longer just an architecture sketch.

What is currently true:

• the plugin runs inside Hermes as a real MemoryProvider
• native explicit writes stay host-owned and can be mirrored into Brainstack
• explicit multi-rule packs can remain as raw archival truth without requiring compiled behavior-policy re-growth
• ordinary turns no longer depend on a Brainstack-specific communication-governor lane
• graph, transcript, continuity, and corpus shelves remain distinct instead of collapsing into one flat memory blob
• doctor output distinguishes active backends from explicit degraded states instead of treating silent fallback as success
• release hygiene tooling rejects tracked private runtime state, local planning state, and high-confidence secret-shaped payloads
• recent-work operating truth is workstream-scoped so project status and agent assignments do not collapse into one canonical memory
• workstream recap evidence is typed and scoped, so compact operating state can anchor recap answers before broad continuity or corpus fallback
• explicit scoped workstream recap capture can create idempotent operating anchors without guessing workstream identity from prose
• store substrate checks expose schema and migration-ledger health through the doctor surface
• explicit backup/restore helpers and migration dry-run reports support safer local upgrades
• traceable retrieval-candidate diagnostics expose selected and suppressed evidence without changing the default prompt packet
• a shadow global allocator can inspect how a tighter evidence budget would behave before it becomes live behavior
• local markdown/wiki files can enter the corpus shelf through explicit allowlisted source adapters instead of raw prompt stuffing
• shelf-aware export and dry-run import reports make memory moves inspectable, redacted, and mutation-free by default
• the installer recognizes Hermes' native interrupted-turn external-memory guard, so Brainstack follows the upstream host seam instead of forcing a stale local patch
• public-safe memory fixtures reproduce the critical failure classes without leaking live Discord data
• evidence traces expose proof chains from source span to packet selection
• token-cost baseline reports measure selected and dropped public evidence cost without enabling a new optimizer

Release posture:

• Brainstack is optimized for native Hermes integration first
• donor refreshes are explicit and reviewable, not silent rewrites
• benchmark artifacts are treated as supporting evidence, not runtime authority
• public payloads exclude private runtime state, local auth, sessions, and planning files

Repo scope

This repository is a focused Brainstack slice containing:

• the Hermes-native Brainstack plugin code under brainstack/
• donor boundaries and refresh logic under brainstack/donors/ and scripts/
• minimal host-compatibility payload under host_payload/agent/
• install and doctor tooling for Hermes checkouts

This repository intentionally does not ship Hermes host files like:

• run_agent.py
• agent/prompt_builder.py
• tools/memory_tool.py
• gateway/session.py
• private runtime trees such as hermes-config/
• local planning/workflow state such as .planning/

If a live defect is rooted in explicit-truth capture, transport metadata precedence, or user-surface greeting behavior, the fix belongs on the Hermes host seam unless it can be shown to be a true Brainstack provider defect.

Repo layout

brainstack/
docs/
host_payload/agent/
scripts/
brainstack_doctor.py
install_into_hermes.py
update_hermes_with_brainstack.py

Included operational tooling

Reproducible quality gates

Use these gates before publishing a release or changing memory-kernel behavior:

python -m pip install -r requirements-dev.txt
python -m pytest -q
python -m ruff check .
python -m mypy brainstack scripts tests --explicit-package-bases --ignore-missing-imports
python scripts/brainstack_golden_recall_eval.py
python scripts/brainstack_multilingual_multimodal_gate.py
python scripts/check_release_hygiene.py --repo .
python install_into_hermes.py --help
python brainstack_doctor.py --help

The tracked test suite is paired with install and doctor smoke checks because Brainstack is a Hermes plugin: release readiness means the code passes locally and the target Hermes seam still verifies.

Installation into Hermes

Brainstack is meant to be installed into a fresh Hermes checkout, not copied around by hand.

Dry-run compatibility check:

python install_into_hermes.py /path/to/hermes-agent --enable --doctor --dry-run --runtime docker

By default the installer uses --host-patch-mode core, which applies only Brainstack payload/config/dependency work plus minimal memory-provider seams. Use --host-patch-mode compat only for explicit host-runtime compatibility hotfixes, and --host-patch-mode legacy only for emergency rollback/testing of the previous broad host patch behavior.

The installer also uses --gateway-patch-mode auto by default. This detects whether the target Hermes checkout already contains the required Gateway TurnContract/tool-profile/context-budget/SLO/renderer support. If upstream support is missing, it applies the bundled Hermes Gateway patch set and records the bundle hash in .brainstack-install-manifest.json. Use --gateway-patch-mode skip only when you intentionally want raw upstream Hermes without the optimized Discord gateway path.

Real install:

python install_into_hermes.py /path/to/hermes-agent --enable --doctor --runtime docker

Local non-Docker install:

python install_into_hermes.py /path/to/hermes-agent --enable --doctor --runtime local

What the installer does:

Safety boundaries:

• unknown upstream host changes are surfaced through doctor checks
• secrets, private Hermes runtime config, local auth, session state, and .planning/ stay out of release payloads
• donor refreshes stay explicit and inspectable
• API-first deployment remains separate from the Hermes-native plugin path

Upstream Hermes refresh workflow

When Hermes upstream changes, the intended flow is:

python update_hermes_with_brainstack.py /path/to/hermes-agent --pull --reinstall --doctor --runtime local

If the target runtime is Dockerized and the Docker image bakes Hermes source into the image, rebuild after reinstall:

python update_hermes_with_brainstack.py /path/to/hermes-agent --pull --reinstall --doctor --docker-rebuild --runtime docker

Current updateability is the middle path:

• explicit donor registry
• explicit local adapter seams
• bounded refresh reporting
• local smoke verification
• runtime overrides are preserved across pull/reinstall by default, including compression, discord, proactive_mode, and proactive_kill_switch

Use --no-preserve-runtime-overrides only when you intentionally want the target Hermes config to accept upstream or installer defaults for those blocks.

That keeps donor drift inspectable without turning updates into silent rewrites.

Docker helper after install

cd /path/to/hermes-agent
./scripts/hermes-brainstack-start.sh start
./scripts/hermes-brainstack-start.sh rebuild
./scripts/hermes-brainstack-start.sh full
./scripts/hermes-brainstack-start.sh purge
./scripts/hermes-brainstack-start.sh reset
./scripts/hermes-brainstack-start.sh status
./scripts/hermes-brainstack-start.sh logs

The helper is intentionally small:

• start brings the stack up
• rebuild rebuilds with cache and restarts
• full does a no-cache pull, build, and restart
• stop stops the running service
• purge clears conversational persistence, including Brainstack DB, state DB, and session replay files
• reset purges conversational persistence and starts again
• status shows compose status plus readiness summary from gateway_state.json
• logs tails live logs

start, rebuild, and full wait for readiness instead of claiming success as soon as the container exists. purge and reset ask for an explicit DELETE confirmation before wiping memory and session state.

Doctor checks

brainstack_doctor.py is designed to fail closed.

It validates that the target checkout still looks like Hermes, that the provider/plugin loader surfaces exist, that Brainstack is present and importable, that Hermes native explicit-memory surfaces remain enabled, and that config selects Brainstack without replacing the host's builtin profile write path. It also probes configured Kuzu and Chroma backend openability, checks read-only runtime handoff surfaces, and treats missing requested capabilities as explicit degraded states. In docker mode it checks readiness-aware health wiring and recognizes upstream-style runtime ownership normalization. In local mode it skips the Docker-specific assumptions.

If Hermes upstream removes a required provider surface, the correct outcome is an explicit incompatibility report, not a silent partial install.

Current direction

The current corrective direction is narrow and concrete:

• keep Brainstack on the memory/state/policy side of the Hermes boundary
• reduce installer host edits toward native Hermes seams wherever upstream already provides the surface
• make backend degradation, runtime handoff, and recall packet selection inspectable before claiming confidence
• keep exact-fact, recent-work, and stale-residue handling universal rather than live-case-specific
• keep recent-work authority scoped by workstream instead of promoting unscoped idle summaries as canonical truth

Legal Terms

Brainstack is proprietary source-available software: only personal, non-commercial, local use is permitted by default; all commercial, company/internal, hosted, redistribution, integration, derivative-product, model-training, and sublicensing use requires prior written permission. See LEGAL.md.