SIGN IN SIGN UP

feat: add Hermes Agent integration (proxy + plugin) (#465)

## Summary

Two-layer integration for [Hermes
Agent](https://github.com/NousResearch/hermes-agent) (163K stars, by
Nous Research) — gives Hermes users the full Lore memory pipeline with
minimal code.

## Architecture

### Layer 1: Proxy redirect (`lore run hermes`)
Adds Hermes to agent auto-detection in `agents.ts`. When `lore run`
detects `hermes` on PATH, it sets `OPENAI_BASE_URL` and
`HERMES_INFERENCE_PROVIDER=custom` to route all LLM calls through the
Lore gateway. This alone provides all 20+ gateway features (temporal
storage, distillation, knowledge curation, gradient compression, hybrid
recall, cache warming, etc.).

### Layer 2: Python plugin (`lore-hermes`)
A Hermes general plugin (`pip install lore-hermes`) that addresses
limitations of the proxy-only approach:

| Limitation | Plugin solution |
|---|---|
| Hermes's ContextCompressor fires at 50%, double-compressing | Context
engine passthrough: never compresses locally |
| No gateway auto-start without `lore run` | `on_session_start` hook
discovers/starts gateway |
| Fingerprint-based session ID (less reliable) | `pre_llm_call` hook
injects `[lore:session-id=...]` markers |
| No Hermes-side memory UX | CLI: `hermes lore status`, `hermes lore
recall` |

### Layer 3: Gateway-side marker parsing
Parses `[lore:session-id=...]` and `[lore:project=...]` context markers
from user messages for reliable session/project identification (Tier 2.5
between learned headers and fingerprint fallback).

## Changes

### Gateway (TypeScript)
- `packages/gateway/src/cli/agents.ts` — Hermes entry in AGENTS array
- `packages/gateway/src/cli/run.ts` — Updated error message
- `packages/gateway/src/pipeline.ts` — Context marker extraction
functions + Tier 2.5 session identification + project marker injection
at both handleConversationTurn and handleCompaction

### Plugin (Python, new package)
- `packages/hermes/pyproject.toml` — pip package with entry point
- `packages/hermes/lore_hermes/engine.py` — `LoreContextEngine`
passthrough
- `packages/hermes/lore_hermes/gateway.py` — Gateway discovery +
auto-startup
- `packages/hermes/lore_hermes/__init__.py` — Registration (context
engine + hooks + CLI)
- `packages/hermes/lore_hermes/plugin.yaml` — Hermes plugin manifest

### Tests
- `packages/gateway/test/context-markers.test.ts` — 20 unit tests for
marker parsing (all pass)
- `packages/hermes/tests/test_engine.py` — Context engine tests
- `packages/hermes/tests/test_gateway.py` — Gateway discovery tests
- `packages/hermes/test-integration.sh` — End-to-end integration test
script

## Usage

```bash
# Recommended: everything automatic
lore run hermes

# Or standalone (plugin handles gateway)
pip install lore-hermes
hermes

# CLI commands
hermes lore status
hermes lore recall "what was the auth bug?"
```

## Verification
- `bun run typecheck` — all 4 packages pass
- `bun test` — 1825 pass, 20 new tests all pass, 3 pre-existing failures
(unrelated)
B
Burak Yigit Kaya committed
b2e27da10f24af735dd4c7469bb9e2d403ef1576
Parent: 34b25fb
Committed by GitHub <noreply@github.com> on 5/24/2026, 4:00:32 PM