Skip to content

WORKSPACE.md

Latest commit

 

History

History
418 lines (297 loc) · 16.6 KB

WORKSPACE.md

File metadata and controls

418 lines (297 loc) · 16.6 KB

Hermes Memory Stack Workspace Notes

Purpose: this file is the handoff map for a fresh Hermes/Emil session that opens this repository independently. Read this before editing the project.

1. What this project is

yelixir-dev/hermes-memory-stack is a one-command, choice-driven bootstrap pack for Hermes Agent. It installs and configures an optional layered memory / knowledge / execution-pattern environment for a fresh or existing Hermes setup.

The repository is not a dump of Yorha's private Hermes state. It is an integration/distribution layer that helps a user enable selected components safely:

  • Hermes skills for memory-stack operating policy.
  • Axiom Perception MCP for empirical UI/procedural execution-pattern caching.
  • Hindsight as the personal durable memory backend.
  • llmwiki as a markdown/wiki-style shared knowledge map.
  • NotebookLM CLI as an optional source-grounded external workspace.
  • NotebookLM → llmwiki inventory sync as an optional routing map.
  • semble_rs as an optional codebase/log exploration helper.
  • Auxiliary model routing templates for Hermes helper tasks.

The pack is designed around choice-first installation:

  • No forced external API.
  • API-free modes exist.
  • NotebookLM and Google login are optional.
  • Secrets stay local.
  • ~/.hermes/config.yaml is backed up before patching.
  • Uninstall/restore helpers remove only stack-owned files.

2. Repository identity

  • Public GitHub repo: yelixir-dev/hermes-memory-stack
  • Current local path on Yorha's machine: /Users/yorha/dev/hermes-memory-stack
  • Remote used locally: git@github.com-hermes:yelixir-dev/hermes-memory-stack.git
  • Main branch: main
  • Preferred commit identity: yElixir / yelixir-dev, email yelixir.dev@gmail.com

3. High-level architecture

