Hybrid Search

Postgram blends lexical and semantic retrieval so queries can match both exact terms and semantic intent.

What this page covers

This page explains the default ranking model, what happens when embeddings are unavailable, and practical search options for humans and agents.

Core workflow

1. Call search via REST:

curl -X POST http://127.0.0.1:3100/api/search \
  -H "Authorization: Bearer $PGM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"private knowledge graph", "limit":20}'

2. Or use CLI with optional filters:

pgm search "private knowledge graph" --type=memory --limit 20

3. Inspect edge summaries in compact results. Search output may include edges.count and edges.relations when matching entities have graph connections.

4. Expand graph context only when the user’s question needs connected context:

pgm search "pgvector" --expand-graph

5. For agent UIs, request compact output (--toon) or compact JSON when chaining results.

Notes

• Default blend is 60% vector and 40% BM25, with recency-aware score adjustments.
• Search requires a reachable embedding provider. Writes can still succeed when it is unavailable, but enrichment and search fail until the provider recovers.
• API responses include ranked results plus optional chunk text, similarity, and final score.
• Compact search results may include edge counts and relation labels without neighbor content. Treat them as traversal hints, not as graph expansion.
• Use graph expansion for causes, provenance, decisions, dependencies, blockers, ownership, involvement, related discussions, or ambiguous search hits. Skip it for direct facts already present in the search result.