Skip to content

EVOLUTION.md

Latest commit

 

History

History
132 lines (93 loc) · 6.09 KB

EVOLUTION.md

File metadata and controls

132 lines (93 loc) · 6.09 KB

Stack Evolution Model

Hermes Memory Stack is not only an installer. It is meant to become a small, self-improving operating layer around Hermes Agent.

Core Idea

Each component keeps doing what it is best at, but the stack maintains compact routing metadata so Hermes can choose the right tool more aggressively:

  • Hermes memory / Hindsight — durable personal facts and environment facts.
  • Skills — reusable procedures and policies.
  • Axiom Perception MCP — empirical UI/browser/native execution patterns.
  • llmwiki — shared markdown/semantic knowledge base and routing indexes.
  • NotebookLM — optional source-grounded external reference workspaces.
  • semble_rs — optional codebase/search/log signal extraction.
  • Hermes cron — lightweight scheduled maintenance.

The important pattern is: do not dump everything into memory. Store only compact maps, indexes, and summaries in the layer that helps routing.

NotebookLM → llmwiki Inventory Sync

When NotebookLM is installed and authenticated, the pack can install a periodic metadata sync:

NotebookLM notebooks/sources
  → compact inventory script
  → ~/wiki/_meta/notebooklm-inventory.md
  → Hermes can read the map before deciding whether to ask NotebookLM

The sync stores only:

  • notebook title
  • notebook ID
  • source titles
  • source URLs
  • source status/type
  • short NotebookLM-generated summary
  • keyword hints

It never stores:

  • Google cookies
  • storage_state.json
  • OAuth tokens
  • API keys
  • full source bodies
  • personal browser profile data

The installer only activates this flow when NotebookLM CLI exists and notebooklm auth check --test --json succeeds. If NotebookLM is installed but not logged in, the installer copies the helper script and prints the post-login activation command.

Organic Improvement Loops

1. Component inventory loop

Periodically write compact inventories into ~/wiki/_meta/:

  • _meta/notebooklm-inventory.md
  • _meta/mcp-inventory.md — MCP servers and tool names
  • _meta/skills-inventory.md — installed stack skills and when to load them
  • _meta/providers-inventory.md — named providers and safe routing notes, with env var names only

These files are not secrets. They are routing maps.

2. Skill refinement loop

When a task succeeds after non-trivial debugging:

  1. Capture the final working procedure as a skill or patch an existing skill.
  2. Add pitfalls that caused the debugging loop.
  3. Add verification commands.
  4. Keep one-session artifacts out of memory.

Hermes already has a curator concept for skill lifecycle maintenance. This pack should cooperate with that instead of inventing a second skill manager.

3. Pattern cache loop

For UI/browser workflows:

  1. Try to recall an Axiom Perception pattern before manual exploration.
  2. Execute and verify.
  3. Record success/failure outcome.
  4. Save improved patterns only when the workflow is stable and reusable.

4. Source-grounded reference loop

For external manuals, PDFs, websites, and research packs:

  1. Keep the large/full source corpus in NotebookLM or another source-grounded workspace.
  2. Keep only notebook/source maps in llmwiki.
  3. Ask NotebookLM only when the routing map says it is relevant.
  4. File durable synthesis back into llmwiki only when it is broadly useful.

4a. NotebookLM source-pack automation loop

A future source-pack helper can turn a documentation root URL into a maintained NotebookLM notebook:

  1. Accept a root URL plus scope rules, for example same domain and path prefix.
  2. Discover child pages from sitemap, llms.txt / llms-full.txt when available, and bounded same-site links.
  3. Extract clean Markdown with an LLM-friendly crawler/extractor such as crawl4ai or trafilatura.
  4. Store only a local manifest of URL, title, content hash, source ID, and last sync time; never store cookies or NotebookLM auth state in the repo.
  5. Create or select the target notebook through notebooklm-py / notebooklm CLI and add URL or bundled Markdown sources.
  6. Respect NotebookLM source limits by bundling small pages into grouped Markdown sources and splitting large docs across notebooks when needed.
  7. On a scheduled run, compare hashes and use a versioned-preservation refresh: keep existing sources, write a dated snapshot/history entry, and add only changed bundles as new dated sources. Do not delete/re-add old sources by default, because that can destroy NotebookLM source context.
  8. Sync the resulting notebook/source inventory back to llmwiki so Hermes can route future questions to the right notebook.

This should remain opt-in because NotebookLM is Google-hosted and the consumer automation path uses unofficial APIs. Enterprise users can use the official NotebookLM Enterprise API path instead when available.

5. Stack doctor loop

A future hermes-memory-stack doctor helper can check:

  • NotebookLM auth and inventory freshness
  • Axiom MCP registration
  • llmwiki CLI availability
  • Hindsight backend health
  • installed stack skills
  • stale or duplicate routing maps
  • accidental secrets in stack-managed files

Proposed Future Enhancements

  1. Activation manifest — ~/.hermes/memory-stack/manifest.json listing enabled components, health checks, and routing files.
  2. Meta inventory scripts — scheduled sync scripts for MCP, skills, providers, and cron jobs.
  3. NotebookLM source-pack helper — URL-root-to-notebook automation for public docs, with bounded crawling, manifest-based change detection, and scheduled refresh.
  4. Stack doctor — single command to check all enabled components.
  5. Stack upgrade command — pull new pack version, refresh scripts/skills, preserve local secrets.
  6. Skill patch suggestions — cron job that reviews recent successful workflows and suggests skill updates, but does not auto-edit without user approval.
  7. Disposable profile smoke tests — installer test harness using a temporary HERMES_HOME.

Privacy Rule

The stack should prefer compact, non-secret metadata over raw exports. If a data item would be sensitive when posted to a public GitHub issue, it should not go into stack-managed shared maps by default.