The project has three main surfaces:

  1. Installer / uninstaller

    • install.sh
    • uninstall.sh
    • helper scripts under scripts/

  2. Distributed skills

    • skills/hermes-memory-stack/
    • skills/axiom-perception/
    • skills/llm-wiki/
    • skills/notebooklm/
    • skills/semble-rs/

  3. Public documentation and shareable visual assets

    • README.md
    • ACKNOWLEDGEMENTS.md
    • SECURITY.md
    • EVOLUTION.md
    • docs/*.png

The repo intentionally keeps public generated visual output PNG-only and places infographic PNGs directly under docs/. Temporary HTML used for rendering belongs under .tmp/ and must be deleted after render. Source images and cardnews images are internal-only and live under .internal/; do not commit them.

4. Important files and what they do

Root files

install.sh

Main installer. It is intended to work both in clone/review mode and in one-command mode:

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

or:

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

Important behaviors:

  • Keeps output plain ASCII so minimal terminals do not render ANSI escape codes literally.
  • Reads prompts from /dev/tty when invoked via curl | bash.
  • Fetches the full repo tarball in one-command mode so bundled skills/scripts are available.
  • Backs up ~/.hermes/config.yaml before patching.
  • Installs bundled skills into ~/.hermes/skills/.
  • Configures Hindsight / memory routing.
  • Optionally installs/configures llmwiki.
  • Optionally registers Axiom Perception MCP with split command/args form: hermes mcp add perception --command uvx --args axiom-perception-mcp
  • Optionally installs semble_rs via cargo.
  • Optionally installs NotebookLM CLI via uv tool install 'notebooklm-py[cookies,browser]'.
  • Optionally installs NotebookLM inventory sync helper.
  • Planned: optionally installs NotebookLM source-pack automation only after the user separately opts in; the builder is installed/updated from GitHub (yelixir-dev/notebooklm-source-pack-builder) rather than Yorha's internal working tree; see NOTEBOOKLM_SOURCE_PACKS.md.
  • Optionally patches Hermes auxiliary routing.
  • Runs smoke tests at the end.

Recent feature: if the default Hermes provider is GPT OAuth (openai-codex) and an OpenAI Codex OAuth token exists in ~/.hermes/auth.json, configure_hindsight() asks whether to connect Hindsight local-embedded LLM calls to that current GPT OAuth token. If accepted, it calls:

python3 scripts/patch-config.py \
  --hindsight-mode gpt-oauth-reuse \
  --hindsight-auth-json "$HERMES_HOME/auth.json"

This is opt-in and local-only. Tokens are not committed or bundled.

uninstall.sh

Choice-driven uninstall / restore helper. It can remove stack-owned files and optionally restore the latest Hermes config backup. It must not remove Hermes itself, sessions, auth files, personal memory, Google cookies, or unrelated user config.

README.md

Public bilingual documentation. Keep it user-facing and practical:

  • Quick install
  • What the pack can install
  • Design principles
  • Install profiles
  • NotebookLM behavior
  • NotebookLM source-pack automation plan
  • Hindsight / memory routing
  • llmwiki modes
  • Uninstall / restore
  • Troubleshooting
  • Acknowledgements

Do not fill it with maintainer-only internal notes. Put workspace/development notes in this file instead.

ACKNOWLEDGEMENTS.md

Upstream projects and authorship/license references. Update it when adding or removing upstream integrations.

SECURITY.md

Security policy and secret-handling expectations. Update this if installer behavior changes how tokens or credentials are handled.

EVOLUTION.md

Project-evolution notes. Use sparingly; detailed operational handoff should go in WORKSPACE.md.

CRONJOBS.md

Snapshot of Yorha's current Hermes cron jobs relevant to this project/workspace. When a user asks about cron jobs or scheduled updates, read this file first, then run hermes cron list or the cronjob tool to refresh live state.

NOTEBOOKLM_SOURCE_PACKS.md

Planning boundary for integrating NotebookLM Source Pack Builder into Memory Stack. It defines the opt-in installer path, cron/update strategy, safety boundaries for cookies/auth, and llmwiki inventory update rules. This is a plan document; the source-pack builder remains an independent project until its CLI contract is stable.

scripts/

scripts/patch-config.py

Best-effort Hermes config patcher. It keeps secrets out of committed files and writes only to the user's local Hermes home at install time.

Key modes:

  • --hindsight-mode oauth-reuse

    • Records provider/OAuth reuse intent in config.

  • --hindsight-mode openai-compatible

    • Patches Hindsight-related config for an OpenAI-compatible endpoint via env-var reference.

  • --hindsight-mode gpt-oauth-reuse

    • Reads the local Hermes auth file.
    • Finds an OpenAI Codex / GPT OAuth access token.
    • Sets Hermes memory provider to Hindsight.
    • Writes $HERMES_HOME/hindsight/config.json for Hindsight local_embedded mode.
    • Writes local env values to $HERMES_HOME/.env.
    • Writes the embedded-daemon env file under ~/.hindsight/profiles/hermes.env.
    • Does not store the token in the repo.

  • --detect-gpt-oauth

    • Exits 0 when the default Hermes provider is GPT OAuth and a usable token exists.
    • Used by install.sh to decide whether to show the GPT OAuth reuse prompt.

  • --aux-provider / --aux-model

    • Patches Hermes auxiliary helper tasks to a named provider/model.

scripts/write-llmwiki-env-shim.py

Writes a helper env shim for llmwiki extraction/embedding configuration.

scripts/sync-notebooklm-inventory.py

Collects NotebookLM notebook/source inventory into a compact routing map. It does not copy full source bodies or auth state.

scripts/install-notebooklm-inventory-sync.sh

Installs the NotebookLM inventory sync as a Hermes cron job after NotebookLM authentication is active.

scripts/generate-infographics.py

Deterministically generates temporary HTML for documentation infographics.

Important project rules:

  • Public output names use 언어_페이지순서_페이지제목, e.g. eng_01_overall.png and kor_05_references.png.
  • Public infographic PNGs are placed directly under docs/; do not use docs/infographics/ or docs/assets/ for the GitHub-facing layout.
  • The NieR:Automata HELP theme is the preferred visual tone: warm beige grid, muted gray-brown panels, thin technical linework, dusty low-chroma accents, quiet manual/help UI mood, compact source/profile block.
  • Optional local reference images live under .internal/assets/ or another directory supplied through HERMES_MEMORY_STACK_ASSET_DIR; these assets are not committed.

scripts/render-infographics.js

Uses Playwright/Chromium to render generated HTML into PNGs and create a contact sheet. HTML render sources are temporary.

config/

config/env.template

Example env names only. Never commit real secrets. Includes placeholder names such as:

  • HINDSIGHT_LLM_API_KEY
  • LLMWIKI_API_KEY
  • LLMWIKI_EMBEDDINGS_API_KEY
  • POD_00_LITELLM_KEY
  • COMMANDCODE_BRIDGE_API_KEY

config/profiles/minimal.yaml

Minimal profile: lightweight start, typically skills + Axiom, no forced external API.

config/profiles/api-free.yaml

API-free profile: local/wiki-oriented operation without mandatory external LLM APIs.

config/profiles/full.yaml

Full/selectable profile: enables the broadest set of optional configuration paths.

skills/

Bundled skills copied into ~/.hermes/skills/ by the installer.

skills/hermes-memory-stack/SKILL.md

Operating policy for the overall stack.

skills/axiom-perception/SKILL.md

Axiom Perception MCP usage: procedural execution-pattern cache, not long-term factual memory.

skills/llm-wiki/SKILL.md

llmwiki usage: markdown/shared knowledge map.

skills/notebooklm/SKILL.md

NotebookLM usage: optional source-grounded external research workspace.

skills/semble-rs/SKILL.md

semble_rs usage: codebase/log exploration helper.

docs/

docs/

Public shareable overview images live directly here. Current naming convention:

eng_01_overall.png
eng_02_minimal.png
eng_03_normal.png
eng_04_advanced.png
eng_05_references.png
kor_01_overall.png
kor_02_minimal.png
kor_03_normal.png
kor_04_advanced.png
kor_05_references.png

Rules:

  • PNG-only infographic files in public docs.
  • No HTML left here.
  • Do not keep separate docs/infographics/ or docs/assets/ folders unless Yorha changes the publishing rule.
  • The renderer writes the QA contact sheet to .internal/contact-sheet.png; do not commit it.
  • Regenerate with:
python3 scripts/generate-infographics.py
node scripts/render-infographics.js

.internal/ and .tmp/

Local-only working areas on Yorha's machine. .internal/ is ignored and must not be committed.

  • .internal/assets/: optional source images for local infographic rendering, such as yelixir-profile.png and yelixir-pod-friend.png.
  • .internal/cardnews/: Korean internal cardnews PNGs and renderer.
  • .internal/cardnews_eng/: English internal cardnews PNGs and renderer.
  • .tmp/: temporary render HTML or scratch files.

These are excluded locally and should not be committed unless Yorha explicitly changes the rule.

5. Security and privacy rules

  1. Never commit API keys, OAuth tokens, cookies, storage_state.json, personal memory, or private Hermes config.
  2. install.sh may read local auth/config files only at install time and only to configure the user's local machine.
  3. GPT OAuth reuse for Hindsight is opt-in. It copies a local access token into local env files so Hindsight can use the same GPT endpoint.
  4. If GPT OAuth expires, the user should re-authenticate Hermes and rerun the installer/config step.
  5. NotebookLM is optional and requires manual browser login. The pack does not bundle Google credentials.
  6. NotebookLM source-pack automation must remain a second-level opt-in path and must not upload private/local corpora unless the user explicitly asks.
  7. Axiom Perception is treated as a procedural pattern cache, not as factual memory.
  8. Hindsight durable memory should contain stable user/environment facts, not temporary task progress.

6. Verification checklist before pushing

Run these before committing installer/config changes:

bash -n install.sh
bash -n uninstall.sh
python3 -m py_compile scripts/*.py

For a safe config-patcher smoke test, use a temporary HERMES_HOME:

tmp_home="$(mktemp -d)"
mkdir -p "$tmp_home"
cat > "$tmp_home/config.yaml" <<'YAML'
model:
  default: gpt-5.5
  provider: openai-codex
  base_url: https://chatgpt.com/backend-api/codex
memory: {}
YAML
cat > "$tmp_home/auth.json" <<'JSON'
{
  "active_provider": "openai-codex",
  "credential_pool": {
    "openai-codex": [
      {"access_token": "test-token", "base_url": "https://chatgpt.com/backend-api/codex"}
    ]
  }
}
JSON
hindsight_home="$(mktemp -d)"
HERMES_HOME="$tmp_home" HINDSIGHT_HOME="$hindsight_home" python3 scripts/patch-config.py --detect-gpt-oauth
HERMES_HOME="$tmp_home" HINDSIGHT_HOME="$hindsight_home" python3 scripts/patch-config.py \
  --hindsight-mode gpt-oauth-reuse \
  --hindsight-auth-json "$tmp_home/auth.json"

For visual artifacts:

python3 scripts/generate-infographics.py
node scripts/render-infographics.js
test ! -d docs/assets
test ! -d docs/infographics
test ! -e docs/contact-sheet.png
test -e .internal/contact-sheet.png
find docs -name '*.html' -print  # must print nothing

Inspect .internal/contact-sheet.png with vision or manually before reporting success; do not commit the contact sheet.

7. Common edit patterns

Adding a new optional integration

  1. Add a bundled skill under skills/<integration>/SKILL.md.
  2. Add installer option in install.sh.
  3. Add helper scripts under scripts/ if needed.
  4. Update README.md in both English and Korean sections.
  5. Update ACKNOWLEDGEMENTS.md if an upstream project is referenced.
  6. Update SECURITY.md if credentials/auth/cookies are involved.
  7. Run syntax checks and any relevant smoke tests.
  8. Commit and push only intentional files.

Adding NotebookLM source-pack automation

  1. Keep NotebookLM CLI support and source-pack automation as separate prompts.
  2. Install/update the Source Pack Builder from its GitHub repo (https://github.com/yelixir-dev/notebooklm-source-pack-builder.git) and do not depend on Yorha's internal working tree.
  3. Require manual notebooklm login and notebooklm auth check --test --json before upload or cron activation.
  4. Store only secret-free source-pack manifests: URL, title, hash, source ID, timestamps, and status.
  5. Install refresh as a Hermes script-only cron so unchanged refreshes produce no output.
  6. Run the NotebookLM inventory sync after successful deploy/refresh so llmwiki receives a compact routing map.
  7. Update uninstall.sh to remove only stack-owned scripts/cron registrations, not user notebooks, cookies, browser profiles, or source-pack data unless explicitly requested.

Updating cron-related automation

  1. Read CRONJOBS.md first.
  2. Run hermes cron list or use the cronjob tool for live state.
  3. Update CRONJOBS.md if jobs are created, removed, paused, or materially changed.
  4. Do not create recursive cron jobs.
  5. Keep Stage 1 internal-stack updates and Stage 2 project updates separate.

Updating infographics or cardnews

  1. Use deterministic HTML/CSS → PNG rendering.
  2. Follow language-first filenames: eng_01_title.png, kor_01_title.png.
  3. Keep public docs PNG-only.
  4. Use the NieR:Automata HELP theme.
  5. Render a contact sheet.
  6. Inspect for clipping, overlap, tofu boxes, missing images, and theme drift.

8. Open TODOs / future work

  • Add a more robust token-refresh story for GPT OAuth → Hindsight reuse. Current behavior copies the current access token; if the OAuth token expires, rerun the installer after Hermes re-authentication.
  • Consider adding an explicit non-interactive installer flag for GPT OAuth reuse once the behavior has been battle-tested.
  • Expand automated tests around scripts/patch-config.py if the repo grows a formal test suite.
  • Keep CRONJOBS.md synchronized with live Hermes cron state whenever scheduled jobs are changed.
  • Continue refining public infographics and internal cardnews as Yorha requests.

9. Session handoff prompt suggestion

For a new independent thread/session, start with:

Load the `yorha-hermes-memory-stack` skill. Then read /Users/yorha/dev/hermes-memory-stack/WORKSPACE.md and CRONJOBS.md first. Inspect git status before editing. This repo is the Hermes Memory Stack one-command install pack; use the SSH remote git@github.com-hermes:yelixir-dev/hermes-memory-stack.git; do not commit secrets, source assets, contact sheets, or internal cardnews folders.