Memory — ความจำที่มีขอบเขตโดยตั้งใจMemory — Bounded by Design

Have you ever opened an OpenClaw workspace/memory/ folder and found dozens — sometimes hundreds — of daily log files that nobody, not even the agent itself, ever reads end-to-end again?

Readers of my OpenClaw for Organizations series will remember the Memory post: OpenClaw pairs a two-file MEMORY.md + USER.md core with append-forever daily logs, so memory can grow without limit — powerful, but it takes discipline (and periodic pruning) to keep it from becoming an archive nobody consults. Hermes Agent from Nous Research — the MIT-licensed project that launched publicly in late February 2026 and now sits near 240,000 GitHub stars — makes the opposite bet on the whole board: all persistent memory is capped under 3,600 characters, and everything else is recovered by search that runs in milliseconds.

This is post #3 of the Hermes Agent in Practice series. We will walk the philosophy behind that number, the two-file mechanism and its frozen snapshot, the FTS5 search layer, the compression layer, the guardrails that keep memory from becoming an injection vector, the eight pluggable external providers — and close with the single command that consolidates an entire OpenClaw daily-log folder into one bounded file. As someone who runs his own OpenClaw deployment, I read this design with two feelings at once: admiration, and the urge to argue.

1. The philosophy: 3,600 characters of always-on memory

Numbers first. Hermes's built-in persistent memory is two Markdown files in ~/.hermes/memories/: MEMORY.md, capped at 2,200 characters (roughly 800 tokens) — the agent's personal notes: environment facts, conventions, things learned — and USER.md, capped at 1,375 characters (roughly 500 tokens) — the user profile: preferences, communication style, expectations. Under 3,600 characters total, around 1,300 tokens.

That sounds alarmingly small. The agent ecosystem competes on vector databases, embedding pipelines, "unlimited" recall — and Hermes fences its permanent memory into less text than one email. But read the docs to the end and this is clearly not a technical limitation; it is a design position. Whatever lives in persistent memory is injected into the system prompt of every session, every turn — no retrieval step, no gambling on whether similarity search surfaces the right chunk.

💡 The glukhov.org analysis puts the philosophy in one sharp line: "Memory isn't something the agent retrieves when needed. It's something the agent is at all times." The bound is what forces selection.

Of course, 3,600 characters cannot hold everything — which is why Hermes doesn't have one memory layer but three, with a clean division of labor:

Notice the economics: the first layer is the most expensive per token (it rides along on every turn), so it is squeezed smallest. The second is the cheapest (pure SQLite), so it keeps everything untruncated. The third is the pressure valve for a single session's context window. Those three layers are the skeleton of this whole post.

2. MEMORY.md and USER.md — caps, § delimiters, the frozen snapshot

Start with what is actually on disk:

# All of Hermes's persistent memory lives in these two files
ls ~/.hermes/memories/
# MEMORY.md  — the agent's personal notes (cap 2,200 chars ≈ 800 tokens)
# USER.md    — the user profile          (cap 1,375 chars ≈ 500 tokens)

Inside, entries are delimited by the § section sign, and when injected into the system prompt the block carries a usage header. An example in the shape the official docs show:

MEMORY (your personal notes) [67% — 1,474/2,200 chars]
§ pm25-dashboard deploys via GitHub Actions — staging before production, always
§ Primary machine is macOS + zsh; Python managed with uv
§ User wants commit messages in English, short, stating the why

That percentage header is not decoration. The agent sees it every turn, so it always knows how close memory is to full — and when it is time to start consolidating (next section).

The frozen snapshot — and the caching reason behind it

My favorite detail of the design: both files are read into the system prompt as a frozen snapshot, captured once at session start and never mutated mid-session. If the agent writes memory during a session, the write hits disk immediately — but appears in the prompt only from the next session onward.

