hermes guardian

zero-trust memory protection for autonomous agents: Intercepting attacks where input filters fail

Comment 1

HermesGuardian - Current Architecture Path

This document reflects the path the repository is actually taking now.

It intentionally supersedes older assumptions about required apps/web, mandatory cloud services, or chain-first UI data sources when those do not match the current codebase.

1. Direction

HermesGuardian is being built as a local-first memory defense product.

The order of truth is:

  1. packages/core owns scoring logic
  2. packages/plugin is the authoritative enforcement boundary
  3. the local dashboard reads the plugin's local data
  4. chain receipts are supplemental evidence, not the primary source of truth
  5. cloud services are optional later expansion, not the immediate blocker

This means the product is still useful if every remote service is absent:

  • the plugin still blocks malicious writes
  • the local dashboard still shows local evidence
  • the user still has an audit trail on disk

2. Current Repo Shape

hermes-guardian/
├── apps/
│   └── dashboard/          # Vite React SPA for the local-first dashboard
│
├── packages/
│   ├── core/               # TrustScorer, patterns, semantic signal, judge client
│   └── plugin/             # Hermes plugin, local event log, local server
│
├── contracts/              # Solana Anchor receipt programs
└── docs/                   # Architecture, plan, threat model

Things that do not exist yet in the repo:

  • apps/api
  • apps/detection
  • apps/learning

Those are not immediate blockers if the equivalent capability is delivered locally first.

3. Current Runtime Flow

Plugin and scorer

Current real path:

  1. Hermes calls the plugin hook in packages/plugin
  2. the plugin builds a WriteEvent
  3. packages/core scores the write with temporal, pattern, and optional judge
  4. the plugin logs the scored event locally
  5. the plugin allows or blocks the write

Current status:

  • scorer path is real
  • fail-closed ambiguous handling exists
  • scored event metadata is logged
  • local JSONL event flow exists

Still missing for the full plugin path:

  • full Hermes MemoryProvider lifecycle implementation
  • background sync and flush behavior

Local dashboard path

Current real path:

  1. apps/dashboard builds a static SPA
  2. packages/plugin serves the SPA and local read APIs
  3. dashboard pages fetch local data from the plugin server

Current status:

  • Events, Overview, Threat, and Memory Gate read live /api/events
  • when event data is missing or unavailable, those event surfaces fall back to sample rows
  • BaselinesPage reads live /api/baseline/diff
  • ProvenancePage reads live /api/events plus /api/provenance/:id
  • ProvenancePage renders an interactive XyFlow DAG for one event
  • FleetPage reads live /api/fleet/summary
  • FleetPage renders a local topology graph from propagation evidence
  • scripts/seed_demo_data.sh can pre-populate demo-ready local evidence

This means the dashboard is now local-first and mostly real, with sample fallback retained only for event-stream surfaces.

4. What Is Real vs Mock

Real now

  • packages/core scoring pipeline
  • plugin enforcement hook
  • JSONL event schema with score breakdown
  • local event API at /api/events
  • local provenance API at /api/provenance/:id
  • local fleet summary plus topology payload at /api/fleet/summary
  • interactive XyFlow provenance graph
  • interactive XyFlow fleet topology graph
  • reproducible demo seed path for local first-load state
  • Solana Anchor receipt programs under contracts/
  • verified local Solana build and deploy path

Mock or incomplete now

  • richer PLUR propagation state beyond local replay-derived topology edges
  • continuous drift monitoring beyond point-in-time baseline diffs
  • remote multi-user backend

5. Chain Position

The repo is currently on a Solana Anchor path, not the older Base Sepolia Solidity path described in the original broad requirements document.

That means:

  • contracts/ is the single intended on-chain workspace
  • chain work should continue on Solana unless we explicitly change direction
  • the requirements doc still needs to be interpreted with that correction in mind
  • the local toolchain and localnet deploy path are now verified in-repo

Important architectural rule:

Solana should not be the source of truth for dashboard graphs.

The provenance graph and fleet graph should be driven by local provenance and propagation records first. Solana receipts can be shown as:

  • a receipt badge
  • an anchor timestamp
  • an external verification link
  • a hash proof reference in a details panel

Chain data is evidence, not the primary model for the UI.

6. Recommended Build Order

The path that makes the repo coherent is:

  1. finish plugin persistence and lifecycle
  2. finish local dashboard data plumbing
  3. add reproducible attack scenario tests
  4. add provenance, baselines, drift monitor, and PLUR gate
  5. add Solana receipt writer integration
  6. only then decide whether separate cloud services are worth the extra code

This order keeps the product aligned with the core principle that the plugin is the ground truth.

7. Optional Later Expansions

These can exist later if they provide a real capability increase, but they are not required merely to satisfy an older diagram:

  • apps/api

    • remote event aggregation
    • team accounts
    • shared provenance views
    • auth and persistence outside the local machine

  • apps/detection

    • isolated hosted LLM judge endpoint
    • hosted score or embed endpoints
    • provider key isolation

  • apps/learning

    • scheduled red or blue loop
    • pattern evolution from blocked write history
    • dashboard-visible cycle summaries

If we implement equivalent local-first behavior and the remote service adds no new product value, we should prefer the simpler local path.

8. Near-Term Architecture Targets

Plugin target

packages/plugin should grow into:

  • enforcement hook
  • lifecycle wrapper for Hermes memory APIs
  • local JSONL log
  • local SQLite store
  • provenance builder
  • baseline snapshotter
  • PLUR gate hooks

Dashboard target

apps/dashboard should evolve from mixed live or mock pages into:

  • live event feed
  • real memory gate view
  • real baseline diff view
  • real provenance graph view
  • real fleet or propagation view
  • seeded first-load demo liveness for review sessions

Server target

The local server now exposes:

  • GET /api/events
  • GET /api/provenance/:id
  • GET /api/baseline/diff
  • GET /api/fleet/summary
  • GET /api/receipts

Still optional later:

  • local update streaming

We do not need to force FastAPI immediately if the current lightweight server remains sufficient, but websocket or richer endpoint work may justify that upgrade later.

9. Non-Negotiable Rules

  1. The plugin remains the only authoritative write-time gate
  2. packages/core remains the single source of scoring logic
  3. Dashboard graphs must be sourced from local records, not from chain data
  4. Mock dashboard surfaces must be replaced before claiming those features are implemented
  5. Separate cloud apps are justified only when they add capabilities the local path does not already cover

Built With

Share this project:

Updates