📄 user-guide/features/mcp.md

sidebar_position: 4 title: "MCP (Model Context Protocol)" description: "Connect Hermes Agent to external tool servers via MCP - and control exactly which MCP tools Hermes loads"

MCP (Model Context Protocol)

MCP ช่วยให้ Hermes Agent เชื่อมต่อกับ external tool servers เพื่อให้ agent สามารถใช้เครื่องมือที่อยู่ภายนอกตัว Hermes เองได้ ไม่ว่าจะเป็น GitHub, ฐานข้อมูล, file systems, browser stacks, internal APIs, และอื่น ๆ อีกมากมาย

หากคุณเคยต้องการให้ Hermes ใช้เครื่องมือที่มีอยู่แล้วที่อื่น MCP มักจะเป็นวิธีที่สะอาดที่สุดในการทำเช่นนั้น

สิ่งที่ MCP มอบให้

• การเข้าถึงระบบนิเวศของเครื่องมือภายนอก โดยไม่ต้องเขียนเครื่องมือ native Hermes ก่อน
• stdio servers แบบ local และ remote HTTP MCP servers ในการกำหนดค่าเดียวกัน
• การค้นพบและการลงทะเบียนเครื่องมือโดยอัตโนมัติเมื่อเริ่มต้นระบบ
• Utility wrappers สำหรับ MCP resources และ prompts เมื่อเซิร์ฟเวอร์รองรับ
• การกรองระดับเซิร์ฟเวอร์ (Per-server filtering) เพื่อให้คุณเปิดเผยเฉพาะ MCP tools ที่คุณต้องการให้ Hermes เห็นจริง ๆ

เริ่มต้นใช้งานอย่างรวดเร็ว

1. ติดตั้ง support MCP (รวมอยู่ใน standard install script แล้ว):

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

1. เพิ่ม MCP server ในไฟล์ ~/.hermes/config.yaml:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

1. เริ่มต้น Hermes:

hermes chat

1. สั่งให้ Hermes ใช้ capability ที่รองรับ MCP

ตัวอย่างเช่น:

List the files in /home/user/projects and summarize the repo structure.

Hermes จะค้นพบเครื่องมือของ MCP server และใช้งานมันเหมือนกับเครื่องมืออื่น ๆ

ประเภทของ MCP servers

Stdio servers

Stdio servers ทำงานเป็น local subprocesses และสื่อสารผ่าน stdin/stdout

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"

ควรใช้ stdio servers เมื่อ:

• server ถูกติดตั้งในเครื่อง local
• คุณต้องการการเข้าถึง local resources ที่มีความหน่วงต่ำ (low-latency)
• คุณกำลังทำตามเอกสารของ MCP server ที่แสดง command, args, และ env

HTTP servers

HTTP MCP servers คือ remote endpoints ที่ Hermes เชื่อมต่อโดยตรง

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

ควรใช้ HTTP servers เมื่อ:

• MCP server ถูกโฮสต์ที่อื่น
• องค์กรของคุณเปิดเผย internal MCP endpoints
• คุณไม่ต้องการให้ Hermes สร้าง local subprocess สำหรับ integration นั้น

การอ้างอิงการกำหนดค่าพื้นฐาน

Hermes อ่าน MCP config จาก ~/.hermes/config.yaml ภายใต้ mcp_servers

คีย์ทั่วไป (Common keys)

ตัวอย่าง stdio ขั้นต่ำ

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

ตัวอย่าง HTTP ขั้นต่ำ

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

วิธีที่ Hermes ลงทะเบียน MCP tools

Hermes จะใส่ prefix ให้กับ MCP tools เพื่อป้องกันการชนกับชื่อที่ built-in:

mcp_<server_name>_<tool_name>

ตัวอย่าง:

ในทางปฏิบัติ โดยปกติคุณไม่จำเป็นต้องเรียกชื่อที่มี prefix นี้ด้วยตนเอง - Hermes จะเห็นเครื่องมือและเลือกใช้ในระหว่างการให้เหตุผล (reasoning) ตามปกติ

MCP utility tools

เมื่อรองรับแล้ว Hermes ยังลงทะเบียน utility tools รอบ ๆ MCP resources และ prompts:

• list_resources
• read_resource
• list_prompts
• get_prompt

สิ่งเหล่านี้จะถูกลงทะเบียนต่อ server ด้วยรูปแบบ prefix เดียวกัน ตัวอย่างเช่น:

• mcp_github_list_resources
• mcp_github_get_prompt

สำคัญ

Utility tools เหล่านี้จะมีความสามารถในการรับรู้ (capability-aware):

• Hermes จะลงทะเบียน resource utilities ก็ต่อเมื่อ MCP session นั้นรองรับ resource operations จริง ๆ
• Hermes จะลงทะเบียน prompt utilities ก็ต่อเมื่อ MCP session นั้นรองรับ prompt operations จริง ๆ

ดังนั้น server ที่เปิดเผย callable tools แต่ไม่มี resources/prompts จะไม่ได้รับ wrappers เพิ่มเติมเหล่านี้

การกรองต่อ server (Per-server filtering)

คุณสามารถควบคุมได้ว่าแต่ละ MCP server จะมีส่วนร่วมเครื่องมือใดกับ Hermes ทำให้สามารถจัดการ namespace ของเครื่องมือได้อย่างละเอียด

ปิดใช้งาน server ทั้งหมด

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

ถ้า enabled: false, Hermes จะข้าม server นั้นไปโดยสมบูรณ์และจะไม่พยายามเชื่อมต่อด้วยซ้ำ

Whitelist server tools

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [create_issue, list_issues]

เฉพาะ MCP server tools เหล่านั้นเท่านั้นที่จะถูกลงทะเบียน

Blacklist server tools

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer]

จะลงทะเบียน server tools ทั้งหมด ยกเว้นที่ถูกยกเว้น

กฎลำดับความสำคัญ (Precedence rule)

หากมีทั้งสองอย่าง:

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

include จะมีผลเหนือกว่า

กรอง utility tools ด้วย

คุณยังสามารถปิดใช้งาน utility wrappers ที่เพิ่มโดย Hermes ได้แยกต่างหาก:

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

นั่นหมายความว่า:

• tools.resources: false ปิดใช้งาน list_resources และ read_resource
• tools.prompts: false ปิดใช้งาน list_prompts และ get_prompt

ตัวอย่างเต็มรูปแบบ

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [create_issue, list_issues, search_code]
      prompts: false

  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]
      resources: false

  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

จะเกิดอะไรขึ้นถ้าทุกอย่างถูกกรองออกไป?

หาก config ของคุณกรองเครื่องมือที่เรียกใช้ได้ทั้งหมด และปิดใช้งานหรือละเว้น utility ที่รองรับทั้งหมด Hermes จะไม่สร้าง runtime MCP toolset ที่ว่างเปล่าสำหรับ server นั้น

สิ่งนี้ช่วยให้รายการเครื่องมือสะอาด

พฤติกรรมขณะรันไทม์ (Runtime behavior)

เวลาค้นพบ (Discovery time)

Hermes ค้นพบ MCP servers เมื่อเริ่มต้นระบบ และลงทะเบียนเครื่องมือของพวกมันใน tool registry ปกติ

