Proactive for Hermes Agent

Hermes Agent용 독립 로컬 우선·침묵 우선 워크플로 — 먼저 발견하고 제안하며, 지원되는 외부 쓰기 전에는 명시적으로 승인

Independent project; not affiliated with or endorsed by Nous Research or Hermès.

Proactive for Hermes Agent의 목표 V1은 이메일과 일정을 단순 검색하는 도구가 아니다. 아직 비활성인 src/hermes_proactive/ SQLite Runtime은 현재 상황을 Profile별 World Model로 정리하고, 중요한 변화와 약속을 찾아내며, Quiet Hours와 개입 예산을 통과한 항목만 Hermes의 개인 Home Channel로 보내도록 설계되었다. Gmail 또는 Google Calendar 변경마다 전체 Preview와 명시적 승인을 요구하는 설명도 이 새 Runtime의 목표 계약이며, 현재 활성 Legacy Optional Skill dispatch의 보증을 뜻하지 않는다.

먼저 읽어야 할 현재 상태

이 저장소의 src/hermes_proactive/에는 새 SQLite Runtime의 로컬 구현과 안전성 검증 코드가 있다. 이 저장소는 source-only release candidate이며, 새 Runtime은 아직 Production이 아니다.

항목	현재 상태
Python package	`hermes-proactive==1.0.0rc1`
새 SQLite Runtime	로컬 구현·테스트 대상, 기본 비활성
Optional Skill Production dispatch	기존 Legacy Runtime 유지
Public bootstrap	`release-manifest.json`의 `public_bootstrap_ready=false`; 설치 차단
Gmail / Calendar live write	조직 소유 synthetic tenant와 외부 승인 증거 전에는 차단
Canonical cutover	`IMP-0609` Acceptance 전에는 금지
V1 Provider	Gmail, Google Calendar만 지원

status가 production_dispatch=legacy_runtime와 canonical_sqlite_runtime_active=false를 반환하는 것이 현재의 정상 동작이다. 로컬 코드가 통과했다는 사실을 GA, 공개 배포, 실제 Google 쓰기 승인으로 해석하면 안 된다.

현재 실제 Hermes Optional Skill Production entrypoint는 optional-skills/productivity/hermes-proactive/의 Legacy Runtime으로 dispatch된다. Legacy는 로컬 JSON state에 이메일·일정 등 plaintext PII를 보존할 수 있고, Microsoft Graph·IMAP·SMTP·CalDAV·POP3 같은 과거의 non-V1 provider compatibility 설정도 유지한다. 이 Legacy 경로에는 아래 새 Runtime의 canonical SQLite, field encryption, OS Secret Store, Profile isolation, transactional outbox 보증이 소급 적용되지 않는다. 과거 설정이 존재하거나 동작한다는 사실은 V1 지원 또는 새 provider 지원을 뜻하지 않는다.

public_bootstrap_ready=false인 동안 이 후보는 source 검증용일 뿐이다. GA, 공개 bootstrap, 실제 Google write, 새 Runtime 활성화, Legacy quarantine/cutover를 주장하지 않는다.

무엇을 해결하는가

놓치기 쉬운 약속을 구조화한다

Gmail thread와 Calendar event를 Profile별 Observation/Evidence로 정규화한다.
Entity, Claim, Fact, Preference, Relationship, Commitment, Intent, Conflict를 revision으로 보존한다.
모순된 정보는 덮어쓰지 않고 Conflict로 남긴다.
오래되거나 불완전한 Source를 근거로 “문제없음”을 만들지 않는다.

필요한 순간에만 먼저 말한다

Micro / Night / Weekly Dream과 Morning Memory Review를 구분한다.
Situation score, freshness, cooldown, dedupe, interruption budget을 결정적으로 평가한다.
기본 Quiet Hours는 현지 시각 21:00–07:00이다.
Quiet Hours 우회는 deterministic Critical Allowlist만 가능하다.
같은 Situation을 여러 채널에 중복 전송하지 않는다.

외부 변경은 사용자가 통제한다

