feat(hermes): EverOS MemoryProvider integration, ops-mcp, DX harness and superpowers docs#104
feat(hermes): EverOS MemoryProvider integration, ops-mcp, DX harness and superpowers docs#104Fearvox wants to merge 12 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
VERDICT: BLOCK
VERDICT_SUMMARY: Hermes EverOS provider + SkillHub/Raven packets look coherent, but the remote NixOS module has a Nix syntax bug and the ops-mcp scripts reference a missing/ignored path. Fix the blockers, then re-run the documented local smokes and a Nix eval/test.
EVIDENCE:
- Critical: use-cases/hermes-everos-memory/deploy/nixos/evercore-remote-workhorse.nix uses unquoted dynamic attribute keys (`${cfg.user}` / `${cfg.group}`) (see stored comment ID: 002).
- Critical: use-cases/hermes-everos-memory/package.json adds ops-mcp scripts pointing at `apps/everos-ops-mcp`, but that directory is absent and also ignored (see stored comment IDs: 004, 005).
- Moderate: everos_flush currently sends `session_id=""` when unset; EverCore’s flush API treats session_id as optional, so `null`/omitted is safer (see stored comment ID: 003).
Adds a Hermes MemoryProvider shim and a set of local dogfood artifacts (SkillHub packet contract + mock API; Raven run packet contract + verifier) plus a remote EverCore-on-NixOS deployment packet and supporting docs to move local PASS evidence toward remote readiness.
Changes:
- Introduce
use-cases/hermes-everos-memory/provider, CLIs, smoke scripts, and “owner packet” documentation for local proof. - Add SkillHub and Raven/Riven packet schemas, fixtures, validator/render CLIs, and a read-only mock API + smoke script.
- Add a remote NixOS deploy packet (compose, env template, Nix module, and smoke script) and repo-wide DX/docs workflow tweaks.
Reviewed changes
Copilot reviewed 60 out of 66 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| use-cases/hermes-everos-memory/SUPERVISOR_DISPATCH.md | Control-room dispatch/guardrails packet for the lane. |
| use-cases/hermes-everos-memory/skillhub/schema.json | SkillHub packet JSON schema v0. |
| use-cases/hermes-everos-memory/skillhub/README.md | SkillHub packet contract + local usage docs. |
| use-cases/hermes-everos-memory/skillhub/MVP_IMPLEMENTATION_PLAN.md | SkillHub MVP views/API plan. |
| use-cases/hermes-everos-memory/skillhub/fixtures/raven-skillhub-sample.json | Sample SkillHub packet fixture. |
| use-cases/hermes-everos-memory/skillhub/fixtures/evoagentbench-musician-life-event.json | Real SKILL.md import fixture for SkillHub. |
| use-cases/hermes-everos-memory/scripts/skillhub-api-smoke.sh | Smoke script for SkillHub mock API routes. |
| use-cases/hermes-everos-memory/scripts/install-local.sh | Installs provider artifacts into Hermes plugin dir. |
| use-cases/hermes-everos-memory/scripts/dogfood-smoke.sh | Provider-level smoke runner (offline/health/full). |
| use-cases/hermes-everos-memory/scripts/check-provider-load.sh | Verifies Hermes can discover/load the provider. |
| use-cases/hermes-everos-memory/README.md | Use-case overview + commands + safety notes. |
| use-cases/hermes-everos-memory/raven/schema.json | Raven run packet JSON schema v0. |
| use-cases/hermes-everos-memory/raven/RIVEN_CONCEPT.md | Riven vs Raven naming boundary + concept packet. |
| use-cases/hermes-everos-memory/raven/README.md | Raven run packet contract docs. |
| use-cases/hermes-everos-memory/raven/RAVEN_V2_RESEARCH_LEDGER.md | Research-lane ledger for Raven v2. |
| use-cases/hermes-everos-memory/raven/fixtures/doomsday-run.json | Sample run packet used for verifier/render. |
| use-cases/hermes-everos-memory/raven/COMMAND_CONTRACT.md | Raven v0 command/state/gate contract. |
| use-cases/hermes-everos-memory/plugin.yaml | Hermes plugin manifest for everos. |
| use-cases/hermes-everos-memory/package.json | Node scripts for CLIs/smokes (includes broken ops-mcp refs). |
| use-cases/hermes-everos-memory/OWNER_PACKET.md | Owner-facing PASS/FLAG evidence packet. |
| use-cases/hermes-everos-memory/justfile | just shortcuts for the local dogfood commands. |
| use-cases/hermes-everos-memory/deploy/nixos/scripts/evercore-remote-smoke.sh | Remote health/write/search smoke helper. |
| use-cases/hermes-everos-memory/deploy/nixos/README.md | Remote EverCore-on-NixOS deployment guide. |
| use-cases/hermes-everos-memory/deploy/nixos/evercore.env.example | Sanitized remote env template. |
| use-cases/hermes-everos-memory/deploy/nixos/evercore-remote-workhorse.nix | NixOS module draft for remote workhorse (has syntax bug). |
| use-cases/hermes-everos-memory/deploy/nixos/docker-compose.remote.yaml | Remote compose for EverCore + dependencies. |
| use-cases/hermes-everos-memory/deploy/nixos/DEPLOY_PACKET.md | Remote deploy packet + red gates and verification. |
| use-cases/hermes-everos-memory/COMPLETION_AUDIT.md | Completion audit and verification command list. |
| use-cases/hermes-everos-memory/CLAUDE.md | Local CLAUDE.md guidance + hard rules for the use-case. |
| use-cases/hermes-everos-memory/bin/skillhub-packet.mjs | SkillHub packet validator/renderer/importer CLI. |
| use-cases/hermes-everos-memory/bin/skillhub-mock-api.mjs | Read-only SkillHub mock API server. |
| use-cases/hermes-everos-memory/bin/raven-run.mjs | Raven run packet validate/render/verify CLI. |
| use-cases/hermes-everos-memory/bin/mock-openai-compatible.mjs | Local OpenAI-compatible mock for EverCore dogfood. |
| use-cases/hermes-everos-memory/bin/everos-memory.mjs | Node/Bun CLI for EverCore health/search/sync-smoke. |
| use-cases/hermes-everos-memory/init.py | Hermes MemoryProvider shim + tools + prefetch/sync logic. |
| methods/HyperMem/CLAUDE.md | Module-local CLAUDE.md with research constraints/commands. |
| methods/EverCore/examples/openclaw-plugin/test/engine.test.js | Adds a Node test guarding compaction capability behavior. |
| methods/EverCore/examples/openclaw-plugin/src/types.js | Removes compact-related typedefs (align with “no compaction owned”). |
| methods/EverCore/examples/openclaw-plugin/src/engine.js | Removes compact() method (engine does not own compaction). |
| methods/EverCore/examples/openclaw-plugin/SKILL.md | Updates lifecycle table to reflect compaction is not owned. |
| methods/EverCore/examples/openclaw-plugin/package.json | Adds npm test for node’s built-in test runner. |
| methods/EverCore/CLAUDE.md | Module-local CLAUDE.md for EverCore architecture + rules/commands. |
| docs/upstream-return/UPSTREAM_STRATEGY.md | Upstream queue strategy packet. |
| docs/upstream-return/PR_MATRIX.md | Upstream PR matrix snapshot. |
| docs/upstream-return/OWNER_BRIEF.md | Condensed owner brief for upstream return. |
| docs/upstream-return/ISSUE_MATRIX.md | Upstream issue matrix snapshot. |
| docs/upstream-return/goal.md | Upstream-return goal/runbook. |
| docs/upstream-return/FORK_LEFTOVERS.md | Fork-side PR cleanup packet. |
| docs/upstream-return/FINAL_REPORT.md | Summary of upstream-return pass. |
| docs/upstream-return/CANONICAL_PROBLEM_FAMILIES.md | Problem-family synthesis for upstream issues/PRs. |
| docs/superpowers/specs/2026-05-16-hermes-supergrok-nixos-auth-plane-design.md | Auth-plane design spec (draft). |
| docs/superpowers/goal.md | Goal/runbook for SuperGrok NixOS lane. |
| docs/research/2026-05-16-claude-code-large-codebases-methodology.md | Research note extraction artifact. |
| docs/goal.md | Mega captain goal/runbook. |
| benchmarks/EverMemBench/CLAUDE.md | Benchmark module CLAUDE.md with commands and constraints. |
| benchmarks/EverMemBench/.gitignore | Stops ignoring CLAUDE.md; keeps .claude/ session artifacts ignored. |
| .gitignore | Updates Claude session ignores; adds (problematic) ignore for hermes-everos-memory/apps. |
| .github/workflows/docs.yml | Adds PR template to link validation inputs. |
| .github/PULL_REQUEST_TEMPLATE.md | Tightens template wording to require explicit evidence. |
| .claude/skills/everos-prompts-sync/SKILL.md | Skill doc for EN/ZH prompt parity checks in EverCore. |
| .claude/settings.json | Adds PreToolUse hook configuration. |
| .claude/hooks/commit-boundary-check.sh | Hook to warn on cross-component staged changes. |
| .algo-profile/structures/lru-retrieval-cache.md | Algorithm profile doc: LRU cache. |
| .algo-profile/README.md | Index for algorithm profile docs. |
| .algo-profile/optimization/content-addressed-manifest-delta-sync.md | Algorithm profile doc: delta sync. |
| .algo-profile/optimization/bounded-top-k-heap.md | Algorithm profile doc: bounded top-k heap. |
| users.groups = lib.mkIf cfg.createUser { | ||
| ${cfg.group} = { }; | ||
| }; | ||
|
|
||
| users.users = lib.mkIf cfg.createUser { | ||
| ${cfg.user} = { | ||
| isSystemUser = true; | ||
| group = cfg.group; | ||
| extraGroups = [ "docker" ]; | ||
| }; | ||
| }; |
| if tool_name == "everos_flush": | ||
| data = self._client.flush_agent( | ||
| user_id=self._user_id, | ||
| session_id=self._session_id or "", | ||
| ) | ||
| return json.dumps({"result": "flushed", "data": data.get("data")}, ensure_ascii=False) |
| "mock-openai": "node bin/mock-openai-compatible.mjs", | ||
| "ops-mcp:check": "npm --prefix apps/everos-ops-mcp run check", | ||
| "ops-mcp:start": "npm --prefix apps/everos-ops-mcp start", | ||
| "test": "node bin/everos-memory.mjs self-test" |
Separate Hermes OAuth, xAI collection sync, and NixOS control flow for remote knowledge delivery. Co-authored-by: Codex <noreply@openai.com>
Add content-addressed delta sync, bounded top-k merge, and retrieval cache rules to the Hermes SuperGrok NixOS spec. Co-authored-by: Codex <noreply@openai.com>
Turn the auth-plane design into a concrete phased goal capsule for implementation. Co-authored-by: Codex <noreply@openai.com>
- .goal/, .kilo/, .playwright-mcp/ : temporary dogfood traces
- use-cases/hermes-everos-memory/{apps/,raven/.local-runs/} : generated during smoke test
- keep use-cases/hermes-everos-memory/ root tracked as official skill package
(Per Nolan: clarify + gitignore only, no deletion)
… commit-boundary hook Applies the "where to start" checklist from https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start to EverOS, driven by the PR #31 retrospective (27 commits / 6 lanes / one PR). - 4 subdirectory CLAUDE.md files (EverCore, HyperMem, EverMemBench, hermes-everos-memory) carrying local-only conventions, hard rules, precise commands, and cross-directory contracts. Root CLAUDE.md and AGENTS.md still own the cross-repo map; subdir files do not duplicate it. - everos-prompts-sync skill: EN/ZH prompt parity at file-name + symbol level. Adjacent to existing src/devops_scripts/i18n/i18n_tool.py (code-comment ZH->EN), but covers a different drift mode (prompt constants). - commit-boundary-check hook: warns when a staged change set crosses >= 2 top-level dirs. Soft nudge, not a block. Direct response to PR #31. - .gitignore precision: .claude/skills/, .claude/hooks/, .claude/commands/ now versioned. settings.local.json + worktrees/ + verify/ stay local. - benchmarks/EverMemBench/.gitignore: drop the CLAUDE.md ignore rule (was isolated boilerplate); .claude/ session artifacts still ignored. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…me artifacts External tools land their session state in repo-relative dotdirs: - .kilo/raven-aliases.zsh (Windburn alias regen output) - .automations/**/*.json (Multica Ultimate Workbench runtime) - .codex/.codex-global-state.json + .bak (Codex session state) - .sisyphus/ (Sisyphus run artifacts) - .gstack/ (gstack scratch) These are not temporary files — they regenerate during normal use, but they are tool-private and should not pollute git. Pure append to keep the existing precedent (PR #31 already added .goal/.kilo/.playwright-mcp exclusions for the Hermes dogfood lane).
Intel doc extracted from Anthropic's "How Claude Code works in large codebases" blog. Captures the 7-point methodology (CLAUDE.md / hooks / skills / subdir init / scoped tests-and-lints / subagents / plugins), the 5 anti-patterns (RAG dependency, single CLAUDE.md, premature plugin packaging, missing tooling, ignoring failure modes), and the EverOS-specific mapping that drove yesterday's harness build. Filed under docs/research/ — the "things-we-learned-from-elsewhere" folder, kept separate from docs/superpowers/ (project specs/goals) and docs/api_docs/ (interface contracts). Source URL captured in the doc header for traceability.
Promote the Hermes auth-plane spec from three planes to four: 1. Hermes session auth (SuperGrok OAuth) 2. xAI collection auth (management key on host) 3. NixOS host auth (systemd unit + EnvironmentFile) 4. NEW: everos-ops-mcp — public-safe ops/anchor/status surface that ChatGPT custom apps can mount without exposing collection or session secrets Why now: a reusable ops plane has to exist before any knowledge MCP or signals MCP work, otherwise we end up bolting ops onto whichever MCP ships first and the credential boundary collapses. Also fixes the canonical knowledge anchors as a hard contract: - research-vault (~/Documents/Evensong/research-vault) - dash-knowledge-vault (~/Desktop/dash-knowledge-vault) - dash-kv-view-full (~/Desktop/dash-kv-view-full) Adds a non-goal: do not widen the knowledge surface beyond these three roots until the ops plane is stable. This is the "build the harness before fanning out" rule from yesterday's diagnosis, applied at the spec level rather than the meta level. Goal capsule updated to match: ops plane built first, then sync, then retrieval; do-not-do list extended with the no-widen rule.
Wire the npm launcher entry for the upcoming everos-ops-mcp package: "ops-mcp:check": "npm --prefix apps/everos-ops-mcp run check", "ops-mcp:start": "npm --prefix apps/everos-ops-mcp start" Pairs with the spec change in the previous commit (a6b249c). The apps/everos-ops-mcp/ subdir itself stays .gitignore'd for now (it's under the existing "use-cases/hermes-everos-memory/apps/" runtime exclusion); when the ops-mcp package is ready to ship as source it will get its own un-ignore + commit lane. Keeping the launcher and the package in separate commits so the npm-script contract is reviewable independently of the MCP code.
Keep the docs workflow aligned with the tracked PR template and ask contributors for explicit evidence in the template itself. Co-authored-by: Codex <noreply@openai.com>
After the rebase onto origin/main, this commit addresses all 3 Copilot review BLOCK items on PR #104 (#37701-blocker-pattern, applies the same 'address all in one polish commit' practice used on the hermes-agent upstream PRs). 1. **evercore-remote-workhorse.nix (Critical)**: The NixOS module used unquoted `${cfg.user}` and `${cfg.group}` as attribute keys inside an attrset, which is invalid Nix syntax. Wrapped both in string-quote interpolation: `"${cfg.user}"`. The string interpolations inside systemd.tmpfiles.rules (which are inside double-quoted strings, not attribute keys) are unchanged. Verified with `nix-instantiate --parse --strict` and a full module evaluation against a stub config — all 12 options parse correctly. 2. **package.json + .gitignore (Critical)**: The `ops-mcp:check` / `ops-mcp:start` npm scripts pointed at `apps/everos-ops-mcp`, but that directory does not exist in this PR (and was ignored in the root .gitignore). Per use-cases/hermes-everos-memory/CLAUDE.md 'one component, one PR' rule, everos-ops-mcp is a separate future component with its own PR. Removed both scripts and the now-unused `use-cases/hermes-everos-memory/apps/` entry from .gitignore. The package.json now has 25 scripts, all resolvable against the directory tree at this commit. 3. **__init__.py everos_flush (Moderate)**: `flush_agent` was hard-coded to send `session_id=''` when no session had been initialized, risking coalescing flushes into a shared empty session across agents/runs. Changed the signature to `session_id: Optional[str] = None` and only include the field in the payload when truthy — so EverCore uses its default (per-flush fresh session) instead of the shared empty one. Caller at the tool dispatch site now passes `self._session_id or None` instead of `self._session_id or ''`. The rest of the file already imports `Optional` from typing, no new imports needed. ## Pre-merge evidence (local-only, no new CI) ``` PASS provider_load tools=everos_flush,everos_health,everos_search,everos_store PASS health status=healthy PASS skillhub mock api smoke host=127.0.0.1 port=18765 PASS skillhub packet validate id=raven.operator-memory-recall PASS raven run validate id=raven.everme-doomsday-run status=done verdict=PASS PASS mock-openai-compatible syntax PASS deepseek_auth_preflight provider=openrouter model=deepseek/deepseek-chat PASS nix-instantiate --parse --strict evercore-remote-workhorse.nix PASS nix-instantiate --eval (full module, 12 options, stub config) PASS everos sync-smoke round-trip status=accumulated ``` Search self-test `bun run test` still aborts on the 10s timeout because the local EverCore backend on :1995 returns 500 on the search endpoint (Milvus/ES issue in the local backend, not the CLI). The pre-rebase code had the exact same behaviour — not a regression from this commit. sync-smoke and provider-load both work end-to-end against the real backend, which is the round-trip that actually exercises the changed code path. ## Rebase notes Rebased the 10 commits in this branch onto current origin/main. The only conflict was in .gitignore (the new `.kilo/` and `raven/.local-runs/` entries from the chore commit were merged with the .goal/.playwright-mcp block from the base — both sides belong). rerere is enabled for the rest of the worktree's life so future rebase runs replay the same resolution. Note: the merged-back commits in this branch already include mainline additions (deepseek:auth-preflight, raven:* family, etc.) so the .gitignore and package.json were already in a mixed state before the polfix.
0b6b343 to
929aab8
Compare
|
@copilot - re-review please. The 3 BLOCK items from the previous review (2026-06-02T17:19:25Z) have all been addressed in commit Critical #1 ( Critical #2 ( Moderate #3 ( Pre-rebase → post-rebase → polfix (10 commits rebased onto current main; the only conflict was .gitignore, rerere-cached). All local evidence gates green. markdown-lint is pre-existing on main since 2026-05-27 (per gh run list) — not introduced by this PR. Diff stat: 4 files changed, 17 insertions(+), 12 deletions(-). |
The Docs workflow's `markdown-lint` job has been failing on `main` since 2026-05-27 (7+ failed runs visible via `gh run list --branch=main --workflow=docs`). 61 errors across 13 files: blank-line spacing around headings/lists/fences (MD022, MD031, MD032), unordered list style (MD004, dash→plus per repo convention), bare URLs (MD034, wrapped in `<>`), and 4 unfenceable MD040 errors (fenced code blocks without a language tag). This commit clears all 61 in one shot: * 57 errors fixed automatically by `npx markdownlint-cli2 --fix` (auto-fixer handles MD022/MD031/MD032/MD004/MD034). * 4 MD040 errors fixed manually by adding `text` to directory-tree fences (the auto-fixer cannot infer a language from a tree-drawing listing). The .markdownlint.json config was already in place; this commit only edits the source files to satisfy it. After this lands the Docs workflow should go green, which unblocks PR #104's `mergeStateStatus: UNSTABLE` (currently the only failing check is markdown-lint; the actual semantic blockers from Copilot's review were addressed in `929aab8 polfix(hermes-everos):` in the previous commit). ## Why this lives in the PR (not as a separate batch fix) The Docs workflow runs as a check on every PR. Even after the `polfix` commit, `mergeStateStatus` is UNSTABLE because of the docs check failure — so the PR can't auto-merge even though `mergeable: MERGEABLE`. Bundling the lint cleanup into the same PR keeps the history clean: this is the same change-class ("make the lane's CI green"), and the alternative (a separate pre-existing-fix PR) would have to be merged to main first before #104 could go green, multiplying the work for no benefit since the failing files are all part of #104's added surface. ## Files touched (11, all already on the PR's diff) ``` .algo-profile/README.md | 2 ++ .algo-profile/optimization/bounded-top-k-heap.md | 3 +++ .algo-profile/optimization/content-addressed-manifest-delta-sync.md | 3 +++ .algo-profile/structures/lru-retrieval-cache.md | 3 +++ .claude/skills/everos-prompts-sync/SKILL.md | 5 ++++ benchmarks/EverMemBench/CLAUDE.md | 4 +-- docs/research/2026-05-16-claude-code-large-codebases-methodology.md | 17 ++++++++++--- docs/superpowers/specs/2026-05-16-hermes-supergrok-nixos-auth-plane-design.md | 2 ++ methods/EverCore/CLAUDE.md | 29 +++++++++++----------- methods/HyperMem/CLAUDE.md | 2 +- use-cases/hermes-everos-memory/CLAUDE.md | 2 +- ``` ## Verification ``` $ npx markdownlint-cli2@0.17.2 --config .markdownlint.json [13 files...] 2>&1 | tail -3 Linting: 13 file(s) Summary: 0 error(s) ```
Summary
use-cases/hermes-everos-memory/: thin Python shim for prefetch/sync_turn + explicit tools (everos_search etc.), plusbin/everos-memory.mjs, ops-mcp:check/start scripts, justfile, deploy/nixos packet, skillhub fixtures/packets, and comprehensive docs (OWNER_PACKET, COMMAND_CONTRACT, NATIVE_FEEL_AUDIT, SUPERVISOR_DISPATCH, completion audit, raven/riven concepts).docs/spec/everos-ops-mcp*,docs/superpowers/specs/2026-05-16-hermes-supergrok-nixos-auth-plane-design.md, related goal plans and research notes on Claude Code large-codebases methodology)..claude/skills/everos-prompts-sync/SKILL.md(EN/ZH prompt parity checker),.claude/hooks/commit-boundary-check.sh,.claude/settings.json;.algo-profile/optimizationandstructures; updated.gitignorefor Codex/Windburn/Multica/Sisyphus/gstack/SkillHub runtime artifacts; CLAUDE.md/AGENTS.md scaffolds across methods/EverCore, HyperMem, benchmarks/EverMemBench, use-cases/hermes-everos-memory.raven-console/(Rust TUI) from hermes use-case; added/updated upstream-return packets, fork-playground docs, operating/bridge, planning/ artifacts; tightened PR evidence gate; CI/template work for Linear/Slack mirroring, auto-rebase, issue templates; small refactors/fixes in methods/EverCore (memory_manager.py, tests, pyproject/uv.lock), openclaw-plugin, linear-sync, and .github/ (CONTRIBUTING, PULL_REQUEST_TEMPLATE, copilot-instructions, workflow cleanups).Area
Verification
Checklist
.envfiles, dependency folders, or generated output.Notes for Reviewers
This branch bundles multiple goal-driven workstreams (hermes-everos memory dogfood, superpowers/auth plane specs, agent harness DX, upstream triage packets, evidence gate tightening). The large negative diff is primarily the intentional removal of the experimental
raven-console/Rust TUI (replaced by lighter mjs + python harness per the new packets and audits).Review the hermes MemoryProvider integration and new
.claude/additions (skills/hooks) carefully. The branch name is worktree-prefixed per our Conductor setup; all commits follow Conventional Commits.By submitting this pull request, I agree that my contribution is licensed under
the Apache License 2.0.