Dynamic Tool Discovery

MCP servers สามารถแจ้งให้ Hermes ทราบเมื่อเครื่องมือที่พร้อมใช้งานมีการเปลี่ยนแปลงขณะรันไทม์ โดยการส่ง notification ชื่อ notifications/tools/list_changed เมื่อ Hermes ได้รับ notification นี้ มันจะดึงรายการเครื่องมือของ server ใหม่โดยอัตโนมัติและอัปเดต registry - ไม่จำเป็นต้องทำ /reload-mcp ด้วยตนเอง

สิ่งนี้มีประโยชน์สำหรับ MCP servers ที่ความสามารถมีการเปลี่ยนแปลงแบบ dynamic (เช่น server ที่เพิ่มเครื่องมือเมื่อมีการโหลด database schema ใหม่ หรือลบเครื่องมือเมื่อบริการออฟไลน์)

การรีเฟรชจะมีการป้องกันด้วย lock เพื่อไม่ให้ notification ที่ถี่เกินไปจาก server เดียวกันทำให้เกิดการรีเฟรชที่ทับซ้อนกัน Prompt และ resource change notifications (prompts/list_changed, resources/list_changed) จะได้รับแต่ยังไม่ได้ดำเนินการ

การโหลดซ้ำ (Reloading)

หากคุณเปลี่ยน MCP config ให้ใช้:

/reload-mcp

สิ่งนี้จะโหลด MCP servers ใหม่จาก config และรีเฟรชรายการเครื่องมือที่พร้อมใช้งาน สำหรับการเปลี่ยนแปลงเครื่องมือขณะรันไทม์ที่ถูก push โดย server เอง ให้ดูที่ Dynamic Tool Discovery ด้านบน

Toolsets

MCP server ที่กำหนดค่าไว้แต่ละตัวจะสร้าง runtime toolset เมื่อมันมีส่วนร่วมเครื่องมือที่ลงทะเบียนอย่างน้อยหนึ่งตัว:

mcp-<server>

สิ่งนี้ทำให้ MCP servers ง่ายต่อการให้เหตุผลในระดับ toolset

Security model

Stdio env filtering

สำหรับ stdio servers, Hermes จะไม่ส่ง full shell environment ของคุณไปโดยไม่ตรวจสอบ

จะส่งเฉพาะ env ที่กำหนดค่าอย่างชัดเจน บวกกับ baseline ที่ปลอดภัยเท่านั้น สิ่งนี้ช่วยลดการรั่วไหลของ secret โดยไม่ได้ตั้งใจ

Config-level exposure control

การรองรับการกรองใหม่นี้ยังเป็น security control:

• ปิดใช้งานเครื่องมืออันตรายที่คุณไม่ต้องการให้ model เห็น
• เปิดเผยเฉพาะ whitelist ขั้นต่ำสำหรับ server ที่มีความอ่อนไหว
• ปิดใช้งาน resource/prompt wrappers เมื่อคุณไม่ต้องการเปิดเผย surface นั้น

ตัวอย่างกรณีการใช้งาน

GitHub server ที่มี surface การจัดการ issue ขั้นต่ำ

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue]
      prompts: false
      resources: false

ใช้งานแบบนี้:

Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.

Stripe server ที่ลบ actions อันตรายออกไป

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

ใช้งานแบบนี้:

Look up the last 10 failed payments and summarize common failure reasons.

Filesystem server สำหรับ root ของโปรเจกต์เดียว

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

ใช้งานแบบนี้:

Inspect the project root and explain the directory layout.

การแก้ไขปัญหา (Troubleshooting)

MCP server ไม่เชื่อมต่อ

ตรวจสอบ:

# Verify MCP deps are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

จากนั้นตรวจสอบ config ของคุณและเริ่ม Hermes ใหม่

เครื่องมือไม่ปรากฏ

สาเหตุที่เป็นไปได้:

• server ล้มเหลวในการเชื่อมต่อ
• discovery ล้มเหลว
• filter config ของคุณยกเว้นเครื่องมือเหล่านั้น
• utility capability ไม่มีอยู่บน server นั้น
• server ถูกปิดใช้งานด้วย enabled: false

หากคุณตั้งใจกรองเครื่องมือ สิ่งนี้ถือเป็นเรื่องปกติ

ทำไม resource หรือ prompt utilities ถึงไม่ปรากฏ?

เนื่องจาก Hermes จะลงทะเบียน wrappers เหล่านั้นก็ต่อเมื่อทั้งสองอย่างเป็นจริง:

1. config ของคุณอนุญาตให้ทำได้
2. session ของ server นั้นรองรับ capability จริง ๆ

สิ่งนี้เป็นไปตามเจตนาและทำให้รายการเครื่องมือมีความซื่อสัตย์

MCP Sampling Support

MCP servers สามารถร้องขอ LLM inference จาก Hermes ผ่าน protocol sampling/createMessage สิ่งนี้ช่วยให้ MCP server สามารถขอให้ Hermes สร้างข้อความในนามของมันได้ - มีประโยชน์สำหรับ server ที่ต้องการความสามารถ LLM แต่ไม่มี model access ของตัวเอง

Sampling เปิดใช้งานโดยค่าเริ่มต้น สำหรับ MCP servers ทั้งหมด (เมื่อ MCP SDK รองรับ) กำหนดค่าได้ต่อ server ภายใต้คีย์ sampling:

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # เปิดใช้งาน sampling (default: true)
      model: "openai/gpt-4o"  # Override model สำหรับ sampling requests (optional)
      max_tokens_cap: 4096     # Max tokens ต่อ sampling response (default: 4096)
      timeout: 30              # Timeout ในหน่วยวินาทีต่อ request (default: 30)
      max_rpm: 10              # Rate limit: max requests ต่อนาที (default: 10)
      max_tool_rounds: 5       # Max tool-use rounds ใน sampling loops (default: 5)
      allowed_models: []       # Allowlist ของชื่อ model ที่ server อาจร้องขอ (empty = any)
      log_level: "info"        # Audit log level: debug, info, หรือ warning (default: info)

sampling handler รวมถึง sliding-window rate limiter, per-request timeouts, และ tool-loop depth limits เพื่อป้องกันการใช้งานที่มากเกินไป Metrics (จำนวน request, errors, tokens used) จะถูกติดตามต่อ server instance

ในการปิดใช้งาน sampling สำหรับ server เฉพาะ:

mcp_servers:
  untrusted_server:
    url: "https://mcp.example.com"
    sampling:
      enabled: false

การรัน Hermes เป็น MCP server

นอกเหนือจากการเชื่อมต่อ ไปยัง MCP servers แล้ว Hermes ยังสามารถ เป็น MCP server ได้ด้วย สิ่งนี้ช่วยให้ agent อื่น ๆ ที่รองรับ MCP (Claude Code, Cursor, Codex, หรือ MCP client ใด ๆ) สามารถใช้ messaging capabilities ของ Hermes ได้ - เช่น การแสดงรายการ conversation, การอ่าน message history, และการส่งข้อความข้ามแพลตฟอร์มที่เชื่อมต่อทั้งหมดของคุณ

เมื่อใดที่ควรใช้สิ่งนี้

