Skip to content

perf(api): run scoped search's post-search reads on one session, add Server-Timing - #2119

Merged
groksrc merged 2 commits into
mainfrom
shipright/BMEM-150
Nov 15, 2026
Merged

groksrc merged 2 commits into
mainfrom
shipright/BMEM-150

Conversation

@groksrc

@groksrc groksrc commented Nov 15, 2026

Copy link
Copy Markdown
Member

Summary

The database-scoped search route (QUERY /v2/search/) now runs every read after the search on one database session, so a search that returns hits opens two sessions instead of four. The response also gains a Server-Timing header with each step's time. The aim is to cut connection checkouts and transactions per search on remote (Postgres) databases, and to show which step is slow without needing tracing access.

What changed

  • search_scope (src/basic_memory/api/v2/routers/scoped_search_router.py) opens one db.scoped_session after the search. Project external IDs, valid-time metadata (when the query asks for it), entity hydration and the semantic-index freshness check all run on it, one after another. Nothing runs concurrently, so a small connection pool never makes a read wait behind another request.
  • ScopedSearchService.get_entities_by_id and semantic_index_current_as_of take an optional caller-owned session, the way include_legacy_note_type_spellings already does. With no session passed they behave exactly as before.
  • The search itself keeps its own session. Its SearchReader is shared with the per-project search route, and that route is unchanged.
  • New header, in this order: Server-Timing: search;dur=<ms>, hydrate;dur=<ms>, freshness;dur=<ms>, each value to one decimal place. hydrate covers project IDs, temporal metadata and entity hydration. Every entry is present even when its step reads nothing, including searches with no hits.
  • Response bodies are unchanged.

Tests

  • New: a route test counts pool checkouts during one scoped search with hits, temporal metadata and stale embeddings, and asserts 2. Against the previous route it fails with assert 4 == 2.
  • New: a route test checks the header's entries and their order, for a search with hits and one without.
  • New: unit tests call get_entities_by_id and semantic_index_current_as_of with and without a caller's session.
  • Run locally, unchanged existing tests included:
    • SQLite: tests/api/v2/test_scoped_search_router.py and tests/repository/test_semantic_index_freshness.py, 60 passed.
    • Postgres: those two files plus tests/api/v2/test_search_semantic_freshness.py and tests/api/v2/test_search_hydration.py, 76 passed and 1 skipped.
  • ruff check, ruff format --check and pyright pass on the changed files. CI's test.yml runs the full matrix.

Risks

  • One connection is held through hydration and the freshness check. That is still less total checkout time than the three separate sessions it replaces.
  • The header holds step durations only, no data.
  • Rollback: revert this PR.

Board ticket: BMEM-150.

🤖 Generated with Claude Code

…Server-Timing

The database-scoped search route (QUERY /v2/search/) opened four database
sessions for one search: the search, project identities and valid time,
entity hydration, and the semantic-index freshness check. Each one checks
out a pooled connection and runs its own transaction, which costs round
trips on a remote database.

Every read after the search now runs on one session, so a search with hits
opens two sessions instead of four. ScopedSearchService.get_entities_by_id
and semantic_index_current_as_of take an optional caller-owned session;
callers that pass none behave as before, so the per-project route is
unchanged. The search keeps its own session because its reader is shared
with that route.

The response also carries a Server-Timing header with the time of each
step: search, hydrate and freshness.

BMEM-150

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-15T06:26:04.454633Z fc8a55c PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

I, Drew Cain <groksrc@gmail.com>, hereby add my Signed-off-by to this commit: fc8a55c

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Drew Cain <groksrc@gmail.com>

@groksrc groksrc left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No blocking findings.

I reviewed head fbc6b72 against the scoped-search acceptance criteria. The route keeps the search session separate, then runs project identity, temporal metadata, entity hydration, and semantic-index freshness reads on one caller-owned session. The optional session parameters preserve the existing lifecycle when callers pass no session. The response adds search, hydrate, and freshness Server-Timing entries in the required order without changing its body.

The regression tests cover two connection checkouts for a search with hits, headers for searches with and without hits, and both caller-owned and internally owned session paths. The timing header exposes only durations, so it does not disclose search data.

Verification:

  • uv run pytest tests/api/v2/test_scoped_search_router.py tests/repository/test_semantic_index_freshness.py -q: 60 passed in 271.41 seconds.
  • GitHub reports all 42 checks green at fbc6b72, including SQLite, PostgreSQL, semantic search, static checks, CodeQL, coverage, Developer Certificate of Origin, and the contributor license agreement.
  • git diff --check reports no whitespace errors.

Next step: Shipright can treat this pull request as review:done and continue its pipeline.

@groksrc groksrc added the review:done Automated review found no blocking issues label Nov 15, 2026
@groksrc
groksrc merged commit f51393e into main Nov 15, 2026
43 checks passed
@groksrc
groksrc deleted the shipright/BMEM-150 branch November 15, 2026 07:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:done Automated review found no blocking issues

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant