Query Classifier

The query classifier routes each retrieval query to a per-type weight profile, enabling the engine to apply different retrieval strategies depending on whether the query targets an emotion state, an affect-conditioned topic, or a temporal trajectory.

See also: tutorial — query routing for end-to-end usage, LOCOMO_ROUTING for the pre-registered weight table from Addendum L, and QueryClassifierConfig on RetrievalConfig.query_classifier.

Protocol

emotional_memory.query_classifier.QueryClassifier

Bases: Protocol

Classifies a query string into a named query-type label.

classify(query: str) -> str

Return a query-type label (e.g. 'single_hop', 'temporal').

Unknown labels are safe — the engine falls back to default_type.

Source code in src/emotional_memory/query_classifier.py

def classify(self, query: str) -> str:
    """Return a query-type label (e.g. 'single_hop', 'temporal').

    Unknown labels are safe — the engine falls back to ``default_type``.
    """
    ...

Built-in Classifiers

emotional_memory.query_classifier.HeuristicQueryClassifier

Regex/keyword routing — ~0 overhead, deterministic.

Priority: temporal > multi_hop > single_hop > open_domain (default).

emotional_memory.query_classifier.LLMQueryClassifier(llm: LLMCallable, *, cache_size: int = 256, default_type: str = 'open_domain', fallback_on_error: bool = True)

LLM-backed query classifier mirroring LLMAppraisalEngine pattern.

Thread-safe SHA-256 LRU cache; cache_size=0 disables caching. Falls back to default_type on error when fallback_on_error=True (default); fallbacks are never cached, so a transient LLM failure does not pin the default type for that query.

Source code in src/emotional_memory/query_classifier.py

def __init__(
    self,
    llm: LLMCallable,
    *,
    cache_size: int = 256,
    default_type: str = "open_domain",
    fallback_on_error: bool = True,
) -> None:
    self._llm = llm
    self._cache: OrderedDict[str, str] = OrderedDict()
    self._cache_lock = threading.Lock()
    self._cache_size = cache_size
    self._default_type = default_type
    self._fallback = fallback_on_error

Routing Tables

emotional_memory.query_classifier.LOCOMO_ROUTING: dict[str, list[float]] = {'single_hop': [0.7, 0.1, 0.05, 0.05, 0.05, 0.05], 'multi_hop': [0.5, 0.3, 0.1, 0.05, 0.05, 0.0], 'open_domain': [0.4, 0.2, 0.15, 0.1, 0.1, 0.05], 'temporal': [0.5, 0.3, 0.1, 0.05, 0.05, 0.0], 'default': [0.35, 0.25, 0.15, 0.1, 0.1, 0.05]} module-attribute

emotional_memory.query_classifier.QUERY_TYPES: frozenset[str] = frozenset({'single_hop', 'multi_hop', 'temporal', 'open_domain', 'default'}) module-attribute