• คุณต้องการให้ Claude Code, Cursor, หรือ coding agent อื่น ๆ ส่งและอ่านข้อความ Telegram/Discord/Slack ผ่าน Hermes
• คุณต้องการ MCP server เดียวที่เชื่อมต่อกับ messaging platforms ทั้งหมดของ Hermes ในคราวเดียว
• คุณมี Hermes gateway ที่กำลังทำงานอยู่พร้อมกับ platforms ที่เชื่อมต่อแล้ว

เริ่มต้นใช้งานอย่างรวดเร็ว

hermes mcp serve

สิ่งนี้จะเริ่มต้น stdio MCP server MCP client (ไม่ใช่คุณ) จะจัดการ lifecycle ของ process

การกำหนดค่า MCP client

เพิ่ม Hermes ใน config ของ MCP client ของคุณ ตัวอย่างเช่น ใน ~/.claude/claude_desktop_config.json ของ Claude Code:

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

หรือหากคุณติดตั้ง Hermes ในตำแหน่งเฉพาะ:

{
  "mcpServers": {
    "hermes": {
      "command": "/home/user/.hermes/hermes-agent/venv/bin/hermes",
      "args": ["mcp", "serve"]
    }
  }
}

เครื่องมือที่พร้อมใช้งาน

MCP server เปิดเผย 10 tools ซึ่งตรงกับ surface ของ channel bridge ของ OpenClaw บวกกับ channel browser เฉพาะของ Hermes:

ระบบ Event

MCP server มี live event bridge ที่ poll ฐานข้อมูล session ของ Hermes สำหรับข้อความใหม่ สิ่งนี้ทำให้ MCP clients รับรู้ถึง incoming conversations แบบ near-real-time:

# Poll สำหรับ events ใหม่ (non-blocking)
events_poll(after_cursor=0)

# รอ event ถัดไป (บล็อกจนกว่าจะหมด timeout)
events_wait(after_cursor=42, timeout_ms=30000)

ประเภท event: message, approval_requested, approval_resolved

event queue อยู่ในหน่วยความจำ (in-memory) และเริ่มทำงานเมื่อ bridge เชื่อมต่อ ข้อความเก่าสามารถเข้าถึงได้ผ่าน messages_read

Options

hermes mcp serve              # โหมดปกติ
hermes mcp serve --verbose    # Debug logging บน stderr

วิธีการทำงาน

MCP server อ่าน conversation data โดยตรงจาก session store ของ Hermes (~/.hermes/sessions/sessions.json และ SQLite database) background thread จะ poll ฐานข้อมูลสำหรับข้อความใหม่และรักษา event queue ในหน่วยความจำ สำหรับการส่งข้อความ มันใช้โครงสร้างพื้นฐาน send_message เดียวกันกับ Hermes agent เอง

gateway ไม่จำเป็นต้องทำงานสำหรับการดำเนินการอ่าน (การแสดงรายการ conversation, การอ่าน history, การ poll events) แต่จำเป็นต้องทำงานสำหรับการดำเนินการส่ง เนื่องจาก platform adapters ต้องการการเชื่อมต่อที่ทำงานอยู่

ข้อจำกัดปัจจุบัน

• รองรับเฉพาะ Stdio transport (ยังไม่มี HTTP MCP transport)
• Event polling ที่ช่วงประมาณ 200ms ผ่าน DB polling ที่ปรับให้เหมาะสมด้วย mtime (ข้ามการทำงานเมื่อไฟล์ไม่มีการเปลี่ยนแปลง)
• ยังไม่มี protocol push notification claude/channel
• ส่งได้เฉพาะข้อความ (ไม่รองรับการส่ง media/attachment ผ่าน messages_send)

เอกสารที่เกี่ยวข้อง

• Use MCP with Hermes
• CLI Commands
• Slash Commands
• FAQ

📄 user-guide/features/memory.md

sidebar_position: 3 title: "Persistent Memory" description: "How Hermes Agent remembers across sessions — MEMORY.md, USER.md, and session search"

Persistent Memory

Hermes Agent มีหน่วยความจำที่ถูกจำกัดและคัดสรรมาอย่างดี ซึ่งจะคงอยู่แม้จะข้ามเซสชัน (sessions) ไปแล้วก็ตาม สิ่งนี้ช่วยให้ Agent สามารถจดจำความชอบของคุณ โครงการของคุณ สภาพแวดล้อมของคุณ และสิ่งต่างๆ ที่ได้เรียนรู้ไปแล้ว

How It Works

หน่วยความจำของ Agent ประกอบด้วยไฟล์สองไฟล์:

ทั้งสองไฟล์จะถูกจัดเก็บไว้ใน ~/.hermes/memories/ และจะถูกฉีด (injected) เข้าไปใน system prompt เป็นภาพรวมที่ถูกแช่แข็ง (frozen snapshot) เมื่อเริ่มเซสชัน Agent จะจัดการหน่วยความจำของตัวเองผ่าน memory tool — โดยสามารถเพิ่ม เปลี่ยน หรือลบรายการต่างๆ ได้

:::info Character limits ช่วยให้หน่วยความจำมีความกระชับ เมื่อหน่วยความจำเต็ม Agent จะทำการรวมหรือแทนที่รายการต่างๆ เพื่อให้มีพื้นที่สำหรับข้อมูลใหม่ :::

How Memory Appears in the System Prompt

เมื่อเริ่มเซสชันทุกครั้ง รายการหน่วยความจำจะถูกโหลดจาก disk และแสดงผลใน system prompt เป็นบล็อกที่ถูกแช่แข็ง:

══════════════════════════════════════════════
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

รูปแบบประกอบด้วย:

• ส่วนหัว (header) ที่แสดงว่าใช้ store ใด (MEMORY หรือ USER PROFILE)
• เปอร์เซ็นต์การใช้งานและจำนวนตัวอักษร เพื่อให้ Agent ทราบขีดจำกัด
• รายการแต่ละรายการที่ถูกคั่นด้วยตัวคั่น § (section sign)
• รายการสามารถมีหลายบรรทัดได้

Frozen snapshot pattern: การฉีด system prompt จะถูกจับภาพเพียงครั้งเดียวเมื่อเริ่มเซสชัน และจะไม่เปลี่ยนแปลงระหว่างเซสชัน นี่คือสิ่งที่ตั้งใจทำ — เพื่อรักษา prefix cache ของ LLM สำหรับประสิทธิภาพ เมื่อ Agent เพิ่ม/ลบรายการหน่วยความจำระหว่างเซสชัน การเปลี่ยนแปลงจะถูกบันทึกไปยัง disk ทันที แต่จะไม่ปรากฏใน system prompt จนกว่าเซสชันถัดไปจะเริ่ม Tool responses จะแสดงสถานะแบบเรียลไทม์เสมอ

Memory Tool Actions

Agent ใช้ memory tool ด้วย actions เหล่านี้:

• add — เพิ่มรายการหน่วยความจำใหม่
• replace — แทนที่รายการที่มีอยู่ด้วยเนื้อหาที่อัปเดต (ใช้การจับคู่ substring ผ่าน old_text)
• remove — ลบรายการที่ไม่เกี่ยวข้องแล้ว (ใช้การจับคู่ substring ผ่าน old_text)