Gmail 답장/초안 및 Google Calendar 생성·수정·삭제는 전체 Preview가 먼저다.
승인은 immutable proposal version과 payload hash에 결합된다.
내용, 수신자, 일정, 첨부, 권한이 바뀌면 기존 승인은 무효다.
외부 side effect는 transactional outbox와 one-shot executor를 거친다.
응답 손실로 결과를 모르면 outcome_unknown에 두고 자동 재시도하지 않는다.

새 SQLite Runtime의 핵심 안전 불변식

다음 불변식은 비활성 src/hermes_proactive/ Runtime의 계약이다. 활성 Legacy JSON dispatch가 동일한 저장·암호화·Secret Store·outbox 보증을 제공한다는 설명이 아니다.

한 설치와 한 canonical database는 정확히 한 Hermes Profile에 속한다.
Profile 간 조회, 링크, Delivery, 승인, 실행은 모두 금지한다.
OAuth token, key, approval nonce, raw provider content는 일반 SQLite/JSON/log에 저장하지 않는다.
Secret material은 Profile-bound OS Secret Store에만 둔다.
LLM-facing 코드는 Provider write credential을 보유하거나 executor를 직접 호출하지 않는다.
Prompt, 이메일, 문서, Tool 결과는 모두 untrusted data다. 정책과 권한을 바꿀 수 없다.
Delivery와 Provider write는 committed outbox claim 없이 실행하지 않는다.
Source freshness를 증명하지 못하면 전체 기능을 건강하다고 표시하지 않는다.

새 SQLite Runtime 구조

아래 그림은 목표 V1 구조이며 현재 활성 Legacy Optional Skill의 실행 흐름이 아니다.

flowchart LR
    H[Hermes Profile / Cron / Gateway] --> A[Hermes Compatibility Adapter]
    A --> R[Profile-bound Runtime]
    G[Gmail + Google Calendar read adapters] --> O[Observation / Evidence]
    O --> W[World Model]
    W --> D[Dreaming + Memory Review]
    D --> S[Situation / Policy gates]
    S --> Q[Transactional outboxes]
    Q --> H
    S --> P[Proposal + full Preview]
    P --> V[Verified private approval]
    V --> E[One-shot executor]
    E --> G
    R --> DB[(Canonical SQLite)]
    R --> SS[OS Secret Store]

현재 Production dispatch는 이 흐름으로 전환되지 않았으며 IMP-0609 전에는 전환할 수 없다.

새 Runtime 목표 구조의 소유권은 다음처럼 분리된다.

Hermes: Profile context, Native Cron, Gateway, Home Channel, Session/Memory surface
ProActive: canonical SQLite, World Model, Dreaming, Situation policy, Proposal/Approval/Execution, outbox
Google adapters: Gmail/Calendar transport와 exact-account binding
LLM: 제한된 structured inference만 수행; 정책·권한·실행 권한 없음

새 SQLite Runtime V1 기능 상태

영역	로컬 구현	Production 의미
Profile/DB/Secret Store binding	있음	exact evidence가 없으면 시작 차단
Gmail read/sync/reconciliation	있음	실제 계정 증거는 Release gate 필요
Calendar read/sync/reconciliation	있음	실제 계정 증거는 Release gate 필요
World Model / Dreaming	있음	모델 capability·budget·freshness가 필요
Memory projection	committed outbox worker 있음	current-profile Hermes Memory binding 필요
Situation / Quiet Hours / budgets	있음	calibration과 private Home Channel 확인 필요
Delivery	outbox-backed worker 있음	private recipient proof 없으면 차단
Gmail / Calendar write	preview/approval/executor adapter 있음	synthetic tenant gate 전에는 live write 차단
Outcome reconciliation	read-only reconciliation 있음	`outcome_unknown` 자동 재실행 금지
Backup / restore / retention / purge	로컬 adapter 있음	destructive owner authority 계약 해결 전 fail-closed
Private dashboard	loopback read-only surface	owner-proof issuer와 Production composition 전에는 비활성
Public installer	verify-before-execute 구현	signed assets와 attestation 전에는 의도적으로 종료

새 SQLite Runtime Provider 범위

V1 Tier 1

Gmail
Google Calendar

V1 Production 경로에 노출하지 않는 항목

Generic IMAP: post-V1 read-only beta
SMTP: post-V1 별도 capability
CalDAV: post-V1 별도 capability
Microsoft Graph / Outlook: deferred
POP3: unsupported

요구 환경

Python 3.11 이상; 현재 release candidate 검증 범위는 3.11–3.14
uv 0.11.29
Hermes Agent의 승인된 Profile/Capability surface
Profile-bound OS Secret Store
후속 승인된 live-acceptance에서만 필요한 Gmail/Google Calendar OAuth client와 정확한 read scope — 현재 새 Runtime setup composition은 차단
Production writer를 위한 허용된 SQLite/WAL evidence

실제 Google credential, 개인 데이터, Production secret을 fixture·CI·개발 환경에 넣지 않는다.

지금 설치할 수 있는 범위

1. 인증된 source checkout에서 로컬 검증

공개 bootstrap이 열리기 전의 유일한 새 Runtime 사용 범위다.

git clone https://github.com/madrobotnet/proactive.git
cd proactive
uv sync --locked
uv run hermes-proactive status
uv run hermes-proactive runtime-probe

예상되는 핵심 상태:

production_dispatch: legacy_runtime
canonical_sqlite_runtime_active: false
new_runtime.activation_state: inactive

이 명령은 Production database를 만들거나 migration/writer를 시작하지 않는다.

2. 명시적 Profile 진단

Ambient Profile을 추측하지 않는다. Profile과 Hermes home을 모두 지정한다.

uv run hermes-proactive diagnostic \
  --profile-id PROFILE_ID \
  --hermes-home /absolute/path/to/hermes-home

uv run hermes-proactive health \
  --profile-id PROFILE_ID \
  --hermes-home /absolute/path/to/hermes-home

진단은 secret value 대신 redacted status/reason code만 출력한다. 불완전한 evidence는 blocked, degraded, stale, unknown 중 하나로 표시하며 건강 상태로 승격하지 않는다.

3. 기존 Optional Skill 사용자

이미 설치된 Optional Skill의 Production dispatch는 계속 Legacy Runtime을 사용한다. 새 package를 수동으로 연결하거나 Legacy state를 새 Runtime의 canonical state로 취급하지 않는다. Cutover와 rollback/quarantine은 IMP-0609에서 별도로 수행한다.

4. 공개 설치

현재는 지원하지 않는다. install.sh와 install.ps1은 public_bootstrap_ready=false에서 fail-closed로 종료한다. 향후 공개 설치는 다음을 모두 검증한 뒤에만 wheel을 풀고 hermes-proactive setup을 실행한다.

immutable commit과 exact release tag
install manifest와 wheel SHA-256
GitHub OIDC/Sigstore SLSA provenance
SPDX SBOM attestation
package name/version/Requires-Python/console mapping
안전한 wheel extraction 경로
승인된 새 Runtime setup composition

Legacy installer fallback은 없다.

Setup이 아직 CLI에 없는 이유

CanonicalSetupCoordinator는 Profile, DB, Secret Store, private Home/approval channel, locale/timezone, Quiet Hours, Google read scopes/accounts/calendars, Dreaming, calibration, retention 안내를 typed preview로 검증한다. 그러나 resumable setup checkpoint를 저장할 canonical DDL과 실제 installed composition은 아직 정본 계약으로 닫히지 않았다.

따라서 가짜 setup complete, caller boolean, JSON fallback, 자동 Profile 탐색을 제공하지 않는다. Issue #2가 해결되고 signed artifact에 포함될 때까지 공개 setup은 차단된다.

승인된 Cutover 이후의 사용자 흐름

아래는 현재 활성 경로가 아니라 V1의 목표 사용자 흐름이다.

Hermes Profile과 개인 Home Channel을 확인한다.
Quiet Hours를 확인한다. 입력하지 않으면 21:00–07:00이다.
Gmail/Calendar read-only OAuth account를 명시적으로 연결한다.
Calendar allowlist와 계정별 scope를 Preview에서 확인한다.
Shadow calibration으로 먼저 관찰한다. 이 단계에서는 일반 Nudge와 write가 없다.
verified private activation을 별도로 승인한다.
Morning Review에서 기억 후보를 채택, 거절, 수정, 보류한다.
Action이 필요하면 전체 Preview를 검토하고 그 버전에 한 번만 승인한다.
실행 결과가 불명확하면 자동 재시도하지 않고 reconciliation 상태를 확인한다.

