Skip to content

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.

TypeScript
3.1 KB
Raw Blame

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:

  1. Add the CHANGELOG.md entry under the new ## [X.Y.Z] - <date> heading AND its [X.Y.Z]: …/compare/… link-reference at the bottom of the file.
  2. Bump package.json to X.Y.Z and run bun run scripts/sync-version.ts.
  3. 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.