Memory and Profiles — Persistent Context in Hermes Agent

By Hermes Agent·Jul 16, 2026·8 min read·memory profiles hermes-agent quickstart

Explore Hermes Agent's memory system, Honcho integration, and profile management for cross‑session persistence, enabling rich, context‑aware interactions.

<Breadcrumb>
  Home > Quick Start Guides > Memory and Profiles
</Breadcrumb>

1. Overview

Hermes Agent is designed to remember what happened, why it matters, and who it involves. Its memory architecture blends three complementary layers:

Layer	Purpose	Lifetime
Episodic Memory	Stores raw conversation turns, timestamps, and raw user intent.	Session‑only (cleared when the session ends)
Semantic Memory	Extracts concepts, entities, and relationships from episodes, turning raw logs into reusable knowledge.	Persisted across sessions (via Honcho)
Profile Memory	Holds persona‑specific preferences, role definitions, and custom prompts.	Persisted per profile, switchable on the fly

Together these layers give Hermes a “long‑term brain” that can recall past interactions, reason about them, and adapt its tone to the active profile.

2. How Hermes Memory Works

2.1 Episodic Memory

Every inbound and outbound message is captured as an episode:

{
  "id": "e7b9c4a2",
  "timestamp": "2026-07-17T14:03:12Z",
  "direction": "user",
  "content": "Can you suggest a vegan dinner for two?",
  "metadata": { "intent": "recipe_suggestion", "entities": ["vegan", "dinner", "two"] }
}

Episodes are stored in an in‑memory queue that is automatically flushed when the session ends. The queue is accessible to the LLM via a system prompt that looks like:

You have access to the last 12 episodes of the conversation. Use them to maintain continuity.

2.2 Semantic Memory

When an episode is archived, Hermes runs a semantic extractor (a lightweight LLM call or a rule‑based parser) that:

Normalizes entities (e.g., "vegan dinner" → MealType: Vegan, MealTime: Dinner).
Indexes concepts in a vector store (by default, a Faiss index backed by the Honcho service).
Links related concepts (e.g., linking the user’s “vegan dinner” request to a stored recipe collection).

The result is a knowledge node:

{
  "nodeId": "k_42f9",
  "type": "RecipeRequest",
  "attributes": {
    "diet": "vegan",
    "servings": 2,
    "meal": "dinner"
  },
  "sourceEpisode": "e7b9c4a2"
}

These nodes survive beyond the current session and can be retrieved with a simple query:

await hermes.memory.search("vegan dinner for two", { topK: 3 });

2.3 Session Persistence

While episodic memory is volatile, Hermes automatically hydrates the LLM with the most relevant semantic nodes at the start of each new session. This “context re‑hydration” ensures the agent can say:

“Welcome back! I remember you liked a vegan dinner for two last week. Would you like a different recipe this time?”

The persistence mechanism is powered by Honcho, a managed vector store that guarantees durability and fast similarity search.

3. Honcho Integration for Long‑Term Memory

Honcho is Hermes’ default long‑term storage provider. It offers:

Scalable vector indexing (FAISS, HNSW, or proprietary GPU‑accelerated back‑ends)
Versioned snapshots (useful for rollback or audit)
Tenant isolation (each profile gets its own namespace)

3.1 Connecting Hermes to Honhon

Add the following to hermes.config.js:

module.exports = {
  memory: {
    provider: "honcho",
    endpoint: "https://api.honcho.ai",
    apiKey: process.env.HONCHO_API_KEY,
    namespace: "default", // will be overridden per profile
  },
};

3.2 Managing Namespaces

When a profile is activated, Hermes automatically prefixes all memory keys with the profile’s namespace:

await hermes.memory.setNamespace(`profile_${profileId}`);

This isolation prevents cross‑profile leakage while still allowing a global namespace for truly universal knowledge (e.g., public facts, common sense).

3.3 Back‑up & Restore

Honcho supports export/import of vector snapshots. To back up a profile’s knowledge:

hermes memory export --profile=travel_guide --output=travel_guide_snapshot.zip

To restore:

hermes memory import --profile=travel_guide --input=travel_guide_snapshot.zip

4. Profiles System

Profiles let you swap personas without restarting the agent. A profile bundles:

Component	Description
System Prompt	Core instructions that define tone, role, and any domain‑specific rules.
Memory Namespace	Isolated vector space for that profile’s semantic nodes.
Preferences	User‑specific defaults (e.g., language, units, recurring interests).
Custom Functions	Optional JS hooks for domain‑specific actions (e.g., `fetchTravelItinerary`).

4.1 Creating a Profile

hermes profile create \
  --id=travel_guide \
  --name="Travel Guide" \
  --system-prompt="You are a friendly travel guide with a deep knowledge of European destinations."

The command creates a new namespace in Honcho (profile_travel_guide) and stores the system prompt.

4.2 Switching Profiles at Runtime

Within a conversation, you can instruct the user to change personas:

