feat(core): add inspect query retrieval execution trace - #1250
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8a849d955f
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
8a849d9 to
c8ccf63
Compare
phernandez
left a comment
phernandez
left a comment
There was a problem hiding this comment.
Reviewed the --show-ids amendment (8a849d95 → c8ccf630). Verified locally: 27
inspect/trace tests pass, lint + typecheck clean. Assessment:
Right design, cleanly executed. The change is rendering-only — type-qualified row IDs
were always present in the JSON contract, so surfacing them in human output required no
schema or API change, preserving the single-machine-contract invariant. --show-ids
follows the --show-misses render-only pattern exactly (accepted-but-inert under
--json, where IDs are already complete), and the type:id format matches the trace's
own key representation.
Two observations, neither blocking:
- The amendment also adds entity permalinks under result titles unconditionally (no
flag) in both rich and plain output. It's a good call — results become directly
copy-pasteable intobm inspect chunks— but it's beyond the literal "ids as optional
arg" scope, so flagging for awareness. Plain output'spermalink=prefix keeps it
greppable. - Permalinks render only for
type == "entity"rows; observation/relation rows have
synthetic permalinks too but stay ID-only. Reads as deliberate noise reduction — with
--show-idsevery row type gets its identity — andinspect chunksoutput already
leads withtype:idheaders, so the two commands stay consistent.
Test coverage is properly two-sided: the flag's presence asserted in rich/plain/JSON
paths, and its absence asserted in the no-flag plain case. Good to merge with the stack.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c8ccf630c9
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 64a81a28b1
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
64a81a2 to
90c95b3
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 90c95b338c
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
90c95b3 to
5582c5f
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5582c5f9ea
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
5582c5f to
d552e70
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d552e706cc
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
d552e70 to
63e2058
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 63e2058e84
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
63e2058 to
06bff0e
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 06bff0e3e6
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
06bff0e to
6c59769
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6c597695e5
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
6c59769 to
4d3cb59
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4d3cb5955c
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
4d3cb59 to
b6be274
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b6be274b79
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
b6be274 to
2a07c8d
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2a07c8d95e
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
1dd1dc3 to
1ac1d1a
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1ac1d1af9f
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
1ac1d1a to
af6b473
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: af6b4739eb
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
af6b473 to
26bf0bc
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 26bf0bc64f
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
26bf0bc to
cbbe5f8
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cbbe5f8fde
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
cbbe5f8 to
6d97b86
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6d97b86f88
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
6d97b86 to
055b9a2
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 055b9a2d64
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
055b9a2 to
3329041
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3329041db9
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
3329041 to
70b7e67
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 70b7e678d2
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
70b7e67 to
1a558ef
Compare
Signed-off-by: phernandez <paul@basicmachines.co>
1a558ef to
75f67b2
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 75f67b212f
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Signed-off-by: phernandez <paul@basicmachines.co>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 25034856ea
ℹ️ 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".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Signed-off-by: phernandez <paul@basicmachines.co>
1 participant
Why
Search returns ranked results without exposing how FTS, vector retrieval, fusion,
hydration, filtering, and reranking produced them. That makes score and index-readiness
problems difficult to diagnose without recreating retrieval work that can diverge from
the execution being explained.
This PR adds an opt-in execution trace captured by the same search call that returns the
results. It completes the v0.23 retrieval-inspector scope from #1155 without changing the
ordinary search response or the MCP
search_notescontract. It now targetsmaindirectly after the note-level chunk inspector from #1249 merged.
What Changed
SearchTraceCollectorand frozen, per-mode trace unions for FTS, vector, andhybrid retrieval.
threshold/filter/missing-row rejection, normalized FTS scores, fusion, reranking, and
the final page window.
POST /v2/projects/{id}/inspect/queryand the corresponding typed client call.bm inspect query "<query>"with rich, plain, JSON, and auto-JSON output.--show-misses; JSON always includesevery captured candidate and remains the stable machine-readable schema.
--show-idsoptionally addstype-qualified search-index trace keys such as
entity:1,relation:4, andobservation:9; it does not alter JSON.batches large hydration-drop classifications, scopes stale external-index evidence by
entity owner, and records FTS-only duration on SQLite and Postgres.
Implementation Details
reconstruct an explanation, and nested stable-pool retrieval is deliberately excluded
from the visible candidate trace.
FtsQueryTrace | VectorQueryTrace | HybridQueryTraceunion at the service boundary.Finalization fails fast when a required stage is missing.
keys, similarities, bounded rejection details, and stored/configured identities.
by the trace; trace construction itself remains database-free.
trace is not Nonechecks and keywordforwarding. Trace-only readiness and drop-classification SQL executes strictly under
those guards.
SearchResultscorereplacement, plus post-rerank movement and tail-demotion behavior.
main; feat(cli): add inspect chunks note-level retrieval view #1249'salready-landed chunk-inspector commit is no longer duplicated in this PR.
Testing
Automated
BASIC_MEMORY_ENV=test uv run pytest tests/repository/test_search_trace.py tests/repository/test_chunk_inspection.py tests/api/v2/test_inspect_router.py tests/cli/test_inspect_command.py -q --no-cov— 92 passed, 1 skipped.
BASIC_MEMORY_TEST_POSTGRES=1 BASIC_MEMORY_ENV=test uv run pytest tests/repository/test_search_trace.py -q --no-cov— 23 passed.
BASIC_MEMORY_ENV=test uv run pytest tests/api/v2/ tests/cli/ -q --no-cov— 950 passed.
just fast-check— passed (Ruff fix/format andtytype checking).git range-diffconfirmed the query-trace commit was preserved across the base rewrite;git diff --checkandgit merge-base --is-ancestor origin/main HEADpassed.Risks / Follow-ups
unchanged.
an exhaustive scan of the corpus.
planned.
Closes #1155 for the v0.23 Phase 1+2 scope.