Hermes Agent Tutorial 2: Memory System — Persistent Memory and User Modeling

Tutorial Overview

Series index: Hermes Agent Tutorial Series

This tutorial covers Hermes Agent’s Memory System — the first core differentiator that sets Hermes apart from other AI assistants. Unlike Claude Code or Cursor, Hermes remembers across sessions.

What you will learn

✅ Why Hermes’s memory is different from other agents
✅ The Honcho dialectic user modeling approach
✅ How memory nudges work
✅ Cross-session recall with FTS5 search
✅ Viewing and managing stored memories

Why Memory Matters

The problem with most AI assistants

Every conversation with Claude Code, Cursor, or ChatGPT starts fresh. They forget:

Your coding style preferences
Project context you explained last week
Decisions you made together
Lessons learned from previous debugging

flowchart LR
    A[Session 1] --> B[Knowledge built]
    B --> C[Session ends]
    C --> D[Session 2]
    D --> E[Start from zero]

    style C fill:#ffcccc
    style E fill:#ffcccc

Hermes’s different approach

Hermes Agent implements a learning loop that persists knowledge:

flowchart TD
    A[User interaction] --> B[Experience stored]
    B --> C[Memory nudge triggers]
    C --> D[Knowledge persisted]
    D --> E[Session search indexed]
    E --> F[Future recall enabled]
    F --> A

    style B fill:#e1f5ff
    style D fill:#e8f5e9
    style F fill:#fff3e0

Comparison

Feature	Hermes Agent	Claude Code	Cursor	ChatGPT
Cross-session memory	✅ Honcho	❌ None	❌ None	❌ Limited
User modeling	✅ Dialectic	❌ Static	❌ Static	❌ Profile
Session search	✅ FTS5	❌ No	❌ No	❌ Limited
Auto-persistence	✅ Nudges	❌ Manual	❌ Manual	❌ Manual

Honcho Dialectic User Modeling

What is Honcho?

Honcho is Hermes’s user modeling engine built on dialectic principles. Instead of a static user profile, Honcho maintains an evolving model of who you are through ongoing dialogue.

Analogy: Think of Honcho as a librarian who not only stores your books but understands why you read them, what patterns emerge, and how your interests evolve.

How dialectic modeling works

sequenceDiagram
    participant U as User
    participant H as Hermes
    participant Honcho as Honcho Engine
    participant M as Memory Store

    U->>H: Shares preference
    H->>Honcho: Process interaction
    Honcho->>Honcho: Detect pattern
    Honcho->>M: Store insight
    M->>Honcho: Retrieve context
    Honcho->>H: User model updated
    H->>U: Tailored response

    style Honcho fill:#e1f5ff

Key components

User Profile — Preferences, style, constraints
Interaction History — All conversations indexed
Pattern Detection — Recurring themes and behaviors
Insight Synthesis — What Hermes learns about you

Memory Nudges

What are memory nudges?

Memory nudges are periodic prompts that Hermes sends to itself, asking: “Should I persist this knowledge?”

This solves the problem of humans forgetting to tell the agent what’s important.

Nudge timing

Nudge Type	Trigger	Purpose
Session-end	Conversation closes	Summarize key learnings
Pattern-detected	3+ similar requests	Persist preference
User-declared	“Remember this”	Immediate storage
Periodic	Every 10 turns	Check for valuable info

Example nudge flow

User: I always use pytest for Python tests, not unittest

[After 3 turns]

Hermes (internal nudge): Pattern detected: pytest preference. Should persist?
→ YES: Store preference
→ Memory: "User prefers pytest over unittest for Python testing"

[Next session]

User: Write tests for this function

Hermes: Using pytest as you prefer... (retrieved from memory)

Cross-Session Recall

FTS5 Search

Hermes uses SQLite’s FTS5 (Full-Text Search) for session history indexing:

flowchart LR
    A[Past sessions] --> B[FTS5 indexed]
    B --> C[Query triggered]
    C --> D[Relevant matches]
    D --> E[LLM summarizes]
    E --> F[Context injected]

    style B fill:#e8f5e9
    style E fill:#fff3e0

How recall works

Indexing — Every conversation is indexed with metadata
Query — Current context triggers search
Retrieval — FTS5 finds relevant past sessions
Summarization — LLM condenses into usable context
Injection — Relevant memory added to current prompt

Manual recall

You can explicitly query memory:

/recall "What did we decide about the API structure?"
/search "debugging sessions from last month"

Viewing and Managing Memories

Memory location

Hermes stores memories in:

~/.hermes/memory/
├── sessions/          # Indexed conversation history
├── user_profile.json  # Dialectic user model
├── insights.json      # Synthesized learnings
└── preferences.json   # Declared preferences

Viewing memory

Use the /memory command:

/memory show           # View current user profile
/memory list           # List stored insights
/memory search [query] # Search sessions

Managing memory

# View via CLI
hermes memory show

# Export memories
hermes memory export --format json

# Clear specific memory
hermes memory forget "pytest preference"

# Full reset (careful!)
hermes memory reset

Manual memory editing

You can directly edit memory files:

# View user profile
cat ~/.hermes/memory/user_profile.json

# Edit preferences
nano ~/.hermes/memory/preferences.json

Best Practices

For effective memory

Declare preferences explicitly — “Remember: I use TypeScript strict mode”
Confirm important decisions — “Let’s lock in this API structure”
Review periodically — Use /memory show to verify accuracy
Clean stale data — Remove outdated preferences

Memory hygiene

Practice	Command	Frequency
Review profile	`/memory show`	Weekly
Clear outdated	`/memory forget`	As needed
Export backup	`hermes memory export`	Monthly

Troubleshooting

Memory not persisting

Cause: Memory nudges disabled.

Fix:

hermes config set memory.nudges.enabled true

Recall returning nothing

Cause: Search query too specific.

Fix: Use broader terms or check /memory list first.

Memory consuming too much space

Cause: Long history accumulation.