[!NOTE]
🖼️ Infographic placeholder — Hero Banner · Generate the image, save it as docs/images/en-hero-banner.png, then replace this block with <img src="docs/images/en-hero-banner.png" width="800">.

Generation prompt: A wide, modern hero banner for an open-source AI project called "Hermes Active". Pure white background, ultra-minimal design, a thin coral-orange heartbeat pulse line running across the center that morphs into a few simple chat bubbles, the title "Hermes Active" in bold dark gray sans-serif centered, subtitle "Proactive Consciousness for AI Assistants" in light gray small text beneath. No photo realism, no text artifacts, no dark background, clean whitespace, 21:9 aspect ratio.

Hermes Active

Proactive consciousness system for Hermes Agent

Give your AI assistant a heartbeat — let it feel time passing, miss you, think on its own,
and reach out first with full memory of every conversation you've ever had.

Why Hermes Active?
Screenshots
Architecture
Core Systems
Integrations
Tech Stack
Project Structure
Quick Start
Configuration
API Overview
Documentation
License

Why Hermes Active?

[!NOTE]
🖼️ Infographic placeholder — Problem Statement · Save as docs/images/en-problem-statement.png.

Generation prompt: A split-comparison infographic titled "Stateless Cron vs Persistent Consciousness". White background, minimal flat vector style. Left side: light gray area, a simple robot icon facing an empty dialog bubble, broken chain icon, speech bubble saying "Who are you again?". Right side: light coral-orange area, the same robot icon surrounded by a timeline and memory nodes, speech bubble saying "I was just thinking about you". Minimal text, generous whitespace, 16:9.

Every proactive messaging feature in traditional AI agents shares the same flaw: each scheduled task spawns a brand-new, isolated session.

❌ The assistant has no memory of recent conversations when it reaches out
❌ When the user replies, context is gone — "sorry, what were we talking about?"
❌ Every run is stateless — no emotion, no continuity, no sense of time
❌ Replying to a proactive message feels like talking to a stranger

Hermes Active fixes this by running a persistent consciousness layer alongside Hermes Agent:

✅ Proactive messages are written directly into the live session — the user's reply lands in full context
✅ A heartbeat loop gives the assistant an emotional state that evolves with time and interaction
✅ Long-term memory (Hindsight) is recalled before every thought and every reply
✅ An inner contemplation loop lets the assistant think freely, building a compressed "sediment" of its own mind
✅ Runs as a standalone service — zero modifications to Hermes Agent's core (one small optional session-sync patch)

The reference persona shipped with this system is Kally (凯莉) — every prompt, tag and default is fully customizable from the web UI.

Screenshots

