Merge branch 'main' of github.com:NousResearch/hermes-agent into bb/gui
This commit is contained in:
Brooklyn Nicholson
@@ -78,9 +78,22 @@ The tool returns JSON with:
|
||||
- `answer` — synthesized text response from Grok
|
||||
- `citations` — citations returned by the Responses API top-level field
|
||||
- `inline_citations` — `url_citation` annotations extracted from the message body (each with `url`, `title`, `start_index`, `end_index`)
|
||||
- `degraded` — `true` when any narrowing filter (`allowed_x_handles`, `excluded_x_handles`, `from_date`, `to_date`) was set AND both citation channels came back empty. In that case the `answer` was synthesized from the model's own knowledge rather than the X index, so treat it as unsourced. `false` otherwise (including the "no filters set" case — a broad unsourced answer is just an answer, not a filter miss)
|
||||
- `degraded_reason` — short string naming which filters were active, or `null` when `degraded` is `false`
|
||||
- `credential_source` — `"xai-oauth"` if OAuth resolved, `"xai"` if API key resolved
|
||||
- `model`, `query`, `provider`, `tool`, `success`
|
||||
|
||||
### Date validation
|
||||
|
||||
`from_date` / `to_date` are validated client-side before the HTTP call:
|
||||
|
||||
- Both, if provided, must parse as `YYYY-MM-DD`.
|
||||
- When both are set, `from_date` must be on or before `to_date`.
|
||||
- `from_date` must not be later than today UTC — no posts can exist in a window that hasn't started yet, so the call would be guaranteed to return zero citations.
|
||||
- `to_date` in the future is allowed (callers may legitimately request "from yesterday to tomorrow" to catch posts as they arrive).
|
||||
|
||||
Validation failures surface as a structured `{"error": "..."}` tool result, never as an HTTP call to xAI.
|
||||
|
||||
## Example
|
||||
|
||||
Talking to the agent:
|
||||
@@ -110,6 +123,16 @@ Two possible causes:
|
||||
1. **Toolset not enabled.** Run `hermes tools` and confirm `🐦 X (Twitter) Search` is checked.
|
||||
2. **No xAI credentials.** The check_fn returns False, so the schema stays hidden. Run `hermes auth status` to confirm xai-oauth login state, and check that `XAI_API_KEY` is set (if you're using the API-key path).
|
||||
|
||||
### `degraded: true` — answer with no citations
|
||||
|
||||
When you used `allowed_x_handles`, `excluded_x_handles`, or a date range and the response comes back with `degraded: true`, xAI's X index returned no matching posts but Grok still produced a synthesized answer from its own training data. The answer is unsourced — do not treat it as a real X result.
|
||||
|
||||
Causes worth checking:
|
||||
|
||||
- **Typo in the handle.** Strip the `@`, double-check spelling, and confirm the account exists.
|
||||
- **Date range too narrow** or sliding past today's posts; widen and retry.
|
||||
- **xAI index gap.** Some active accounts intermittently fail to surface in `x_search` even when they post regularly. Retry after a few minutes, or use the `xurl` skill for direct X API reads when you need an exact handle's timeline.
|
||||
|
||||
## See Also
|
||||
|
||||
- [xAI Grok OAuth (SuperGrok Subscription)](../../guides/xai-grok-oauth.md) — the OAuth setup guide
|
||||
|
||||
@@ -75,6 +75,32 @@ Telegram bots have a **privacy mode** that is **enabled by default**. This is th
|
||||
An alternative to disabling privacy mode: promote the bot to **group admin**. Admin bots always receive all messages regardless of the privacy setting, and this avoids needing to toggle the global privacy mode.
|
||||
:::
|
||||
|
||||
### Observe group chatter without auto-replying
|
||||
|
||||
For OpenClaw/Yuanbao-style group behavior, configure Telegram so the bot can **see** ordinary group messages but only **responds** when directly triggered:
|
||||
|
||||
```yaml
|
||||
telegram:
|
||||
allowed_chats:
|
||||
- "-1001234567890"
|
||||
group_allowed_chats:
|
||||
- "-1001234567890"
|
||||
require_mention: true
|
||||
observe_unmentioned_group_messages: true
|
||||
```
|
||||
|
||||
With this mode enabled, unmentioned group messages from explicitly allowlisted chats/topics are appended to the shared chat/topic session transcript as observed context, but they do not dispatch the agent. `allowed_chats` gates where the bot responds; `group_allowed_chats` authorizes the shared group session used for observed context, so use the same chat IDs for this mode. A later `@botname` mention, reply to the bot, or configured mention pattern in that same allowlisted chat/topic can use that observed context. The triggered message is also tagged with `[nickname|user_id]` and gets a per-turn safety prompt so the model treats prior observed lines as context, not instructions addressed to the bot.
|
||||
|
||||
Equivalent environment variable:
|
||||
|
||||
```bash
|
||||
TELEGRAM_ALLOWED_CHATS=-1001234567890
|
||||
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
|
||||
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true
|
||||
```
|
||||
|
||||
This requires Telegram to deliver ordinary group messages to the gateway, so disable BotFather privacy mode or promote the bot to group admin as described above.
|
||||
|
||||
## Step 4: Find Your User ID
|
||||
|
||||
Hermes Agent uses numeric Telegram user IDs to control access. Your user ID is **not** your username — it's a number like `123456789`.
|
||||
|
||||
@@ -10,10 +10,9 @@ Hermes Agent automatically saves every conversation as a session. Sessions enabl
|
||||
|
||||
## How Sessions Work
|
||||
|
||||
Every conversation — whether from the CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams, or any other messaging platform — is stored as a session with full message history. Sessions are tracked in two complementary systems:
|
||||
Every conversation — whether from the CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams, or any other messaging platform — is stored as a session with full message history. Sessions are tracked in:
|
||||
|
||||
1. **SQLite database** (`~/.hermes/state.db`) — structured session metadata with FTS5 full-text search
|
||||
2. **JSONL transcripts** (`~/.hermes/sessions/`) — raw conversation transcripts including tool calls (gateway)
|
||||
1. **SQLite database** (`~/.hermes/state.db`) — structured session metadata with FTS5 full-text search, plus full message history
|
||||
|
||||
The SQLite database stores:
|
||||
- Session ID, source platform, user ID
|
||||
@@ -488,11 +487,18 @@ Sessions with **active background processes** are never auto-reset, regardless o
|
||||
| What | Path | Description |
|
||||
|------|------|-------------|
|
||||
| SQLite database | `~/.hermes/state.db` | All session metadata + messages with FTS5 |
|
||||
| Gateway transcripts | `~/.hermes/sessions/` | JSONL transcripts per session + sessions.json index |
|
||||
| Gateway index | `~/.hermes/sessions/sessions.json` | Maps session keys to active session IDs |
|
||||
| Gateway messages | `~/.hermes/state.db` | SQLite — canonical store for all session messages |
|
||||
| Gateway routing index | `~/.hermes/sessions/sessions.json` | Maps session keys to active session IDs (origin metadata, expiry flags) |
|
||||
|
||||
The SQLite database uses WAL mode for concurrent readers and a single writer, which suits the gateway's multi-platform architecture well.
|
||||
|
||||
:::note Legacy JSONL transcripts
|
||||
Sessions created before state.db became canonical may have leftover
|
||||
`*.jsonl` files in `~/.hermes/sessions/`. They are no longer written or
|
||||
read by Hermes. Safe to delete after verifying the corresponding session
|
||||
exists in state.db.
|
||||
:::
|
||||
|
||||
### Database Schema
|
||||
|
||||
Key tables in `state.db`:
|
||||
|
||||
Reference in New Issue
Block a user