Vector memory and bring-your-own embedding key

Status: on by default (org entitlement agentKnowledge.vector, needs agentKnowledge.enabled and ai.enabled). No new route, MCP tool or key family: with it on, agent knowledge search ranks by words AND meaning; without what it needs, search falls back to word ranking and says why.

What changes for a caller

• GET /v1/orgs/{orgId}/agent-knowledge?q=... and MCP memory_search add ranking and semantic: { applied, notice, pendingRows } (pgvector, reciprocal-rank fusion of words and meaning).
• GET /v1/orgs/{orgId}/agent-knowledge/status adds semantic: { enabled, available, model, notice, coverage }.
• Results are still only rows the caller could read by text. A query holding a credential shape is never embedded (notice: secret_in_query).
• A cursor (after=) or a match other than all forces word ranking (word_ranking_requested).

Who pays for embeddings

apps/api/src/lib/ai-byok-gate.ts decides once per org:

Answer	Who	Embeddings
platform	existing orgs, the internal plan, orgs with an AI allowance	made with the platform credential, metered in ai_usage
byok	an org created at or after BILLING_GRANDFATHER_CUTOFF, not internal, with 0 AI tokens, that stored its own OpenRouter key	made with the org's key (openai/text-embedding-3-small, 768 dims), not charged to ai_usage
blocked	the same kind of new org without a key	nothing is sent to any provider; text ranking with notice: embedding_key_required

The same gate decides the issue-embedding backfill.

Notices you may see

pgvector_unavailable (the database has no vector extension yet), embedding_key_required, secret_in_query, word_ranking_requested. Each means "ranked by words only"; never tell a person meaning-based search ran when semantic.applied is false.

Reference

• API reference: /orgs/{orgId}/agent-knowledge and /orgs/{orgId}/agent-knowledge/status in /v1/openapi.json (tag agent-memory); the backfill POST /v1/cron/backfill-knowledge-embeddings is a cron route, not an integration surface.
• MCP tools: memory_search (its description says when meaning-based ranking is on), see the MCP tool reference.
• Design: vector memory (sections 5a, 8, 9).