tools.scour module

Scour – deep unified memory retrieval across KG + pgvector.

+===============================================================================+ | SCOUR | +===============================================================================+ | Queries BOTH the FalkorDB knowledge graph (45k entities, 140k edges) | | AND the Spiral Goddess pgvector store (53k chunks) in a single call. | | | | Returns structured entity data (relationships, provenance, temporal/domain | | concepts) PLUS verbatim conversation fragments. One tool, full-stack | | recall. No confabulation. | +===============================================================================+ | SECURITY: Requires CORE_MEMORY privilege (bit 1) | +===============================================================================+

Built by:

Vivian – The Loopmother (Architect of Infinite Recursion)

async tools.scour.run(query, n_chunks=3, kg_top_k=5, domain=None, temporal=None, ctx=None)[source]

Execute scour: unified knowledge-graph + pgvector memory retrieval.

Module-level entry point for the scour tool. Queries the FalkorDB knowledge graph and the Spiral Goddess pgvector store in a single call and merges them into one structured response, giving the model both the graph-backed facts (entities, relationships, provenance) and the raw conversation text behind them so it can verify rather than confabulate.

Enforces the CORE_MEMORY privilege via _check_core_memory first, then fans out the two retrievals concurrently: the async _query_kg task and the blocking _query_chromadb (which embeds the query through the shared Gemini/OpenRouter pool and runs the pgvector KNN) dispatched to a thread via run_in_executor. Each half is awaited independently so one failing does not sink the other; per-half errors land in {name}_error fields. Setting kg_top_k or n_chunks to 0 skips that half entirely. The user id and a truncated query are logged at info level for auditing.

Called by the tool registry’s execute_tool dispatch: tool_loader.py discovers this module by its TOOL_NAME/run contract and registers run as the handler, so there are no direct in-repo callers.

Parameters:

  • query (str) – Natural-language query searched across both memory systems.

  • n_chunks (int) – Number of verbatim conversation chunks to pull from the vector store; 0 skips the vector half. Defaults to 3.

  • kg_top_k (int) – Maximum knowledge-graph entities to return; 0 skips the KG half. Defaults to 5.

  • domain (str | None) – Optional domain tag used to Python-filter vector-store chunks.

  • temporal (str | None) – Optional period filter applied to KG entities by provenance timestamp.

  • ctx (ToolContext | None) – The ToolContext, injected by the registry; a None context yields an immediate error.

Returns:

An indented JSON string with success and query plus whatever each half contributed (kg_entities/kg_count, chunks/ chunk_count, any *_error keys, and echoed domain_filter / temporal_filter when set), or an error object when the context is missing or authorization fails.

Return type:

str