ไม่มี action read — เนื้อหาหน่วยความจำจะถูกฉีดเข้าสู่ system prompt โดยอัตโนมัติเมื่อเริ่มเซสชัน Agent จะมองว่าหน่วยความจำของมันเป็นส่วนหนึ่งของบริบทการสนทนา

Substring Matching

actions replace และ remove ใช้การจับคู่ substring ที่สั้นและไม่ซ้ำกัน — คุณไม่จำเป็นต้องใช้ข้อความรายการทั้งหมด พารามิเตอร์ old_text เพียงแค่ต้องเป็น 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 ตรงกับหลายรายการ จะมีการส่งข้อผิดพลาดกลับมา โดยขอให้ระบุการจับคู่ที่เฉพาะเจาะจงกว่านี้

Two Targets Explained

memory — Agent's Personal Notes

สำหรับข้อมูลที่ Agent จำเป็นต้องจดจำเกี่ยวกับสภาพแวดล้อม, workflow, และบทเรียนที่ได้เรียนรู้:

• Environment facts (OS, tools, project structure)
• Project conventions and configuration
• Tool quirks and workarounds discovered
• Completed task diary entries
• Skills and techniques that worked

user — User Profile

สำหรับข้อมูลเกี่ยวกับตัวตน, ความชอบ, และรูปแบบการสื่อสารของผู้ใช้:

• Name, role, timezone
• Communication preferences (concise vs detailed, format preferences)
• Pet peeves and things to avoid
• Workflow habits
• Technical skill level

What to Save vs Skip

Save These (Proactively)

Agent จะบันทึกโดยอัตโนมัติ — คุณไม่จำเป็นต้องร้องขอ มันจะบันทึกเมื่อมันเรียนรู้:

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

Skip These

• Trivial/obvious info: "User asked about Python" — คลุมเครือเกินกว่าจะนำไปใช้ประโยชน์ได้
• Easily re-discovered facts: "Python 3.12 supports f-string nesting" — สามารถค้นหาได้จาก web search
• Raw data dumps: Large code blocks, log files, data tables — ใหญ่เกินไปสำหรับหน่วยความจำ
• Session-specific ephemera: Temporary file paths, one-off debugging context
• Information already in context files: SOUL.md และ AGENTS.md content

Capacity Management

หน่วยความจำมีขีดจำกัดตัวอักษรที่เข้มงวด เพื่อให้ system prompt มีขอบเขตที่จำกัด:

What Happens When Memory is Full

เมื่อคุณพยายามเพิ่มรายการที่เกินขีดจำกัด ระบบจะส่งข้อผิดพลาดกลับมา:

{
  "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. อ่านรายการปัจจุบัน (แสดงใน error response)
2. ระบุรายการที่สามารถลบหรือรวมเข้าด้วยกันได้
3. ใช้ replace เพื่อรวมรายการที่เกี่ยวข้องเข้าด้วยกันให้สั้นลง
4. จากนั้นใช้ add สำหรับรายการใหม่

Best practice: เมื่อหน่วยความจำเกิน 80% ของขีดจำกัด (มองเห็นได้ในส่วนหัวของ system prompt) ควรทำการรวมรายการต่างๆ ก่อนที่จะเพิ่มรายการใหม่ ตัวอย่างเช่น การรวมรายการ "project uses X" แยกกันสามรายการ ให้เป็นรายการคำอธิบายโครงการที่ครอบคลุมเพียงรายการเดียว

Practical Examples of Good Memory Entries

รายการที่กระชับและหนาแน่นด้วยข้อมูลจะทำงานได้ดีที่สุด:

# 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

ระบบหน่วยความจำจะปฏิเสธรายการที่ซ้ำกันแบบเป๊ะๆ โดยอัตโนมัติ หากคุณพยายามเพิ่มเนื้อหาที่มีอยู่แล้ว ระบบจะส่งผลสำเร็จพร้อมข้อความ "no duplicate added"

Security Scanning

รายการหน่วยความจำจะถูกสแกนหารูปแบบการ injection และ exfiltration ก่อนที่จะได้รับการยอมรับ เนื่องจากมันถูกฉีดเข้าสู่ system prompt เนื้อหาที่ตรงกับรูปแบบภัยคุกคาม (prompt injection, credential exfiltration, SSH backdoors) หรือมีอักขระ Unicode ที่มองไม่เห็นจะถูกบล็อก

Session Search

นอกเหนือจาก MEMORY.md และ USER.md แล้ว Agent ยังสามารถค้นหาบทสนทนาในอดีตได้โดยใช้ session_search tool:

• All CLI and messaging sessions are stored in SQLite (~/.hermes/state.db) with FTS5 full-text search
• Search queries return relevant past conversations with Gemini Flash summarization
• The agent can find things it discussed weeks ago, even if they're not in its active memory

hermes sessions list    # Browse past sessions

session_search vs memory

Memory ใช้สำหรับข้อเท็จจริงที่สำคัญซึ่งควรอยู่ในบริบทเสมอ Session search ใช้สำหรับคำถามประเภท "เราเคยคุยเรื่อง X เมื่อสัปดาห์ที่แล้วไหม?" ซึ่ง Agent จำเป็นต้องเรียกข้อมูลเฉพาะเจาะจงจากบทสนทนาในอดีต

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, Hermes มาพร้อมกับ 8 external memory provider plugins — รวมถึง Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, และ Supermemory

External providers ทำงาน ควบคู่ไปกับ หน่วยความจำในตัว (ไม่เคยแทนที่) และเพิ่มความสามารถต่างๆ เช่น knowledge graphs, semantic search, automatic fact extraction, และ cross-session user modeling

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

ดูคู่มือ Memory Providers สำหรับรายละเอียดทั้งหมดเกี่ยวกับแต่ละ provider, คำแนะนำในการตั้งค่า, และการเปรียบเทียบ

📄 user-guide/features/memory-providers.md

sidebar_position: 4 title: "Memory Providers" description: "External memory provider plugins - Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory"

Memory Providers

Hermes Agent มาพร้อมกับปลั๊กอิน Memory Provider ภายนอก 8 ตัว ซึ่งช่วยให้ Agent มีความรู้ที่คงอยู่และข้ามเซสชันได้ นอกเหนือจาก MEMORY.md และ USER.md ที่ติดตั้งมาให้แล้ว มี Memory Provider ภายนอกที่สามารถใช้งานได้เพียง ตัวเดียว ในแต่ละครั้ง - ส่วนหน่วยความจำที่ติดตั้งมาให้จะทำงานอยู่เสมอควบคู่กันไป

Quick Start

hermes memory setup      # interactive picker + configuration
hermes memory status     # check what's active
hermes memory off        # disable external provider

คุณยังสามารถเลือก Memory Provider ที่ใช้งานได้ผ่าน hermes plugins → Provider Plugins → Memory Provider

หรือตั้งค่าด้วยตนเองในไฟล์ ~/.hermes/config.yaml:

memory:
  provider: openviking   # or honcho, mem0, hindsight, holographic, retaindb, byterover, supermemory

How It Works

เมื่อ Memory Provider ถูกเปิดใช้งาน Hermes จะดำเนินการโดยอัตโนมัติ:

1. ฉีดบริบทของผู้ให้บริการ เข้าไปใน system prompt (สิ่งที่ผู้ให้บริการรู้)
2. ดึงความทรงจำที่เกี่ยวข้องล่วงหน้า ก่อนการตอบกลับแต่ละครั้ง (ทำงานเบื้องหลัง ไม่บล็อก)
3. ซิงค์การสนทนา ไปยังผู้ให้บริการหลังจากตอบกลับแต่ละครั้ง
4. ดึงความทรงจำเมื่อเซสชันสิ้นสุด (สำหรับผู้ให้บริการที่รองรับ)
5. สะท้อนการเขียนหน่วยความจำที่ติดตั้งมาให้ ไปยังผู้ให้บริการภายนอก
6. เพิ่มเครื่องมือเฉพาะของผู้ให้บริการ เพื่อให้ Agent สามารถค้นหา จัดเก็บ และจัดการความทรงจำได้

หน่วยความจำที่ติดตั้งมาให้ (MEMORY.md / USER.md) ยังคงทำงานได้ตามปกติ ส่วนผู้ให้บริการภายนอกจะทำหน้าที่เสริมความสามารถเพิ่มเติม

Available Providers

Honcho

การสร้างแบบจำลองผู้ใช้ข้ามเซสชันระดับ AI-native ด้วยการให้เหตุผลแบบ dialectic, การฉีดบริบทตามขอบเขตเซสชัน, การค้นหาเชิงความหมาย (semantic search), และข้อสรุปที่คงอยู่ (persistent conclusions) บริบทพื้นฐานตอนนี้รวมถึงสรุปเซสชันควบคู่ไปกับการแสดงตัวแทนผู้ใช้ (user representation) และ peer cards ทำให้ Agent รับรู้ว่ามีการพูดคุยอะไรไปแล้ว

Tools (5): honcho_profile (อ่าน/อัปเดต peer card), honcho_search (semantic search), honcho_context (session context - summary, representation, card, messages), honcho_reasoning (LLM-synthesized), honcho_conclude (สร้าง/ลบ conclusions)

Architecture: การฉีดบริบทสองชั้น - ชั้นพื้นฐาน (session summary + representation + peer card, รีเฟรชเมื่อ contextCadence) บวกกับส่วนเสริมแบบ dialectic (LLM reasoning, รีเฟรชเมื่อ dialecticCadence) ส่วนเสริมแบบ dialectic จะเลือก prompt แบบ cold-start (ข้อเท็จจริงทั่วไปของผู้ใช้) เทียบกับ warm prompts (บริบทตามขอบเขตเซสชัน) โดยอัตโนมัติ ขึ้นอยู่กับว่ามีบริบทพื้นฐานอยู่หรือไม่

สามปุ่มปรับการตั้งค่าที่ตั้งฉากกัน ควบคุมค่าใช้จ่ายและความลึกได้อย่างอิสระ:

• contextCadence - ความถี่ที่ชั้นพื้นฐานรีเฟรช (ความถี่ในการเรียก API)
• dialecticCadence - ความถี่ที่ LLM แบบ dialectic ทำงาน (ความถี่ในการเรียก LLM)
• dialecticDepth - จำนวนรอบ .chat() ต่อการเรียก dialectic หนึ่งครั้ง (1-3, ความลึกของการให้เหตุผล)

Setup Wizard:

hermes honcho setup        # (legacy command) 
# or
hermes memory setup        # select "honcho"

Config: $HERMES_HOME/honcho.json (profile-local) หรือ ~/.honcho/config.json (global). ลำดับการแก้ไข: $HERMES_HOME/honcho.json > ~/.hermes/honcho.json > ~/.honcho/config.json. ดู config reference และ Honcho integration guide.

{
  "apiKey": "your-key-from-app.honcho.dev",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "peerName": "your-name",
      "workspace": "hermes"
    }
  }
}

