hermes-memory-stack

name	hermes-memory-stack
description	Use when installing, configuring, or explaining the Hermes Memory Stack: a layered optional memory/input bootstrap for Hermes Agent with skills, Axiom Perception MCP, llmwiki, Hindsight routing, optional semble_rs, and optional NotebookLM.
version	0.1.0
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["hermes","memory","rag","mcp","llmwiki","hindsight","bootstrap"],"related_skills":["llm-wiki","axiom-perception","semble-rs","notebooklm"]}}

Hermes Memory Stack

Overview

Hermes Memory Stack is a layered bootstrap for fresh Hermes Agent installations. It separates durable personal memory, reusable procedures, shared agent knowledge, UI execution patterns, code exploration, and external source-grounded research.

The stack is intentionally optional and privacy-preserving: no API keys, OAuth tokens, Google cookies, personal memory, or NotebookLM auth state are bundled.

Layer Map

• Hermes memory / Hindsight — personal preferences and durable environment facts.
• session_search — recall of past conversations.
• skills — reusable procedures and operating policies.
• Axiom Perception MCP — procedural execution-pattern cache for UI/browser/native workflows.
• llmwiki — shared markdown/semantic knowledge base for agents.
• semble_rs — optional codebase exploration and noisy log digest CLI.
• NotebookLM — optional Google-account external source-grounded research workspace; not core memory.
• NotebookLM inventory sync — optional post-auth cron flow that writes compact notebook/source maps to ~/wiki/_meta/notebooklm-inventory.md for routing decisions.

Install Pattern

Use the repo installer:

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

Safer review-first mode:

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

Uninstall / Restore Pattern

Use the bundled uninstaller when the user wants to remove or roll back the stack:

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

It should remove only stack-owned artifacts by default: bundled skills, helper scripts, the NotebookLM inventory cron job, optional perception MCP registration, and optionally the NotebookLM routing inventory file. It should snapshot the current config first, then optionally restore the latest ~/.hermes/config.yaml.bak.*. It must not remove Hermes Agent itself, personal memory, sessions, auth files, Google cookies, or unrelated user config.

Configuration Philosophy

The installer should always follow this sequence:

1. Detect Hermes and prerequisites.
2. Back up ~/.hermes/config.yaml before patching.
3. Ask the user which integrations they want.
4. Install only selected components.
5. Keep secrets in ~/.hermes/.env; never write real secrets to repo files.
6. Leave NotebookLM login as a manual browser step.
7. If NotebookLM is selected and later authenticated, optionally install the inventory sync helper and Hermes cron job.
8. Run smoke tests and print remaining manual steps.
9. For child CLIs that ask follow-up questions (for example hermes mcp add tool enable prompts), attach stdin to /dev/tty under curl | bash; otherwise the child sees EOF and prints Cancelled.

Recommended Modes

• Minimal — skills + Axiom, no external API.
• API-free — skills + Axiom + llmwiki markdown mode + optional semble_rs.
• Local-first — local/OAuth bridge for extraction; optional local embeddings.
• LiteLLM/OpenAI-compatible — explicit endpoint + env-var based keys.
• Full — all selectable components, with NotebookLM still optional.

Organic Improvement Pattern

Use compact routing metadata to make the pack more proactive without polluting durable personal memory:

1. Keep large/full source corpora in their native systems such as NotebookLM.
2. Sync only compact maps into llmwiki, especially under ~/wiki/_meta/.
3. Patch skills when a workflow becomes reusable or a pitfall is discovered.
4. Record Axiom outcomes for UI/browser/native workflow patterns.
5. Add periodic doctor/inventory scripts before adding more always-on memory.

Recommended inventory files:

• _meta/notebooklm-inventory.md — NotebookLM notebooks, source titles/URLs/status, short summaries.
• _meta/mcp-inventory.md — configured MCP servers and what they are for.
• _meta/skills-inventory.md — stack skills and load triggers.
• _meta/providers-inventory.md — provider names and env-var references only, never keys.

Common Pitfalls

1. Do not treat NotebookLM as Hermes memory. It is an external source workspace.
2. Do not bundle Google cookies, storage state, OAuth tokens, or API keys.
3. Do not force external APIs; provide API-free and local-first modes.
4. Do not overwrite a user's config without a timestamped backup.
5. Do not assume Hermes OAuth can be read directly by every tool; route through a provider/bridge when needed.
6. For curl ... | bash, read wizard input from /dev/tty; stdin is occupied by the piped script.
7. For Axiom Perception MCP, register command/args separately: hermes mcp add perception --command uvx --args axiom-perception-mcp. Do not pass "uvx axiom-perception-mcp" as one command string.
8. When a child CLI asks its own prompt under curl | bash, redirect its stdin from /dev/tty; otherwise it may immediately say Cancelled even though the user did not choose cancel.

Verification Checklist

• hermes config check passes or reports only expected missing user choices.
• Installed skills exist under ~/.hermes/skills.
• If Axiom was selected, hermes mcp list shows perception.
• If llmwiki was selected, llmwiki or llmwiki-stack is available.
• If semble_rs was selected, semble_rs --help works.
• If NotebookLM was selected, user has been instructed to run notebooklm login manually.
• If NotebookLM inventory sync was selected, _meta/notebooklm-inventory.md exists after auth and the Hermes cron job is listed.