Cấu trúc dữ liệu cốt lõi

Trạng thái của agent Hermes không chỉ là "danh sách tin nhắn cộng với một loạt công cụ".
Vì nó phục vụ nhiều nền tảng, duy trì với SQLite và thực thi các lệnh trong các môi trường khác nhau nên trạng thái được trải rộng trên nhiều lớp.
Tài liệu này giúp bạn xem "tiểu bang thực sự tồn tại ở đâu" dưới dạng một bản đồ duy nhất.

Đề xuất đọc

• glossary.md -- tra cứu các thuật ngữ không quen thuộc ở đây.
• entity-map.md -- tra cứu các ranh giới không rõ ràng ở đây.

Bắt đầu với một chủ đề

messages  -> current conversation (runtime)
session   -> conversation persistence (SQLite)
memory    -> cross-session knowledge (files)
config    -> runtime configuration (YAML + environment variables)

Hầu hết các agent chỉ có lớp đầu tiên. agent Hermes có bốn, vì nó cần tồn tại khi khởi động lại, mở rộng nền tảng và chuyển đổi cấu hình.

1. Trạng thái hội thoại

Tin nhắn

Danh sách tin nhắn đầy đủ cho cuộc trò chuyện hiện tại. Định dạng OpenAI.

messages = [
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "...", "tool_calls": [...]},
    {"role": "tool", "tool_call_id": "...", "content": "..."},
]

Đây là đầu vào mà mô hình nhìn thấy ở mỗi lượt. Nó không phải là lớp hiển thị trò chuyện.

Lưu ý: Trong nội bộ, agent Hermes lưu trữ các trường bổ sung trên các tin nhắn trợ lý (chẳng hạn như reasoning và finish_reason), nhưng các trường này sẽ bị loại bỏ trước khi gửi tới API. Vì vậy, thông báo nội bộ và thông báo liên kết API không giống nhau.

Phần liên quan: s01

Lời nhắc hệ thống

Không phải là một phần của danh sách tin nhắn. Được chuẩn bị trước khi bắt đầu mỗi lệnh gọi API.

Tổng hợp từ nhiều nguồn:

SOUL.md (persona)
  + MEMORY.md / USER.md (memory)
  + HERMES.md or AGENTS.md or CLAUDE.md or .cursorrules (project config, in decreasing priority)
  + tool definitions
  + skill inventory

Được lắp ráp một lần, sau đó được lưu vào bộ nhớ đệm. Các cuộc gọi tiếp theo sẽ sử dụng lại bộ đệm. Tại sao phải lưu vào bộ nhớ đệm? Bởi vì bộ nhớ đệm nhắc nhở của Anthropic yêu cầu dấu nhắc hệ thống không thay đổi qua các lượt.

Phần liên quan: s04

2. Trạng thái bền bỉ

Phiên (SQLite)

Bản ghi của một cuộc trò chuyện hoàn chỉnh.

session = {
    "id": "...",
    "source": "cli" | "telegram" | "discord" | ...,
    "model": "...",
    "system_prompt": "...",       # Stored after first assembly, reused later
    "parent_session_id": "...",   # After compression, new session points to old session
    "started_at": ...,
    "message_count": ...,
    "input_tokens": ...,
    "output_tokens": ...,
    "estimated_cost_usd": ...,
}

Điều gì làm cho Hermes Agent trở nên độc đáo ở đây:

• source tags nền tảng mà tin nhắn đến từ. Điều này cho phép bạn lọc các phiên theo nền tảng.
• system_prompt được lưu để phiên tiếp tục không cần phải tập hợp lại (giữ bộ đệm nhất quán).
• parent_session_id triển khai chuỗi phiên: sau khi nén, lịch sử cũ không bị mất -- bạn có thể truy ngược lại chuỗi.

Phần liên quan: s03

Bảng tin nhắn (SQLite)

Mỗi tin nhắn trong một phiên được lưu trữ dưới dạng một hàng riêng biệt.

message_row = {
    "session_id": "...",
    "role": "user" | "assistant" | "tool",
    "content": "...",
    "tool_calls": "...",     # JSON-serialized
    "tool_call_id": "...",
    "tool_name": "...",
    "timestamp": ...,
    "token_count": ...,
}

Chỉ mục FTS5 được xây dựng trên cột nội dung, cho phép tìm kiếm toàn văn qua các phiên lịch sử.

Phần liên quan: s03

3. Trạng thái công cụ

Nhập công cụ (Nhập sổ đăng ký)

tool = {
    "name": "web_search",
    "toolset": "web",
    "schema": {"description": "...", "parameters": {...}},
    "handler": ...,       # The function that actually executes the tool
    "is_async": False,    # Whether it needs async bridging
    "requires_env": [],   # Which environment variables it depends on
}

Mỗi tệp công cụ đăng ký một mục như thế này khi nó được nhập.

Điều làm cho Hermes Agent trở nên độc đáo ở đây: is_async cờ. Nếu Đúng, lớp điều phối sẽ gửi cuộc gọi vào vòng lặp sự kiện liên tục thay vì gọi trực tiếp. Đây là cách triển khai mẫu "vòng lặp đồng bộ + cầu nối không đồng bộ".

Phần liên quan: s02

Mẫu nguy hiểm

pattern = (r'\brm\s+-[^\s]*r', "recursive delete")

