From 372ac6ed932810050575e8765a3bb5df8f46b3bb Mon Sep 17 00:00:00 2001 From: Chris Graf Date: Mon, 29 Jun 2026 22:10:12 -0500 Subject: [PATCH 1/3] Add `hm` manual page Summary Add a section-1 manual page for the Hive Memory CLI and include it in release archives so packaged installs carry the same command reference as source checkouts. - document global options, command groups, config, files, and security boundaries - package `man/man1/hm.1` into release tarballs - smoke-test that release archives include the manpage Testing - `bash tests/shell/release-scripts-test` - `cargo fmt --all --check` - `cargo test --locked` - scoped `checkrun format` / `checkrun lint` on changed files - `git diff --check` --- README.md | 3 +- man/man1/hm.1 | 142 +++++++++++++++++++++++++++++++ scripts/package-release.sh | 2 + scripts/smoke-release.sh | 1 + tests/shell/release-scripts-test | 9 ++ 5 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 man/man1/hm.1 diff --git a/README.md b/README.md index 6a78315..0709c1b 100644 --- a/README.md +++ b/README.md @@ -633,7 +633,8 @@ scripts/release.sh --push Linux archives use musl targets; published assets use installer-facing platform names (e.g. `hm--linux-x86_64-musl.tar.gz`, -`hm--macos-aarch64.tar.gz`). +`hm--macos-aarch64.tar.gz`). Release archives include the `hm` +binary, project metadata, and the `man/man1/hm.1` manual page. ## License diff --git a/man/man1/hm.1 b/man/man1/hm.1 new file mode 100644 index 0000000..603cd50 --- /dev/null +++ b/man/man1/hm.1 @@ -0,0 +1,142 @@ +.TH HM 1 "2026-06-30" "hive-memory" "User Commands" +.SH NAME +hm \- durable plain-text memory for AI agents +.SH SYNOPSIS +.B hm +.RI [ global-options ] +.I command +.RI [ args ...] +.SH DESCRIPTION +.B hm +is the Hive Memory command-line interface. It manages durable, shareable, +plain-text memory for AI agents across sessions, agents, machines, and +projects. +.PP +The canonical store is ordinary files on disk: Markdown notes with TOML front +matter, JSON event sidecars, curated Markdown, and rebuildable indexes. Hive +Memory uses store and project identities so synced folders can move across +machines without losing scope. +.SH GLOBAL OPTIONS +.TP +.BI --config " path" +Use a specific config file instead of the default XDG config path. +.TP +.BI --store " name" +Select a configured store. +.TP +.BI --as-agent " id" +Attribute writes and hook events to a specific agent identity. +.TP +.BR -h ", " --help +Show help. +.TP +.BR -V ", " --version +Print version information. +.SH COMMANDS +.TP +.B stores +Initialize, list, show, diagnose, and migrate memory stores. +.TP +.B remember +Write a durable fact, preference, project context note, or reminder. +.TP +.B note +Write a lower-confidence raw note for later triage. +.TP +.B search +Search curated and remembered memory, with optional inbox inclusion and +explanations. +.TP +.B context +Assemble agent-readable context within a token budget. +.TP +.B sync-status +Report store and index freshness without mutating state. +.TP +.B retag +Correct a record's persisted kind. +.TP +.B classify +Run the LLM kind-classification pass for pending or selected records. +.TP +.B capture +Extract durable fact candidates from a conversation and stage or promote them. +.TP +.B reconcile +Reconcile a candidate fact into memory using add, update, delete, or noop +decisions. +.TP +.B refresh +Rebuild indexes and derived state. +.TP +.B flush +Publish queued offline writes where the selected store supports it. +.TP +.B outbox +Inspect or manage queued offline writes. +.TP +.B projects +Resolve, bind, unbind, alias, list, and show project identities. +.TP +.B hook +Handle agent lifecycle events such as session start, prompt submit, tool +complete, and stop. +.TP +.B doctor +Run top-level diagnostics. Use +.B --quick +for hook-friendly checks. +.TP +.B promote +Promote a raw inbox note into curated memory. +.TP +.B inbox +Inspect raw inbox notes. +.TP +.B eval +Capture retrieval misses and bad hits as eval fixtures. +.SH CONFIGURATION +The default config path is +.IR ~/.config/hive-memory/config.toml . +A minimal config selects a default store and maps store names to roots: +.PP +.RS +.nf +default_store = "personal" + +[stores.personal] +root = "${HOME}/hive-memory/personal" +description = "Personal memory" +.fi +.RE +.SH FILES +.TP +.I ~/.config/hive-memory/config.toml +Default configuration file. +.TP +.I /manifest.toml +Store identity and metadata. +.TP +.I /memories/ +Remembered and curated memory content. +.TP +.I /inbox/ +Raw notes and staged capture candidates. +.SH SECURITY +Hive Memory refuses common secret-looking content on the write path and labels +context blocks by source, scope, store, and trust. Context output is data for an +agent to consider; it is not a higher-priority instruction channel. +.SH EXIT STATUS +.TP +.B 0 +The command completed successfully. +.TP +.B 1 +The command could not complete because of failed checks, missing data, or store +state. +.TP +.B 2 +Usage or configuration error. +.SH SEE ALSO +.BR hm " " help , +.BR hm " " " --help" diff --git a/scripts/package-release.sh b/scripts/package-release.sh index 586e796..a9078c3 100755 --- a/scripts/package-release.sh +++ b/scripts/package-release.sh @@ -52,6 +52,8 @@ HIVE_MEMORY_BUILD_COMMIT="$commit" HIVE_MEMORY_BUILD_VERSION="$tag" \ install -m 0755 "target/${target}/release/hm" "$staging/hm" install -m 0644 README.md "$staging/README.md" install -m 0644 LICENSE "$staging/LICENSE" +mkdir -p "$staging/man/man1" +install -m 0644 man/man1/hm.1 "$staging/man/man1/hm.1" mkdir -p "$dist_dir" # Local package+smoke loops should test the archive that was actually produced, diff --git a/scripts/smoke-release.sh b/scripts/smoke-release.sh index 4d81015..52e9b53 100755 --- a/scripts/smoke-release.sh +++ b/scripts/smoke-release.sh @@ -43,6 +43,7 @@ trap cleanup EXIT tar -xzf "$archive" -C "$smoke" +test -f "$smoke/man/man1/hm.1" "$smoke/hm" --version "$smoke/hm" stores init personal --root "$smoke_store" diff --git a/tests/shell/release-scripts-test b/tests/shell/release-scripts-test index 6644fec..150da2d 100755 --- a/tests/shell/release-scripts-test +++ b/tests/shell/release-scripts-test @@ -41,6 +41,15 @@ _release_workflow=$(cat "$HIVE_MEMORY_DIR/.github/workflows/release.yml") _assert_contains "release workflow: uses exact reusable tag command" \ 'tag-command: scripts/release-tag.sh' "$_release_workflow" +if [[ -f "$HIVE_MEMORY_DIR/man/man1/hm.1" ]]; then + _pass "manpage: hm.1 exists" +else + _fail "manpage: hm.1 exists" +fi +_hm_manpage=$(cat "$HIVE_MEMORY_DIR/man/man1/hm.1") +_assert_contains "manpage: documents hm command" "hm \\-" "$_hm_manpage" +_assert_contains "manpage: documents hook command" ".B hook" "$_hm_manpage" + rc=0 ( cd "$HIVE_MEMORY_DIR" || exit 1 From 1b868c416c8eda6c12060e69bf0bdfaafe40e820 Mon Sep 17 00:00:00 2001 From: Chris Graf Date: Mon, 29 Jun 2026 22:26:56 -0500 Subject: [PATCH 2/3] Fix `hm` manpage command contracts Summary Bring the `hm` manual page in line with the current command set and exit status contract. - describe `outbox` as flushing queued offline writes - describe `eval` as retrieval metrics and fixture capture - document the distinct config, privacy, and backend exit codes Testing - `bash tests/shell/release-scripts-test` - `cargo fmt --all --check` - `cargo test --locked` - scoped `checkrun format` and `checkrun lint` for PR files - `git diff --check` --- man/man1/hm.1 | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/man/man1/hm.1 b/man/man1/hm.1 index 603cd50..2b688f0 100644 --- a/man/man1/hm.1 +++ b/man/man1/hm.1 @@ -73,7 +73,7 @@ Rebuild indexes and derived state. Publish queued offline writes where the selected store supports it. .TP .B outbox -Inspect or manage queued offline writes. +Flush queued offline writes to reachable stores. .TP .B projects Resolve, bind, unbind, alias, list, and show project identities. @@ -94,7 +94,8 @@ Promote a raw inbox note into curated memory. Inspect raw inbox notes. .TP .B eval -Capture retrieval misses and bad hits as eval fixtures. +Run retrieval corpus metrics and capture retrieval misses or bad hits as eval +fixtures. .SH CONFIGURATION The default config path is .IR ~/.config/hive-memory/config.toml . @@ -132,11 +133,19 @@ agent to consider; it is not a higher-priority instruction channel. The command completed successfully. .TP .B 1 -The command could not complete because of failed checks, missing data, or store -state. +Operational or user error. .TP .B 2 -Usage or configuration error. +Invalid CLI usage. +.TP +.B 3 +Configuration or schema validation failure. +.TP +.B 4 +Privacy or safety refusal. +.TP +.B 5 +Backend unavailable and no outbox fallback was available. .SH SEE ALSO .BR hm " " help , .BR hm " " " --help" From 12fa280e26638ee51048af4890292777a7806cbf Mon Sep 17 00:00:00 2001 From: Chris Graf Date: Mon, 29 Jun 2026 23:04:32 -0500 Subject: [PATCH 3/3] Document `hm` manpage release artifact Summary Keep the release contract in SPEC.md aligned with the package and smoke scripts by listing the hm manual page in the archive contents. Testing - tests/shell/release-scripts-test - cargo fmt --check - cargo test - cargo clippy --all-targets --all-features -- -D warnings - checkrun format SPEC.md - checkrun lint SPEC.md - git diff --check --- SPEC.md | 1 + 1 file changed, 1 insertion(+) diff --git a/SPEC.md b/SPEC.md index 69cfe64..c589265 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1929,6 +1929,7 @@ Each archive contains: hm README.md LICENSE +man/man1/hm.1 completions/ # optional after CLI stabilizes ```