lcbp3/specs/200-fullstacks/231-hermes-agent/data-model.md

// File: specs/200-fullstacks/231-hermes-agent/data-model.md // Change Log: // - 2026-05-29: Initial data model for Hermes Agent

Data Model: Hermes Agent

Feature: 231-hermes-agent | Date: 2026-05-29

Important

: Hermes ไม่เพิ่มหรือแก้ DMS production schema ทุกกรณี (ADR-031, FR-017) Data model นี้ทั้งหมดอยู่ใน Hermes-owned storage (SQLite / container volume) ไม่ใช่ DMS MariaDB

---

1. HermesOperationsLog (SQLite table: hermes_operations_log)

บันทึก inbound/outbound DevOps operations ทุก transaction ของ Hermes

Field	Type	Constraints	Description
id	TEXT (UUIDv7)	PRIMARY KEY	Transaction ID — ใช้ UUIDv7 ตาม ADR-019
operator_identity	TEXT	NOT NULL	Telegram user ID หรือ CLI session identity
command_type	TEXT	NOT NULL	เช่น TELEGRAM_INBOUND, TELEGRAM_OUTBOUND, ORCHESTRATION_TASK, GIT_WRITE
target_system	TEXT	NOT NULL	เช่น TELEGRAM, GITEA, CLOUD_AI, DEV_QDRANT
command_summary	TEXT	NOT NULL	Redacted command description (ห้ามมี secret/token/sensitive path)
status	TEXT	NOT NULL	PENDING / IN_PROGRESS / COMPLETED / FAILED / REJECTED
created_at	DATETIME	NOT NULL DEFAULT CURRENT_TIMESTAMP
completed_at	DATETIME	NULLABLE
error_classification	TEXT	NULLABLE	เช่น AUTH_FAILURE, RATE_LIMIT, FORBIDDEN_ACTION, EXTERNAL_API_ERROR
gitea_token_identity	TEXT	NULLABLE	Token scope/identity สำหรับ Git write actions (ไม่ใช่ token value)
target_repo	TEXT	NULLABLE	สำหรับ Git write actions
target_branch	TEXT	NULLABLE	สำหรับ Git write actions

Retention: 90 วัน แล้ว archive/delete ตาม DevOps log policy Access: Read เฉพาะ admin/operator ที่จำเป็น Redaction: command_summary ต้องผ่าน secret scanner ก่อน insert

---

2. HermesRateLimitState (Redis key pattern)

Key Pattern	Value	TTL	Description
hermes:telegram:{telegramUserId}	INT (request count)	60s	Rate limit counter per user; expire ทุก 60 วินาที

---

3. HermesBullMQJobs (Redis via hermes-notification-queue)

Job: telegram-devops-outbound

Field	Type	Description
transactionId	string (UUIDv7)	Reference ID for tracking
chatId	string	Telegram chat ID
message	string	Outbound message text (ไม่มี secret/PII)
retryCount	number	Current retry count (max 3)

---

4. HermesOrchestrationTask (Redis via hermes-orchestration-queue)

Job: orchestration-task

Field	Type	Description
taskId	string (UUIDv7)	Task tracking ID
taskType	DEVOPS / DMS_FEATURE / SCHEMA_DB / BUG_FIX	กำหนด context loading strategy
description	string	Task description (no production data)
contextSources	string[]	Context files to load
maxIterations	number	Self-correction loop limit (default: 3)
telegramChatId	string	สำหรับ progress/result notification
createdAt	string (ISO 8601)

---

5. SOUL.md (Container File: /volume1/docker/hermes/SOUL.md)

ไม่ใช่ DB table แต่เป็น plain Markdown file working journal ใน container volume

Structure per session entry:

## Session {ISO_DATETIME}
Task: {task description}
TaskType: {DEVOPS|DMS_FEATURE|SCHEMA_DB|BUG_FIX}
Context loaded: {comma-separated context files}
Sub-agents delegated: {count} code generation calls
Iterations: {count} ({result of last iteration})
PR created: {branch} → #{pr_number}
Status: {DONE|ESCALATED|FAILED}

File management:

• Read at session start for context resumption
• Append only (never overwrite previous entries)
• Rotate (clear and archive) every 30 days or manual clear
• Never synced to repo — container volume only

---

6. DevQdrantCollection (lcbp3_code_chunks on ASUSTOR:6334)

Field	Type	Description
id	string (UUID)	Chunk ID
repoName	string	Repository name (e.g., lcbp3)
moduleName	string	Module path (e.g., backend/src/modules/correspondence)
filePath	string	Relative file path
chunkIndex	number	Chunk position in file
content	string	Code chunk text
vector	float[]	nomic-embed-text embedding (768 dimensions)

ไม่ใช้ projectPublicId filter (ซึ่งเป็น DMS document isolation key) — ใช้ repoName + moduleName แทน ตาม ADR-031 v2.0

---

Entity Relationships

HermesAgent
  ├── orchestrates → HermesOrchestrationTask (via hermes-orchestration-queue)
  │     ├── delegates → HermesSubAgent (Cloud AI: Claude Haiku / GPT-4o-mini)
  │     ├── searches → DevQdrantCollection (code patterns)
  │     └── records → SOUL.md (session journal)
  └── bridges → HermesTelegramGateway
        ├── validates → HermesRateLimitState (Redis)
        ├── records → HermesOperationsLog (SQLite)
        └── dispatches → HermesBullMQJobs (hermes-notification-queue)
              └── sends → Telegram API

---

State Transitions: HermesOperationsLog.status

PENDING → IN_PROGRESS → COMPLETED
                      → FAILED
         → REJECTED (allowlist/rate-limit/forbidden-action check)

State Transitions: HermesOrchestrationTask

QUEUED → CONTEXT_LOADING → SUB_AGENT_DELEGATED
                         → SELF_CORRECTION (max 3 iterations)
                         → PR_CREATED → DONE
                         → ESCALATED (>3 iterations, notify Developer)
                         → FAILED