{
  "baseUrl": "http://localhost:8000",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "peerName": "your-name",
      "workspace": "hermes"
    }
  }
}

:::tip Migrating from hermes honcho หากคุณเคยใช้ hermes honcho setup มาก่อน config และข้อมูลฝั่ง server ทั้งหมดของคุณยังคงอยู่ เพียงแค่เปิดใช้งานผ่าน setup wizard อีกครั้ง หรือตั้งค่า memory.provider: honcho ด้วยตนเองเพื่อเปิดใช้งานผ่านระบบใหม่ :::

Multi-peer setup:

Honcho สร้างแบบจำลองการสนทนาในรูปแบบของ peers ที่แลกเปลี่ยนข้อความ - user peer หนึ่งตัวบวกกับ AI peer หนึ่งตัวต่อ Hermes profile โดยทั้งหมดแชร์ workspace workspace คือสภาพแวดล้อมที่ใช้ร่วมกัน: user peer เป็น global ทั่วทุก profile, ส่วน AI peer แต่ละตัวเป็น identity ของตัวเอง ทุก AI peer จะสร้าง representation / card ที่เป็นอิสระจาก observations ของตัวเอง ดังนั้น profile coder จะยังคงเน้นด้านโค้ด ในขณะที่ profile writer จะยังคงเน้นด้านการแก้ไข แม้จะใช้ user คนเดียวกัน

การแมป:

New profile, fresh Honcho peer

hermes profile create coder --clone

--clone จะสร้าง host block hermes.coder ใน honcho.json ด้วย aiPeer: "coder", workspace ที่แชร์, peerName ที่สืบทอด, recallMode, writeFrequency, observation, ฯลฯ AI peer จะถูกสร้างขึ้นอย่างกระตือรือร้น (eagerly) ใน Honcho เพื่อให้มีอยู่ก่อนข้อความแรก

Existing profiles, backfill Honcho peers

hermes honcho sync

สแกนทุก Hermes profile, สร้าง host blocks สำหรับ profile ใด ๆ ที่ยังไม่มี, สืบทอดการตั้งค่าจาก block hermes default, และสร้าง AI peers ใหม่แบบ eager ทันที ทำงานแบบ Idempotent - จะข้าม profile ที่มี host block อยู่แล้ว

Per-profile observation

แต่ละ host block สามารถแทนที่การตั้งค่า observation ได้อย่างอิสระ ตัวอย่าง: profile ที่เน้นโค้ดซึ่ง AI peer สังเกตผู้ใช้ แต่ไม่ได้สร้างแบบจำลองตัวเอง:

"hermes.coder": {
  "aiPeer": "coder",
  "observation": {
    "user": { "observeMe": true, "observeOthers": true },
    "ai":   { "observeMe": false, "observeOthers": true }
  }
}

Observation toggles (ชุดละชุดต่อ peer):

Presets ผ่าน observationMode:

• "directional" (default) - ทั้งสี่ flags เปิด. การสังเกตแบบสมมาตรเต็มรูปแบบ; เปิดใช้งาน dialectic ข้าม peer.
• "unified" - user observeMe: true, AI observeOthers: true, ที่เหลือเป็น false. single-observer pool; AI สร้างแบบจำลองผู้ใช้ แต่ไม่สร้างแบบจำลองตัวเอง, user peer สร้างแบบจำลองตัวเองเท่านั้น.

