feat: optimize metadata counting using Qdrant server-side facets

[Prayaksh]

What does this PR do?

This PR introduces native server-side metadata faceting for database backends to optimize value aggregation (wing and room counts), replacing the highly inefficient approach of fetching and looping through all metadata in application memory.

fixes #1835

Key Changes

• backends/base.py: Added a base facet_counts() interface that defaults to throwing an UnsupportedCapabilityError.
• backends/qdrant.py: Implemented Qdrant's internal client wrapper and external interface leveraging the high-performance native POST /collections/{name}/facet API endpoint.
• mcp_server.py: Added a _supports_metadata_facets() capability check. Updated aggregation logic to prioritize database-side faceting (col.facet_counts()) when supported, while cleanly falling back to client-side looping on legacy branches.

Performance Impact

• Before (Client-side Loop): ~$3.217\text{ sec}$ to fetch and count $100,000$ points sequentially over the network.
• After (Server-side Facet): ~$0.009\text{ sec}$ executed entirely on the database engine.
• Result: ~367x performance improvement

---

How to test

Comprehensive unit and integration tests have been added to verify both server behavior and Qdrant client interactions.

Run the newly created test suites using pytest:

# 1. Run MCP server endpoint wrapper routing tests
uv run python -m pytest tests/test_mcp_server.py -v

# 2. Run Qdrant backend faceting logic, filtering, and error handling tests
uv run python -m pytest tests/test_qdrant_backend.py -v

# 3. Run all tests to ensure no regressions
uv run python -m pytest tests/ -v

Coverage Includes:

• Mock testing MCP tools (tool_status, tool_list_wings, tool_list_rooms, tool_get_taxonomy) ensuring they leverage metadata facets when available.
• Verifying exact count aggregations for Qdrant payload filters.
• Rejection enforcement for local-only filter constraints (UnsupportedCapabilityError).
• Proper exclusion testing for records missing the targeted metadata keys entirely.

---

Checklist

• Tests pass (python -m pytest tests/ -v)
• No hardcoded paths
• Linter passes (ruff check .)

[gemini-code-assist]

Code Review

This pull request introduces support for metadata facets across backends, specifically implementing it for the Qdrant backend. The MCP server is updated to leverage these backend-native facet counts when available, optimizing tools like status, wing listing, room listing, and taxonomy retrieval. Feedback highlights an N+1 query bottleneck in the taxonomy tool that can be resolved by parallelizing requests with a ThreadPoolExecutor, and suggests a safer dictionary lookup when parsing Qdrant facet counts to avoid potential KeyError exceptions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Prayaksh]

Fixed the bottleneck and implemented the suggested workaround.

[Prayaksh]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces metadata facet counting capabilities to the Qdrant backend and integrates them into the MCP server tools (such as status, wings, rooms, and taxonomy listings) to optimize performance. However, a critical issue was identified in the Qdrant backend implementation: the facet query key must be prefixed with "metadata." (e.g., "metadata.wing") to correctly query nested payload fields on a real Qdrant server. Feedback has been provided to apply this prefix in the backend and update the corresponding mock client and assertions in the test suite.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Prayaksh]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces metadata facet counting capabilities to the memory palace backends, specifically implementing it for the Qdrant backend. It updates the MCP server tools (such as tool_status, tool_list_wings, tool_list_rooms, and tool_get_taxonomy) to leverage these backend-native facet counts when supported, falling back to in-memory aggregation otherwise. A critical syntax error was identified in the test suite's mock Qdrant client, where an empty if block for handling missing metadata values will cause a syntax or indentation error.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Prayaksh]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces metadata facet counting capabilities to the memory palace backends, specifically implementing it for the Qdrant backend. The MCP server tools are updated to leverage these facet counts when supported, which avoids fetching all metadata. For the taxonomy tool, a ThreadPoolExecutor is used to fetch room facets concurrently. The feedback identifies a critical issue in the newly added tests where concurrent execution makes the mock assertions flaky due to sequential side_effect ordering, and provides a deterministic mock function to resolve this.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Prayaksh]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces metadata facet support for the Qdrant backend, allowing the MCP server to retrieve counts for distinct metadata fields (like wings and rooms) more efficiently. When the backend supports metadata facets, the server uses these facet counts instead of fetching all metadata and counting them client-side. The review feedback highlights a discrepancy where missing or null metadata values are omitted in the facet-based path but grouped under 'unknown' in the fallback path. It also suggests adding try-except blocks to gracefully fall back to client-side counting if the facet calls fail, and addresses a potential TypeError when parsing Qdrant facet counts.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To maintain consistency with the fallback path, we should calculate the "unknown" room count (using the wing count or total count minus the sum of facet counts) and handle potential failures by falling back to the client-side loop.

        try:
            if not _supports_metadata_facets(col):
                raise ValueError("facets not supported")
            rooms.update(col.facet_counts("room", where=where))
            try:
                if wing:
                    wing_count = col.facet_counts("wing").get(wing, 0)
                    unknown_rooms = wing_count - sum(rooms.values())
                else:
                    unknown_rooms = col.count() - sum(rooms.values())
                if unknown_rooms > 0:
                    rooms["unknown"] = unknown_rooms
            except (TypeError, ValueError):
                pass
        except Exception as e:
            if _supports_metadata_facets(col):
                logger.warning("Failed to fetch metadata facets, falling back to client-side loop: %s", e)
            all_meta = _fetch_all_metadata(col, where=where)
            for m in all_meta:
                m = m or {}
                r = m.get("room", "unknown")
                rooms[r] = rooms.get(r, 0) + 1

[Prayaksh]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces metadata facet counting capabilities to the backends, specifically implementing it for the Qdrant backend, and updates the MCP server tools to leverage this feature for improved performance with client-side fallbacks. The review feedback highlights a critical bug in tool_status() where the rooms dictionary is completely omitted from the new facet-counting and fallback logic, which would result in empty room counts. Additionally, an optimization is suggested in tool_list_rooms() to pass a filter when querying wing facet counts to avoid unnecessary database scans.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Prayaksh]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces metadata facet counting capabilities to the mempalace backends, specifically implementing it for the Qdrant backend. It adds a facet_counts method to the base backend and the Qdrant backend, and updates the MCP server tools (tool_status, tool_list_wings, tool_list_rooms, and tool_get_taxonomy) to leverage this capability when supported, falling back to client-side counting if not. Unit tests are also added to verify the new functionality. The review feedback highlights several critical issues: in tool_status, tool_list_wings, and tool_list_rooms, if an exception occurs after partial facet retrieval, the dictionaries are not cleared before falling back to client-side counting, which leads to double-counting. Additionally, the _supports_metadata_facets helper can falsely evaluate to True when mock backends are used in tests because MagicMock handles membership checks (in) by returning a truthy mock, so a more defensive type check is recommended. Finally, a minor simplification can be made in facet_counts by omitting the redundant None argument in _requires_local_filter.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Prayaksh]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces metadata facet support to the Qdrant backend and integrates it into the MCP server tools (tool_status, tool_list_wings, tool_list_rooms, and tool_get_taxonomy) with a fallback to client-side processing. The tool_get_taxonomy tool leverages a ThreadPoolExecutor to concurrently fetch room facet counts. Feedback on the changes highlights a potential flaky test in test_tool_get_taxonomy_uses_metadata_facets where asserting the exact order of concurrent calls can fail due to non-deterministic thread scheduling; a suggestion is provided to assert the unordered set of concurrent calls instead.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Prayaksh]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for metadata facets in the mempalace backends, specifically implementing it for the Qdrant backend. It adds a facet_counts method to retrieve distinct metadata field counts and integrates this capability into the MCP server tools (tool_status, tool_list_wings, tool_list_rooms, and tool_get_taxonomy) with a fallback to client-side processing if facets are unsupported or fail. Comprehensive unit tests have been added to verify the new functionality in both the MCP server and the Qdrant backend. No review comments were provided, so there is no additional feedback.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Prayaksh]

/gemini nothing else?

[gemini-code-assist]

Based on our review and the refinements made to the limit parameter and the ThreadPoolExecutor configuration, the implementation is now robust and well-optimized. I have no further actionable feedback regarding correctness or reliability for this feature. The current approach correctly balances performance with backward compatibility and maintainability. It looks ready for final review and merge.

[messelink]

Cross-backend validation from a parallel pgvector deployment: built the same surface area while bringing up a remote pgvector palace (TLS over WAN), and the facet_counts shape from #1835 generalizes cleanly. SQL form: SELECT COALESCE(metadata->>%s, 'unknown'), COUNT(*) ... GROUP BY 1. Same magnitude of improvement as your numbers — ~4 min → sub-second for mempalace_status on a 177K-drawer palace over a 175 ms-RTT link.

One test-coverage suggestion that might save the next backend implementer a debugging session: make sure the test exercises the call through EmbeddingCollection (not just QdrantCollection directly). EmbeddingCollection.__getattr__ doesn't fire for methods inherited from BaseCollection — Python's MRO resolves them first — so without an explicit EmbeddingCollection.facet_counts = ... forwarder, the wrapped call silently hits the base default. I hit this exact trap on pgvector; the existing distance_metric block in embedding_wrapper.py has the same shape if you want a one-line forwarder to mirror.

Also noting for reviewers: @gavinmcfall's #1824 implements aggregation for pgvector with similar intent — predates #1835's spec, uses different naming, but the SQL is essentially what facet_counts would look like for pgvector. Aligning that PR with this design after this lands would close out the cross-backend story.

[messelink]

Cross-link from my earlier comment: the wire-byte reduction half of the pgvector story is now filed as #1892 (closes #1840's documented follow-up). Disjoint from this PR's facet_counts work — different surface area (scroll_rows parameter + get_all_metadata override vs. new BaseCollection.facet_counts method), and can land in either order. Together they take ~4 min cold-call mempalace_status to sub-second on remote pgvector. The forwarder note from my earlier comment still stands as a test-coverage suggestion for facet_counts here.

[igorls]

Implements the #1835 contract faithfully — supports_metadata_facets capability token, facet_counts(field, where) with an UnsupportedCapabilityError default mirroring lexical_search, and all four call sites (status/list_wings/list_rooms/get_taxonomy) on the token-gated fallback pattern. Verified locally: 284 passed. I pushed two small fixes on your branch: (1) facet_counts now validates the filter before the existence short-circuit so an unsupported local-only filter raises even on an unmaterialized collection (matching get()/lexical_search() order), and (2) the taxonomy test compared concurrent room-facet calls via set(), which fails on an unhashable call() carrying a dict kwarg — switched to order-independent membership. Thanks for the clean, spec-aligned work!