Module knowledge_embedding 

Embedding-based Knowledge Retrieval for ctx_knowledge.

Wraps ProjectKnowledge with a vector index for semantic recall. Facts are automatically embedded on remember and searched via cosine similarity on recall, with hybrid exact + semantic ranking.

Structs

FactEmbedding

KnowledgeEmbeddingIndex

ScoredFact

Constants

BACKFILL_PER_REMEMBER

Per-remember cap for backfill_missing. One MiniLM mini-batch (embed_batch chunks at 64) — bounded latency on the write path while an actively-used project converges to full vector coverage within a few calls.

SEMANTIC_DUP_THRESHOLD

Cosine threshold above which a freshly-remembered fact is treated as a semantic near-duplicate of an existing one. Deliberately conservative — only genuine paraphrases (“DB is Postgres” / “we persist to PostgreSQL”) clear it, so the advisory stays signal, not noise. Non-destructive: it nudges the agent to judge, never auto-merges (distinct facts can be near in embedding space, e.g. “Postgres 14” vs “Postgres 15”).

Functions

backfill_missing

Lazy vector backfill: embeds up to cap current facts that are missing from the side-car index. Facts land without vectors on two paths — the consolidation/ETL writers never embed at all, and a non-blocking remember skips its side-car while the engine is still warming up. Without a healer those facts stay invisible to mode=semantic recall until a manual embeddings_reindex. Called from remember under the per-project lock once the engine is warm, so active projects self-heal incrementally. Returns the number of facts embedded.

compact_against_knowledge

embed_and_store

find_semantic_duplicates

Embedding-based near-duplicate detection for remember. Mirrors the lexical find_cross_key_similar but scores cosine similarity, so paraphrases that share few tokens are still caught. Read-only against the pre-upsert index, so the incoming fact never matches itself. Returns advisory hits for the agent to resolve via judge — it never mutates or merges facts.

format_scored_facts

missing_current_facts

Current facts that have no vector in the side-car index, most valuable first (same ordering as embeddings_reindex: confidence, then recency). Engine-free so the selection is unit-testable with raw indices.

reset

semantic_recall

semantic_recall_semantic_only