hermes-cortex

Files (24)

• SKILL.md
• 2026-06-17-post-merge-bugfixes.md · references/
• agents-loop-governance-template.md · references/
• auto-profile-detection.md · references/
• bible-prep-issues.md · references/
• cortex-update-deployment-map.md · references/
• cron-model-migration.md · references/
• hermes-dot-dir-cleanup.md · references/
• install-update-650fc94.md · references/
• installation-audit-methodology.md · references/
• langfuse-data-population.md · references/
• langfuse-v3-migration.md · references/
• memory-architecture.md · references/
• multi-project-memory-layers.md · references/
• naming-conventions.md · references/
• offline-knowledge-subcommands.md · references/
• plugin-enablement.md · references/
• profile-auth-inheritance.md · references/
• project-cortex-directory.md · references/
• public-repo-privacy.md · references/
• script-deployment-architecture.md · references/
• security-hardening.md · references/
• seed-project-bootstrapping.md · references/
• session-state-pattern.md · references/

SKILL.md (first lines)

# Hermes Cortex Setup

Hermes Cortex is the local AI infrastructure layer that provides:
- **Ollama** — Local LLM inference server
- **mycortex** — Postgres-native knowledge brain with hybrid RAG search (legacy brain replacement, decommissioned 2026-08-02)
- **systemd (Linux) / launchd (macOS) services** — Persistent daemons for Ollama, mycortex, Dashboard
- **Hermes plugins** — `/brain` slash command for knowledge queries (`mycortex-command`)

> **⚠️ The legacy `brain` CLI is DEAD — the `mycortex` CLI replaces it.** All `brain` CLI commands below are
> legacy. The mycortex CLI lives at `ops/scripts/manage/mycortex` (deployed to
> `~/.hermes-cortex/scripts/mycortex`): `sources add|list|remove`, `sync`,
> `search`, `list`, `stats`, `doctor`. Runs over mycortex-postgres (:15432) —
> no daemon, no bun; sync is a cron. Legacy brain troubleshooting sections further
> down are historical and kept only for migration reference.

## Installation

### Prerequisites

```bash
# Verify Python 3.12+ (canonical interpreter for cortex scripts)
python3 --version

# Verify Docker (required for mycortex-postgres + Langfuse)
docker --version

# Supported OS: Linux (systemd, apt/dnf/pacman), macOS (launchd, brew), WSL
uname -s # Linux or Darwin
```

### Run the Installer

The installer lives at `ops/install/install.sh` (moved from repo root in v2.0.0):

```bash
git clone --depth 1 https://github.com/lukemcqueen/hermes-cortex.git ~/hermes-cortex
cd ~/hermes-cortex
bash ops/install/install.sh

# Check prerequisites only (no install):
bash ops/install/install.sh --check

# macOS — Laptop profile: lean, no Docker
CORTEX_PROFILE=laptop bash ops/install/install.sh

# Linux — auto-detects systemd, apt/dnf/pacman
CORTEX_OS=linux bash ops/install/install.sh
```

**Idempotent** — safe to re-run. Skips already-installed steps.

The installer runs **~30 steps** (exact count varies by OS/profile):