Google 권한 원칙

초기 연결은 read scope만 요청한다.

Gmail: gmail.readonly 또는 승인된 metadata-only 범위
Calendar: calendar.calendarlist.readonly, calendar.events.readonly

Write 권한은 별도 연결·별도 capability다. Custody mode도 명시적이다.

HERMES_READ_BROKER: Hermes가 read credential custody를 증명
PROACTIVE_OAUTH: ProActive OS Secret Store가 단일 refresh owner

두 mode 사이를 자동 import/switch하지 않는다. 복수 계정은 각 account/session/custody binding을 독립적으로 검사한다.

Quiet Hours와 Critical

기본: 현지 시각 21:00–07:00
DST fold/gap을 포함해 timezone-aware clock으로 계산
Critical은 사용자 문구나 LLM label이 아니라 deterministic allowlist로만 판정
Routine/high-value 항목은 Quiet Hours 중 보류
Digest/Nudge/Urgent의 cooldown·burst·daily budget을 독립 적용
Source가 stale/unknown이면 all-clear 메시지를 만들지 않음

Approval과 실행

Preview에는 실행에 영향을 주는 모든 필드가 있어야 한다.

Gmail: account, thread, recipients, subject/body, attachment metadata
Calendar: account, calendar, time/timezone, attendees, recurrence, conference/reminder fields
Edit 결과는 새 proposal version
Approval은 exact proposal/version/payload hash/actor/private channel에 결합
Raw approval nonce는 DB/WAL/log/export에 저장하지 않음
Executor child는 credential reference만 전달받고 one-shot으로 종료
outcome_unknown은 terminal hold이며 자동 retry 대상이 아님

새 SQLite Runtime 데이터와 Privacy

아래 표는 비활성 SQLite Runtime의 목표 저장 계약이다. 활성 Legacy Optional Skill의 로컬 JSON state에는 plaintext PII가 남을 수 있으며, Legacy 데이터는 새 Runtime의 field encryption·blind index·OS Secret Store 보증을 받지 않는다.

데이터	위치
World Model, queue, audit, revision	Profile-bound canonical SQLite
OAuth token, encryption/signing key	Profile-bound OS Secret Store
민감 field	versioned authenticated encryption
lookup용 값	purpose/profile/field-bound blind index
Hermes Memory	committed projection outbox를 통한 요약 projection만
log/health/dashboard	redacted reason code와 opaque fingerprint만

Export는 secret/token/approval nonce를 포함하지 않아야 하며 기본적으로 owner-authenticated encrypted archive다. Person forget, Google disconnect, full Profile purge는 projection·blind index·pending proposal·key/token/Cron까지 처리해야 한다. 현재 destructive owner confirmation issuer와 Profile Secret Store namespace purge attestation이 정본화되지 않았으므로 Production data-control capability는 Issue #5, #7, #8, #9가 닫히기 전까지 fail-closed다.

Private dashboard

Dashboard는 일반 사용자의 주 실행면이 아니라 read-only 진단/복구 surface다.

127.0.0.1/::1 loopback only
explicit Profile binding
untrusted third-party asset 0개
mutation endpoint 0개
secret/raw content 0개
URL, browser storage, cookie, log에 owner proof 저장 금지
activation, source freshness, Situation/Proposal fingerprint, queue/outcome-unknown, Dreaming/calibration, incident/retention 상태만 표시

서버는 자동 시작하지 않는다. Production launcher와 proof issuer는 release composition이 승인될 때까지 비활성이다.

Health 해석

healthy는 required component의 최신 evidence가 모두 있을 때만 가능하다. 최소한 다음이 분리되어 보인다.

activation / incident gate
Hermes adapter / Profile / DB schema / writer ownership
Secret Store / key availability / key rotation
Google OAuth/provider / Gmail sync+reconciliation / Calendar sync+reconciliation
Native Cron / model capability / Dreaming / memory projection
Situations / Home Channel / delivery
approval+executor / all transactional outboxes
retention / data control