Server-side toggles ที่ตั้งค่าผ่าน Honcho dashboard จะมีผลเหนือกว่าค่า default ท้องถิ่น - และจะซิงค์กลับเมื่อเริ่มต้นเซสชัน

ดู Honcho page สำหรับ reference observation ฉบับเต็ม

{
  "apiKey": "your-key",
  "workspace": "hermes",
  "peerName": "eri",
  "hosts": {
    "hermes": {
      "enabled": true,
      "aiPeer": "hermes",
      "workspace": "hermes",
      "peerName": "eri",
      "recallMode": "hybrid",
      "writeFrequency": "async",
      "sessionStrategy": "per-directory",
      "observation": {
        "user": { "observeMe": true, "observeOthers": true },
        "ai": { "observeMe": true, "observeOthers": true }
      },
      "dialecticReasoningLevel": "low",
      "dialecticDynamic": true,
      "dialecticCadence": 2,
      "dialecticDepth": 1,
      "dialecticMaxChars": 600,
      "contextCadence": 1,
      "messageMaxChars": 25000,
      "saveMessages": true
    },
    "hermes.coder": {
      "enabled": true,
      "aiPeer": "coder",
      "workspace": "hermes",
      "peerName": "eri",
      "recallMode": "tools",
      "observation": {
        "user": { "observeMe": true, "observeOthers": false },
        "ai": { "observeMe": true, "observeOthers": true }
      }
    },
    "hermes.writer": {
      "enabled": true,
      "aiPeer": "writer",
      "workspace": "hermes",
      "peerName": "eri"
    }
  },
  "sessions": {
    "/home/user/myproject": "myproject-main"
  }
}

ดู config reference และ Honcho integration guide.

OpenViking

Context database จาก Volcengine (ByteDance) ที่มีลำดับชั้นความรู้แบบ filesystem-style, การดึงข้อมูลแบบ tiered, และการดึงความทรงจำอัตโนมัติออกเป็น 6 หมวดหมู่

Tools: viking_search (semantic search), viking_read (tiered: abstract/overview/full), viking_browse (filesystem navigation), viking_remember (store facts), viking_add_resource (ingest URLs/docs)

Setup:

# Start the OpenViking server first
pip install openviking
openviking-server

# Then configure Hermes
hermes memory setup    # select "openviking"
# Or manually:
hermes config set memory.provider openviking
echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env

Key features:

• Tiered context loading: L0 (~100 tokens) → L1 (~2k) → L2 (full)
• Automatic memory extraction on session commit (profile, preferences, entities, events, cases, patterns)
• viking:// URI scheme สำหรับการเรียกดูความรู้แบบลำดับชั้น

Mem0

การดึงข้อเท็จจริง (fact extraction) ด้วย LLM ฝั่ง server พร้อม semantic search, reranking, และการลบข้อมูลซ้ำอัตโนมัติ

Tools: mem0_profile (all stored memories), mem0_search (semantic search + reranking), mem0_conclude (store verbatim facts)

Setup:

hermes memory setup    # select "mem0"
# Or manually:
hermes config set memory.provider mem0
echo "MEM0_API_KEY=your-key" >> ~/.hermes/.env

Config: $HERMES_HOME/mem0.json

Hindsight

หน่วยความจำระยะยาวด้วย knowledge graph, entity resolution, และ multi-strategy retrieval เครื่องมือ hindsight_reflect ให้การสังเคราะห์ความทรงจำข้าม (cross-memory synthesis) ที่ผู้ให้บริการอื่นไม่มีให้ นอกจากนี้ยังคงการสนทนาทั้งหมด (รวมถึง tool calls) พร้อมการติดตามเอกสารระดับเซสชันโดยอัตโนมัติ

Tools: hindsight_retain (store with entity extraction), hindsight_recall (multi-strategy search), hindsight_reflect (cross-memory synthesis)

Setup:

hermes memory setup    # select "hindsight"
# Or manually:
hermes config set memory.provider hindsight
echo "HINDSIGHT_API_KEY=your-key" >> ~/.hermes/.env

setup wizard จะติดตั้ง dependencies โดยอัตโนมัติ และติดตั้งเฉพาะสิ่งที่จำเป็นสำหรับโหมดที่เลือก (hindsight-client สำหรับ cloud, hindsight-all สำหรับ local) ต้องใช้ hindsight-client >= 0.4.22 (จะอัปเกรดอัตโนมัติเมื่อเริ่มเซสชันหากล้าสมัย)

Local mode UI: hindsight-embed -p hermes ui start

Config: $HERMES_HOME/hindsight/config.json

ดู plugin README สำหรับ reference configuration ฉบับเต็ม

Holographic

Local SQLite fact store พร้อม FTS5 full-text search, trust scoring, และ HRR (Holographic Reduced Representations) สำหรับการสอบถามเชิงพีชคณิตแบบ compositional

Tools: fact_store (9 actions: add, search, probe, related, reason, contradict, update, remove, list), fact_feedback (helpful/unhelpful rating ที่ใช้ฝึก trust scores)

Setup:

hermes memory setup    # select "holographic"
# Or manually:
hermes config set memory.provider holographic

Config: config.yaml ภายใต้ plugins.hermes-memory-store

Unique capabilities:

• probe - การเรียกคืนเชิงพีชคณิตเฉพาะ entity (ข้อเท็จจริงทั้งหมดเกี่ยวกับบุคคล/สิ่งของ)
• reason - การสอบถาม AND แบบ compositional ข้ามหลาย entity
• contradict - การตรวจจับข้อเท็จจริงที่ขัดแย้งกันโดยอัตโนมัติ
• Trust scoring พร้อม feedback แบบไม่สมมาตร (+0.05 helpful / -0.10 unhelpful)

RetainDB

Cloud memory API พร้อม hybrid search (Vector + BM25 + Reranking), 7 memory types, และ delta compression

Tools: retaindb_profile (user profile), retaindb_search (semantic search), retaindb_context (task-relevant context), retaindb_remember (store with type + importance), retaindb_forget (delete memories)

Setup:

hermes memory setup    # select "retaindb"
# Or manually:
hermes config set memory.provider retaindb
echo "RETAINDB_API_KEY=your-key" >> ~/.hermes/.env

ByteRover

หน่วยความจำแบบคงทนผ่าน brv CLI - knowledge tree แบบลำดับชั้นพร้อม tiered retrieval (fuzzy text → LLM-driven search). Local-first พร้อม cloud sync แบบทางเลือก

Tools: brv_query (search knowledge tree), brv_curate (store facts/decisions/patterns), brv_status (CLI version + tree stats)

Setup:

# Install the CLI first
curl -fsSL https://byterover.dev/install.sh | sh

# Then configure Hermes
hermes memory setup    # select "byterover"
# Or manually:
hermes config set memory.provider byterover

Key features:

• Automatic pre-compression extraction (บันทึก insights ก่อนที่ context compression จะทิ้งมันไป)
• Knowledge tree ถูกจัดเก็บที่ $HERMES_HOME/byterover/ (profile-scoped)
• SOC2 Type II certified cloud sync (optional)

Supermemory

