Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
CLAUDE.md
Guidance for agents working in this repository.
Versioning
package.json version is the single source of truth. The version is
mirrored into several manifests (plugin.yaml, plugins/hermes/plugin.yaml,
.claude-plugin/plugin.json, .codex-plugin/plugin.json,
plugins/codex/.codex-plugin/plugin.json, openclaw.plugin.json),
pyproject.toml and uv.lock.
Never hand-edit the version in those mirrored files. To bump the version,
edit package.json only, then propagate with:
bun run scripts/sync-version.ts
CI gates on bun run scripts/sync-version.ts --check (the validate job,
step "Verify manifest version sync"). Hand-editing one file leaves the
others drifted and fails that gate before any other check runs. Run the
--check form locally before pushing a version change.
WHEN to bump: inside the feature PR, before the first push
The version bump is part of the change itself, NOT a separate later step.
Bump package.json (and run sync-version.ts) on the feature branch and
include it in the SAME pull request as the feature, before you push. Every
release-bearing squash commit on main carries its version in the title -
e.g. feat: … (v1.5.0) (#NN) - because the bump rode in with the feature.
Concretely, for any feature/fix PR that ships a release:
- Add the
CHANGELOG.mdentry under the new## [X.Y.Z] - <date>heading AND its[X.Y.Z]: …/compare/…link-reference at the bottom of the file. - Bump
package.jsontoX.Y.Zand runbun run scripts/sync-version.ts. - Commit both, then push the branch and open the PR.
Do this even though main is protected (direct pushes are rejected; all
changes go through a PR) - which is exactly why the bump cannot be a
post-merge step: a forgotten bump means package.json and the CHANGELOG
heading disagree on main and a second PR is needed to reconcile them.
This OVERRIDES the generic feature-release-playbook default ("do not bump
version mid-PR; bump once in the release phase"). That default assumes a
maintainer can push the bump straight to main at release time; this repo
cannot, so the bump belongs in the feature PR. The GitHub release
(gh release create vX.Y.Z) is published AFTER that PR merges and only tags
the already-bumped commit - it never changes the version.
Codex plugin mirrors
Codex installs the plugin from ./plugins/codex only, and its cache copy
drops symlinks. So plugins/codex/skills/ is a real, byte-identical copy of
skills/, LICENSE, README.md, SECURITY.md and .codexignore in
plugins/codex/ are real copies generated from the repository root, and plugins/codex/hooks/hooks.json is generated from
hooks/hooks.json (SessionEnd timeouts capped at Codex's 3 s limit, and a
commandWindows cmd.exe form added to every hook). Every hook command must
end in the o2b-hook <name> fallback, or the sync refuses it. Never
edit the copies and never turn them back into symlinks. After changing a
skill or hooks/hooks.json, run:
bun run sync-plugin-mirrors
CI gates on bun run sync-plugin-mirrors:check (the validate and
windows jobs), and the pre-commit hook runs the same check.