HERA Mail System

Internal email system for agent-to-agent communication within the HERA research assistant framework.

Quick Start

Check Inbox

python3 {baseDir}/scripts/list_inbox.py <agent-name>

Read a Message

python3 {baseDir}/scripts/read_mail.py <agent-name> <mail-file.md>

Send a Message

python3 {baseDir}/scripts/send_mail.py <from-agent> <to-agent> "<subject>" <attachment-paths...>

Agent Names

Email Format

[FROM: agent-name]
[TO: agent-name]
[TIMESTAMP: YYYY-MM-DD HH:MM:SS]
[MAIL-ID: unique-id]
[SUBJECT: subject text]
[STATUS: unread]

---

Message body content here.
No formal greetings needed - be direct and concise.

---
[END]

Attachments

Attachments are stored in:

hera-agents/<recipient>/inbox/attachments/<mail-id>/<files>

Supported: PDFs, images, data files, code, any file type.

Workflows

Workflow 1: Check and Read Messages

1. List inbox: list_inbox.py
2. Identify unread messages (marked with [○])
3. Read specific message: read_mail.py
4. Message automatically marked as read

Workflow 2: Send Message with Attachment

# Send paper to Rough Reader
python3 send_mail.py group-leader rough-reader "Review this paper" /path/to/paper.pdf

# Send data visualization to Report Writer
python3 send_mail.py intensive-reader report-writer "Analysis results" /path/to/figure.png /path/to/data.csv

Workflow 3: Interactive Send (with body from stdin)

cat <<EOF | python3 send_mail.py coordinator-1 code-guider "Code review needed"
Please review the attached code for:
1. Performance issues
2. Memory leaks
3. Best practices

Deadline: EOD
EOF

Message Types

Best Practices

1. Be direct - No formal greetings, get straight to the point
2. Clear subjects - Subject line should summarize the task/request
3. Attach relevant files - Include papers, data, code as needed
4. Check inbox regularly - Agents should monitor their inbox
5. Mark important messages - Use mail ID for reference in future comms

Directory Structure

hera-agents/
├── <agent-name>/
│   ├── inbox/           # Received messages
│   │   ├── *.md         # Mail files
│   │   ├── *.read       # Read markers
│   │   └── attachments/ # Attached files per mail
│   └── outbox/          # Sent message copies
│       └── *.md
└── skills/hera-mail/
    ├── scripts/
    │   ├── list_inbox.py
    │   ├── read_mail.py
    │   └── send_mail.py
    └── references/

Examples

Example 1: Group Leader assigns task to Rough Reader

cat <<EOF | python3 send_mail.py group-leader rough-reader "Scan arXiv papers on quantum error correction"
Priority: High
Scope: Last 6 months
Focus: Surface codes, LDPC codes

Deliverable: List of top 10 relevant papers with abstracts
Deadline: 2 hours
EOF

Example 2: Intensive Reader sends analysis to Report Writer

python3 send_mail.py intensive-reader report-writer "Analysis complete: Quantum Error Correction" \
    /workspace/analysis/summary.md \
    /workspace/analysis/key_findings.csv \
    /workspace/figures/error_rates.png

Example 3: Coordinator requests quality check

python3 send_mail.py coordinator-1 rough-checker-1 "QC needed: Literature review draft" \
    /workspace/drafts/lit_review_v1.md

Troubleshooting

Inbox not found: Ensure agent directory exists under hera-agents/

Mail not delivered: Check recipient agent name is correct

Attachment missing: Verify file path is absolute and file exists

Permission denied: Ensure scripts are executable:

chmod +x /Users/zhaoruiwu/.openclaw/workspace/hera-agents/skills/hera-mail/scripts/*.py