หน่วยความจำระยะยาวเชิงความหมาย (Semantic) พร้อม profile recall, semantic search, explicit memory tools, และการ ingest การสนทนาเมื่อเซสชันสิ้นสุดผ่าน Supermemory graph API

Tools: supermemory_store (save explicit memories), supermemory_search (semantic similarity search), supermemory_forget (forget by ID หรือ best-match query), supermemory_profile (persistent profile + recent context)

Setup:

hermes memory setup    # select "supermemory"
# Or manually:
hermes config set memory.provider supermemory
echo 'SUPERMEMORY_API_KEY=***' >> ~/.hermes/.env

Config: $HERMES_HOME/supermemory.json

Environment variables: SUPERMEMORY_API_KEY (required), SUPERMEMORY_CONTAINER_TAG (overrides config).

Key features:

• Automatic context fencing - ลบ recalled memories ออกจาก captured turns เพื่อป้องกัน memory pollution แบบ recursive
• Session-end conversation ingest สำหรับการสร้างความรู้ระดับ graph ที่สมบูรณ์ยิ่งขึ้น
• Profile facts ถูกฉีดในรอบแรกและช่วงเวลาที่กำหนดค่าได้
• Trivial message filtering (ข้าม "ok", "thanks", ฯลฯ)
• Profile-scoped containers - ใช้ {identity} ใน container_tag (เช่น hermes-{identity} → hermes-coder) เพื่อแยก memories ต่อ Hermes profile
• Multi-container mode - เปิดใช้งาน enable_custom_container_tags ด้วยรายการ custom_containers เพื่อให้ Agent สามารถอ่าน/เขียนข้าม containers ที่ตั้งชื่อได้ การดำเนินการอัตโนมัติ (sync, prefetch) ยังคงอยู่บน container หลัก

{
  "container_tag": "hermes",
  "enable_custom_container_tags": true,
  "custom_containers": ["project-alpha", "shared-knowledge"],
  "custom_container_instructions": "Use project-alpha for coding context."
}

Support: Discord · [email protected]

Provider Comparison

Profile Isolation

ข้อมูลของแต่ละ provider จะถูกแยกตาม profile:

• Local storage providers (Holographic, ByteRover) ใช้ path $HERMES_HOME/ ซึ่งแตกต่างกันไปตาม profile
• Config file providers (Honcho, Mem0, Hindsight, Supermemory) จัดเก็บ config ใน $HERMES_HOME/ เพื่อให้แต่ละ profile มี credentials ของตัวเอง
• Cloud providers (RetainDB) จะอนุมานชื่อ project-scoped โดยอัตโนมัติ
• Env var providers (OpenViking) ถูกกำหนดค่าผ่านไฟล์ .env ของแต่ละ profile

Building a Memory Provider

ดู Developer Guide: Memory Provider Plugins สำหรับวิธีสร้างผู้ให้บริการหน่วยความจำของคุณเอง

📄 user-guide/features/personality.md

sidebar_position: 9 title: "Personality & SOUL.md" description: "Customize Hermes Agent's personality with a global SOUL.md, built-in personalities, and custom persona definitions"

บุคลิกภาพและ SOUL.md

บุคลิกภาพของ Hermes Agent สามารถปรับแต่งได้อย่างสมบูรณ์แบบ SOUL.md คือ ตัวตนหลัก (primary identity) - เป็นสิ่งแรกใน system prompt และกำหนดว่า agent คือใคร