Một biểu thức chính quy được ghép nối với một mô tả mà con người có thể đọc được.

Hệ thống duy trì một danh sách các mẫu này. Các lệnh đầu cuối được khớp với danh sách trước khi thực thi. Sự trùng khớp sẽ kích hoạt luồng phê duyệt.

Phê duyệt được lưu vào bộ đệm mỗi phiên: cùng một loại hoạt động chỉ cần phê duyệt một lần trong một phiên.

Phần liên quan: s09

4. Trạng thái trí nhớ và kỹ năng

Bộ nhớ (Tệp)

# MEMORY.md example
- User prefers tabs for indentation
- Project uses pytest for testing
- Database is PostgreSQL 15

Dữ liệu không có cấu trúc. Chỉ cần đánh dấu văn bản. agent đọc và viết nó.

Điều khiến Hermes Agent trở nên độc đáo ở đây: bộ nhớ được chia thành hai tệp -- MEMORY.md lưu trữ các ghi chú của agent, USER.md lưu trữ hồ sơ người dùng.

Phần liên quan: s07

Kỹ năng (Tệp)

# SKILL.md example
name: data-analysis
description: Analyze CSV data and generate reports
---
How to use:
1. Read the CSV file
2. Analyze with pandas
3. Generate a markdown report

Mỗi kỹ năng là một tệp SKILL.md bên trong thư mục riêng của nó. agent có thể tạo, chỉnh sửa và xóa chúng.

Điểm khác biệt chính so với các công cụ: mã công cụ được viết bởi con người; nội dung kỹ năng được quản lý bởi agent.

Phần liên quan: s08

5. Trạng thái cấu hình

Cấu hình (Từ điển hợp nhất)

config = {
    "model": "...",
    "base_url": "...",
    "api_key": "...",
    "enabled_toolsets": [...],
    "max_iterations": 90,
    "personality": "...",
}

Có nguồn gốc từ nhiều nguồn và được hợp nhất theo mức độ ưu tiên: đối số CLI > biến môi trường > config.yaml > mặc định.

Điều khiến Hermes Agent trở nên độc đáo ở đây: nó hỗ trợ cách ly Hồ sơ. Mỗi Hồ sơ là một thư mục HERMES_HOME riêng biệt với cấu hình, bộ nhớ, phiên và kỹ năng riêng.

Phần liên quan: s11

6. Trạng thái cổng

Sự kiện tin nhắn (Định dạng tin nhắn thống nhất)

event = {
    "text": "...",
    "message_type": "text" | "command" | "image" | ...,
    "source": {
        "platform": "telegram",
        "chat_id": "...",
        "user_id": "...",
        "chat_type": "dm" | "group",
    },
}

Tất cả các bộ điều hợp nền tảng đều tạo ra cùng một định dạng này. Cổng không cần quan tâm tin nhắn đến từ nền tảng nào.

Điều làm cho Hermes Agent trở nên độc đáo ở đây: source cấu trúc bao gồm các thứ nguyên nền tảng, trò chuyện, người dùng và chuỗi -- đủ để phân biệt chính xác "các cuộc hội thoại khác nhau trên cùng một nền tảng".

Phần liên quan: s12, s13

7. Trạng thái môi trường thực thi

Môi trường (Phiên bản của Giao diện trừu tượng)

Không có cấu trúc dữ liệu thống nhất duy nhất. Thay vào đó là một giao diện:

# Core methods
env.run_command(command) -> output
env.write_file(path, content)
env.read_file(path) -> content

Sáu cách triển khai đều có trạng thái nội bộ riêng (Docker có container_id, SSH có thông tin kết nối, Modal có sandbox_id), nhưng tất cả đều hiển thị cùng một giao diện.

Phần liên quan: s14

8. Trạng thái nhiệm vụ theo lịch trình

Công việc (Từ điển)

job = {
    "id": "...",
    "schedule": {
        "kind": "cron" | "interval" | "once",
        "expr": "0 9 * * *",    # cron mode
        "minutes": 30,           # interval mode
        "run_at": "...",         # once mode
    },
    "prompt": "Generate weekly report",
    "enabled": True,
    "last_run_at": "...",
    "next_run_at": "...",
}

Được lưu trữ trong một tệp JSON. Bộ lập lịch hoạt động định kỳ, kiểm tra các công việc đến hạn.

Phần liên quan: s15

Đặt tất cả lại với nhau

Runtime
  messages[]        Current conversation
  tool registry     Capability catalog
  environment       Where commands run

SQLite
  sessions          Conversation records
  messages table    Individual messages
  FTS5 index        Full-text search

File System
  SOUL.md           Persona
  MEMORY.md         Memory
  USER.md           User profile
  skills/           Skill files
  config.yaml       Configuration
  jobs.json         Scheduled tasks

Gateway (optional)
  adapters{}        Platform connections
  message events    Unified messages
  session routing   Session routing

Ranh giới giảng dạy

Bảng tham chiếu này giúp bạn xác định vị trí "một phần trạng thái nhất định thuộc về lớp nào".

Nó không đi sâu vào chi tiết đầy đủ của mọi lĩnh vực. Khi bạn biết lớp nào sở hữu một phần trạng thái, hãy quay lại phần tương ứng để thực hiện hoàn chỉnh.