🌐 English · 한국어

Hermes Memory Stack

One-command, choice-driven memory and knowledge bootstrap for Hermes Agent.

Hermes Memory Stack installs an optional layered memory and knowledge environment for fresh Hermes Agent setups. It can add skills, Axiom Perception MCP, llmwiki modes, Hindsight routing helpers, optional NotebookLM integration, optional source-pack automation, and optional code/log helpers without bundling user secrets.

Important

This repository does not bundle API keys, OAuth tokens, Google cookies, personal memory, or private config. The installer asks what to enable and keeps user-controlled secrets in ~/.hermes/.env.

At a glance

Layer	What it adds
Skills	Reusable operating procedures for Hermes memory-stack workflows
Axiom Perception MCP	Procedural execution-pattern cache for repeated UI/workflow tasks
llmwiki	API-free, extraction, local/OAuth bridge, or hybrid knowledge modes
Hindsight routing	Optional durable-memory provider routing helpers
NotebookLM	Optional external source-grounded workspace and inventory sync
Source packs	Optional public-docs bundling workflow for NotebookLM refreshes
semble_rs	Optional codebase exploration and log digest helper

Quick Install

Review-first mode:

git clone https://github.com/yelixir-dev/hermes-memory-stack
cd hermes-memory-stack
./install.sh

One-command mode:

curl -fsSL https://raw.githubusercontent.com/yelixir-dev/hermes-memory-stack/main/install.sh | bash

30-second proof after install:

hermes skills list | grep -E 'yorha-hermes-memory-stack|notebooklm|native-mcp'
test -f ~/.hermes/config.yaml && echo "Hermes config present"

Expected result: at least one installed memory-stack skill or integration route is listed, and Hermes still has a config file after the backed-up patch step.

What It Can Install

• Hermes skills for memory-stack operating policy
• Axiom Perception MCP as a procedural execution-pattern cache
• llmwiki in API-free, extraction-only, local/OAuth bridge, or hybrid embedding mode
• Hindsight/Hermes memory routing helpers
• optional semble_rs for codebase exploration and log digest
• optional NotebookLM CLI for source-grounded external research
• optional NotebookLM → llmwiki inventory sync after NotebookLM is authenticated
• optional NotebookLM source-pack helper for public docs roots, gated behind nlm-pack and manual NotebookLM auth
• optional Hermes auxiliary model routing template

Design Principles

1. Choice-first — no forced external APIs.
2. API-free mode exists — useful for private/local users.
3. NotebookLM is optional — Google login and external service usage are never required.
4. Secrets stay local — use .env, never commit real keys.
5. Config is backed up — ~/.hermes/config.yaml is copied before patching.
6. Layer separation:
   • Hermes memory / Hindsight: personal durable facts
   • session_search: past conversation recall
   • skills: reusable procedures
   • Axiom: empirical execution patterns
   • llmwiki: shared agent knowledge
   • NotebookLM: optional external source workspace
   • semble_rs: optional code/log helper

Install Profiles

Minimal

• skills
• Axiom Perception MCP
• no external API
• no NotebookLM

API-free

• skills
• Axiom Perception MCP
• llmwiki markdown/wiki mode
• optional semble_rs
• no external API required

Full / Selectable

• Hindsight routing wizard
• llmwiki mode wizard
• Axiom
• optional semble_rs
• optional NotebookLM
• optional auxiliary routing

NotebookLM

NotebookLM support is optional and off by default.

If enabled, the installer installs the CLI and browser dependencies, then prints manual login instructions:

notebooklm login
notebooklm auth check --test --json
notebooklm list --json

After NotebookLM is authenticated, the optional inventory sync can write a compact routing map to:

~/wiki/_meta/notebooklm-inventory.md

This sync stores notebook names, IDs, source titles/URLs/statuses, and very short summaries only. It does not copy source bodies or any auth state. If selected, it installs:

~/.hermes/scripts/sync_notebooklm_inventory.py
~/.hermes/scripts/install_notebooklm_inventory_sync.sh

and creates a silent Hermes cron job when authentication is already active.

No Google cookie, storage_state.json, or account credential is bundled or copied.

NotebookLM source-pack automation

NotebookLM source-pack automation is a second-level opt-in path, not a default install step. The workflow is: install NotebookLM support, authenticate manually, then optionally enable a source-pack helper that turns a public documentation root into bundled Markdown NotebookLM sources with manifest-based refresh.

Memory Stack does not implement the crawler/bundler itself. It installs and refreshes the independent Source Pack Builder from GitHub by default:

uv tool install "git+https://github.com/yelixir-dev/notebooklm-source-pack-builder.git@main" --force

The safe CLI contract used after the GitHub install/update is:

nlm-pack sync <pack-name> --config <config.yaml> --no-upload --json
nlm-pack refresh <pack-name> --config <config.yaml> --versioned --upload --json

Packaged files:

config/notebooklm-source-pack.example.yaml
scripts/install-notebooklm-source-pack-sync.sh

If selected during NotebookLM setup, the installer copies these to:

~/.hermes/notebooklm-source-packs/examples/notebooklm-source-pack.example.yaml
~/.hermes/scripts/install_notebooklm_source_pack_sync.sh