• SOUL.md - ไฟล์บุคลิกภาพที่คงทน (durable persona file) ซึ่งอยู่ใน HERMES_HOME และทำหน้าที่เป็นตัวตนของ agent (slot #1 ใน system prompt)
• built-in หรือ custom /personality presets - การทับซ้อนของ system-prompt ในระดับ session

หากคุณต้องการเปลี่ยนว่า Hermes คือใคร - หรือต้องการแทนที่ด้วยบุคลิกภาพของ agent ที่แตกต่างไปอย่างสิ้นเชิง - ให้แก้ไข SOUL.md

SOUL.md ทำงานอย่างไรในปัจจุบัน

Hermes จะทำการใส่ (seed) ไฟล์ SOUL.md เริ่มต้นโดยอัตโนมัติในตำแหน่ง:

~/.hermes/SOUL.md

ที่แม่นยำกว่านั้นคือ มันจะใช้ HERMES_HOME ของ instance ปัจจุบัน ดังนั้นหากคุณรัน Hermes ด้วย home directory ที่กำหนดเอง มันจะใช้:

$HERMES_HOME/SOUL.md

พฤติกรรมที่สำคัญ

• SOUL.md คือตัวตนหลักของ agent มันจะอยู่ใน slot #1 ของ system prompt โดยแทนที่ตัวตนเริ่มต้นแบบ hardcoded
• Hermes จะสร้าง SOUL.md เริ่มต้นโดยอัตโนมัติหากยังไม่มีไฟล์นี้
• ไฟล์ SOUL.md ของผู้ใช้ที่มีอยู่จะไม่ถูกเขียนทับโดยเด็ดขาด
• Hermes จะโหลด SOUL.md จาก HERMES_HOME เท่านั้น
• Hermes จะไม่ค้นหา SOUL.md ใน current working directory
• หาก SOUL.md มีอยู่แต่ว่างเปล่า หรือไม่สามารถโหลดได้ Hermes จะใช้ตัวตนเริ่มต้นแบบ built-in
• หาก SOUL.md มีเนื้อหา เนื้อหานั้นจะถูกแทรกเข้าไปตามต้นฉบับ (verbatim) หลังจากการสแกนความปลอดภัยและการตัดทอน (truncation)
• SOUL.md จะไม่ ถูกทำซ้ำในส่วน context files - มันจะปรากฏเพียงครั้งเดียว ในฐานะตัวตน

นั่นทำให้ SOUL.md เป็นตัวตนที่แท้จริงสำหรับผู้ใช้แต่ละคนหรือ instance แต่ละ instance ไม่ใช่แค่ชั้นที่เพิ่มเข้าไป

เหตุผลของการออกแบบนี้

สิ่งนี้ช่วยให้บุคลิกภาพมีความคาดเดาได้

หาก Hermes โหลด SOUL.md จาก directory ใดก็ตามที่คุณบังเอิญเปิดมัน บุคลิกภาพของคุณอาจเปลี่ยนแปลงอย่างไม่คาดคิดระหว่างโปรเจกต์ต่างๆ การโหลดจาก HERMES_HOME เท่านั้น ทำให้บุคลิกภาพนั้นเป็นของ instance ของ Hermes เอง

นอกจากนี้ยังทำให้การสอนผู้ใช้ทำได้ง่ายขึ้น:

• "แก้ไข ~/.hermes/SOUL.md เพื่อเปลี่ยนบุคลิกภาพเริ่มต้นของ Hermes"

ตำแหน่งที่ควรแก้ไข

สำหรับผู้ใช้ส่วนใหญ่:

~/.hermes/SOUL.md

หากคุณใช้ home directory ที่กำหนดเอง:

$HERMES_HOME/SOUL.md

ควรใส่เนื้อหาอะไรใน SOUL.md?

ใช้สำหรับคำแนะนำด้านน้ำเสียงและบุคลิกภาพที่คงทน เช่น:

• tone
• communication style
• level of directness
• default interaction style
• สิ่งที่ควรหลีกเลี่ยงในเชิงรูปแบบ (stylistically)
• วิธีที่ Hermes ควรจัดการกับความไม่แน่นอน ความขัดแย้ง หรือความคลุมเครือ

ควรใช้สำหรับ:

• คำแนะนำโปรเจกต์แบบครั้งเดียว (one-off project instructions)
• file paths
• repo conventions
• รายละเอียด workflow ชั่วคราว

สิ่งเหล่านี้ควรอยู่ใน AGENTS.md ไม่ใช่ SOUL.md

เนื้อหา SOUL.md ที่ดี

ไฟล์ SOUL ที่ดีควรมีคุณสมบัติดังนี้:

• มีความเสถียรข้าม context
• กว้างพอที่จะใช้ได้ในการสนทนาหลายรูปแบบ
• เฉพาะเจาะจงพอที่จะกำหนดรูปลักษณ์ของน้ำเสียงได้อย่างเป็นรูปธรรม
• มุ่งเน้นที่การสื่อสารและตัวตน ไม่ใช่คำแนะนำเฉพาะงาน

ตัวอย่าง

# Personality

You are a pragmatic senior engineer with strong taste.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler
- Push back when something is a bad idea
- Admit uncertainty plainly
- Keep explanations compact unless depth is useful

## What to avoid
- Sycophancy
- Hype language
- Repeating the user's framing if it's wrong
- Overexplaining obvious things

## Technical posture
- Prefer simple systems over clever systems
- Care about operational reality, not idealized architecture
- Treat edge cases as part of the design, not cleanup

สิ่งที่ Hermes แทรกเข้าไปใน prompt

เนื้อหาของ SOUL.md จะถูกใส่โดยตรงใน slot #1 ของ system prompt - ตำแหน่งตัวตนของ agent จะไม่มีการเพิ่มภาษาห่อหุ้มใดๆ

เนื้อหาจะผ่านกระบวนการ:

• prompt-injection scanning
• truncation หากมีขนาดใหญ่เกินไป

หากไฟล์ว่างเปล่า มีแต่ช่องว่าง (whitespace-only) หรือไม่สามารถอ่านได้ Hermes จะใช้ตัวตนเริ่มต้นแบบ built-in ("You are Hermes Agent, an intelligent AI assistant created by Nous Research..."). การ fallback นี้ยังใช้เมื่อตั้งค่า skip_context_files (เช่น ใน context ของ subagent/delegation)

การสแกนความปลอดภัย (Security scanning)

SOUL.md จะถูกสแกนเหมือนกับไฟล์อื่นที่บรรจุ context สำหรับรูปแบบ prompt injection ก่อนที่จะถูกรวมเข้าไป

นั่นหมายความว่าคุณควรยังคงมุ่งเน้นที่ persona/voice มากกว่าการพยายามแอบใส่ meta-instructions แปลกๆ เข้าไป

SOUL.md vs AGENTS.md

นี่คือความแตกต่างที่สำคัญที่สุด

SOUL.md

ใช้สำหรับ:

• identity
• tone
• style
• communication defaults
• behavior ระดับบุคลิกภาพ

AGENTS.md

ใช้สำหรับ:

• project architecture
• coding conventions
• tool preferences
• repo-specific workflows
• commands, ports, paths, deployment notes

กฎที่เป็นประโยชน์:

• หากสิ่งนั้นควรตามคุณไปทุกที่ มันควรอยู่ใน SOUL.md
• หากสิ่งนั้นเป็นของโปรเจกต์ มันควรอยู่ใน AGENTS.md

SOUL.md vs /personality

SOUL.md คือบุคลิกภาพเริ่มต้นที่คงทนของคุณ

/personality คือ overlay ระดับ session ที่เปลี่ยนแปลงหรือเสริม system prompt ปัจจุบัน

ดังนั้น:

• SOUL.md = น้ำเสียงพื้นฐาน (baseline voice)
• /personality = การสลับโหมดชั่วคราว (temporary mode switch)

ตัวอย่าง:

• รักษา SOUL ที่เป็นกลางไว้ แล้วใช้ /personality teacher สำหรับการสนทนาแบบสอน
• รักษา SOUL ที่กระชับไว้ แล้วใช้ /personality creative สำหรับการระดมสมอง

built-in personalities

Hermes มาพร้อมกับ built-in personalities ที่คุณสามารถสลับไปใช้ได้ด้วย /personality

การสลับบุคลิกภาพด้วยคำสั่ง (commands)

CLI

/personality
/personality concise
/personality technical

Messaging platforms

/personality teacher

เหล่านี้เป็น overlay ที่สะดวก แต่ SOUL.md ทั่วโลกของคุณยังคงมอบบุคลิกภาพเริ่มต้นที่คงอยู่ให้กับ Hermes เว้นแต่ว่า overlay นั้นจะเปลี่ยนแปลงมันอย่างมีความหมาย

custom personalities ใน config

คุณยังสามารถกำหนด custom personalities ที่มีชื่อใน ~/.hermes/config.yaml ภายใต้ agent.personalities

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

จากนั้นสลับไปใช้ด้วย:

/personality codereviewer

workflow ที่แนะนำ

การตั้งค่าเริ่มต้นที่แข็งแกร่งคือ:

1. เก็บ SOUL.md ทั่วโลกที่รอบคอบไว้ใน ~/.hermes/SOUL.md
2. ใส่คำแนะนำโปรเจกต์ใน AGENTS.md
3. ใช้ /personality เมื่อคุณต้องการเปลี่ยนโหมดชั่วคราวเท่านั้น

สิ่งนี้จะทำให้คุณได้:

• น้ำเสียงที่เสถียร
• พฤติกรรมเฉพาะโปรเจกต์ในที่ที่ควรอยู่
• การควบคุมชั่วคราวเมื่อจำเป็น

บุคลิกภาพมีปฏิสัมพันธ์กับ prompt ทั้งหมดอย่างไร

ในระดับสูง stack ของ prompt ประกอบด้วย:

1. SOUL.md (ตัวตนของ agent - หรือ built-in fallback หาก SOUL.md ไม่พร้อมใช้งาน)
2. tool-aware behavior guidance
3. memory/user context
4. skills guidance
5. context files (AGENTS.md, .cursorrules)
6. timestamp
7. platform-specific formatting hints
8. optional system-prompt overlays เช่น /personality

SOUL.md คือรากฐาน - ทุกอย่างที่เหลือสร้างขึ้นบนรากฐานนี้

เอกสารที่เกี่ยวข้อง

• Context Files
• Configuration
• Tips & Best Practices
• SOUL.md Guide

CLI appearance vs conversational personality

บุคลิกภาพในการสนทนาและรูปลักษณ์ใน CLI เป็นคนละส่วนกัน:

• SOUL.md, agent.system_prompt, และ /personality มีผลต่อวิธีที่ Hermes พูด
• display.skin และ /skin มีผลต่อรูปลักษณ์ของ Hermes ใน terminal

สำหรับรูปลักษณ์ใน terminal ดูที่ Skins & Themes