Persistent Memory

Hermes Agent에는 session을 넘어 유지되는 bounded, curated memory가 있습니다. 이를 통해 사용자의 preference, project, environment, agent가 학습한 내용을 기억할 수 있습니다.

동작 방식

agent memory는 두 file로 구성됩니다.

File	Purpose	Char Limit
MEMORY.md	agent의 personal notes - environment fact, convention, 학습한 내용	2,200 chars(~800 tokens)
USER.md	user profile - 사용자의 preference, communication style, expectation	1,375 chars(~500 tokens)

둘 다 ~/.hermes/memories/에 저장되며, session 시작 시 frozen snapshot으로 system prompt에 inject됩니다. agent는 memory tool로 자신의 memory를 관리합니다. entry를 add, replace, remove할 수 있습니다.

정보

character limit은 memory를 집중된 상태로 유지하기 위한 장치입니다. memory가 가득 차면 agent는 새 정보를 넣기 위해 entry를 consolidate하거나 replace합니다.

system prompt에 memory가 표시되는 방식

모든 session 시작 시 memory entry가 disk에서 load되고, frozen block으로 system prompt에 render됩니다.

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations

format에는 다음이 포함됩니다.

• 어떤 store인지 보여 주는 header(MEMORY 또는 USER PROFILE)
• agent가 capacity를 알 수 있도록 usage percentage와 character count
• §(section sign) delimiter로 구분된 individual entry
• multiline entry 지원

Frozen snapshot pattern: system prompt injection은 session 시작 시 한 번 capture되고 session 중에는 바뀌지 않습니다. 이는 의도된 동작입니다. 성능을 위해 LLM prefix cache를 유지하기 때문입니다. agent가 session 중 memory entry를 add/remove하면 변경 내용은 즉시 disk에 persist되지만, 다음 session이 시작되기 전까지 system prompt에는 나타나지 않습니다. tool response는 항상 live state를 보여 줍니다.

Memory tool action

agent는 memory tool에서 다음 action을 사용합니다.

• add - 새 memory entry 추가
• replace - 기존 entry를 updated content로 교체(old_text를 통한 substring matching 사용)
• remove - 더 이상 관련 없는 entry 제거(old_text를 통한 substring matching 사용)

read action은 없습니다. memory content는 session 시작 시 system prompt에 자동으로 inject됩니다. agent는 자신의 memory를 conversation context의 일부로 봅니다.

substring matching

replace와 remove action은 짧고 고유한 substring matching을 사용합니다. 전체 entry text가 필요하지 않습니다. old_text parameter는 정확히 하나의 entry를 식별하는 고유 substring이면 충분합니다.

# If memory contains "User prefers dark mode in all editors"
memory(action="replace", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

substring이 여러 entry에 match되면 더 구체적인 match를 요구하는 error가 반환됩니다.

두 target 설명

memory - agent의 personal notes

agent가 environment, workflow, 학습한 내용을 기억해야 할 때 사용합니다.

• environment facts(OS, tools, project structure)
• project convention과 configuration
• 발견한 tool quirks와 workaround
• completed task diary entry
• 효과가 있었던 skill과 technique

user - user profile

사용자의 identity, preference, communication style에 대한 정보에 사용합니다.

• name, role, timezone
• communication preference(concise vs detailed, format preference)
• pet peeves와 피해야 할 것
• workflow habit
• technical skill level

저장할 것과 건너뛸 것

적극적으로 저장할 것

agent는 사용자가 요청하지 않아도 자동으로 저장합니다. 다음을 학습하면 저장합니다.

• User preferences: "I prefer TypeScript over JavaScript" → user에 저장
• Environment facts: "This server runs Debian 12 with PostgreSQL 16" → memory에 저장
• Corrections: "Don't use sudo for Docker commands, user is in docker group" → memory에 저장
• Conventions: "Project uses tabs, 120-char line width, Google-style docstrings" → memory에 저장
• Completed work: "Migrated database from MySQL to PostgreSQL on 2026-01-15" → memory에 저장
• Explicit requests: "Remember that my API key rotation happens monthly" → memory에 저장

저장하지 않을 것

• Trivial/obvious info: "User asked about Python" - 너무 모호해 유용하지 않음
• Easily re-discovered facts: "Python 3.12 supports f-string nesting" - web search로 쉽게 다시 찾을 수 있음
• Raw data dumps: 큰 code block, log file, data table - memory에 비해 너무 큼
• Session-specific ephemera: 임시 file path, 일회성 debugging context
• Information already in context files: SOUL.md 및 AGENTS.md content

capacity management

memory에는 system prompt 크기를 제한하기 위한 엄격한 character limit이 있습니다.

Store	Limit	Typical entries
memory	2,200 chars	8-15 entries
user	1,375 chars	5-10 entries

memory가 가득 차면

limit을 초과하는 entry를 추가하려고 하면 tool은 error를 반환합니다.

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Replace or remove existing entries first.",
  "current_entries": ["..."],
  "usage": "2,100/2,200"
}

