본문으로 건너뛰기

Persistent Memory

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

동작 방식​

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

FilePurposeChar Limit
MEMORY.mdagent의 personal notes - environment fact, convention, 학습한 내용2,200 chars(~800 tokens)
USER.mduser profile - 사용자의 preference, communication style, expectation1,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이 있습니다.

StoreLimitTypical entries
memory2,200 chars8-15 entries
user1,375 chars5-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는 차단됩니다.

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​

FeaturePersistent MemorySession Search
Capacity총 약 1,300 tokensunlimited(모든 session)
Speed즉시 사용(system prompt 안에 있음)search + LLM summarization 필요
Use case항상 사용 가능해야 하는 핵심 사실특정 과거 대화 찾기
Managementagent가 수동으로 curatedautomatic - 모든 session 저장
Token costsession마다 고정(~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를 참고하세요.