The File Fallback: When Simple Beats Clever

+15 Mana ✨
Hermes default memory provider(DOCUMENTATION)

Introduction

There is a temptation when learning about agent memory to assume the more sophisticated provider must be the better choice. It is not. The built-in file provider that ships with Hermes is the right answer for most personal use, and understanding why protects you from over-engineering.

Key Concepts

  • Built-in file provider: The default backend, using ~/.hermes/memories/MEMORY.md and USER.md.
  • Zero infrastructure: No service to run, no API key to manage, no quota.
  • Auditable: The files are plain Markdown. You can open them in any editor.
  • Bounded by design: The small character caps prevent runaway growth.

Real World Context

A solo developer enables Honcho because it sounds impressive, then realizes a week later that all they really wanted was "the agent remembers my preferences". They could have shipped that with the default file provider in five seconds and zero ongoing cost. The simpler tool was the better tool.

Deep Dive

When the file provider is the right call:

  • You are a single user with a small, stable set of preferences and environment facts.
  • Your retrieval pattern is "inject everything at session start", not "find me the relevant fact for this turn".
  • You want offline reliability and zero infrastructure.
  • You want to inspect and hand-edit memory.

When the file provider is the wrong call:

  • You are storing thousands of distinct facts.
  • You serve multiple users with isolated knowledge.
  • You need to retrieve facts by semantic similarity at query time.
  • You need to recover the arc of a long history, not the exact facts.

A practical pattern: even when you eventually adopt Honcho or Hindsight, keep the file provider for your top-level identity. "I prefer terse responses" belongs in USER.md, not in a vector store. The cheapest, simplest place is also the right place for the smallest, most-used facts.

Finally, the file provider is a sanity check on the rest of the system. If you cannot articulate the five facts that should be in your USER.md, no embedding provider is going to save you. Memory is most valuable when the high-leverage facts are dense and curated, regardless of which provider serves them.

Common Pitfalls

  1. Defaulting to the fanciest provider: "Embedding" is not synonymous with "better". Start at simple and only escalate when you feel the limit.
  2. Ignoring file memory after enabling another provider: The built-in file provider still works in parallel; abandoning USER.md loses your highest-leverage facts.

Best Practices

  1. Default to file-based: Switch only when you hit a real limit, not because of theoretical scale.
  2. Hand-curate the files quarterly: Even a great agent benefits from human pruning. Read the files, kill stale entries, tighten the language.

Summary

  • The built-in file provider is the right default for most users.
  • It costs nothing, requires no service, and is fully inspectable.
  • Move to embedding or summarization providers only when you have a real reason: scale, multi-user, or narrative recall.
  • Even after upgrading, keep USER.md for your highest-leverage identity facts.

Code Examples

bash
# Hand-edit your USER.md whenever it drifts
$EDITOR ~/.hermes/memories/USER.md

# Or use the slash command inside Hermes
#   > /memory
#   Shows current entries with usage percentages.
#   You can ask the agent to consolidate, replace, or remove entries.
✓ Completed