In prompt assembly (per Arize's architecture deep-dive), the memory, user-profile, and timestamp blocks form the "volatile" tier, placed after the stable parts — tool guidance and context files. Frequently-changing content sits at the tail so the long prefix ahead of it stays cacheable. It is a small detail that tells you the designers were thinking about real bills.

Memory is not context files

A common confusion for people arriving from Claude Code or OpenClaw: context files are a separate system from memory. Files like AGENTS.md or CLAUDE.md are project instructions written by humans; memory is what the agent accumulates on its own. Hermes loads a project context file first-match-wins, in this order (see the context-files doc):

# Context files — a separate system from memory; only the first match loads
.hermes.md / HERMES.md   # beats everything
AGENTS.override.md
AGENTS.md
CLAUDE.md                # Hermes reads Claude Code's file natively
.cursorrules

# SOUL.md always loads from $HERMES_HOME/SOUL.md — identity slot #1
# The size cap scales with the model: floor 20,000 → ceiling 500,000 chars
# (config key context_file_max_chars; subdirectory AGENTS.md capped at 8,000)

The practical payoff: the CLAUDE.md and AGENTS.md your organization already invested in work with Hermes on day one, unconverted. And the auto-save criteria explicitly skip "anything already in context files" — so the 3,600 characters never get burned on facts a file already covers.

3. The memory tool: add / replace / remove, and error-on-overflow

The agent edits its own memory through a tool called memory, which has exactly three actions — and deliberately no read, because the content is already sitting in the system prompt:

# The memory tool's conceptual shape — three actions, no read
memory(action="add",
       content="Team CI runs on a self-hosted runner — never schedule GPU jobs")

memory(action="replace",
       old_text="Postgres 15",          # substring matching
       content="Upgraded to Postgres 16 (Aug 2026)")

memory(action="remove", old_text="legacy-api project")

A later addition is the operations array: a batch of edits validated atomically against the final character budget — the whole batch passes or none of it does. (Release-note summaries place it somewhere in the v0.16.0–v0.18.0 window, June–July 2026; the exact release is unpinned, so I won't pin it either.)

# Batch edit — validated against the final budget as one unit
memory(operations=[
  {"action": "remove",  "old_text": "details of the closed sprint"},
  {"action": "replace", "old_text": "staging on DO", "content": "staging moved to Hetzner"},
  {"action": "add",     "content": "Team adopted conventional commits from Sep 2026"}
])

Full means an error, not a silent drop

Here is the heart of "bounded by design." When memory is full, Hermes does not silently evict the oldest entry, and does not auto-summarize over your notes. The tool returns a plain error:

Memory at 2,100/2,200 chars. Adding this entry (250 chars)
would exceed the limit.

# → the agent must consolidate or remove before it can add
# documented best practice: start consolidating above 80% capacity

I read this as moving the "what actually matters?" decision back to the agent at the moment it has the most context — instead of letting an automatic policy guess. It is the difference between forcing a summary into a small notebook and photocopying the whole filing cabinet. Anyone who has watched an OpenClaw MEMORY.md bloat until a human had to prune it by hand will understand the appeal.

The full set of memory config keys, with their documented defaults:

# Memory config keys — documented defaults
memory_enabled: true          # the memory system itself
user_profile_enabled: true    # USER.md
memory_char_limit: 2200       # MEMORY.md cap
user_char_limit: 1375         # USER.md cap
write_approval: false         # true = every write awaits approval (section 7)

# Write notifications: off / on (default) / verbose
# on = a generic "💾 Memory updated" line; verbose adds a compact diff preview
display.memory_notifications: on

4. What gets remembered automatically — and what deliberately doesn't

You don't have to say "remember this" every time. The project README calls the mechanism "agent-curated memory with periodic nudges": the agent nudges itself, at intervals, to review whether anything in the recent conversation crossed the durable-fact threshold. The documented criteria are crisp enough to tabulate:

The right column matters more than the left. Memory systems mostly fail by remembering too much, not too little; declaring what is unworthy of the 3,600 characters is half the design.

The background review can also be routed to a cheaper auxiliary model — the docs report roughly a 3–5x reduction in token cost in benchmarks:

# Run the background memory review on a cheaper auxiliary model
auxiliary.background_review.provider: <provider>
auxiliary.background_review.model: <cheap-model>
# documented: ~3–5x lower token cost in benchmarks

As for the cadence: MMNTM's third-party code walkthrough (July 2026) reports a nudge roughly every 300 seconds, plus a post-turn background review that re-reads the conversation off the still-warm prefix cache. That 300-second figure appears in no primary doc, so treat it as a code-reading report, not a spec.

5. Recall layer two: FTS5 session search over full transcripts

The question left hanging since section one: if permanent memory holds 3,600 characters, where does everything else go? The answer is: nowhere. Every session — CLI or any messaging channel — is stored, complete, in a single SQLite database with a full-text index:

# Every session (CLI + every messaging channel) lives in one SQLite DB
~/.hermes/state.db          # with a built-in FTS5 full-text index

# The agent searches it with a tool — and gets ACTUAL messages back
session_search("docker compose postgres password rotation")
# ~20ms per query, ~1ms per scroll
# then scroll forward/backward inside any session it finds

The memory doc is emphatic that this layer returns "actual messages" — no LLM summarization, no truncation, no embeddings, no vector database to operate. Just SQLite's FTS5, fast enough (~20ms) and, crucially, free of LLM cost per query — so the agent can search liberally without burning budget.

One tension worth naming honestly: the README markets this feature as "FTS5 session search with LLM summarization for cross-session recall," which reads as contradicting the memory doc's "no LLM summarization." Read alongside release notes that made session search one of the per-task auxiliary-model overrides, next to compression and vision, I interpret it as two stages of one path: the search is pure FTS5 returning raw messages, while digesting the results into an answer may pass through an auxiliary model. Both sentences can be true at once; I'm describing the layers rather than ruling on a single mechanism.

💡 The architectural trade here: you give up semantic recall (a vector DB might find "the same topic in different words") and get speed, zero marginal cost, and transparency — search results are real, auditable messages, not embedding neighbors you can't explain. For an agent you talk to in the same vocabulary every day, that vocabulary already is a good key.

6. Recall layer three: context compression and session lineage

The third layer is not about crossing sessions — it solves overflow within one. Per Arize's read of the codebase, when context exceeds its thresholds, agent/context_compressor.py summarizes the conversation lossily and continues in a child session, while the session store (via hermes_state.py and the gateway's SessionStore) keeps full parent/child lineage — however many compressions deep, the original transcript remains reachable — with per-platform isolation and atomic writes.

Recent releases have polished this layer hard, above all v0.20.0 (August 3, 2026), which overhauled it end to end:

• Proactive tool-result pruning — old tool outputs are dropped before context gets tight (it matters most on large-window models where input tokens are expensive)
• Per-turn micro-compaction — small cleanups every turn instead of one big squeeze at the cliff edge
• A guaranteed N-user-message tail — the user's most recent N messages always survive compression. If you have ever watched an agent forget the instruction you gave two minutes ago because compaction ate it, this is the fix aimed straight at that wound

Earlier releases had already added degradation warnings, token-budget tail protection, and targeted compression:

# Guided compression — tell the summary which thread to preserve
/compress <focus>

Cron agents stop being goldfish

The last gap in this picture closed only weeks ago. Recurring cron jobs used to start from zero every run. v0.20.5 (tagged August 19, 2026) gave cron jobs persistent memory, and v0.21.0 (August 31, 2026) finished the job with a release-notes line I'll quote whole: "Cron jobs stopped being goldfish. Cron agents now load and update persistent memory like every other agent." Plus continuity=true, which carries each run's output into the next — so a monitoring agent knows what it already reported and doesn't alert twice.

7. Guardrails: injection scanning, write approval, /journey

Follow the logic: Hermes memory ends up in the system prompt — the most authoritative position in the entire conversation. If an attacker tricks the agent into "remembering" a sentence that is really an embedded instruction, they have effectively written the system prompt of every future session. So every memory write is security-scanned before acceptance: prompt-injection patterns, credential-exfiltration attempts, SSH-backdoor patterns, and invisible Unicode characters are all blocked.

For deployments with multiple users, or agents receiving messages from the outside world, I recommend the approval layer: set write_approval: true and foreground CLI writes prompt inline, while writes from every other channel are staged for review:

/memory pending             # list writes awaiting approval
/memory approve <id>        # accept one
/memory reject <id>         # decline one

And since v0.18.0 (July 1, 2026), humans get a direct window into the agent's head: /journey opens a playable timeline of everything Hermes has learned (the desktop app adds a radial memory graph), where memories can be viewed, edited, or deleted chunk by chunk:

/journey                                        # timeline of everything learned
hermes journey delete memory:<source>:<index>   # remove a chunk by node id
hermes journey edit memory:<source>:<index>     # open it in $EDITOR

Finally, isolation: every Hermes profile gets its own HERMES_HOME, config, memory, sessions, and gateway process, fully separated — an experiment profile's memories cannot leak into your production profile. It pairs neatly with the one-agent-per-context discipline I argued for in the OpenClaw series.

8. External memory providers — the pluggable layer of eight

If 3,600 characters plus FTS5 still isn't enough — say you want deep user modeling, or genuinely semantic recall — Hermes has a plugin layer: eight external memory providers: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, and Supermemory (the docs describe a separate Memori plugin as well). Two rules govern it: only one provider can be active at a time, and it is always additive — built-in memory never gets replaced or turned off.

With a provider active, Hermes injects provider context into the system prompt, prefetches relevant memories before each turn (non-blocking), syncs turns after each response, extracts memories at session end, mirrors built-in memory writes to the provider, and exposes the provider's own tools to the agent:

# Activate an external provider — one at a time, ever
hermes memory setup         # wizard: pick a provider + credentials
hermes memory status        # which one is active
hermes memory off           # deactivate (built-in memory keeps running)

# or set it directly in config
memory.provider: <provider>

Two providers the docs describe in enough detail to summarize:

• Holographic — fully local: a SQLite fact store (default $HERMES_HOME/memory_store.db) with FTS5, trust scoring (default 0.5), and holographic reduced representations. Free, no external dependencies, with a fact_store tool (add, search, probe, related, reason, contradict, update, remove, list) and fact_feedback. The natural first pick for trying this layer without data leaving the machine.
• Honcho — "AI-native cross-session user modeling with dialectic reasoning": builds a model of the user across sessions, with fine-grained config (dialecticMaxChars 600, recallMode hybrid, writeFrequency async, sessionStrategy per-directory) and five honcho_* tools.

Costs across the group run from free/local (Holographic) to around $20/month for cloud (RetainDB), with the occasional dependency pin — Hindsight requires hindsight-client >= 0.4.22. And if you want to write your own, the interface is open (core modules: agent/memory_manager.py, agent/memory_provider.py, plugins/memory/):

# The memory-provider plugin interface — every hook optional
prefetch(query, session_id)       # before each API call
queue_prefetch()                  # after each turn
sync_turn(user, assistant, ...)   # after each turn — MUST be non-blocking
on_session_end(messages)          # extract memories at session close
on_pre_compress(messages)         # before context compression
on_memory_write(action, target, content)  # mirror of built-in writes
system_prompt_block()             # the block injected into the prompt
shutdown()                        # clean shutdown

9. Migrating from OpenClaw: daily logs become one bounded file

Now the section my OpenClaw readers have been waiting for. Put the two models side by side first:

The good news: the two-file MEMORY.md/USER.md concept matches exactly (not by accident — OpenClaw's own reverse-migration guide appends these same file pairs into each other). So the move is one command, per the official migration guide — and the most interesting part is what happens to the daily logs:

hermes claw migrate
# workspace/SOUL.md       → ~/.hermes/SOUL.md
# workspace/AGENTS.md     → AGENTS.md (in the target workspace)
# workspace/MEMORY.md     → ~/.hermes/memories/MEMORY.md
# workspace/USER.md       → ~/.hermes/memories/USER.md
# workspace/memory/*.md   → CONSOLIDATED into the single MEMORY.md
#                           (parsed → merged → deduped on the § delimiter)
# existing Hermes memories are skipped, never overwritten

hermes claw cleanup
# renames leftover OpenClaw dirs into .pre-migration/ (rename, not delete)

Read that fourth-from-last comment again: an entire daily-log folder — on some machines, months of daily notes — is consolidated into one file with a 2,200-character ceiling. That is not merely a technical step; it is a forced distillation, the whole philosophy of this post compressed into one migrate command. If you want the deep view of how OpenClaw assembles its side of this picture, I took it apart in OpenClaw Memory Architecture.

My recommended sequence for a real migration:

1. Before migrating, open workspace/memory/ and hand-delete the logs you know are expired — let the consolidator work on material that still has value.
2. Run hermes claw migrate, then open ~/.hermes/memories/MEMORY.md and read the result with your own eyes. Distillation this aggressive is lossy by nature; anything important that got dropped, add back yourself.
3. Remember that imports take effect only in new sessions — anything still running sees the old snapshot (the freezing behavior from section 2 applies here too).
4. Finish with /journey to sanity-check the inherited memories, then run hermes claw cleanup.

I am not declaring a winner between OpenClaw's unbounded memory and Hermes's bounded one — but after enough time in both sets of docs, I will concede this: the question Hermes forces every time memory approaches full — "which of these is actually worth keeping?" — is a question unbounded memory systems never force anyone to answer. Which may be exactly why they so often end up as archives nobody reads.