📸 Screenshots captured from the web console (http://localhost:18720). Regenerate with scripts/screenshot_readme.py.

Dashboard System overview: sessions, messages, task stats, consciousness status at a glance.	Active Consciousness Live VA emotion gauges, heartbeat log stream, thought log with full LLM reasoning.
Passive Consciousness Injection switches, Jinja2 template editor with live preview, per-signal test buttons.	Free Consciousness Contemplation rounds timeline, thinking-chain inspector, sediment viewer.
Scheduled Tasks Cron editor with placeholder insertion, prompt preview, execution logs.	Injection Analytics ECharts dashboards: injection trends, emotion/longing/heat distributions.

Architecture

[!NOTE]
🖼️ Infographic placeholder — Architecture Overview · Save as docs/images/en-architecture.png.

Generation prompt: A clean system-architecture infographic. White background, minimal flat design. Center: a rounded rectangle "FastAPI Backend" with three simple gear icons labeled "Heartbeat", "Contemplation", "Scheduler". Top: a panel "Vue 3 Web Console" connected by thin arrows labeled "JWT REST API". Right: a "Hermes Agent" box connected by "Public APIs". Bottom: two light gray cylinders labeled "state.db (R/O)" and "active.db (R/W)". All connectors in light gray thin lines, key nodes accented in coral-orange, generous whitespace, 16:9.

graph TB
    subgraph Console["Web Console — Vue 3 + Naive UI"]
        UI[Dashboard · Sessions · Messages<br/>Cron · Active/Passive/Free Consciousness · Analytics]
    end

    subgraph Backend["Hermes Active Backend — FastAPI :18720"]
        direction TB
        CRON[Task Scheduler<br/>APScheduler]
        HB[Heartbeat Loop<br/>Active Consciousness]
        FC[Contemplation Loop<br/>Free Consciousness]
        PC[Context Builder<br/>Passive Consciousness]
        SHARED[Shared Services<br/>ThoughtEngine · ContextCollector · LLM<br/>Message · Weather · Hindsight · Template]
        CRON --> SHARED
        HB --> SHARED
        FC --> SHARED
        PC --> SHARED
    end

    subgraph Hermes["Hermes Agent — unmodified core"]
        GW[Gateway<br/>WeChat · Feishu]
        HOOK[passive-consciousness plugin<br/>pre_llm_call hook]
        LLM[call_llm · SOUL.md · SessionDB]
    end

    ADB[(active.db<br/>read-write)]
    SDB[(state.db<br/>read-only + proactive writes)]
    HS[[Hindsight<br/>long-term memory]]
    WX[[Weather APIs<br/>Amap · QWeather]]

    UI -->|JWT REST| Backend
    HOOK -->|HTTP: render context| PC
    SHARED -->|public APIs| LLM
    SHARED -->|send proactive message| GW
    Backend --> ADB
    Backend --> SDB
    SHARED --> HS
    SHARED --> WX

Dual-database design

Database	Access	Contents	Location
`state.db`	Read-only (sole exception: proactive messages are written back)	Hermes Agent's sessions & messages	`~/.hermes/state.db`
`active.db`	Read-write	Users, configs, cron jobs, task logs, heartbeat & thought logs, contemplation logs, injection logs	`data/active.db`

Hermes Active never writes Hermes' configuration and never mutates conversation history — it only appends the proactive messages it sends, flagged with a configurable mark (e.g. [凯莉 14:30]: …), so the main agent naturally sees them as its own.

Core Systems

[!NOTE]
🖼️ Infographic placeholder — Four Systems Overview · Save as docs/images/en-four-systems.png.

Generation prompt: A 2x2 grid infographic of four systems. White background, minimal icon style. Top-left "Active Consciousness": a simple heart outline with pulse line. Top-right "Passive Consciousness": an envelope icon with injection arrow. Bottom-left "Free Consciousness": a brain outline with contemplation symbol. Bottom-right "Scheduled Tasks": a calendar with clock icon. Unified coral-orange for icons, light gray accents, generous whitespace, 16:9.

Active Consciousness — the heartbeat

A scheduler fires every N seconds (default 600) and runs a full perceive → feel → decide → act cycle. Nothing is scripted: the emotion state, the decision score and the message itself all emerge from live context.

flowchart TD
    A[⏱ Heartbeat tick] --> B[Load persisted emotion state]
    B --> C[Evolve emotion over elapsed time<br/>arousal decays · social need grows · valence regresses to neutral]
    C --> D[Collect context bundle<br/>conversations · memories · weather · time · habits]
    D --> E[LLM emotion assessment<br/>reads recent chat, outputs VA values]
    E --> F[Dynamic-weight merge<br/>confidence-scored fusion of evolved + assessed]
    F --> G[Decision matrix<br/>score = intensity × time fitness × silence factor × frequency limit]
    G --> H{Score vs thresholds}
    H -->|≥ send threshold| I[Generate thought via ThoughtEngine]
    H -->|≥ memory threshold| J[Generate thought via ThoughtEngine]
    H -->|below| K[skip — no LLM call, no cost]
    I --> L{Send protection}
    L -->|pass| M[Send via WeChat / Feishu<br/>append to state.db with proactive mark]
    L -->|blocked| N[Retain thought to Hindsight<br/>nothing is wasted]
    J --> N
    M --> O[Retain thought to Hindsight<br/>write heartbeat + thought logs]
    N --> O

Emotion system — Valence/Arousal + Social Need

The assistant's mood is a persisted three-dimensional state:

Dimension	Range	Meaning	Natural drift
Valence	0.0 – 1.0	pleasant ↔ unpleasant	regresses toward neutral (0.5)
Arousal	0.0 – 1.0	activated ↔ calm	decays over time
Social need	0.0 – 1.0	desire to interact	grows with silence

From these, a dominant label is derived (calm, happy, content, longing, yearning, missing, anxious, bored, concerned).

Each heartbeat fuses two independent estimates of the emotional state:

Deterministic evolution — the previous state drifted forward by elapsed time (rates configurable: decay_rate, social_need_growth, valence_regression)
LLM assessment — a dedicated prompt asks the LLM to read the recent conversation and output fresh VA values

The fusion weight is not fixed: a confidence score (range sanity + agreement with the evolved state) shifts the blend between 0.7/0.3 and 0.3/0.7. If the LLM returns garbage (all zeros), the evolved value takes over silently.

Decision matrix

Sending is a scored decision, never a timer:

score = emotion_intensity × time_fitness × silence_factor × frequency_limit

Factor	How it's computed
`emotion_intensity`	blended VA magnitude of the merged state
`time_fitness`	time-of-day table — morning & evening windows 1.0, work hours 0.7–0.9, deep night 0.3
`silence_factor`	0.6 within 30 min of the user's last message → 1.0 after 6 h of silence
`frequency_limit`	hard gate: 0 once the hourly send cap is reached

Score	Decision	Effect
`≥ send_threshold` (default 0.35)	`auto_send`	generate thought → protection check → send
`≥ memory_threshold` (default 0.05)	`memory`	generate thought → retain to Hindsight only
`< memory_threshold`	`skip`	heartbeat ends without any LLM call

Thought engine

Thoughts are generated by a dedicated pipeline (ContextCollector → ThoughtEngine → LLM → parser):

Context bundle — structured conversations (cross-session, per-platform, tool messages filtered), Hindsight recall results, emotion state, time context (hour / workday / mealtime), weather, user habits from USER.md
Fully templated prompts — system & user prompts are stored in the database and editable in the UI, with placeholders: {session_context}, {hindsight_context}, {weather_display}, {emotion_display}, {time}, {persona}
SKIP protocol — the LLM may answer SKIP when it has nothing worth saying; the heartbeat then stores nothing and sends nothing
Reasoning capture — chain-of-thought is extracted with a three-tier fallback (reasoning_content → reasoning → reasoning_details) and shown in the thought log
Thought typing — each thought is classified (memory, env, emotion, silence, time, assoc) and retained to Hindsight with tags (active_consciousness, dominant emotion, high_emotion, user_related)

Send protection

Three independent guards run after a thought is generated but before it is sent — blocked thoughts are retained to memory instead of discarded:

Guard	Config key	Default
Silence window — user just messaged	`active.no_send_after_user_msg_minutes`	5 min
Heat guard — user is actively chatting	`active.no_send_while_heat_above`	1.0 msg/h
Vibe guard — emotional intensity too low	`active.no_send_while_vibe_below`	0.15
Cooldown between sends	`active.cooldown_minutes`	30 min

Tiered LLM configuration

Three independent LLM slots, each falling back to the one above:

thought_llm  →  emotion_llm  →  llm (universal)

Every slot supports hermes mode (reuse Hermes Agent's own call_llm, zero extra keys) or custom mode (any OpenAI-compatible provider/model/key/base_url). Connectivity can be tested per-slot from the UI.

Observability

Every heartbeat and every thought is persisted with its complete detail payload — prompts sent, raw LLM responses, reasoning, recall results, decision inputs, protection verdicts — inspectable in the web UI. A nightly job (03:00) prunes logs older than 30 days.

Passive Consciousness — context injection

Active consciousness acts; passive consciousness perceives. Whenever the user sends a message, a Hermes plugin assembles a live "state of mind" snapshot and injects it into the prompt — so the reply naturally reflects how long it's been, how the conversation feels, what's on the assistant's mind, and what the weather is like. No extra LLM call is made on the user's turn.

sequenceDiagram
    participant U as User
    participant G as Hermes Gateway
    participant P as passive-consciousness plugin
    participant B as Hermes Active backend
    participant L as LLM

    U->>G: sends a message
    G->>P: pre_llm_call hook
    P->>B: HTTP — request consciousness context
    B->>B: longing score · chat heat · emotional intensity<br/>weather · Hindsight recall + reflect
    B->>B: render active Jinja2 template
    B-->>P: [CONSCIOUSNESS_CONTEXT] block
    P-->>G: inject into system prompt
    G->>L: user message + consciousness context
    L-->>U: context-aware reply

Injected signals

Signal	Source	Computation
💕 Longing	`state.db`	minutes since the user's last message ÷ 300, capped at 1.0 — five levels from `calm` to `anxious`
🔥 Chat heat	`state.db`	user messages in the last hour — `cold / warm / hot / fire`
🎭 Emotional intensity	`active.db`	written by the active-consciousness heartbeat — `工作 / 日常 / 八卦 / 情感 / 深度情感`
🌤 Weather	Amap / QWeather	unified `weather.*` config, cached, with high/low temperature alerts
📖 Memories	Hindsight Recall	semantic search over long-term memory
💭 Reflection	Hindsight Reflect	synthesized analysis of the current situation

Jinja2 template system

The injected block is rendered from user-managed Jinja2 templates — create multiple templates, switch the active one, preview with mock data, and browse the full variable catalog from the UI. Conditional sections ({% if inject_emotion %}) mean one template serves many configurations. The block is wrapped in a configurable tag (default [CONSCIOUSNESS_CONTEXT]) so the main agent knows how to treat it.

Platform filtering & analytics

Platform whitelist — injection runs only on enabled platforms (e.g. WeChat only)
Injection logs — every injection (success / skipped / error) is persisted with context length, scores and template id
Analytics dashboard — success rate, hourly/daily/weekly trends, emotion & longing & heat distributions, correlation stats (e.g. high-emotion × high-heat), rendered with ECharts
Per-signal test endpoints — each pipeline stage (longing, heat, emotion, weather, recall, reflect, full assembly) has a one-click test button in the UI

The plugin lives at ~/.hermes/plugins/passive-consciousness/ — see docs/plugin-installation.md.

Free Consciousness — inner contemplation

Between heartbeats and user messages, the assistant can simply… think. Free consciousness is a scheduled contemplation loop with no task, no user waiting, and no expected output — an inner space where the assistant continues its own train of thought.

flowchart LR
    A[Scheduler tick<br/>every N minutes] --> B[Assemble thinking chain]
    B --> C{Realtime context?}
    C -->|enabled| D[+ current time<br/>+ emotion state<br/>+ recent conversations]
    C -->|disabled| E[Pure chain]
    D --> F[LLM contemplation]
    E --> F
    F --> G[Parse structured output<br/>thinking · summary · discovery]
    G --> H[Write contemplation log]
    G --> I{New discovery?}
    I -->|optional| J[Retain to Hindsight]
    H --> K{Compression due?}
    K -->|every 10 distant rounds| L[LLM compresses old rounds<br/>into sediment]

Four-layer memory model

The thinking chain keeps unbounded contemplation affordable by layering recency:

Layer	Content	Cost
Sediment (意识积淀)	LLM-compressed narrative of all distant rounds, refreshed every 10 rounds	~300 chars total
Recent rounds (default 3)	full verbatim thinking	high
Mid rounds (default 17)	one-line summaries	low
Distant rounds	key discoveries only	minimal

The result: the assistant always sees everything it ever concluded (sediment), what it was recently thinking (full text), and the highlights in between — a persistent inner narrative that survives indefinitely without blowing up the context window.

All contemplation logs — including the exact prompt, raw response, reasoning and token estimates — are browsable in the UI.

Scheduled Tasks

The foundation layer: cron-style jobs with context injection, managed entirely from the web UI — independent from Hermes Agent's built-in cron.

flowchart LR
    A[Cron trigger] --> B[Resolve session<br/>with fallback & auto-reset]
    B --> C[Collect context]
    C --> D[Render placeholders<br/>into prompt template]
    D --> E[LLM generation<br/>+ optional SOUL.md persona]
    E --> F[Send via platform API]
    F --> G[Append message to state.db<br/>with proactive mark]
    G --> H[Write full task log]

Placeholder system — {session} (recent cross-session conversations), {memory} (Hindsight recall + reflect), {weather} (live weather), {time} (custom strftime via a picker component)
Context blocks in prompts — declare per-job context requirements inline; the parser extracts them before rendering
Session fallback — if the gateway's in-memory session is gone, the job resolves (or resets) the active session from state.db automatically
Persona injection — optionally append Hermes' SOUL.md to the system prompt
Full logging — every run stores the rendered prompt, LLM request/response, send result and duration
Multi-platform — WeChat and Feishu sending through Hermes' own platform adapters

Web Console

A complete management UI (Vue 3 + Naive UI + Pinia + ECharts), served directly by the backend — no separate web server:

Page	What you can do
Dashboard	session/message/task statistics, system health at a glance
Sessions / Messages	browse every session and message in `state.db`, search, delete, send manually
Active Consciousness	live emotion gauges, heartbeat & thought logs with full LLM details, all thresholds and prompts editable
Passive Consciousness	injection switches, template CRUD with live preview, platform whitelist, per-signal test buttons
Free Consciousness	contemplation rounds, thinking-chain inspector, sediment viewer, interval & prompt config
Cron Jobs / Task Logs	visual cron editor, placeholder insertion, run-now, execution history
Analysis	injection analytics with trend / distribution / correlation charts
Config / System Logs	every configuration key in one place, live backend log viewer

Authentication is JWT-based (default admin / admin — change it on first login), with route guards on the frontend and middleware on every API.

Integrations

Hermes Active integrates with Hermes Agent through public interfaces only:

Integration point	Interface	Purpose
LLM calls	`agent.auxiliary_client.call_llm()`	thought / emotion / contemplation generation
Response parsing	`extract_content_or_reasoning()`	content + reasoning extraction
Persona	`agent.prompt_builder.load_soul_md()`	load `SOUL.md`
Session data	`hermes_state.SessionDB`	read sessions & messages, append proactive messages
WeChat sending	`gateway.platforms.weixin.send_weixin_direct()`	proactive delivery
Feishu sending	`gateway.platforms.feishu.FeishuAdapter`	proactive delivery
Session sync	`gateway/extensions/session_fallback.py`	⚠️ small patch — keeps gateway memory in sync when `state.db` changes externally

External services:

Hindsight — long-term memory: Recall (semantic search), Reflect (synthesis), Retain (thought storage). Optional; the system degrades gracefully without it.
Weather — Amap (高德) and QWeather (和风) providers behind one unified weather.* configuration, with result caching and change-threshold detection.

Tech Stack

Layer	Technology
Backend	Python 3.12+ · FastAPI · SQLAlchemy 2 · APScheduler · Jinja2
Frontend	Vue 3 · Naive UI · Vue Router · Pinia · ECharts · Vite
Storage	SQLite — dual database (`state.db` read-only / `active.db` read-write)
LLM	Any OpenAI-compatible API, or Hermes Agent's own client
Memory	Hindsight (Recall / Reflect / Retain)
Weather	Amap · QWeather
Auth	JWT (python-jose) · bcrypt

Project Structure

hermes-active/
├── backend/                        # FastAPI backend (port 18720)
│   ├── main.py                     # entry point, lifespan starts all schedulers
│   ├── config.py                   # server constants
│   ├── models/                     # SQLAlchemy tables + Pydantic schemas
│   │   ├── database.py             # dual-engine setup (state.db / active.db)
│   │   ├── active.py               # users, configs, task/heartbeat/thought/contemplation logs
│   │   └── *_consciousness.py      # consciousness domain models
│   ├── routers/                    # REST API layer
│   │   ├── auth.py · sessions.py · messages.py · config.py
│   │   ├── cron.py · task_logs.py · stats.py · system_logs.py
│   │   ├── active_consciousness.py · passive_consciousness.py · free_consciousness.py
│   │   └── hindsight.py · llm.py · test.py
│   ├── services/                   # business logic
│   │   ├── active_consciousness_service.py   # heartbeat, emotion, decision, retention
│   │   ├── thought_engine.py                 # thought generation pipeline
│   │   ├── context_collector.py              # structured context bundle
│   │   ├── passive_consciousness_service.py  # signals: longing / heat / intensity
│   │   ├── template_service.py               # Jinja2 injection templates
│   │   ├── analysis_service.py               # injection analytics
│   │   ├── free_consciousness_service.py     # contemplation loop + sediment
│   │   ├── scheduler_service.py              # cron jobs with placeholders
│   │   ├── message_service.py                # platform sending + state.db appends
│   │   ├── weather_service.py                # Amap / QWeather with cache
│   │   ├── llm_service.py · config_service.py · auth_service.py
│   │   └── session_service.py · fallback_session_service.py · state_db.py
│   └── tests/                      # pytest suites (emotion, decision, e2e, weather…)
├── frontend/                       # Vue 3 console (dev port 5173, proxy to backend)
│   └── src/
│       ├── views/                  # one view per console page
│       ├── api/                    # axios wrappers with JWT interceptor
│       ├── components/             # layout, charts, pickers
│       └── router/ · store/
├── deployment/
│   ├── systemd/                    # user service unit
│   └── hermes-agent-patches/       # session_fallback patch + instructions
└── docs/                           # design documents & installation guides

Quick Start

[!NOTE]
🖼️ Infographic placeholder — Deployment Topology · Save as docs/images/en-deployment.png.

Generation prompt: A deployment topology infographic for a self-hosted AI system. White background, minimal blueprint style. One light gray rounded rectangle representing a server, containing four white cards: "hermes-active :18720", "Hermes Gateway", "Hindsight :8888", "plugins/". Outside: a phone icon on the left, a browser icon on the right, arrows showing message flow. All connectors in light gray thin lines, key nodes accented in coral-orange, generous whitespace, 16:9.

Prerequisites

Python 3.12+ and Node.js 18+
A running Hermes Agent installation (~/.hermes/hermes-agent)
Optional: Hindsight for long-term memory

Install

# Hermes Active lives inside the Hermes home directory
cd ~/.hermes
git clone https://github.com/your-org/hermes-active.git
cd hermes-active

# Backend — reuse Hermes Agent's venv so its modules are importable
cd backend
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install
npm run build        # the backend serves frontend/dist directly

Run

cd ~/.hermes/hermes-active/backend
python main.py       # http://localhost:18720  (admin / admin)

For development: npm run dev starts the frontend on :5173 with API proxying.

Production

systemd unit — ready-made user service in deployment/systemd/
session-sync patch — apply the 4-file patch in deployment/hermes-agent-patches/ so the gateway notices externally-appended messages
passive-consciousness plugin — install into ~/.hermes/plugins/ per docs/plugin-installation.md
Full walkthrough: docs/deployment.md

⚠️ Change the default password immediately after first login, and set JWT_SECRET_KEY in production.

Configuration

All configuration lives in the configs table of active.db and is editable from the web UI — nothing is hard-coded. Highlights:

Active consciousness

Key	Default	Description
`active_consciousness.enabled`	`false`	master switch
`active_consciousness.active.heartbeat_interval`	`600`	heartbeat period (seconds)
`active_consciousness.active.send_tag`	`凯莉`	proactive mark prepended in `state.db`
`active_consciousness.decision.send_threshold`	`0.35`	score needed to auto-send
`active_consciousness.decision.memory_threshold`	`0.05`	score needed to retain as memory
`active_consciousness.decision.max_per_hour` / `max_per_day`	`2` / `5`	send rate limits
`active_consciousness.emotion.decay_rate`	`0.02`	arousal decay per hour
`active_consciousness.emotion.social_need_growth`	`0.01`	social-need growth per hour
`active_consciousness.emotion.valence_regression`	`0.1`	valence regression speed
`active_consciousness.llm.*`	hermes mode	universal LLM (tiered: `emotion_llm.`, `thought_llm.`)
`active_consciousness.hindsight.*`	localhost:8888	recall/store banks, limits, toggles

Passive consciousness

Key	Default	Description
`passive_consciousness.enabled`	`false`	master switch
`passive_consciousness.passive.inject_emotion / inject_heat / inject_memory / inject_thought`	`true`	per-signal toggles
`passive_consciousness.passive.inject_tag`	`[CONSCIOUSNESS_CONTEXT]`	wrapper tag of the injected block
`passive_consciousness.platforms.whitelist`	`["weixin"]`	platforms where injection runs
`passive_consciousness.templates.*`	default template	Jinja2 template list + active id
`passive_consciousness.hindsight.*`	enabled	recall limit, reflect toggle

Free consciousness

Key	Default	Description
`free_consciousness.enabled`	`false`	master switch
`free_consciousness.interval_minutes`	`30`	contemplation period
`free_consciousness.recent_rounds` / `mid_rounds`	`3` / `17`	thinking-chain layer sizes
`free_consciousness.sediment_compress_interval`	`10`	rounds between sediment compressions
`free_consciousness.include_context`	`true`	inject realtime time/emotion/conversations
`free_consciousness.store_to_hindsight`	`false`	retain discoveries to long-term memory
`free_consciousness.prompts.system` / `prompts.user`	built-in	fully templated contemplation prompts

Weather (unified)

Key	Default	Description
`weather.enabled`	`false`	master switch shared by cron, heartbeat and injection
`weather.provider`	`qweather`	`amap` or `qweather`
`weather.city` / `weather.adcode`	`北京` / `370100`	QWeather city name / Amap adcode
`weather.amap_key` / `weather.qweather_key`	—	provider API keys
`weather.cache_hours`	`4`	result cache TTL

Environment variables: JWT_SECRET_KEY — JWT signing key (set it in production).

API Overview

Everything the UI does is available over REST (JWT required except /health and login):

Group	Representative endpoints
Auth	`POST /api/auth/login`
Sessions & messages	`GET /api/sessions` · `GET /api/messages/{session_id}` · `POST /api/messages/send` · `POST /api/messages/send-and-inject`
Cron	`GET/POST/PUT/DELETE /api/cron/jobs` · `POST /api/cron/jobs/{id}/run` · `GET /api/task-logs`
Active consciousness	`GET/PUT /api/active-consciousness/config` · `GET .../status` · `GET .../heartbeats` · `GET .../thoughts` · `POST .../test/*`
Passive consciousness	`GET/PUT /api/passive-consciousness/config` · `GET .../status` · `GET/POST/PUT/DELETE .../templates` · `POST .../test/` · `GET .../analysis/`
Free consciousness	`GET/PUT /api/free-consciousness/config` · `GET .../status` · `GET .../logs` · `POST .../run`
Misc	`GET /api/stats` · `GET /api/system-logs` · `POST /api/llm/test` · `GET /health`

Documentation

Document	Contents
docs/deployment.md	full deployment walkthrough
docs/plugin-installation.md	passive-consciousness plugin setup
deployment/hermes-agent-patches/	session-sync patch instructions
docs/	design documents & architecture deep-dives

License

MIT License — see LICENSE for details.

[!NOTE]
🖼️ Infographic placeholder — Footer Banner · Save as docs/images/en-footer-banner.png.

Generation prompt: A minimal footer ribbon for an open-source README. Pure white background, an ultra-thin coral-orange gradient line spanning the center with a tiny heartbeat pulse symbol, elegant small dark gray sans-serif text "Hermes Active — Built with ❤️ for the Hermes Agent Community", clean whitespace, 6:1 wide ratio.

Built with ❤️ for the Hermes Agent community

hermes-active