docs: polish sweep — fix stale docstrings, dead paths, PyPI-visible links (closes #21, #22, #23, #24, #25, #26, #27, #15)

Hunter Bundle E. 8 findings that mostly didn't affect runtime but
degraded the first-read experience — wrong tier copy, broken links on
PyPI, stale PNG duplicates, gitignored paths cited as sources.

- F12 (#21): vector_search.py module docstring rewritten — acknowledges
  tier-aware embedder resolution (Model2Vec / Qwen3 per tier), not the
  v0.3.0 Model2Vec-only framing. Adds sentence-transformers to Dependencies.
- F13 (#22): bench_truememory_base.py header — was copy-pasted from Pro
  and still said "Pro Tier (+HyDE)". Rewritten to describe Base (Qwen3 +
  gte-reranker, HyDE off, 91.5%). Usage examples now reference the right
  script name.
- F14 (#23): category-heatmap.png deleted — was byte-identical to
  category-grouped-bars.png (MD5 f00c08...). Only live reference was to
  grouped-bars; heatmap filename was dead (CHANGELOG historical mention only).
- F15 (#24): README v0.3.0-chart caveat moved above the first benchmark
  chart (was after all three). Option 2 interim per the finding — chart
  regeneration (Option 1) is a separate deferred task.
- F16 (#25): BENCHMARK_RESULTS.md no longer cites gitignored
  `_working/benchmarks_56combo/...` paths as authoritative. The aggregate
  numbers in the table are the canonical reference; the Modal scripts
  reproduce them.
- F17 (#26): 8 relative text links in README rewritten to absolute
  github.com/.../blob/main/... URLs. PyPI's markdown renderer doesn't
  rewrite relative paths, so the links 404'd on the package page for
  install.sh, CLAUDE.md.example, LICENSE, and four benchmarks/* refs.
- F18 (#27): `_nm_format_ctx` / `_nm_make_hyde_fn` renamed to `_tm_*` in
  the four bench scripts (bench_truememory_{edge,base,pro}.py,
  modal_benchmark.py) — stray neuromem-namespace helpers from pre-rebrand.
  Purely cosmetic; scripts are ship-in-sdist so the brand leak was visible.
- F40 (#15): documented `--help` precedence over `--setup` (Unix
  convention — docs-emitting flags short-circuit side-effects) with an
  inline comment in mcp_server.main and a regression-lock test in
  test_cli_help.py.

pytest 197 passed / 1 skipped (baseline 196 + 1 new F40 test).
ruff clean. Local `python -m build && twine check --strict` PASSED.

Author: buildingjoshbetter

README.md

@@ -29,6 +29,8 @@
 
 Tested on [LoCoMo](https://github.com/snap-research/locomo), the standard benchmark for conversational memory. 1,540 questions across 10 conversations. All 8 systems share the same answer model, judge, scoring, top-k, and byte-identical answer prompt — only retrieval differs.
 
+> **Note on charts:** the hero banner and the three charts below still show the v0.3.0 single-Pro-tier layout (91.5%). Chart regeneration is tracked for a later release; all numerical claims in the README text and tables reflect the v0.4.0 three-tier scores (90.1 / 91.5 / 91.8%).
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/assets/charts/leaderboard-bar.png?v=2" alt="LoCoMo 8-System Comparison" />
 </p>
@@ -39,7 +41,7 @@ TrueMemory achieves **state-of-the-art accuracy for fully-local memory systems**
   <img src="https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/assets/charts/accuracy-vs-cost.png?v=2" alt="Accuracy vs Infrastructure Cost" />
 </p>
 
-All scores use the same evaluation pipeline: GPT-4.1-mini answer generation, GPT-4o-mini judge (3x majority vote), temperature=0. Zero errors across 12,320 total answers. Scores use a lenient semantic-match judge; rankings are valid across all systems but absolute values are higher than published LoCoMo baselines using strict exact-match. [Full methodology](benchmarks/locomo/BENCHMARK_RESULTS.md) and reproduction scripts in [`benchmarks/`](benchmarks/locomo/).
+All scores use the same evaluation pipeline: GPT-4.1-mini answer generation, GPT-4o-mini judge (3x majority vote), temperature=0. Zero errors across 12,320 total answers. Scores use a lenient semantic-match judge; rankings are valid across all systems but absolute values are higher than published LoCoMo baselines using strict exact-match. [Full methodology](https://github.com/buildingjoshbetter/TrueMemory/blob/main/benchmarks/locomo/BENCHMARK_RESULTS.md) and reproduction scripts in [`benchmarks/`](https://github.com/buildingjoshbetter/TrueMemory/blob/main/benchmarks/locomo/).
 
 ---
 
@@ -57,8 +59,6 @@ All scores use the same evaluation pipeline: GPT-4.1-mini answer generation, GPT
 
 TrueMemory Pro nearly matches EverMemOS across all 4 question categories. Mem0 collapses on multi-hop reasoning (37.7% vs 90.7%).
 
-> The hero banner and charts in this README still show the v0.3.0 single-Pro-tier layout (91.5%). Chart regeneration is tracked for a later release; all numerical claims in the README text and tables reflect the v0.4.0 three-tier scores above.
-
 ---
 
 ## 🏗️ Edge / Base / Pro
@@ -101,7 +101,7 @@ curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/
 
 > **What this actually does:** installs [uv](https://docs.astral.sh/uv/) (Astral's Python tool manager) if needed, fetches a managed Python 3.12 into `~/.local/share/uv/`, installs TrueMemory into an isolated tool environment, and auto-configures Claude Code and Claude Desktop. **Your system Python is never touched.** No sudo, no venvs, no pip struggle. Uninstall cleanly with `uv tool uninstall truememory`.
 
-> **Want to audit the script first?** It's ~140 lines of shell, no sudo, stays entirely under `$HOME`. Read the source at [`install.sh`](install.sh), or download and inspect locally: `curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.sh -o install.sh && less install.sh && sh install.sh`.
+> **Want to audit the script first?** It's ~140 lines of shell, no sudo, stays entirely under `$HOME`. Read the source at [`install.sh`](https://github.com/buildingjoshbetter/TrueMemory/blob/main/install.sh), or download and inspect locally: `curl -LsSf https://raw.githubusercontent.com/buildingjoshbetter/TrueMemory/main/install.sh -o install.sh && less install.sh && sh install.sh`.
 
 > **Want Base or Pro (adds Qwen3 embeddings + gte-reranker + sentence-transformers, ~1.5-2.5GB depending on OS)?**
 > ```bash
@@ -149,7 +149,7 @@ After setup, TrueMemory runs automatically. It stores what you tell it and recal
 
 ### Make it automatic (optional)
 
-Copy [`CLAUDE.md.example`](CLAUDE.md.example) to your home directory as `CLAUDE.md`. This tells Claude to store your preferences and recall them without being asked:
+Copy [`CLAUDE.md.example`](https://github.com/buildingjoshbetter/TrueMemory/blob/main/CLAUDE.md.example) to your home directory as `CLAUDE.md`. This tells Claude to store your preferences and recall them without being asked:
 
 ```bash
 cp CLAUDE.md.example ~/CLAUDE.md
@@ -214,9 +214,9 @@ uvx creates a cached environment on first run; subsequent spawns are fast. Good
 
 Every benchmark script is self-contained and runs on [Modal](https://modal.com).
 
-- **[Leaderboard & Reproduction](benchmarks/locomo/README.md)**: run any system yourself
-- **[Full Technical Report](benchmarks/locomo/BENCHMARK_RESULTS.md)**: per-category breakdowns, latency, cost, hardware
-- **[Evaluation Config](benchmarks/locomo/EVAL_CONFIG.md)**: exact models, prompts, parameters
+- **[Leaderboard & Reproduction](https://github.com/buildingjoshbetter/TrueMemory/blob/main/benchmarks/locomo/README.md)**: run any system yourself
+- **[Full Technical Report](https://github.com/buildingjoshbetter/TrueMemory/blob/main/benchmarks/locomo/BENCHMARK_RESULTS.md)**: per-category breakdowns, latency, cost, hardware
+- **[Evaluation Config](https://github.com/buildingjoshbetter/TrueMemory/blob/main/benchmarks/locomo/EVAL_CONFIG.md)**: exact models, prompts, parameters
 
 ---
 
@@ -237,4 +237,4 @@ Every benchmark script is self-contained and runs on [Modal](https://modal.com).
 
 ## ⚖️ License
 
-Licensed under [Apache 2.0](LICENSE). Free for personal and commercial use.
+Licensed under [Apache 2.0](https://github.com/buildingjoshbetter/TrueMemory/blob/main/LICENSE). Free for personal and commercial use.

assets/charts/category-heatmap.png

@@ -42,7 +42,7 @@ Question categories: **Cat 1** = single-hop, **Cat 2** = multi-hop, **Cat 3** =
 | Supermemory | 77.7% (219) | 64.5% (207) | 64.6% (62) | 61.7% (519) | 65.4% |
 | Mem0 | 78.0% (220) | 37.7% (121) | 74.0% (71) | 63.5% (534) | 61.4% |
 
-TrueMemory tier per-category numbers are sourced from the authoritative 56-grid sweep (`_working/benchmarks_56combo/results/` in the repo's working archive, files: `mini_b1_model2vec_miniml6_hyde_off_result.json` for Edge, `pro_qwen3_256d_gte_reranker_hyde_off_result.json` for Base, `qwen3_256d__gte_reranker_result.json` for Pro).
+TrueMemory tier per-category numbers are sourced from the authoritative 56-grid sweep. The raw result JSONs live in a gitignored working archive (not distributed with the package); the aggregate numbers in the table above are the canonical reference, and the Modal bench scripts in `benchmarks/locomo/scripts/` reproduce them end-to-end.
 
 ### Legacy v0.3.0 configurations (deprecated in v0.4.0)
 

benchmarks/locomo/BENCHMARK_RESULTS.md

@@ -1,10 +1,10 @@
 #!/usr/bin/env python3
 """
-LoCoMo Benchmark — TrueMemory Pro Tier (+HyDE, T4 GPU)
-======================================================
-TrueMemory Pro tier using Qwen3-Embedding-0.6B @ 256d Matryoshka embeddings,
-gte-reranker-modernbert-base (149M params) reranker, and HyDE (Hypothetical
-Document Embeddings) via OpenRouter LLM. Paper §2.0 target: 91.8%.
+LoCoMo Benchmark — TrueMemory Base Tier (default, HyDE off)
+===========================================================
+TrueMemory Base tier using Qwen3-Embedding-0.6B @ 256d Matryoshka embeddings
+and gte-reranker-modernbert-base (149M params) reranker. HyDE is OFF — Base
+is the fully-offline default tier, no LLM API calls. Paper §2.0 target: 91.5%.
 Requires a T4 GPU on Modal.
 
 This is a fully self-contained Modal script. No local imports required.
@@ -15,8 +15,8 @@
 Usage:
     modal secret create openrouter-key OPENROUTER_API_KEY=sk-or-...
 
-    modal run --detach bench_truememory_pro.py          # Full run (10 convs, 1540 Qs)
-    modal run --detach bench_truememory_pro.py --smoke  # Smoke test (1 conv, 5 Qs)
+    modal run --detach bench_truememory_base.py          # Full run (10 convs, 1540 Qs)
+    modal run --detach bench_truememory_base.py --smoke  # Smoke test (1 conv, 5 Qs)
 
     modal volume get locomo-results / ./results --force
 """
@@ -186,7 +186,7 @@ def fmsg(m): return f"[{m['timestamp']}] {m['speaker']} to {m['recipient']}: {m[
 
 # ── TrueMemory Context Formatting ─────────────────────────────────────────
 
-def _nm_format_ctx(results):
+def _tm_format_ctx(results):
     """Format TrueMemory results with metadata — matches v2 scripts exactly."""
     parts = []
     for r in results:
@@ -231,7 +231,7 @@ def retrieve_truememory_base(conv_data, conv_idx):
     for qa in get_qa(conv_data):
         sr = engine.search_agentic(qa["question"], limit=100,
                                    use_hyde=False, use_reranker=True)
-        ctx = _nm_format_ctx(sr)
+        ctx = _tm_format_ctx(sr)
         results.append((qa["question"], qa["category"], qa["answer"], ctx or "No results found."))
     engine.close()
     os.unlink(tmp_db)

benchmarks/locomo/scripts/bench_truememory_base.py

@@ -185,7 +185,7 @@ def fmsg(m): return f"[{m['timestamp']}] {m['speaker']} to {m['recipient']}: {m[
 
 # ── TrueMemory Context Formatting ─────────────────────────────────────────
 
-def _nm_format_ctx(results):
+def _tm_format_ctx(results):
     """Format TrueMemory results with metadata — matches v2 scripts exactly."""
     parts = []
     for r in results:
@@ -229,7 +229,7 @@ def retrieve_truememory_edge(conv_data, conv_idx):
     results = []
     for qa in get_qa(conv_data):
         sr = engine.search_agentic(qa["question"], limit=100, use_hyde=False, use_reranker=True)
-        ctx = _nm_format_ctx(sr)
+        ctx = _tm_format_ctx(sr)
         results.append((qa["question"], qa["category"], qa["answer"], ctx or "No results found."))
     engine.close()
     os.unlink(tmp_db)

benchmarks/locomo/scripts/bench_truememory_edge.py

@@ -186,7 +186,7 @@ def fmsg(m): return f"[{m['timestamp']}] {m['speaker']} to {m['recipient']}: {m[
 
 # ── TrueMemory Context Formatting ─────────────────────────────────────────
 
-def _nm_format_ctx(results):
+def _tm_format_ctx(results):
     """Format TrueMemory results with metadata — matches v2 scripts exactly."""
     parts = []
     for r in results:
@@ -202,7 +202,7 @@ def _nm_format_ctx(results):
         parts.append(f"{meta} {r['content']}")
     return "\n\n".join(parts)
 
-def _nm_make_hyde_fn():
+def _tm_make_hyde_fn():
     """Create HyDE LLM callable via OpenRouter — matches v2 scripts."""
     client = mkc()
     def _call(prompt):
@@ -221,7 +221,7 @@ def retrieve_truememory_pro(conv_data, conv_idx):
     from truememory.reranker import get_reranker
     import tempfile
     get_reranker(model_name="Alibaba-NLP/gte-reranker-modernbert-base")
-    llm_fn = _nm_make_hyde_fn()
+    llm_fn = _tm_make_hyde_fn()
     msgs = parse_conv(conv_data)
     _tmp_db_file = tempfile.NamedTemporaryFile(suffix=".db", prefix=f"pro_{conv_idx}_", delete=False)
     tmp_db = _tmp_db_file.name
@@ -242,7 +242,7 @@ def retrieve_truememory_pro(conv_data, conv_idx):
     for qa in get_qa(conv_data):
         sr = engine.search_agentic(qa["question"], limit=100, llm_fn=llm_fn,
                                    use_hyde=True, use_reranker=True)
-        ctx = _nm_format_ctx(sr)
+        ctx = _tm_format_ctx(sr)
         results.append((qa["question"], qa["category"], qa["answer"], ctx or "No results found."))
     engine.close()
     os.unlink(tmp_db)

benchmarks/locomo/scripts/bench_truememory_pro.py

@@ -377,7 +377,7 @@ def retrieve_supermemory(conv_data, conv_idx):
         results.append((qa["question"], qa["category"], qa["answer"], ctx or "No memories found."))
     return results
 
-def _nm_format_ctx(results):
+def _tm_format_ctx(results):
     """Format TrueMemory results with metadata — matches v2 scripts exactly."""
     parts = []
     for r in results:
@@ -393,7 +393,7 @@ def _nm_format_ctx(results):
         parts.append(f"{meta} {r['content']}")
     return "\n\n".join(parts)
 
-def _nm_make_hyde_fn():
+def _tm_make_hyde_fn():
     """Create HyDE LLM callable via OpenRouter — matches v2 scripts."""
     client = mkc()
     def _call(prompt):
@@ -429,7 +429,7 @@ def retrieve_truememory_base(conv_data, conv_idx):
     results = []
     for qa in get_qa(conv_data):
         sr = engine.search_agentic(qa["question"], limit=100, use_hyde=False, use_reranker=True)
-        ctx = _nm_format_ctx(sr)
+        ctx = _tm_format_ctx(sr)
         results.append((qa["question"], qa["category"], qa["answer"], ctx or "No results found."))
     engine.close()
     import os
@@ -447,7 +447,7 @@ def retrieve_truememory_pro(conv_data, conv_idx):
     from truememory.reranker import get_reranker
     import tempfile
     get_reranker(model_name="Alibaba-NLP/gte-reranker-modernbert-base")
-    llm_fn = _nm_make_hyde_fn()
+    llm_fn = _tm_make_hyde_fn()
     msgs = parse_conv(conv_data)
     _tmp_db_file = tempfile.NamedTemporaryFile(suffix=".db", prefix=f"pro_{conv_idx}_", delete=False)
     tmp_db = _tmp_db_file.name
@@ -468,7 +468,7 @@ def retrieve_truememory_pro(conv_data, conv_idx):
     for qa in get_qa(conv_data):
         sr = engine.search_agentic(qa["question"], limit=100, llm_fn=llm_fn,
                                    use_hyde=True, use_reranker=True)
-        ctx = _nm_format_ctx(sr)
+        ctx = _tm_format_ctx(sr)
         results.append((qa["question"], qa["category"], qa["answer"], ctx or "No results found."))
     engine.close()
     import os

benchmarks/locomo/scripts/modal_benchmark.py

@@ -45,6 +45,23 @@ def test_help_long_flag_exits_cleanly():
     assert "--version" in result.stdout
 
 
+def test_help_beats_setup_when_both_passed():
+    """Hunter F40 regression lock: `truememory-mcp --setup --help` must
+    print help and exit 0 WITHOUT running `_setup_claude`. This is the
+    conventional Unix precedence — docs-emitting flags short-circuit
+    side-effecting operations. Flipping this would be a CHANGELOG-worthy
+    behaviour change."""
+    result = _run_cli(["--setup", "--help"])
+    assert result.returncode == 0
+    assert result.stdout.lstrip().startswith("Usage: truememory-mcp"), (
+        f"expected help banner at start; got:\n{result.stdout}"
+    )
+    # `_setup_claude` prints distinctive markers not present in _HELP_TEXT.
+    assert "Manual setup:" not in result.stdout
+    assert "existing config preserved" not in result.stdout
+    assert "stale entry replaced" not in result.stdout
+
+
 def test_help_short_flag_exits_cleanly():
     """`truememory-mcp -h` must behave identically to --help."""
     result = _run_cli(["-h"])

tests/test_cli_help.py

@@ -1115,6 +1115,12 @@ def main():
 
     # Informational flags — these must return immediately, before mcp.run()
     # blocks on stdin or _preload_models() starts background threads.
+    #
+    # Hunter F40: if both `--help` and `--setup` are passed, `--help` wins
+    # (checked first, below). This is the conventional Unix posture —
+    # docs-emitting flags short-circuit any side-effecting operation — and
+    # is locked in by tests/test_cli_help.py. Flipping the precedence would
+    # be a behaviour change worth a CHANGELOG entry.
     if "--help" in argv or "-h" in argv:
         print(_HELP_TEXT)
         return 0

truememory/mcp_server.py

@@ -1,25 +1,36 @@
 """
 TrueMemory Vector Search
-======================
+========================
 
-Semantic search using Model2Vec (potion-base-8M, 256-dim) embeddings stored
-in a sqlite-vec virtual table.  Provides nearest-neighbor retrieval based on
-cosine distance so that queries like "networking problems" can surface results
-about ECONNREFUSED even when no keywords overlap.
+Tier-aware semantic search backed by a sqlite-vec virtual table. The
+embedding model is resolved from the active tier when :func:`get_model`
+is first called — the module itself imports cleanly with only cheap
+constants computed:
+
+    edge → Model2Vec potion-base-8M @ 256d (CPU, ~30MB)
+    base → Qwen3-Embedding-0.6B @ 256d Matryoshka (GPU recommended, ~1.5GB)
+    pro  → Qwen3-Embedding-0.6B @ 256d Matryoshka (GPU recommended, ~1.5GB)
+
+The active tier comes from the ``TRUEMEMORY_EMBED_MODEL`` env var
+(``edge`` / ``base`` / ``pro``) or ``~/.truememory/config.json``; MCP-server
+callers may also invoke :func:`set_embedding_model` at runtime. Cosine-
+distance nearest-neighbour search surfaces queries like "networking
+problems" against stored "ECONNREFUSED" messages without keyword overlap.
 
 Usage::
 
-    from truememory.storage import create_db, load_messages_from_file
+    from truememory.storage import create_db
     from truememory.vector_search import init_vec_table, build_vectors, search_vector
 
     conn = create_db("truememory.db")
-    load_messages_from_file(conn, "synthetic_v2_messages.json")
+    # ... insert messages ...
     init_vec_table(conn)
     build_vectors(conn)
     results = search_vector(conn, "networking problems", limit=5)
 
 Dependencies:
-    - model2vec (``pip install model2vec``)
+    - model2vec (``pip install model2vec``) — for the edge tier
+    - sentence-transformers (``pip install truememory[gpu]``) — for base / pro
     - sqlite-vec (``pip install sqlite-vec``)
     - numpy
 """