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/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 ``` diff --git a/man/man1/hm.1 b/man/man1/hm.1 new file mode 100644 index 0000000..2b688f0 --- /dev/null +++ b/man/man1/hm.1 @@ -0,0 +1,151 @@ +.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 +Flush queued offline writes to reachable stores. +.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 +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 . +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 +Operational or user error. +.TP +.B 2 +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" 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