memhooks 0.5.0

Backend-neutral parser, resolver, validator, and CLI for filesystem-scoped AI agent memory routing
Documentation
# Publishing the Rust crate

This is maintainer documentation for publishing `memhooks` to crates.io.

## Current registry state

MemHooks v0.4.1 is already published on crates.io. The repository has an authenticated crates.io publishing secret configured and every release candidate is package-tested with:

```bash
cargo publish --dry-run
```

The first publication was also verified by installing the registry release and running the installed binary.

## Before every release

Run:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
cargo run --quiet -- validate --all
rm -f Cargo.lock
cargo publish --dry-run
```

The standard CI workflow performs these checks.

## Authentication

Publishing automation uses the GitHub Actions repository secret:

```text
CARGO_REGISTRY_TOKEN
```

A fallback `CRATES_IO_TOKEN` may be supported by one-shot release workflows, but `CARGO_REGISTRY_TOKEN` is preferred.

Never commit registry credentials to the repository or expose them in logs/issues/chats.

## Package contents

The crates.io package intentionally contains the Rust package and documentation needed by crate/CLI users:

```text
Cargo.toml
LICENSE
README.md
src/**
docs/**
```

Repository artwork, Python runtime hooks, example projects, and unrelated assets do not need to inflate the Rust crate package.

## docs.rs

`src/lib.rs` includes `docs/rust-library.md` as crate-level documentation. Because `docs/**` is packaged, docs.rs builds the API landing page from the same maintained guide used in the repository.

When public Rust APIs change, update `docs/rust-library.md` in the same pull request. CI treats Rustdoc warnings as errors.

## Package version versus protocol version

They are intentionally separate.

Current v0.5 release line:

```text
package/release: 0.5.0
protocol schema:  memhooks/v2
```

A package patch/minor release does not inherently require another protocol schema change. Change the protocol version only when the protocol contract itself changes incompatibly or deliberately establishes a new schema generation.

## Recommended release sequence

1. update `Cargo.toml`, `SKILL.md`, README/status, docs, examples, tests, and changelog;
2. run full CI including Rustdoc and `cargo publish --dry-run`;
3. merge the release PR;
4. publish the crate with the configured registry credential;
5. verify the exact version can be installed from crates.io;
6. verify/update the matching GitHub release/tag;
7. confirm docs.rs can build the packaged documentation;
8. remove one-shot publisher workflows after successful publication.

## Provider-neutral release check

For `memhooks/v2`, a release review should explicitly verify that provider-native vocabulary has not leaked into the universal core.

Provider-specific concepts belong under `backends.<provider>` and provider reference docs. Examples:

- Hindsight `bank`, memory categories, Reflect, Mental Models;
- Mem0 filters, entity-scope IDs, result limits, thresholds, reranking, graph toggles;
- OpenViking hierarchy/native retrieval controls;
- Honcho peer/session/reasoning controls.

The generic Rust model/validator must not require one provider SDK or provider ontology.

## Trusted publishing

Now that crate ownership exists, crates.io trusted/passwordless publishing can be preferred when configured and appropriate. Until then, keep the registry token limited to the repository secret and rotate/revoke it according to normal credential hygiene.