Verify the Memex Repo Before Committing
Run memex's three CI gates locally — cargo fmt --check, cargo clippy
with warnings denied, and the workspace test suite — so a red CI is caught
on your machine before you push. Optionally extend the run with the
Postgres-gated integration suite. This complements, and does not replace,
memex's own CI (.github/workflows/ci.yml); CI stays the authority.
When to Use
- Immediately before invoking
commit-changes on a memex working tree.
- After editing any Rust source under
crates/ (cli, sync, db, mcp,
extract), Cargo.toml, or rust-toolchain.toml.
- When a memex CI run went red and you want to reproduce the failing
gate locally with the same toolchain.
- Before opening a pull request against
pjt222/memex.
Inputs
- Required: A checkout of the memex repo (a clone of
github.com/pjt222/memex) with cwd set to the repo root. The gates
read rust-toolchain.toml (pinned 1.96.0 + rustfmt/clippy
components), so run from the root, not a subcrate.
- Required: A Rust toolchain on
PATH (rustup provisions the
pinned channel via rustup show). Confirm with command -v cargo.
- Optional (integration gate only): A running Postgres+pgvector on
:5433 (the memex-pg container) and a sourced .env supplying
MEMEX_TEST_PG_URL (and VOYAGE_API_KEY for embedding-backed tests).
Procedure
Step 1: Confirm the toolchain and working directory
The gates must run from the repo root so rust-toolchain.toml selects the
pinned 1.96.0 toolchain — local and CI rustfmt/clippy then match.
# From the memex repo root
test -f rust-toolchain.toml || { echo "not at memex repo root"; exit 1; }
rustup show # provisions/reports the pinned 1.96.0 toolchain
command -v cargo # toolchain must be on PATH
Expected: rust-toolchain.toml exists, rustup show reports the
active toolchain as 1.96.0, and cargo resolves to a path.
On failure: If you are not at the repo root, cd there first. If
cargo is missing, add it to PATH (e.g. export PATH="$HOME/.cargo/bin:$PATH")
and re-run.
Step 2: Gate 1 — format check
Mirrors the CI rustfmt job (cargo fmt --all --check). Read-only: it
reports formatting drift without rewriting files.
cargo fmt --all --check
Expected: Exit 0 and no diff output — the tree is already formatted.
On failure: Non-zero exit prints the unformatted hunks. Apply the
fix with cargo fmt --all, re-stage, and re-run this gate. Mark the
overall verify FAIL until this gate is clean.
Step 3: Gate 2 — clippy with warnings denied
Mirrors the CI clippy step (cargo clippy --workspace --all-targets -- -D warnings).
--all-targets lints tests and examples too; -D warnings makes any
lint a hard error, matching CI exactly.
cargo clippy --workspace --all-targets -- -D warnings
Expected: Exit 0 with no warnings emitted.
On failure: Each warning is promoted to an error and listed with its
lint name and source span. Fix the code (or, only when justified, add a
scoped #[allow(...)]), then re-run. Mark the overall verify FAIL until
clean.
Step 4: Gate 3 — workspace unit tests
Mirrors the CI unit-tests step (cargo test --workspace). This runs the
non-ignored suite across every crate.
cargo test --workspace
Expected: Exit 0 and a test result: ok. line for each crate's test
binary. The unit count is ~49 at v0.4.0 and grows per milestone
(M5 adds watcher tests). Treat the count as informational only — assert
on exit 0 / test result: ok, never on a specific number.
On failure: A non-zero exit and test result: FAILED. name the
failing tests. Reproduce a single one with
cargo test --workspace <test_name> -- --nocapture, fix, and re-run.
Mark the overall verify FAIL.
Step 5: Gate 4 (optional) — Postgres-gated integration suite
The #[ignore]-gated integration suite is omitted from CI today (it needs
a Postgres+pgvector service and a VOYAGE_API_KEY secret — see
docs/CONTINUE_HERE.md §5). Run it locally only when the database and
.env are available; skip this gate otherwise without failing verify.
# Only when the memex-pg container is up and .env is sourced:
docker start memex-pg # idempotent if already running
set -a && . ./.env && set +a # exports MEMEX_TEST_PG_URL, VOYAGE_API_KEY, ...
MEMEX_TEST_PG_URL="$MEMEX_TEST_PG_URL" cargo test --workspace -- --include-ignored
Expected: Exit 0 with test result: ok. including the integration
binaries. The total is ~60 at v0.4.0 (unit + ~11 integration) and
also grows per milestone — informational only.
On failure: If the suite fails because Postgres is unreachable or
MEMEX_TEST_PG_URL is unset, that is an environment gap — note it as
"integration gate skipped" rather than a code FAIL. If it fails with
actual test result: FAILED., treat it as a real FAIL and fix.
Step 6: Report per-gate results and the overall verdict
Summarize each gate (PASS/SKIP/FAIL) and the rolled-up verdict.
# Conceptual rollup: overall is non-zero if ANY required gate failed.
echo "fmt: <PASS|FAIL> clippy: <PASS|FAIL> unit-tests: <PASS|FAIL> integration: <PASS|SKIP|FAIL>"
Expected: Gates 1–3 (required) all PASS. The integration gate is PASS
or SKIP. Overall verdict PASS.
On failure: Exit non-zero overall if ANY required gate (1–3) or a
non-skipped integration run failed. Do not proceed to commit-changes
until the verdict is PASS.
Validation
Common Pitfalls
- Asserting a fixed test count. Counts grow each milestone; a literal
assert 49 turns a healthy run red. Assert exit 0 / test result: ok
and report the count as ~N at v0.4.0.
- Running from a subcrate. Outside the repo root,
rust-toolchain.toml
is not picked up, so local fmt/clippy can drift from CI's 1.96.0 and
give false greens or reds. Always run from the root.
- Treating a skipped integration gate as a failure. No Postgres / no
.env means SKIP, not FAIL. Only test result: FAILED. on a run that
actually executed is a real failure.
- Dropping
--all-targets from clippy. Without it, lints in test and
example code are missed, so local clippy passes while CI fails. Match
CI's --workspace --all-targets -- -D warnings exactly.
- Treating this as a CI replacement. This is a local early-warning
gate. The authority remains
.github/workflows/ci.yml; a green local
run does not exempt a PR from CI.
- Forgetting to source
.env before the integration gate. A
.env-loading gotcha is documented in docs/OBSERVATIONS.md; export
the file (set -a && . ./.env && set +a) so MEMEX_TEST_PG_URL reaches
the test process.
Related Skills
memex — the umbrella skill for agent-native shared memory; this gate
guards commits made within its workflow.memex-wrap — session-close ritual; run memex-verify as its pre-commit
gate before the wrap commits.memex-init — session-start ritual that pairs with this close-side gate.commit-changes — the next step once all required gates pass.