| Step | Component | What it does |
|------|-----------|--------------|
| 0 | System Check | Verifies OS, RAM, disk, Docker, network before touching anything |
| 1 | Ollama | Native installer per OS, bound to localhost; pulls `nomic-embed-text:v1.5` |
| 2 | Bun | JavaScript runtime (still used by some tooling) |
| 3 | mycortex-postgres | Docker Postgres + pgvector, schema migrations (replaces the legacy brain) |
| 4 | Brain directories | `~/brain/{default,…}` with MECE schema, .gitignore, git init |
| 5 | mycortex sources | Registers brain dirs as mycortex sources (via `manage/mycortex` CLI) |
| 6 | Hermes mycortex plugin | `/brain` slash command (`plugins/mycortex-command`) |
| 7 | Hermes utility scripts | heartbeat, memory-to-brain-sync, check-memory-budget, etc. |
| 8 | Cron jobs | Essential crons (auto-remediation, health, memory sync) + orchestrator-only |
| 9 | Hermes skills | Deploys repo `skills/` → `~/.hermes/skills/` via an inline install loop (`install.sh` step 10, `find ... -name SKILL.md` → copy; **skips existing files** — it never overwrites). Ongoing skill updates flow repo → `cortex-update.sh` `sync_skills()` (delta engine, only changed files), NOT this one-time copy. |
| 10 | Hooks | Scoring pre-commit hooks to all projects + post-merge hook |
| 11 | MCP servers | loop-governance (loop-gov-mcp.py), tasks (task-mcp.py) |
| 12 | Web Cache | Semantic web result cache |
| 13 | Langfuse | Docker Compose stack with auto-generated secrets |
| 14 | Cortex Dashboard | Flask app + systemd/launchd service |
| 15 | Offline tools | cache cascade + ZIM viewer |
| 16 | nginx | Reverse proxy (SSL or local-only mode) |
| 17 | Hardening | File permission lockdown on sensitive files |
| 18 | Bootstrap | Bootstraps brain sources (verify + index) |

**What gets installed:**

| Component | Port | Purpose |
|-----------|------|---------|
| Ollama | 11434 | Local LLM serving |
| mycortex-postgres | 15432 | Knowledge brain (Postgres + pgvector, Docker) |
| Langfuse | 3000 | LLM observability (Docker) |
| Cortex Dashboard | 8901 | System health + Langfuse companion |
| ClickHouse (Langfuse) | 8123/9000 | Analytics DB for Langfuse v3 |
| nginx | 11002, 11003 | Reverse proxy for external access |

### Script Deployment Architecture

Hermes Cortex uses a **two-directory deployment model**:

| Directory | Purpose | Managed by |
|-----------|---------|-----------|
| `~/.hermes-cortex/scripts/` | **Canonical runtime location** — all cortex scripts deployed here | `cortex-update.sh` register map |
| `~/.hermes/scripts/` | **Cron resolution** — Hermes Agent cron scheduler looks here | Symlinks → `~/.hermes-cortex/scripts/` |

**How scripts flow:** Repo source → `cortex-update.sh ` → `~/.hermes-cortex/scripts/` → symlink → `~/.hermes/scripts/`. Do NOT manually copy scripts to `~/.hermes/scripts/` — always use `cortex-update.sh` to deploy, then create symlinks.

**To add a new cortex script:**
1. Add `register "ops/path/to/script" "${HERMES_HOME}/scripts/name"` to `cortex-update.sh`
2. Run `bash ~/.hermes-cortex/scripts/cortex-update.sh `
3. Create symlink: `ln -sf ~/.hermes-cortex/scripts/name ~/.hermes/scripts/name`
4. Register in `install-crons.sh` if it's a cron script

**Cleanup of stale duplicates:** If both `~/.hermes/scripts/` and `~/.hermes-cortex/scripts/` have a copy of the same file, replace the `~/.hermes/scripts/` copy with a symlink:
```bash
rm ~/.hermes/scripts/<file> && ln -sf ~/.hermes-cortex/scripts/<file> ~/.hermes/scripts/<file>
```
This was done for 42 files in June 2026. Any future cortex-update maintenance should follow the same pattern — never leave stale regular-file copies in `~/.hermes/scripts/`.

**Cron job script resolution:** The cron scheduler resolves scripts from `HERMES_HOME/scripts/` (`~/.hermes/scripts/`), resolving symlinks via `.resolve()`. The `install-crons.sh` function checks `SCRIPTS_DIR="${HOME}/.hermes-cortex/scripts"` when verifying script existence during cron creation.

**External access (via nginx):**
- Langfuse: `https://your-domain.com:11002` (TLS + basic auth, upstream `127.0.0.1:3000`)
- Cortex Dashboard: `https://your-domain.com:11003` (TLS + basic auth)

### Verify Installation

```bash
# Ollama health

From lukemcqueen/hermes-cortex, MIT.

More from lukemcqueen/hermes-cortex