swap-document-search
Change how the assistant retrieves passages (a dedicated vector database, hybrid keyword and vector search, a search service). Use when the user decides retrieval must scale past Postgres or needs ran
Files1
View on GitHubSKILL.md.claude/skills/swap-document-search/SKILL.md
GitHubSwap document search
- Interface:
PassageSearch(search(org_id, query, limit) -> list[Passage]) inapps/ai/app/assistant.py: all the assistant'ssearch_documentstool needs. - Today:
Documents.searchinapps/ai/app/documents.py: embeds the query and runs a cosine nearest-neighbour query overai.chunk(pgvector, HNSW), scoped to the organization by row-level security (tenant(org_id)). The evals use an in-memory library (apps/ai/evals/library.py); the MCP server (apps/ai/app/mcp_server.py) searches through the sameDocuments. - Env:
AI_EMBEDDINGS,AI_MIN_RELEVANCE(see swap-embeddings).
Only the query side is behind the interface. Indexing (chunks and vectors written by
the worker) and deletion live in Documents too.
Swap
- Implement the new store in
Documents: write passages and vectors where indexing writesDocumentChunktoday, delete them with the document, and query them insearch. Every query must filter by organization: an external store has no row-level security, so the org id goes in every filter. - Keep returning
Passagewith a similarityscore, and keep the relevance floor, so the assistant and MCP tool don't change. - The store's address and key in
apps/ai/app/settings.py,.env.exampleanddocs/environment.md.
Tests
apps/ai/tests/test_service.py covers indexing, retrieval and tenancy; add a case that
one organization can't retrieve another's passages from the new store. Compare quality
with bun run --cwd apps/ai evals.
Finish
- The verify skill.
- Ask the
revieweragent to review the change, and thesecurity-revieweragent: a new implementation brings its own credentials and sends data somewhere new. If you wrote a migration, themigration-revieweragent too. The change is in apps/ai, so thepython-revieweragent as well. - Update the seam's row in the README's "Scaling path" table if what's "Now" changed.