그다음 agent는:

1. 현재 entry를 읽습니다(error response에 표시됨).
2. 제거하거나 consolidate할 수 있는 entry를 찾습니다.
3. replace로 관련 entry를 더 짧은 version으로 merge합니다.
4. 그런 다음 새 entry를 add합니다.

Best practice: memory가 80% 이상 차 있으면(system prompt header에서 확인 가능) 새 entry를 추가하기 전에 consolidate하세요. 예를 들어 "project uses X" entry 세 개를 하나의 종합 project description entry로 합칩니다.

좋은 memory entry의 실제 예

compact하고 information-dense한 entry가 가장 좋습니다.

# Good: Packs multiple related facts
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.

# Good: Specific, actionable convention
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.

# Good: Lesson learned with context
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.

# Bad: Too vague
User has a project.

# Bad: Too verbose
On January 5th, 2026, the user asked me to look at their project which is
located at ~/code/api. I discovered it uses Go version 1.22 and...

duplicate prevention

memory system은 exact duplicate entry를 자동으로 거부합니다. 이미 존재하는 content를 추가하려고 하면 "no duplicate added" message와 함께 success를 반환합니다.

security scanning

memory entry는 system prompt에 inject되므로, accept되기 전에 injection 및 exfiltration pattern scan을 거칩니다. threat pattern(prompt injection, credential exfiltration, SSH backdoor)에 match되거나 invisible Unicode character가 포함된 content는 차단됩니다.

session search

MEMORY.md와 USER.md 외에도 agent는 session_search tool로 과거 대화를 검색할 수 있습니다.

• 모든 CLI 및 messaging session은 SQLite(~/.hermes/state.db)에 저장되며 FTS5 full-text search를 사용합니다.
• search query는 관련 past conversation을 Gemini Flash summarization과 함께 반환합니다.
• active memory에 없는 내용이라도 몇 주 전 논의한 내용을 찾을 수 있습니다.

hermes sessions list    # Browse past sessions

session_search vs memory

Feature	Persistent Memory	Session Search
Capacity	총 약 1,300 tokens	unlimited(모든 session)
Speed	즉시 사용(system prompt 안에 있음)	search + LLM summarization 필요
Use case	항상 사용 가능해야 하는 핵심 사실	특정 과거 대화 찾기
Management	agent가 수동으로 curated	automatic - 모든 session 저장
Token cost	session마다 고정(~1,300 tokens)	on-demand(필요할 때 검색)

Memory는 항상 context에 있어야 하는 critical fact용입니다. Session search는 "지난주에 X에 대해 이야기했나?"처럼 과거 대화의 구체 내용을 recall해야 할 때 사용합니다.

configuration

# In ~/.hermes/config.yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens

external memory providers

MEMORY.md와 USER.md를 넘어 더 깊은 persistent memory가 필요하면 Hermes에는 8개의 external memory provider plugin이 포함되어 있습니다. Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory가 포함됩니다.

external provider는 built-in memory와 함께 실행되며, 이를 대체하지 않습니다. knowledge graph, semantic search, automatic fact extraction, cross-session user modeling 같은 capability를 추가합니다.

hermes memory setup      # pick a provider and configure it
hermes memory status     # check what's active

각 provider의 상세 내용, setup instruction, 비교는 Memory Providers guide를 참고하세요.