Optional feature가 꺼져 있어도 required failure를 가리지 않는다. blocked, stale, unknown, malformed evidence는 non-zero 상태다.

운영 원칙

장기 scheduler는 Hermes Native Cron만 사용한다.
시작 시 owner-only startup lock, DB/profile/schema/runtime/secret/key/provider/outbox/worker evidence를 검사한다.
Queue lease를 복구하되 uncertain external outcome을 재실행하지 않는다.
Backup은 SQLite online backup과 checksum/profile manifest를 사용한다.
Restore 후 retention과 read-only provider reconciliation을 다시 수행한다.
Key rotation은 restart-safe state machine이지만 immutable protected row rewrite와 whole-DB rollback anchor는 Issue #1의 정본 결정 전까지 retirement-ready GA로 표시하지 않는다.

개발과 검증

새 Runtime baseline:

uv sync --locked
uv run pytest
uv run ruff check src tests
uv run ty check src/hermes_proactive
uv run basedpyright
python3 spec/tools/validate_spec_pack.py spec

Legacy 경계를 건드렸을 때:

python3 -m unittest discover -s tests/skills -p 'test_*.py'
python3 -m py_compile optional-skills/productivity/hermes-proactive/scripts/*.py

GitHub Actions는 PR/push에서 자동 실행하지 않는다. Wave 종료 시 exact main SHA를 입력한 workflow_dispatch만 허용하며 Python 3.11–3.14, Linux/Windows/macOS, Runtime, Legacy, lint/type/spec/security evidence를 모두 집계한다.

Release 전에 남은 결정과 증거

공개 추적: V1 production readiness milestone · V1 Readiness project

Issue	성격	필요한 결과
#1	`SPEC_BLOCKER`	immutable record key rotation과 external rollback anchor
#2	package/cutover blocker	canonical setup state/composition, signed wheel entrypoint
#3	external release evidence	live synthetic Google E2E, hosted matrix, trace evidence, sign-off
#4	scale/schema change	memory review와 queue reclaim용 additive indexes + EXPLAIN/scale evidence
#5	`SPEC_BLOCKER`	one-time private-owner authority for export/restore/purge/dashboard
#7	`SPEC_BLOCKER`	Profile Secret Store namespace purge/absence attestation
#8	`SPEC_BLOCKER`	Hermes read-broker 계정의 ProActive detach/disconnect 증거
#9	`SPEC_BLOCKER`	Full-profile purge tombstone/cancel barrier와 모든 worker fence

해결됨: #6은 V1에서 fail-closed 재인증을 선택했다. 회전 중 crash가 나면 기존 token fallback이나 orphan secret 자동 채택 없이 blocked/cleanup_pending으로 남는다.

Release 완료는 issue 개수나 로컬 테스트 개수로 판정하지 않는다. S-12 Acceptance, Mother’s Birthday live Google E2E, fault/security gates, hosted exact-main matrix, signed evidence bundle, human Product/Security approval, Legacy quarantine/rollback을 모두 통과해야 한다.

정본 문서

구현과 README가 충돌하면 다음 순서를 따른다.

spec/HERMES_PROACTIVE_COMPLETION_STANDARD.md
spec/specs/00_SPEC_INDEX.md
S-01–S-12 specifications
machine-readable contracts, DDL, acceptance fixtures
ADRs

Repository 작업 규칙은 AGENTS.md를 따른다.

Security

실제 credential, 개인 Gmail/Calendar 데이터, OAuth token, key, raw approval nonce를 Issue나 로그에 붙이지 않는다. 취약점 신고와 지원 범위는 SECURITY.md를 따른다.

Build Week과 Codex 사용

이 프로젝트의 초기 버전은 Codex로 개발했으며, 현재 source candidate로 방향을 전환한 뒤에도 Codex를 주 개발·검토 환경으로 사용했습니다. AI 보조 작업에는 GPT 계열 모델을 사용했고, GPT-5.6 Terra는 코드·경계·테스트·공개 source 검토에 사용했습니다.

Codex는 설계 검토, 구현, 테스트·lint·type·명세 검증, 그리고 공개 source sanitization에 사용했습니다.
사람이 기능 범위, 안전성 불변식, 공개 범위와 최종 제출 내용을 검토·결정했습니다.
주 Codex build session의 /feedback Session ID는 Devpost 제출에만 사용하며, 저장소에는 공개하지 않습니다.

이 README의 현재 상태·제한·검증 명령은 실제 공개 후보 기준입니다. 실제 Google write, 새 SQLite Runtime Production 활성화, canonical cutover를 완료했다는 의미가 아닙니다.

English overview

Proactive for Hermes Agent is an independently maintained, local-first project. Its target V1 is the inactive src/hermes_proactive/ SQLite Runtime, which turns Gmail and Google Calendar observations into a profile-scoped World Model and delivers policy-approved interventions to the user's private Home Channel. This target architecture is not the active Optional Skill dispatch.

Historical package/import names, paths, and compatibility markers retain hermes-proactive; they are technical identifiers, not an affiliation claim.

Current status

Surface	Status
Package	`hermes-proactive==1.0.0rc1` development release candidate
New SQLite Runtime	Implemented and locally tested; inactive and non-canonical
Production dispatch	Legacy Runtime remains active until `IMP-0609`
V1 providers	Gmail and Google Calendar only
Public bootstrap	Disabled until signed release evidence exists
Live Google writes	Blocked until the external synthetic-tenant gates pass

This repository is not GA. A passing local suite is not authorization to activate the new Runtime, publish a release, or use real Google write credentials.

The active Production entrypoint remains the Legacy Optional Skill Runtime. Its local JSON state may retain plaintext PII and historical non-V1 provider compatibility settings, including Microsoft Graph, IMAP, SMTP, CalDAV, and POP3. Those Legacy paths do not inherit the new Runtime's SQLite, field encryption, OS Secret Store, Profile-isolation, or transactional-outbox guarantees, and their presence is not V1 provider support. This is a source-only candidate with public_bootstrap_ready=false, not GA or evidence of a live Google write or Runtime cutover.

New Runtime safety model

The following guarantees apply to the inactive SQLite Runtime contract, not to the active Legacy JSON dispatch.

One installation and canonical database belong to exactly one Hermes Profile.
Quiet Hours default to 21:00–07:00; only the deterministic Critical Allowlist may bypass them.
Every Gmail or Calendar mutation requires a complete preview and a fresh, explicit approval bound to the immutable proposal version and payload hash.
Every external side effect uses a transactional outbox.
outcome_unknown is never retried automatically.
OAuth tokens, encryption/signing keys, and approval nonces stay out of ordinary SQLite, JSON, logs, dashboards, and exports.
Prompt, email, document, and tool content is untrusted data and cannot change policy, permission, approval, or memory-write rules.

Source-only verification

Until release-manifest.json sets public_bootstrap_ready=true, use a public source checkout:

uv sync --locked
uv run pytest
uv run ruff check src tests
uv run ty check src/hermes_proactive
python3 spec/tools/validate_spec_pack.py spec

Do not bypass the disabled bootstrap. The remaining specification, setup, live-Google, hosted-matrix, signing, owner-authority, destructive-data-control, and cutover gates are listed above under Release 전에 남은 결정과 증거.

The project is independently maintained and is not affiliated with, sponsored by, or endorsed by Nous Research or Hermès.

License

MIT. LICENSE 참조.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
optional-skills/productivity/hermes-proactive		optional-skills/productivity/hermes-proactive
spec		spec
src/hermes_proactive		src/hermes_proactive
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
HERMES_PROACTIVE_ACCOUNT_LINKING_GUIDES.md		HERMES_PROACTIVE_ACCOUNT_LINKING_GUIDES.md
HERMES_PROACTIVE_POST_V1_ROADMAP.md		HERMES_PROACTIVE_POST_V1_ROADMAP.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SKILL.md		SKILL.md
install.ps1		install.ps1
install.sh		install.sh
pyproject.toml		pyproject.toml
release-manifest.json		release-manifest.json
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation