hermes-brain-web

hermes-brain-web is a read-only web UI for two mounted knowledge backends:

• a SQLite fact store
• a markdown brain wiki

It does not bundle Hermes internals, and it does not copy brain data into the repository or image. The container only reads mounted data and renders a browser-oriented UI on top.

What it does

• Browse all facts in the SQLite fact store.
• Browse all pages in the markdown brain wiki.
• Inspect metadata, tags, and relationship context for the selected record.
• Follow an interactive knowledge graph from the detail pane into connected records.
• Browse full graph overviews with lightweight edge interaction so dense wiki graphs remain pannable.
• Pivot from fact-store entities into the facts that reference them.
• Run entirely against read-only mounts.

Stack

• Next.js 16
• React 19
• TypeScript
• better-sqlite3 for local read-only SQLite access
• gray-matter for wiki frontmatter parsing
• Vitest + Testing Library for behavior-focused tests

Runtime contract

The app expects these environment variables inside the container:

• HERMES_BRAIN_SQLITE_PATH=/data/memory/memory_store.db
• HERMES_BRAIN_WIKI_ROOT=/data/wiki
• PORT=3000

The SQLite file and wiki directory can both be mounted read-only. The Docker image includes a healthcheck that calls GET /api/health; the endpoint returns 200 only when the runtime config is valid, the SQLite fact store is readable with the expected schema, and the wiki root is a readable directory.

Run with Docker Compose

1. Edit docker-compose.yml and replace the placeholder host paths.
2. Start the app:

docker compose up --build

3. Open http://localhost:3000.

Network security

This app has no built-in authentication. The Compose default publishes it only on 127.0.0.1, so it is available from the host but not directly from the LAN or other untrusted networks. Do not change the mapping to a wildcard interface for direct remote access: the UI can render sensitive fact-store and wiki content.

For intentional remote access, keep the app on a private network or loopback interface and put a protected reverse proxy or authentication gateway in front of it. Configure TLS, authentication, and firewall or network access controls so only the intended proxy and users can reach the service.

Example volume bindings:

volumes:
  - /absolute/path/to/memory_store.db:/data/memory/memory_store.db:ro
  - /absolute/path/to/wiki/brain:/data/wiki:ro

Container publishing

Forgejo Actions builds the Docker image in CI for pull requests and publishes it to the Forgejo container registry for deployable refs.

Publishing rules:

• pushes to main publish code.mehalter.com/clawlter/hermes-brain-web:dev
• published releases tagged like v1.2.3 publish:
  • code.mehalter.com/clawlter/hermes-brain-web:v1.2.3
  • code.mehalter.com/clawlter/hermes-brain-web:v1
  • code.mehalter.com/clawlter/hermes-brain-web:latest
• pull requests build the image without pushing it

The publish workflow expects a Forgejo Actions secret named PACKAGE_TOKEN with permission to push packages for the owning user.

Local development

Install dependencies:

npm ci

Run the app:

HERMES_BRAIN_SQLITE_PATH=/absolute/path/to/memory_store.db \
HERMES_BRAIN_WIKI_ROOT=/absolute/path/to/wiki/brain \
npm run dev

Quality checks

npm run lint
npm run typecheck
npm test
npm run build

Testing philosophy

The tests focus on behavior rather than brittle snapshots:

• config parsing verifies the container contract
• SQLite loader tests verify fact/entity/bank normalization
• wiki loader tests verify frontmatter parsing and bidirectional wiki-link extraction
• graph builder tests verify neighborhood construction for facts, entities, and wiki pages
• UI tests verify backend switching and graph-driven browsing behavior

Repository safety

• This repository contains no brain data.
• The app is read-only by design.
• Authentication is intentionally out of scope; follow the network security guidance above before exposing it remotely.

Notes on the wiki parser

The wiki browser reads markdown files recursively, parses YAML frontmatter, extracts [[wiki-links]], and computes incoming/outgoing relationships in memory. It excludes the top-level index.md from the page corpus so the curated wiki landing page does not dominate graph results.