Summary

Closes the documented debounce gap from PR #536. mm index gains three flags backed by a file-system-backed debounce queue under ~/.memtomem/index_debounce_queue.json (sidecar-lockfile-protected):

• --debounce-window <SECONDS> — record PATH in the queue and drain entries silent ≥ SECONDS. Designed for PostToolUse[Write] hook callers; rapid consecutive writes to the same file restart the window so a codegen burst is indexed once at the end.
• --flush — synchronously drain every queued entry. Blocks until each file is indexed (or recorded as an error). Worst-case latency ≈ queue depth × per-file index cost. The plugin's Stop hook now chains mm index --flush before mm session end --auto.
• --status — snapshot of the queue (depth, oldest entry). Race-prone by design (no lock); concurrent hooks may modify the queue between the read and any caller action. Use as telemetry only — --flush is the only correctness primitive for "drain the queue".

The three flags are mutually exclusive with each other and with the plain mm index <path> invocation.

Concurrency model

The queue file is replaced atomically via os.replace on every mutation. Locking the queue file directly would disconnect the lock from the file mid-mutation (the OS keeps the locked inode alive after replace, but later openers see a different inode). The lock is therefore on a sidecar ~/.memtomem/.index_debounce_queue.json.lock — never replaced, so all writers serialize on the same inode. Verified by test_concurrent_enqueue_does_not_lose_entries (20 parallel threads, all entries persisted).

Indexer errors keep entries in the queue for retry on the next hook fire — failing files are not silently lost. Last-write-wins for --namespace/--force when the same path is enqueued twice.

RFC-B (PreCompact, deferred) — future-extensibility reserved

When the PreCompact hook contract lands and a checkpoint handler wants to flush only the files Claude Code reports as in-flight, --flush will gain a --paths <list> form. The underlying debounce.drain_all already accepts an optional paths= filter (test_paths_filter_drains_subset_only pins this) so the CLI addition is additive — no second ABI change. CHANGELOG and claude-code.md Caveats both call this out so a future RFC-B reviewer doesn't have to rediscover the extension shape.

Plugin + docs sync

packages/memtomem-claude-plugin/hooks/hooks.json and docs/guides/integrations/claude-code.md Hooks Automation Setup are updated byte-for-byte (TestPluginHooksDocsParity from #536 catches drift):

• PostToolUse[Write] → mm index --debounce-window 5 "$FP"
• Stop → mm index --flush; mm session end --auto (timeout bumped 5000 → 10000 ms to accommodate flush worst-case latency)
• "Important Caveats" — old "Debounce gap" caveat (pointed at native debounce as future work) replaced with "Debounce mechanics" caveat covering queue file, window-restart semantics, Stop-hook flush chain, --status race, and RFC-B extension shape.

Test plan

• uv run pytest packages/memtomem/tests/test_index_debounce.py -m "not ollama" — 19 new tests pass (enqueue semantics, drain-ready/drain-all, status snapshot, 20-thread concurrency, partial-drain retry).
• uv run pytest packages/memtomem/tests -m "not ollama" — 3147 pass, 0 fail (no regressions; TestPluginHooksDocsParity enforces docs↔plugin parity).
• uv run ruff check && uv run ruff format --check && uv run mypy — all clean (mypy advisory, no new errors).
• Manual: mm index --debounce-window 5 /tmp/test.md queues; second call within 5s updates last_seen; third call after 5s drains. mm index --status prints queue depth. mm index --flush drains synchronously.

Open questions for review

• Reviewer: confirm 5-second window default in the plugin recipe is sane for typical codegen burst spacing; lower (1-2s) catches less, higher (10s) delays too much
• Reviewer: confirm sidecar-lockfile pattern over named-pipe / SQLite-WAL alternatives — the existing codebase uses fcntl.flock for _liveness.py so this is consistent
• Reviewer: confirm Stop-hook timeout bump 5000 → 10000 ms is enough for flush worst-case (a burst of 20 files at ~250ms each = 5s; the bump leaves headroom but isn't unbounded)

🤖 Generated with Claude Code