Cron/upload activation requires all of the following first: the GitHub-based builder install/update step succeeds, a user-edited config has an explicit notebooklm.notebook_id, and a manual auth check passes:

notebooklm login
notebooklm auth check --test --json

The integration plan and boundaries are tracked in NOTEBOOKLM_SOURCE_PACKS.md:

• public docs/source roots only by default;
• no Google cookies, storage_state.json, OAuth tokens, private browser profiles, or source bodies in this repo;
• script-only Hermes cron that stays silent on no-op refreshes;
• compact NotebookLM inventory sync back to llmwiki after deploy/refresh;
• NotebookLM Automation / Source Pack Builder remains an independent project with its own implementation and tests.

Hindsight / Memory Routing

The installer can:

• keep existing memory settings
• if the default Hermes provider is GPT OAuth (openai-codex), ask whether Hindsight should reuse the current local GPT OAuth bearer token for local-embedded LLM calls
• record intent to reuse existing Hermes OAuth/provider/bridge where possible
• configure an OpenAI-compatible endpoint via env-var reference
• skip memory changes

GPT OAuth reuse is opt-in and local-only. The installer copies the current OAuth access token from ~/.hermes/auth.json into local Hindsight/Hermes env files so Hindsight's embedded daemon can call the same GPT endpoint; no token is bundled or committed. If the OAuth token expires or Hermes is re-authenticated, rerun the installer or refresh the Hindsight env. Other provider/OAuth reuse remains provider-specific; when direct token reuse is not possible, use an OpenAI-compatible bridge or LiteLLM proxy.

llmwiki Modes

• skip
• API-free markdown/wiki mode
• external OpenAI-compatible extraction
• local/OAuth bridge extraction
• hybrid extraction + embedding endpoint

Embedding is optional. Users can choose no embeddings, external embeddings, or a local embedding endpoint.

Repository Layout

NOTEBOOKLM_SOURCE_PACKS.md
install.sh
uninstall.sh
scripts/
  patch-config.py
  write-llmwiki-env-shim.py
  sync-notebooklm-inventory.py
  install-notebooklm-inventory-sync.sh
  install-notebooklm-source-pack-sync.sh
config/
  env.template
  notebooklm-source-pack.example.yaml
  profiles/
skills/
  hermes-memory-stack/
  llm-wiki/
  axiom-perception/
  semble-rs/
  notebooklm/

Uninstall / Restore

If you want to remove a one-command install or roll back the config, run the uninstall helper.

One-command uninstall/restore:

curl -fsSL https://raw.githubusercontent.com/yelixir-dev/hermes-memory-stack/main/uninstall.sh | bash

Review-first mode:

git clone https://github.com/yelixir-dev/hermes-memory-stack
cd hermes-memory-stack
./uninstall.sh

The uninstaller is also choice-driven. It can:

• remove stack skills copied into ~/.hermes/skills
• remove helper scripts under ~/.hermes/scripts
• remove stack-owned NotebookLM inventory/source-pack cron jobs
• optionally remove ~/wiki/_meta/notebooklm-inventory.md
• remove the perception MCP registration
• optionally restore the latest ~/.hermes/config.yaml.bak.*
• optionally uninstall notebooklm-py, semble_rs, and llm-wiki-compiler

It does not remove Hermes Agent itself, personal memory, sessions, auth files, Google cookies, or unrelated user config.

Troubleshooting

curl | bash runs without letting me choose

This should not happen in a normal terminal. The installer reads wizard input from /dev/tty when the script itself is piped through stdin:

curl -fsSL https://raw.githubusercontent.com/yelixir-dev/hermes-memory-stack/main/install.sh | bash

If there is no interactive TTY at all, the installer falls back to safe defaults and prints a warning. For fully interactive setup on unusual terminals, use clone mode:

git clone https://github.com/yelixir-dev/hermes-memory-stack
cd hermes-memory-stack
./install.sh

Axiom Perception MCP reports No such file or directory: 'uvx axiom-perception-mcp'

Use split command/args form, not a single quoted shell string:

hermes mcp add perception --command uvx --args axiom-perception-mcp

The installer uses this split form. If uvx itself is missing, install uv first and rerun the MCP add command.

Security

This repository intentionally avoids bundling secrets, OAuth tokens, browser storage, personal memory, or private Hermes config. See SECURITY.md for the reporting policy and security boundaries. For private security reports, use the GitHub Security Advisory form at https://github.com/yelixir-dev/hermes-memory-stack/security/advisories/new or email yelixir.dev@gmail.com.

Contributing

Issues and pull requests are welcome. Please keep contributions aligned with the stack boundaries: no committed credentials, no private source bodies, no Google cookies/browser state, and no forced external API dependency.

Acknowledgements

This integration pack references and optionally installs upstream projects including:

• Hermes Agent — https://github.com/NousResearch/hermes-agent
• Axiom Perception MCP — https://github.com/vdalhambra/axiom-perception-mcp
• llm-wiki-compiler — https://github.com/atomicmemory/llm-wiki-compiler
• semble_rs — https://github.com/johunsang/semble_rs
• notebooklm-py — https://github.com/teng-lin/notebooklm-py

See ACKNOWLEDGEMENTS.md for details. This repo is an integration/bootstrap layer; upstream projects retain their own licenses and authorship.