await hermes.profile.switch('travel_guide');

Or via voice:

User: “Switch to travel guide mode.”
Hermes: [recognizes intent] “Sure thing! I’m now your travel guide.”

The switch automatically:

Persists any pending episodic memory.
Loads the new profile’s system prompt.
Re‑hydrates the LLM with the profile’s semantic memory.

4.3 Multi‑Profile Scenarios

A single session can temporarily blend profiles. For example, a corporate assistant may need a “legal advisor” profile for a brief clause:

await hermes.profile.activateTemporary('legal_advisor', { duration: '5m' });

After the timer expires, Hermes reverts to the original profile.

5. Configuring Memory Settings & Commands

Hermes ships with a set of CLI commands and runtime APIs to fine‑tune memory behavior.

5.1 Global Settings

module.exports = {
  memory: {
    maxEpisodes: 20,          // keep up to 20 recent turns in episodic memory
    semanticChunkSize: 256,   // token size for each semantic node
    retentionDays: 90,        // auto‑prune nodes older than 90 days
    similarityThreshold: 0.78,
  },
};

5.2 Runtime Commands

Command	Example	Effect
`memory.flush()`	`await hermes.memory.flush();`	Clears episodic memory immediately.
`memory.search(query, opts)`	`await hermes.memory.search("vegan recipes", { topK: 5 });`	Retrieves the most similar semantic nodes.
`memory.prune()`	`await hermes.memory.prune();`	Removes nodes older than `retentionDays`.
`memory.setNamespace(ns)`	`await hermes.memory.setNamespace('profile_travel_guide');`	Switches the active vector namespace.

5.3 Voice‑Triggered Memory Commands

You can expose memory actions to voice:

{
  "intent": "clear_memory",
  "utterances": [
    "reset our conversation",
    "start over",
    "forget what we talked about"
  ],
  "handler": async () => {
    await hermes.memory.flush();
    return "All right, I’ve cleared the recent conversation. How can I help you now?";
  }
}

The handler runs the same flush() API, giving users a natural way to reset context.

6. Voice Interaction and Memory

When Hermes is used through a voice channel (e.g., a smart speaker), the memory pipeline includes an extra speech‑to‑text (STT) enrichment step:

STT returns raw transcript + confidence scores.
Intent extraction adds metadata to the episode (e.g., confidence: 0.94).
Semantic enrichment may add prosodic cues (e.g., tone=question, urgency=high) as extra attributes.

These attributes become part of the semantic node, enabling the agent to respond with appropriate prosody:

“Sure, here’s a quick vegan recipe (cheerful tone).”

Voice‑first users also benefit from audio‑summaries that leverage stored memory:

await hermes.memory.summarize({
  since: "2026-07-10",
  format: "audio",
});

The function returns an MP3 snippet summarizing the user’s recent activity, perfect for “catch‑up” scenarios.

7. Best Practices for Memory Management

Practice	Why It Matters
Limit episodic depth	Keeping too many episodes inflates prompt size and can exceed token limits. Use `maxEpisodes` wisely.
Chunk semantic data	Break large user inputs into 250‑token chunks before indexing; this improves similarity search relevance.
Namespace hygiene	Periodically audit namespaces for orphaned profiles; remove unused ones to save storage.
Version your system prompts	Store prompts in a version‑controlled repo; changes can be rolled back without losing memory.
Respect privacy	Offer a `memory.clear` voice command and comply with GDPR‑style data‑deletion requests.
Monitor similarity thresholds	Too low a threshold yields noisy matches; too high discards useful context. Adjust after observing retrieval quality.
Leverage temporary profiles	Use them for short‑lived expertise (e.g., legal advice) to keep the main profile lean.
Regularly prune	Schedule `memory.prune()` via a cron job (e.g., nightly) to keep the vector store performant.
Log memory actions	Keep an audit trail of `flush`, `prune`, and `import` operations for debugging and compliance.

8. Further Reading

Hermes Agent Core Docs – Full API reference for hermes.memory, hermes.profile, and hermes.voice.
Honcho Vector Store Guide – Deep dive into index tuning, scaling, and security.
Prompt Engineering Handbook – Strategies for crafting effective system prompts per profile.
Voice UX Patterns – Best practices for designing conversational flows with memory‑aware agents.

You can find these resources in the Docs section of the Hermes portal or via the following links:

9. Quick Reference Cheat Sheet

// Switch profile
await hermes.profile.switch('travel_guide');

// Search memory
const recipes = await hermes.memory.search('vegan dinner', { topK: 3 });

// Flush episodic memory
await hermes.memory.flush();

// Export profile memory
hermes memory export --profile=travel_guide --output=travel.zip;

// Set custom retention
module.exports = {
  memory: { retentionDays: 180 }
};

Ready to make Hermes truly remember you?
Start by creating a profile, enable Honcho, and watch the agent build a lasting, context‑rich relationship.

HERO_IMAGE_PROMPT