Memory Management & Context Engines
Relevant source files
The following files were used as context for generating this wiki page:
- agent/learn_prompt.py
- website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md
- skills/research/llm-wiki/SKILL.md
- plugin-catalog/hermes-memory-wiki.yaml
- optional-skills/software-development/code-wiki/SKILL.md
- skills/software-development/hermes-agent-skill-authoring/SKILL.md
Memory Management and Context Engines provide the Hermes Agent with the ability to maintain persistent knowledge across sessions and adapt to specific project environments. The system utilizes a hierarchical discovery mechanism for local project files and a structured knowledge-base pattern for long-term information retrieval.
Context Discovery Engine
The Context Engine automatically discovers and loads specific Markdown files to shape the agent's persona and technical constraints. It prioritizes project-local instructions found in the working directory and merges them with global personality settings.
Priority and Loading Logic
The engine follows a strict priority system when multiple context files exist. It loads only one project context type per session in the following order:
.hermes.md/HERMES.md(Highest Priority)AGENTS.mdCLAUDE.md.cursorrules
Progressive Discovery
For large projects or monorepos, the engine performs progressive discovery. When the agent navigates into a sub-directory using tools like read_file or terminal, the engine scans that directory and its parent for new AGENTS.md or CLAUDE.md files. This prevents system prompt bloat by injecting sub-directory instructions only when they become relevant to the current task.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md:31-48
The sequence diagram shows how context is discovered at startup and expanded during sub-directory traversal.
Persistent Memory Systems
The project manages long-term memory through structured knowledge bases and persistent files that provide an audit trail of user preferences and session history.
The Karpathy Wiki Pattern
Hermes implements the "LLM Wiki" pattern to build a persistent, compounding knowledge base. Unlike Retrieval-Augmented Generation (RAG) which re-indexes per query, the wiki compiles knowledge into interlinked Markdown files once and keeps them current.
| Layer | Component | Description |
|---|---|---|
| Layer 1 | raw/ | Immutable source material (articles, papers, transcripts). |
| Layer 2 | entities/, concepts/ | Agent-owned synthesis pages created from raw sources. |
| Layer 3 | SCHEMA.md | Defines the structure, tag taxonomy, and conventions. |
Sources: skills/research/llm-wiki/SKILL.md:17-45
Memory Dashboard and Persistent Files
The hermes-memory-wiki plugin provides a browsable dashboard. It integrates persistent memory from two primary files:
MEMORY.md: Audit panel for session-derived facts.USER.md: Stores persistent user preferences and constraints.
Sources: plugin-catalog/hermes-memory-wiki.yaml:4-8
Skill Learning and Memory Authoring
The /learn functionality allows the agent to convert session history and gathered sources into reusable skills. This process involves distilling large prose sources into a "book-to-skill" layout.
Skill Memory Structure
When the agent learns a complex topic, it avoids loading the entire corpus into the prompt. Instead, it creates:
- SKILL.md: A lean index containing central mental models and pointers.
- references/: Detailed chapters or topics stored in individual files, loaded on-demand via
skill_view.
Sources: agent/learn_prompt.py:84-106
The flow chart illustrates the decision logic for structuring new skill memory based on source volume.
Security and Integrity
The Context Engine includes a security scanner to prevent prompt injection. All context files undergo scanning for:
- Instruction override attempts (e.g., "ignore previous instructions").
- Hidden HTML comments or invisible Unicode control characters.
- Credential stealing patterns (e.g.,
curlcommands targeting.env).
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md:118-131, agent/learn_prompt.py:112-120
Content Truncation
To maintain prompt efficiency, context files are truncated if they exceed character limits:
- Root Context: 20,000 characters (approx. 7,000 tokens).
- Sub-directory Hints: 8,000 characters.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/features/context-files.md:144-150
Conclusion
Memory Management and Context Engines enable the Hermes Agent to function as a "stateful" researcher. By combining local context discovery, structured knowledge bases, and on-demand skill loading, the system balances prompt efficiency with deep technical awareness. This architecture ensures that project-specific rules and long-term learning are consistently applied across all agent operations.