@xdarkicex/openclaw-memory-libravdb 1.3.20 → 1.4.0

package/docs/README.md

@@ -9,7 +9,7 @@ to preserve project history and design evolution.
 - [uninstall.md](./uninstall.md) - Clean shutdown and removal guide for the plugin, daemon, and optional local data.
 - [architecture.md](./architecture.md) - End-to-end component model, turn lifecycle, compaction flow, and degraded behavior.
 - [problem.md](./problem.md) - Technical argument for replacing the stock OpenClaw memory lifecycle in this use case.
-- [mathematics-v2.md](./mathematics-v2.md) - Formal reference for hybrid scoring, decay, token budgeting, Matryoshka retrieval, compaction, and planned two-pass retrieval.
+- [mathematics-v2.md](./mathematics-v2.md) - Formal reference for hybrid scoring, decay, token budgeting, Matryoshka retrieval, compaction, planned two-pass retrieval, and temporal-compositional projection.
 - [compaction-evaluation.md](./compaction-evaluation.md) - Real-model benchmark notes for T5 summary confidence, Nomic-space preservation, and the hard preservation gate.
 - [continuity.md](./continuity.md) - Continuity model for invariant context, preserved recent raw session tail, and retrieved older memory.
 - [ast-v2.md](./ast-v2.md) - Reviewed authoritative AST partitioning reference for authored Markdown hard invariants, soft invariants, and variant lore.

package/docs/mathematics-v2.md

@@ -1386,3 +1386,488 @@ retaining for future work:
 These ideas are intentionally preserved as future mathematics rather than
 current contract. The present document remains normative only for the formulas
 and invariants already defined above.
+
+## 9. Temporal-Compositional Retrieval Extension
+
+This section defines a narrow, mathematically principled extension to the
+$\mathrm{Proj}()$ operator that corrects the single-turn-centric failure mode on
+temporal-compositional queries such as "how many days before $X$ did $Y$
+happen."
+
+The extension is self-contained. Every formula in this section is bounded and
+correct under the existing parameter domains. The assembly law
+$C_{\mathrm{total}}(q)$, the budget hierarchy, and the runtime invariants in
+Section 7.10 and [`continuity.md`](./continuity.md) are unchanged. Only the
+internal definition of $\mathrm{Proj}(\mathcal{V}_{\mathrm{rest}}, q)$ is
+refined.
+
+Implemented in: `src/temporal.ts` (planned).
+
+### 9.1 Motivation: The Set-Scoring Gap
+
+The standard Pass-2 score $S_{\mathrm{final}}(d)$ maximizes over individual
+candidates:
+
+$$
+\mathcal{C}_2(q)
+=
+\mathrm{TopK}_{d \in \mathcal{C}_1(q)}
+\left(k_2,\, S_{\mathrm{final}}(d)\right)
+$$
+
+This is optimal when the query is answerable from a single best document. It
+fails when the query requires two complementary date-bearing turns to be
+jointly present, neither of which is individually the best semantic match.
+
+The failure pattern is:
+
+- Turn $A$ covers the query topic broadly, so it earns a high
+  $S_{\mathrm{final}}$ and wins alone.
+- Turn $B$ contains the missing date anchor, but earns only a moderate
+  $S_{\mathrm{final}}$ and is evicted.
+- Neither $A$ alone nor $B$ alone answers the question.
+
+The fix is to move from
+$\underset{d}{\arg\max}\; S_{\mathrm{final}}(d)$ to a coverage-aware set
+selector that rewards a set of candidates for jointly maximizing semantic
+relevance, temporal anchor density, and event-slot coverage while penalizing
+redundancy automatically via marginal scoring.
+
+### 9.2 Temporal Query Indicator $\xi(q)\in[0,1]$
+
+To avoid mutating the retrieval contract for normal queries, the extension
+activates only when the query is detected to be temporal-compositional.
+Define the temporal query indicator using the same saturating-sum pattern as
+$T(t)$ in [`gating.md`](./gating.md):
+
+$$
+\xi(q)
+=
+\min\!\left(
+  \frac{\displaystyle\sum_i s_i \cdot \mathbf{1}[\mathrm{tpat}_i(q)]}
+       {\theta_{\xi}^{\mathrm{norm}}},
+  1
+\right)
+$$
+
+where the shipped temporal patterns $\mathrm{tpat}_i$ are zero-allocation
+byte-lexer matches over the query text, including but not limited to
+"how many days", "how long", "before", "after", "since", "first", "earlier",
+"which came first", "when did", and "between".
+
+Each pattern carries a weight $s_i > 0$. The default normalization constant is
+$\theta_{\xi}^{\mathrm{norm}} = 1.5$, so two strong temporal signals saturate
+$\xi(q)=1$.
+
+By construction, the $\min(\cdot, 1)$ clamp and non-negative numerator
+guarantee:
+
+$$
+\xi(q)\in[0,1]
+$$
+
+If no temporal patterns match, $\xi(q)=0$ and the extension contributes
+nothing to the scoring formula.
+
+The extension activates only when $\xi(q)\ge\theta_\xi$, with shipped default
+$\theta_\xi = 0.3$. Below that threshold, the standard $\mathrm{Proj}$ path
+executes without modification.
+
+### 9.3 Temporal Anchor Density $A(d)\in[0,1]$
+
+A document's temporal anchor density measures how many explicit date or time
+expressions it contains, normalized by a bounded saturation constant.
+Define the anchor count over a lightweight anchor pattern set $\mathcal{P}_A$
+(ISO dates, relative day expressions, clock times, calendar words, Unix
+timestamps):
+
+$$
+A(d)
+=
+\min\!\left(
+  \frac{\displaystyle\sum_j \mathbf{1}[\mathrm{anch}_j(d)]}
+       {\theta_A^{\mathrm{norm}}},
+  1
+\right)
+$$
+
+The default $\theta_A^{\mathrm{norm}} = 3$, so three or more distinct anchor
+expressions saturate $A(d)=1$.
+
+Again, the clamp guarantees:
+
+$$
+A(d)\in[0,1]
+$$
+
+$A(d)$ is a precomputed document-level scalar. It does not depend on the query
+and should be cached in the same document-addressed cache $\Psi$ defined in
+[`ast-v2.md`](./ast-v2.md) Section 7 alongside tier partition and budget
+metadata. The value must be recomputed whenever a stored document is created,
+updated, or regenerated by compaction.
+
+### 9.4 Event-Slot Extraction and Marginal Coverage $\Delta\Phi$
+
+#### 9.4.1 Event-Slot Extraction
+
+For a temporal-compositional query $q$, define the event-slot set:
+
+$$
+E(q)=\langle e_1, e_2, \dots, e_m \rangle
+$$
+
+where each $e_j$ is a short noun-phrase span extracted from $q$ by a
+lightweight span extractor: named entities plus the main noun phrase preceding
+and following any detected temporal-pattern word. The extractor returns at
+most $m_{\max}=4$ slots to bound cost.
+
+When $|E(q)|=0$, all coverage terms evaluate to zero and the formula degrades
+cleanly.
+
+#### 9.4.2 Per-Slot Coverage Indicator
+
+For each slot $e_j$ and candidate document $d$, define the binary slot-match
+indicator:
+
+$$
+\phi_j(d)
+=
+\mathbf{1}\!\left[\varphi(e_j)^\top \varphi(d) \ge \theta_e\right]
+\in \{0,1\}
+$$
+
+where $\varphi(\cdot)$ is the same unit-normalized embedding function defined
+in Section 7.1, and $\theta_e \in [-1,1]$ is the slot-match similarity
+threshold, default $\theta_e = 0.50$.
+
+#### 9.4.3 Marginal Coverage
+
+For a set $\mathcal{S}$ of already-selected documents, define the marginal
+coverage of adding $d$:
+
+$$
+\Delta\Phi(d, \mathcal{S}, q)
+=
+\frac{1}{\max(|E(q)|, 1)}
+\sum_{j=1}^{|E(q)|}
+\phi_j(d)
+\cdot
+\mathbf{1}\!\left[\nexists d' \in \mathcal{S} : \phi_j(d') = 1\right]
+$$
+
+This is the fraction of uncovered event slots that $d$ newly covers.
+
+The outer factor is in $(0,1]$, the sum counts at most $|E(q)|$ binary terms,
+and therefore:
+
+$$
+\Delta\Phi(d, \mathcal{S}, q)\in[0,1]
+$$
+
+The indicator
+$\mathbf{1}\!\left[\nexists d' \in \mathcal{S} : \phi_j(d') = 1\right]$
+ensures that slots already covered by a previously selected document
+contribute zero marginal gain, automatically penalizing redundant anchor turns
+without a separate explicit penalty term.
+
+As $|\mathcal{S}|$ grows, $\Delta\Phi(d,\mathcal{S},q)$ is monotone
+non-increasing: new selections can only cover more slots, leaving fewer
+uncovered slots for later candidates to gain credit for.
+
+### 9.5 Coverage-Augmented Blended Score
+$S_{\mathrm{proj}}(d,\mathcal{S},q)\in[0,1]$
+
+Define the coverage-augmented score for candidate $d$ given already-selected
+set $\mathcal{S}$ and query $q$:
+
+$$
+S_{\mathrm{cov}}(d, \mathcal{S}, q)
+=
+\mu \cdot S_{\mathrm{final}}(d)
++ \nu \cdot A(d)
++ \rho \cdot \Delta\Phi(d, \mathcal{S}, q)
+$$
+
+where:
+
+$$
+\mu,\nu,\rho\in[0,1],
+\qquad
+\mu+\nu+\rho=1
+$$
+
+The default shipped weights are $\mu=0.60$, $\nu=0.20$, and $\rho=0.20$.
+
+Blend this with the standard score using $\xi(q)$ as an interpolation scalar:
+
+$$
+S_{\mathrm{proj}}(d, \mathcal{S}, q)
+=
+(1 - \xi(q)) \cdot S_{\mathrm{final}}(d)
++ \xi(q) \cdot S_{\mathrm{cov}}(d, \mathcal{S}, q)
+$$
+
+Substituting $S_{\mathrm{cov}}$ yields:
+
+$$
+S_{\mathrm{proj}}
+=
+\bigl(1 - \xi(1-\mu)\bigr)\cdot S_{\mathrm{final}}
++ \xi\nu \cdot A
++ \xi\rho \cdot \Delta\Phi
+$$
+
+All coefficients are non-negative, and they sum to one:
+
+$$
+\bigl(1 - \xi(1-\mu)\bigr) + \xi\nu + \xi\rho
+=
+1 - \xi + \xi\mu + \xi\nu + \xi\rho
+=
+1 - \xi + \xi(\mu+\nu+\rho)
+=
+1
+$$
+
+Because $S_{\mathrm{final}}(d)$, $A(d)$, and
+$\Delta\Phi(d,\mathcal{S},q)$ all lie in $[0,1]$, this is a proper convex
+combination, so:
+
+$$
+S_{\mathrm{proj}}(d,\mathcal{S},q)\in[0,1]
+$$
+
+Degeneracy cases:
+
+| Condition | Behavior |
+| --- | --- |
+| $\xi(q)=0$ | $S_{\mathrm{proj}} = S_{\mathrm{final}}(d)$; standard retrieval unchanged |
+| $\xi(q)=1$, $\nu=\rho=0$, $\mu=1$ | Explicit no-op configuration; still $S_{\mathrm{proj}} = S_{\mathrm{final}}(d)$ |
+| $|E(q)|=0$ | $\Delta\Phi=0$ for all $d$; the $\rho$ term vanishes |
+| $\mathcal{S}=\emptyset$ | $\Delta\Phi$ equals full slot-coverage fraction |
+| all slots already covered by $\mathcal{S}$ | $\Delta\Phi=0$ for all remaining $d$ |
+
+Note: the greedy selector below optimizes a submodular coverage term
+$\Delta\Phi$ augmented with fixed document priors $S_{\mathrm{final}}(d)$ and
+$A(d)$. The classic $(1-1/e)$ approximation guarantee applies strictly to the
+coverage component; in practice the blended score preserves greedy usefulness
+for temporal anchor selection.
+
+### 9.6 Temporal Recovery Candidate Set
+$\mathcal{C}_{\mathrm{rec}}(q)$
+
+The root cause of the observed benchmark failure is not only that documents are
+scored incorrectly; it is also that the necessary complementary anchor turn may
+never enter $\mathcal{C}_2(q)$ because its semantic similarity to the
+whole-query embedding is too low.
+
+A bounded recovery pass admits anchor-rich documents below the normal Pass-1
+threshold:
+
+$$
+\mathcal{C}_{\mathrm{rec}}(q)
+=
+\mathrm{TopK}_{d \in
+\left\{d' \in \mathcal{V}_{\mathrm{rest}} :
+\mathrm{sim}(q,d') \ge \theta_{\mathrm{rec}}\right\}}
+\left(k_{\mathrm{rec}},\, A(d)\right)
+\setminus \mathcal{C}_2(q)
+$$
+
+where:
+
+- $\theta_{\mathrm{rec}} < \theta_1$ is a looser semantic floor, default
+  $\theta_{\mathrm{rec}} = 0.15$, preventing pure noise while still admitting
+  anchor-heavy but semantically distant turns.
+- $k_{\mathrm{rec}}$ is a small cap, default $k_{\mathrm{rec}} = 10$, bounding
+  recovery cost to $O(k_{\mathrm{rec}})$.
+
+The combined candidate pool for the greedy selector is:
+
+$$
+\mathcal{C}_{\mathrm{pool}}(q)
+=
+\mathcal{C}_2(q)\cup\mathcal{C}_{\mathrm{rec}}(q)
+$$
+
+By construction,
+$\mathcal{C}_{\mathrm{pool}}(q)\subseteq\mathcal{V}_{\mathrm{rest}}$, so
+partition integrity is preserved.
+
+### 9.7 Greedy Coverage-Aware Selector
+
+Given $\mathcal{C}_{\mathrm{pool}}(q)$, the selector builds the final chosen
+set greedily, using the same rank-then-prefix-accept spirit as the existing
+token-budget packing in Section 7.8.
+
+Let $k_{\mathrm{cov}}\le k_2$ be the maximum number of anchor turns to select,
+default $k_{\mathrm{cov}}=3$.
+
+Initialize:
+
+$$
+\mathcal{S}_0 = \emptyset
+$$
+
+For $i = 0, 1, \dots, k_{\mathrm{cov}}-1$:
+
+$$
+d_i^*
+=
+\underset{d \in \mathcal{C}_{\mathrm{pool}}(q)\setminus\mathcal{S}_i}{\arg\max}
+\;
+S_{\mathrm{proj}}(d, \mathcal{S}_i, q)
+$$
+
+Early stop if:
+
+$$
+S_{\mathrm{proj}}(d_i^*, \mathcal{S}_i, q) < \theta_{\mathrm{stop}}
+$$
+
+with default $\theta_{\mathrm{stop}}=0.10$. Otherwise:
+
+$$
+\mathcal{S}_{i+1} = \mathcal{S}_i \cup \{d_i^*\}
+$$
+
+The final selected set is $\mathcal{S}^*(q)$, or the earlier set at which
+early stopping triggered.
+
+Each greedy step scans at most
+$|\mathcal{C}_{\mathrm{pool}}(q)| \le k_2 + k_{\mathrm{rec}}$ candidates.
+Total complexity is therefore:
+
+$$
+O\!\left(k_{\mathrm{cov}} \cdot (k_2 + k_{\mathrm{rec}})\right)
+$$
+
+which is negligible relative to embedding and vector-search cost.
+
+### 9.8 Modified Projection Operator
+
+The temporal extension redefines $\mathrm{Proj}$ conditionally:
+
+$$
+\mathrm{Proj}(\mathcal{V}_{\mathrm{rest}}, q)
+=
+\begin{cases}
+\mathcal{S}^*(q)\cup\mathcal{C}_{hop}^{*}(q)
+& \text{if } \xi(q) \ge \theta_\xi \\[4pt]
+\mathcal{C}_2(q)\cup\mathcal{C}_{hop}^{*}(q)
+& \text{otherwise}
+\end{cases}
+$$
+
+The assembly law and budget equations remain unchanged:
+
+$$
+C_{\mathrm{total}}(q)=\mathcal{I}_1\cup\mathcal{I}_2^{*}\cup T_{\mathrm{recent}}\cup \mathrm{Proj}(\mathcal{V}_{\mathrm{rest}}, q)
+$$
+
+$$
+\tau_{\mathcal{V}}(q)
+=
+\tau-\tau_{\mathcal{I}_1}
+-\sum_{d\in\mathcal{I}_2^{*}}\mathrm{toks}(d)
+-\sum_{d\in T_{\mathrm{recent}}}\mathrm{toks}(d)
+$$
+
+Documents in $\mathrm{Proj}(\mathcal{V}_{\mathrm{rest}}, q)$ are injected in
+descending $\sigma(d)$ order until $\tau_{\mathcal{V}}(q)$ is exhausted.
+
+For documents entering through the temporal selector, the merged score sequence
+is extended:
+
+$$
+\sigma(d)=
+\begin{cases}
+S_{\mathrm{proj}}(d, \mathcal{S}^*\setminus\{d\}, q)
+& d\in\mathcal{S}^*(q) \\
+S_{hop}(d)
+& d\in\mathcal{C}_{hop}^{*}(q)
+\end{cases}
+$$
+
+For documents that were already present in $\mathcal{C}_2(q)$, the standard
+$S_{\mathrm{final}}(d)$ path remains authoritative and duplicates are excluded
+by construction.
+
+### 9.9 Preservation of Section 7.10 Runtime Invariants
+
+All runtime invariants from Section 7.10 remain preserved:
+
+1. Invariant completeness is unaffected because $\mathcal{I}_1$ injection is
+   independent of $\mathrm{Proj}$.
+2. Soft invariant order preservation is unaffected because
+   $\mathcal{I}_2^{*}$ is unchanged.
+3. Partition integrity is preserved because
+   $\mathcal{C}_{\mathrm{rec}}\subseteq\mathcal{V}_{\mathrm{rest}}$ and
+   $\mathcal{S}^*\subseteq\mathcal{C}_{\mathrm{pool}}
+   \subseteq\mathcal{V}_{\mathrm{rest}}$.
+4. Mandatory recent-tail completeness is unaffected because
+   $T_{\mathrm{base}}\subseteq T_{\mathrm{recent}}$ remains independent of
+   $\mathrm{Proj}$.
+5. Score boundedness is preserved because
+   $S_{\mathrm{proj}}(d,\mathcal{S},q)\in[0,1]$.
+6. Token budget respect is preserved because the result still flows through the
+   same residual variant budget and greedy token packing contract.
+7. Compaction boundary safety is preserved because
+   $\mathcal{S}^*\subseteq\mathcal{V}_{\mathrm{rest}}$.
+8. Hop termination is unchanged because $\mathcal{C}_{hop}^{*}(q)$ is defined
+   identically.
+9. Edge-case safety is preserved by the guards below.
+
+Edge-case additions:
+
+- $\mathcal{C}_{\mathrm{pool}}(q)=\emptyset$: the greedy selector returns
+  $\mathcal{S}^*=\emptyset$ and $\mathrm{Proj}$ reduces to
+  $\mathcal{C}_{hop}^{*}(q)$ only.
+- $|E(q)|=0$: the denominator in $\Delta\Phi$ uses $\max(|E(q)|,1)$, so no
+  division by zero is possible.
+- $\xi(q)<\theta_\xi$: the conditional routes directly to the existing
+  $\mathcal{C}_2(q)\cup\mathcal{C}_{hop}^{*}(q)$ behavior.
+- $\tau_{\mathcal{V}}(q)=0$: the selector may compute $\mathcal{S}^*$, but
+  packing injects zero documents and the budget invariant still holds.
+
+### 9.10 Symbol Table (Section 9 Additions)
+
+| Symbol | Domain | Meaning |
+| --- | --- | --- |
+| $\xi(q)$ | $[0,1]$ | Temporal-compositional query indicator |
+| $\theta_\xi$ | $(0,1)$ | Activation threshold for temporal mode |
+| $\theta_{\xi}^{\mathrm{norm}}$ | $(0,\infty)$ | Saturation normalization for $\xi$ |
+| $A(d)$ | $[0,1]$ | Temporal anchor density of document $d$ |
+| $\theta_A^{\mathrm{norm}}$ | $(0,\infty)$ | Saturation normalization for $A$ |
+| $E(q)$ | ordered tuple set | Event-slot sequence extracted from $q$ |
+| $\phi_j(d)$ | $\{0,1\}$ | Binary slot-match indicator |
+| $\theta_e$ | $[-1,1]$ | Slot-match similarity threshold |
+| $\Delta\Phi(d,\mathcal{S},q)$ | $[0,1]$ | Marginal event-slot coverage |
+| $\mu,\nu,\rho$ | $[0,1]$, sum to 1 | Coverage score weights |
+| $S_{\mathrm{cov}}(d,\mathcal{S},q)$ | $[0,1]$ | Coverage-augmented score |
+| $S_{\mathrm{proj}}(d,\mathcal{S},q)$ | $[0,1]$ | Final blended projection score |
+| $\mathcal{C}_{\mathrm{rec}}(q)$ | $\subseteq\mathcal{V}_{\mathrm{rest}}$ | Recovery candidate set |
+| $\theta_{\mathrm{rec}}$ | $[-1,1]$ | Semantic floor for recovery pass |
+| $k_{\mathrm{rec}}$ | $\mathbb{Z}_{>0}$ | Recovery set size cap |
+| $\mathcal{C}_{\mathrm{pool}}(q)$ | $\subseteq\mathcal{V}_{\mathrm{rest}}$ | Combined greedy input pool |
+| $k_{\mathrm{cov}}$ | $\mathbb{Z}_{>0}, \le k_2$ | Maximum anchor turns to select |
+| $\theta_{\mathrm{stop}}$ | $[0,1]$ | Early-stop floor for greedy selector |
+| $\mathcal{S}^*(q)$ | $\subseteq\mathcal{C}_{\mathrm{pool}}$ | Greedy-selected coverage-aware anchor set |
+
+### 9.11 Relationship to Existing Sections
+
+This section is an extension, not a replacement:
+
+- Section 1 hybrid score $\mathrm{score}(d)$ is unchanged and still feeds
+  $S_{\mathrm{final}}(d)$ as before.
+- Section 7.5 $S_{\mathrm{final}}(d)$ is the first input to
+  $S_{\mathrm{proj}}$; when $\xi(q)=0$, the two are identical.
+- Section 7.7 hop expansion $\mathcal{C}_{hop}^{*}$ is unchanged and is
+  unioned with $\mathcal{S}^*$ exactly as before.
+- Section 7.8 budget arithmetic is unchanged; $\mathrm{Proj}$ is still bounded
+  by $\tau_{\mathcal{V}}(q)$ and still greedy-packed.
+- [`gating.md`](./gating.md) inspired the saturating-sum pattern for $\xi(q)$,
+  but the two operate on different objects and at different pipeline stages.
+- [`ast-v2.md`](./ast-v2.md) Section 7's document-addressed cache $\Psi$ should
+  be extended to store the precomputed $A(d)$ value alongside existing tier and
+  budget metadata.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.3.20",
+  "version": "1.4.0",
   "type": "module",
   "publishConfig": {
     "access": "public"

package/src/context-engine.ts

@@ -12,7 +12,13 @@ import {
   rankSection7VariantCandidates,
 } from "./scoring.js";
 import { buildInjectedMemoryMessageContent, buildMemoryHeader, recentIds } from "./recall-utils.js";
-import { countTokens, estimateTokens, fitPromptBudget } from "./tokens.js";
+import {
+  decideTemporalSelectorGuard,
+  detectTemporalQuerySignal,
+  rankTemporalRecoveryCandidates,
+} from "./temporal.js";
+import type { TemporalRecoveryRankingResult } from "./temporal.js";
+import { countTokens, estimateTokens, fitPromptBudget, fitPromptBudgetFirstFit } from "./tokens.js";
 import type { RpcGetter } from "./plugin-runtime.js";
 import type {
   ContextAssembleArgs,
@@ -57,6 +63,7 @@ export function buildContextEngineFactory(
   }
 
   return {
+    info: { id: "libravdb-memory" },
     ownsCompaction: true,
     async bootstrap({ sessionId, userId }: ContextBootstrapArgs) {
       const rpc = await getRpc();
@@ -190,6 +197,8 @@ export function buildContextEngineFactory(
           systemPromptAddition: "",
         } satisfies ContextAssembleResult;
       }
+      const temporalQuery = detectTemporalQuerySignal(queryText);
+      const temporalSelectorGuard = decideTemporalSelectorGuard(queryText, temporalQuery);
 
       const excluded = recentIds(messages, 4);
       const cached = recallCache.take({ userId, queryText });
@@ -253,6 +262,8 @@ export function buildContextEngineFactory(
           cached,
           excluded,
           queryText,
+          temporalQuery,
+          temporalSelectorGuard,
           sessionId,
           userId,
           messages,
@@ -287,6 +298,8 @@ export function buildContextEngineFactory(
       cached,
       excluded,
       queryText,
+      temporalQuery,
+      temporalSelectorGuard,
       sessionId,
       userId,
       messages,
@@ -303,6 +316,8 @@ export function buildContextEngineFactory(
       cached: ReturnType<RecallCache<SearchResult>["take"]>;
       excluded: string[];
       queryText: string;
+      temporalQuery: ReturnType<typeof detectTemporalQuerySignal>;
+      temporalSelectorGuard: ReturnType<typeof decideTemporalSelectorGuard>;
       sessionId: string;
       userId: string;
       messages: Array<{ role: string; content: string }>;
@@ -562,6 +577,7 @@ export function buildContextEngineFactory(
       // it never modifies the C_total(q) output and does not spend from tau_V.
       let recoveryItems: SearchResult[] = [];
       let rawUserRecoveryDebug: NonNullable<NonNullable<ContextAssembleResult["_debug"]>["rawUserRecoveryCandidates"]> = [];
+      let temporalRecoveryResult: TemporalRecoveryRankingResult | null = null;
       if (recoveryTrigger.fire || crossSessionRawRecovery) {
         profiler?.mark("recovery_expand");
         const recoveryExcludeIDs = [...excluded, ...recentTailIDs, ...theoremSelectedIDs];
@@ -599,14 +615,44 @@ export function buildContextEngineFactory(
             k: Math.max((cfg.topK ?? 8) * 4, 8),
             excludeIds: recoveryExcludeIDs,
           });
-          const reranked = rankRawUserRecoveryCandidates(
-            annotateCollection(rawUserResults.results ?? [], `turns:${userId}`),
-            { queryText },
-          );
+          const annotatedUserResults = annotateCollection(rawUserResults.results ?? [], `turns:${userId}`);
+          temporalRecoveryResult = temporalSelectorGuard.shouldApply
+            ? rankTemporalRecoveryCandidates(annotatedUserResults, {
+                queryText,
+                maxSelected: 3,
+                nowMs: Date.now(),
+                recencyLambda: cfg.recencyLambdaUser ?? 0.00001,
+              })
+            : null;
+          const reranked = temporalRecoveryResult
+            ? temporalRecoveryResult
+            : rankRawUserRecoveryCandidates(annotatedUserResults, { queryText });
           if (debugRecovery) {
             rawUserRecoveryDebug = reranked.debug.slice(0, 8).map((item) => ({
-              ...item,
+              id: item.id,
+              text: item.text,
               selected: false,
+              tokenEstimate: estimateTokens(item.text),
+              temporalAnchorDensity: "temporalAnchorDensity" in item && typeof item.temporalAnchorDensity === "number"
+                ? item.temporalAnchorDensity
+                : 0,
+              semanticScore: "semanticScore" in item && typeof item.semanticScore === "number"
+                ? item.semanticScore
+                : 0,
+              slotCoverage: "slotCoverage" in item && typeof item.slotCoverage === "number"
+                ? item.slotCoverage
+                : undefined,
+              slotMatches: "slotMatches" in item && Array.isArray(item.slotMatches)
+                ? item.slotMatches
+                : undefined,
+              lexicalCoverage: "lexicalCoverage" in item && typeof item.lexicalCoverage === "number"
+                ? item.lexicalCoverage
+                : ("slotCoverage" in item && typeof item.slotCoverage === "number" ? item.slotCoverage : 0),
+              recencyScore: "recencyScore" in item && typeof item.recencyScore === "number"
+                ? item.recencyScore
+                : 0,
+              finalScore: typeof item.finalScore === "number" ? item.finalScore : 0,
+              rationale: typeof item.rationale === "string" ? item.rationale : "",
             }));
           }
           recoveryCandidates.push(
@@ -622,7 +668,7 @@ export function buildContextEngineFactory(
           );
         }
 
-        const fittedRecovery = fitPromptBudget(
+        const fittedRecovery = fitPromptBudgetFirstFit(
           dedupeRecoveryCandidates(recoveryCandidates),
           recoveryReserveTokens,
         );
@@ -667,6 +713,13 @@ export function buildContextEngineFactory(
           ? {
               recoveryTriggerFired: recoveryTrigger.fire,
               crossSessionRawRecovery,
+              recoveryReserveTokens,
+              temporalQueryIndicator: temporalQuery.indicator,
+              temporalQueryActive: temporalQuery.active,
+              temporalQueryPatterns: temporalQuery.matchedPatterns,
+              temporalSelectorApplied: temporalSelectorGuard.shouldApply,
+              temporalSelectorReason: temporalSelectorGuard.reason,
+              temporalRecoverySlots: temporalRecoveryResult?.slots,
               rawUserRecoveryCandidates: rawUserRecoveryDebug,
             }
           : undefined,

package/src/scoring.ts

@@ -1,4 +1,5 @@
 import type { SearchResult } from "./types.js";
+import { getTemporalAnchorDensity } from "./temporal.js";
 
 interface HybridOptions {
   alpha?: number;
@@ -41,6 +42,7 @@ interface RawUserRecoveryOptions {
 export interface RawUserRecoveryDebugCandidate {
   id: string;
   text: string;
+  temporalAnchorDensity: number;
   semanticScore: number;
   lexicalCoverage: number;
   recencyScore: number;
@@ -319,17 +321,29 @@ export function rankRawUserRecoveryCandidates(
   const now = opts.nowMs ?? Date.now();
   const recencyLambda = Math.max(0, opts.recencyLambda ?? 0.00001);
   const keywords = extractKeywords(opts.queryText);
+  const intentPhrases = extractIntentPhrases(opts.queryText);
 
   const ranked = items
     .map((item) => {
       const semanticScore = clamp01(typeof item.score === "number" ? item.score : 0);
       const lexicalCoverage = normalizedKeywordCoverage(keywords, item.text);
       const recencyScore = computeRecencyScore(item, now, recencyLambda);
-      const finalScore = clamp01((0.30 * semanticScore) + (0.60 * lexicalCoverage) + (0.10 * recencyScore));
+      const temporalAnchorDensity = getTemporalAnchorDensity(
+        `${typeof item.metadata.collection === "string" ? item.metadata.collection : "unknown"}::${item.id}`,
+        item.text,
+      );
+      const intentAlignmentBonus = computeIntentAlignmentBonus(item.text, intentPhrases);
+      const finalScore = clamp01(
+        (0.30 * semanticScore) +
+        (0.60 * lexicalCoverage) +
+        (0.10 * recencyScore) +
+        intentAlignmentBonus,
+      );
       const rationale = buildRawUserRecoveryRationale({
         semanticScore,
         lexicalCoverage,
         recencyScore,
+        intentAlignmentBonus,
       });
 
       return {
@@ -340,6 +354,7 @@ export function rankRawUserRecoveryCandidates(
         debug: {
           id: item.id,
           text: item.text,
+          temporalAnchorDensity,
           semanticScore,
           lexicalCoverage,
           recencyScore,
@@ -473,7 +488,11 @@ function buildRawUserRecoveryRationale(scores: {
   semanticScore: number;
   lexicalCoverage: number;
   recencyScore: number;
+  intentAlignmentBonus: number;
 }): string {
+  if (scores.intentAlignmentBonus >= 0.04) {
+    return "intent phrase overlap lifted this candidate toward the query's direct ask";
+  }
   const lexicalDelta = scores.lexicalCoverage - scores.semanticScore;
   if (lexicalDelta > 0.15) {
     return "lexical coverage lifted this candidate above its semantic score";
@@ -487,6 +506,79 @@ function buildRawUserRecoveryRationale(scores: {
   return "semantic and lexical scores were balanced";
 }
 
+function computeIntentAlignmentBonus(text: string, intentPhrases: string[]): number {
+  if (intentPhrases.length === 0) {
+    return 0;
+  }
+  const normalized = normalizeTextForPhraseMatch(text);
+  const matched = intentPhrases.filter((phrase) => normalized.includes(phrase)).length;
+  if (matched === 0) {
+    return 0;
+  }
+  return Math.min(0.08, matched * 0.02);
+}
+
+function extractIntentPhrases(text: string): string[] {
+  const terms = normalizeTerms(text).filter((term) => !INTENT_STOPWORDS.has(term));
+  const phrases: string[] = [];
+  for (let size = 4; size >= 2; size -= 1) {
+    for (let i = 0; i <= terms.length - size; i += 1) {
+      const phraseTerms = terms.slice(i, i + size);
+      if (phraseTerms.some((term) => term.length < 3)) {
+        continue;
+      }
+      const phrase = phraseTerms.join(" ");
+      if (!phrases.includes(phrase)) {
+        phrases.push(phrase);
+      }
+    }
+  }
+  return phrases.slice(0, 12);
+}
+
+function normalizeTextForPhraseMatch(text: string): string {
+  return normalizeTerms(text).join(" ");
+}
+
+const INTENT_STOPWORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "have",
+  "from",
+  "your",
+  "what",
+  "when",
+  "where",
+  "which",
+  "would",
+  "could",
+  "should",
+  "about",
+  "into",
+  "some",
+  "before",
+  "after",
+  "them",
+  "they",
+  "been",
+  "just",
+  "want",
+  "looking",
+  "look",
+  "help",
+  "need",
+  "recommend",
+  "suggestions",
+  "suggest",
+  "advice",
+  "think",
+  "also",
+]);
+
 function extractKeywords(text: string): string[] {
   const tokens = normalizeTerms(text);
   const seen = new Set<string>();

package/src/sidecar.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
@@ -268,13 +269,42 @@ export function daemonProvisioningHint(): string {
 }
 
 export function defaultEndpoint(platform = process.platform, homeDir = os.homedir()): string {
+  // Honour the daemon's own env var first (set by Homebrew LaunchAgent / systemd unit).
+  const envEndpoint = process.env.LIBRAVDB_RPC_ENDPOINT?.trim();
+  if (envEndpoint && isConfiguredEndpoint(envEndpoint)) {
+    return envEndpoint;
+  }
+
   if (platform === "win32") {
     return "tcp:127.0.0.1:37421";
   }
+
+  const sockName = "libravdb.sock";
+  const candidateDirs = [
+    // User-local (npm plugin convention)
+    homeDir?.trim() ? path.join(homeDir, ".clawdb", "run") : null,
+    // Homebrew (Apple Silicon) — matches the Homebrew formula LaunchAgent
+    "/opt/homebrew/var/clawdb/run",
+    // Homebrew (Intel Mac) / manual Linux installs
+    "/usr/local/var/clawdb/run",
+  ].filter((d): d is string => d !== null);
+
+  for (const dir of candidateDirs) {
+    const sockPath = path.join(dir, sockName);
+    try {
+      if (fs.existsSync(sockPath)) {
+        return `unix:${sockPath}`;
+      }
+    } catch {
+      // Permission error or similar — skip this candidate.
+    }
+  }
+
+  // Fallback to the original user-local path so error messages stay familiar.
   const baseDir = homeDir?.trim()
     ? path.join(homeDir, ".clawdb", "run")
     : path.join(".", ".clawdb", "run");
-  return `unix:${path.join(baseDir, "libravdb.sock")}`;
+  return `unix:${path.join(baseDir, sockName)}`;
 }
 
 export function buildSidecarEnv(cfg: PluginConfig): Record<string, string> {

package/src/temporal.ts

@@ -0,0 +1,433 @@
+import type { SearchResult } from "./types.js";
+
+const TEMPORAL_PATTERN_WEIGHTS: Array<{ label: string; weight: number; patterns: RegExp[] }> = [
+  {
+    label: "how many days",
+    weight: 1.0,
+    patterns: [/\bhow\s+many\s+days\b/i],
+  },
+  {
+    label: "how long",
+    weight: 0.9,
+    patterns: [/\bhow\s+long\b/i],
+  },
+  {
+    label: "before or after",
+    weight: 0.8,
+    patterns: [/\bbefore\b/i, /\bafter\b/i],
+  },
+  {
+    label: "since or between",
+    weight: 0.7,
+    patterns: [/\bsince\b/i, /\bbetween\b/i],
+  },
+  {
+    label: "first or earlier",
+    weight: 0.8,
+    patterns: [/\bfirst\b/i, /\bearlier\b/i, /\bwhich\s+came\s+first\b/i],
+  },
+  {
+    label: "when did",
+    weight: 0.7,
+    patterns: [/\bwhen\s+did\b/i],
+  },
+];
+
+const TEMPORAL_ANCHOR_PATTERNS: RegExp[] = [
+  /\b\d{4}-\d{2}-\d{2}\b/g,
+  /\b\d{1,2}\/\d{1,2}(?:\/\d{2,4})?\b/g,
+  /\b(?:jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:t(?:ember)?)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\s+\d{1,2}(?:st|nd|rd|th)?(?:,\s*\d{4})?\b/gi,
+  /\b(?:monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b/gi,
+  /\b(?:today|yesterday|tomorrow|last\s+(?:week|month|year|night|saturday|sunday)|next\s+(?:week|month|year|monday|tuesday|wednesday|thursday|friday|saturday|sunday)|mid-?[a-z]+)\b/gi,
+  /\b\d{1,2}:\d{2}(?:\s?[ap]m)?\b/gi,
+  /\b\d{10,13}\b/g,
+];
+
+const TEMPORAL_XI_NORM = 1.5;
+const TEMPORAL_XI_THRESHOLD = 0.3;
+const TEMPORAL_ANCHOR_NORM = 3;
+const TEMPORAL_ANCHOR_CACHE_MAX = 4096;
+const temporalAnchorCache = new Map<string, number>();
+
+const TEMPORAL_SLOT_STOPWORDS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "that",
+  "this",
+  "have",
+  "from",
+  "your",
+  "what",
+  "when",
+  "where",
+  "which",
+  "would",
+  "could",
+  "should",
+  "about",
+  "into",
+  "some",
+  "them",
+  "they",
+  "been",
+  "just",
+  "want",
+  "looking",
+  "look",
+  "help",
+  "need",
+  "recommend",
+  "suggestions",
+  "suggest",
+  "advice",
+  "think",
+  "also",
+  "did",
+  "does",
+  "do",
+  "after",
+  "before",
+  "since",
+  "between",
+  "first",
+  "earlier",
+  "many",
+  "days",
+  "long",
+  "how",
+  "did",
+  "take",
+  "took",
+  "it",
+  "me",
+  "my",
+  "i",
+]);
+
+export interface TemporalQuerySignal {
+  indicator: number;
+  active: boolean;
+  matchedPatterns: string[];
+}
+
+export interface TemporalSelectorGuardDecision {
+  shouldApply: boolean;
+  slots: string[];
+  reason: string;
+}
+
+export interface TemporalRecoveryDebugCandidate {
+  id: string;
+  text: string;
+  selected: boolean;
+  temporalAnchorDensity: number;
+  semanticScore: number;
+  recencyScore: number;
+  slotCoverage: number;
+  slotMatches: string[];
+  finalScore: number;
+  rationale: string;
+}
+
+export interface TemporalRecoveryRankingResult {
+  ranked: SearchResult[];
+  debug: TemporalRecoveryDebugCandidate[];
+  temporalQuery: TemporalQuerySignal;
+  slots: string[];
+}
+
+export function detectTemporalQuerySignal(queryText: string): TemporalQuerySignal {
+  const matchedPatterns: string[] = [];
+  let weightedMatches = 0;
+
+  for (const entry of TEMPORAL_PATTERN_WEIGHTS) {
+    if (entry.patterns.some((pattern) => pattern.test(queryText))) {
+      matchedPatterns.push(entry.label);
+      weightedMatches += entry.weight;
+    }
+  }
+
+  const indicator = clamp01(weightedMatches / TEMPORAL_XI_NORM);
+  return {
+    indicator,
+    active: indicator >= TEMPORAL_XI_THRESHOLD,
+    matchedPatterns,
+  };
+}
+
+export function getTemporalAnchorDensity(docKey: string, text: string): number {
+  const cacheKey = `${docKey}\n${text}`;
+  const cached = temporalAnchorCache.get(cacheKey);
+  if (typeof cached === "number") {
+    touchTemporalAnchorCache(cacheKey, cached);
+    return cached;
+  }
+
+  const uniqueMatches = new Set<string>();
+  for (const pattern of TEMPORAL_ANCHOR_PATTERNS) {
+    for (const match of text.matchAll(pattern)) {
+      const value = match[0]?.trim().toLowerCase();
+      if (value) {
+        uniqueMatches.add(value);
+      }
+    }
+  }
+
+  const density = clamp01(uniqueMatches.size / TEMPORAL_ANCHOR_NORM);
+  touchTemporalAnchorCache(cacheKey, density);
+  return density;
+}
+
+export function rankTemporalRecoveryCandidates(
+  items: SearchResult[],
+  opts: {
+    queryText: string;
+    maxSelected?: number;
+    nowMs?: number;
+    recencyLambda?: number;
+  },
+): TemporalRecoveryRankingResult {
+  const temporalQuery = detectTemporalQuerySignal(opts.queryText);
+  const slots = extractTemporalSlots(opts.queryText);
+  const recencyLambda = Math.max(0, opts.recencyLambda ?? 0.00001);
+  const now = opts.nowMs ?? Date.now();
+  const maxSelected = Math.max(1, Math.floor(opts.maxSelected ?? 3));
+
+  const decorated = items.map((item) => {
+    const semanticScore = clamp01(typeof item.finalScore === "number" ? item.finalScore : item.score ?? 0);
+    const recencyScore = computeRecencyScore(item, now, recencyLambda);
+    const temporalAnchorDensity = getTemporalAnchorDensity(
+      `${typeof item.metadata.collection === "string" ? item.metadata.collection : "unknown"}::${item.id}`,
+      item.text,
+    );
+    const { coverage, matches } = computeSlotCoverage(slots, item.text);
+    const finalScore = clamp01(
+      (0.40 * semanticScore) +
+      (0.25 * recencyScore) +
+      (0.20 * temporalAnchorDensity) +
+      (0.15 * coverage) +
+      (temporalQuery.active ? 0.05 : 0),
+    );
+    return {
+      item,
+      semanticScore,
+      recencyScore,
+      temporalAnchorDensity,
+      slotCoverage: coverage,
+      slotMatches: matches,
+      finalScore,
+    };
+  });
+
+  const selectedIDs = new Set<string>();
+  const coveredSlots = new Set<string>();
+  const selected: SearchResult[] = [];
+
+  for (let pass = 0; pass < maxSelected; pass += 1) {
+    let best: (typeof decorated)[number] | null = null;
+    let bestScore = Number.NEGATIVE_INFINITY;
+
+    for (const candidate of decorated) {
+      if (selectedIDs.has(candidate.item.id)) {
+        continue;
+      }
+      const marginalCoverage = candidate.slotMatches.filter((slot) => !coveredSlots.has(slot)).length / Math.max(1, slots.length);
+      const combined = candidate.finalScore + (0.25 * marginalCoverage);
+      if (combined > bestScore) {
+        best = candidate;
+        bestScore = combined;
+      }
+    }
+
+    if (!best || bestScore < 0.12) {
+      break;
+    }
+
+    selectedIDs.add(best.item.id);
+    for (const slot of best.slotMatches) {
+      coveredSlots.add(slot);
+    }
+    selected.push({
+      ...best.item,
+      finalScore: best.finalScore,
+    });
+  }
+
+  const remaining = decorated
+    .filter((candidate) => !selectedIDs.has(candidate.item.id))
+    .sort((left, right) => right.finalScore - left.finalScore)
+    .map((candidate) => ({
+      ...candidate.item,
+      finalScore: candidate.finalScore,
+    }));
+
+  const ranked = [...selected, ...remaining];
+  const debug = decorated
+    .sort((left, right) => right.finalScore - left.finalScore)
+    .map((candidate) => ({
+      id: candidate.item.id,
+      text: candidate.item.text,
+      selected: selectedIDs.has(candidate.item.id),
+      temporalAnchorDensity: candidate.temporalAnchorDensity,
+      semanticScore: candidate.semanticScore,
+      recencyScore: candidate.recencyScore,
+      slotCoverage: candidate.slotCoverage,
+      slotMatches: candidate.slotMatches,
+      finalScore: candidate.finalScore,
+      rationale: buildTemporalRecoveryRationale(candidate.slotCoverage, candidate.temporalAnchorDensity, candidate.semanticScore),
+    }));
+
+  return { ranked, debug, temporalQuery, slots };
+}
+
+export function decideTemporalSelectorGuard(
+  queryText: string,
+  temporalQuery: TemporalQuerySignal = detectTemporalQuerySignal(queryText),
+): TemporalSelectorGuardDecision {
+  const slots = extractTemporalSlots(queryText);
+  if (!temporalQuery.active) {
+    return {
+      shouldApply: false,
+      slots,
+      reason: "temporal query gate inactive",
+    };
+  }
+
+  const strongCompositionalPattern = temporalQuery.matchedPatterns.some((pattern) =>
+    pattern === "how many days" ||
+    pattern === "how long" ||
+    pattern === "before or after" ||
+    pattern === "since or between"
+  );
+  if (!strongCompositionalPattern) {
+    return {
+      shouldApply: false,
+      slots,
+      reason: "query lacks strong compositional temporal pattern",
+    };
+  }
+
+  if (slots.length !== 2) {
+    return {
+      shouldApply: false,
+      slots,
+      reason: "query did not resolve to exactly two temporal slots",
+    };
+  }
+
+  return {
+    shouldApply: true,
+    slots,
+    reason: "strong temporal query with two-slot decomposition",
+  };
+}
+
+export function resetTemporalCachesForTest(): void {
+  temporalAnchorCache.clear();
+}
+
+function extractTemporalSlots(text: string): string[] {
+  const clauses = text
+    .split(/(?:\bafter\b|\bbefore\b|\bbetween\b|\bor\b|\band\b|\bthen\b|[?.!,;]+)/i)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  const slots = new Set<string>();
+
+  for (const clause of clauses) {
+    const terms = normalizeTerms(clause)
+      .filter((term) => term.length >= 3 && !TEMPORAL_SLOT_STOPWORDS.has(term));
+    if (terms.length === 0) {
+      continue;
+    }
+    if (terms.length <= 3) {
+      slots.add(terms.join(" "));
+      continue;
+    }
+    slots.add(terms.slice(0, 4).join(" "));
+    slots.add(terms.slice(-4).join(" "));
+  }
+
+  if (slots.size === 0) {
+    const fallback = normalizeTerms(text).filter((term) => term.length >= 3 && !TEMPORAL_SLOT_STOPWORDS.has(term));
+    if (fallback.length > 0) {
+      slots.add(fallback.slice(0, 4).join(" "));
+    }
+  }
+
+  return [...slots].slice(0, 4);
+}
+
+function computeSlotCoverage(slots: string[], candidateText: string): { coverage: number; matches: string[] } {
+  if (slots.length === 0) {
+    return { coverage: 0, matches: [] };
+  }
+
+  const candidateTerms = new Set(normalizeTerms(candidateText));
+  const matches: string[] = [];
+  let covered = 0;
+
+  for (const slot of slots) {
+    const slotTerms = normalizeTerms(slot).filter((term) => term.length >= 3);
+    if (slotTerms.length === 0) {
+      continue;
+    }
+    const overlap = slotTerms.filter((term) => candidateTerms.has(term)).length / slotTerms.length;
+    if (overlap >= 0.5) {
+      covered += 1;
+      matches.push(slot);
+    }
+  }
+
+  return {
+    coverage: covered / Math.max(1, slots.length),
+    matches,
+  };
+}
+
+function buildTemporalRecoveryRationale(slotCoverage: number, anchorDensity: number, semanticScore: number): string {
+  if (slotCoverage >= 0.5 && anchorDensity >= 0.5) {
+    return "slot coverage and temporal anchors both supported this candidate";
+  }
+  if (slotCoverage >= 0.5) {
+    return "slot coverage lifted this candidate toward the query's subevents";
+  }
+  if (anchorDensity >= 0.5) {
+    return "temporal anchors lifted this candidate toward the query's date logic";
+  }
+  if (semanticScore >= 0.6) {
+    return "semantic similarity kept this candidate in the temporal pool";
+  }
+  return "candidate remained in the bounded temporal recovery pool";
+}
+
+function computeRecencyScore(item: SearchResult, now: number, recencyLambda: number): number {
+  const ts = typeof item.metadata.ts === "number" ? item.metadata.ts : now;
+  const ageSeconds = Math.max(0, now - ts) / 1000;
+  return Math.exp(-recencyLambda * ageSeconds);
+}
+
+function normalizeTerms(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/i)
+    .filter((term) => term.length > 0);
+}
+
+function touchTemporalAnchorCache(cacheKey: string, value: number): void {
+  if (temporalAnchorCache.has(cacheKey)) {
+    temporalAnchorCache.delete(cacheKey);
+  }
+  temporalAnchorCache.set(cacheKey, value);
+  if (temporalAnchorCache.size > TEMPORAL_ANCHOR_CACHE_MAX) {
+    const oldestKey = temporalAnchorCache.keys().next().value;
+    if (typeof oldestKey === "string") {
+      temporalAnchorCache.delete(oldestKey);
+    }
+  }
+}
+
+function clamp01(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}

package/src/tokens.ts

@@ -21,6 +21,22 @@ export function fitPromptBudget(items: SearchResult[], budget: number): SearchRe
   return selected;
 }
 
+export function fitPromptBudgetFirstFit(items: SearchResult[], budget: number): SearchResult[] {
+  const selected: SearchResult[] = [];
+  let used = 0;
+
+  for (const item of items) {
+    const cost = estimateTokens(item.text);
+    if (used + cost > budget) {
+      continue;
+    }
+    selected.push(item);
+    used += cost;
+  }
+
+  return selected;
+}
+
 export function countTokens(messages: Array<{ content: string }>): number {
   return messages.reduce((sum, msg) => sum + estimateTokens(msg.content), 0);
 }

package/src/types.ts

@@ -203,12 +203,23 @@ export interface ContextAssembleResult {
       id: string;
       text: string;
       selected: boolean;
+      tokenEstimate: number;
+      temporalAnchorDensity: number;
       semanticScore: number;
+      slotCoverage?: number;
+      slotMatches?: string[];
       lexicalCoverage: number;
       recencyScore: number;
       finalScore: number;
       rationale: string;
     }>;
+    recoveryReserveTokens?: number;
+    temporalQueryIndicator?: number;
+    temporalQueryActive?: boolean;
+    temporalQueryPatterns?: string[];
+    temporalSelectorApplied?: boolean;
+    temporalSelectorReason?: string;
+    temporalRecoverySlots?: string[];
   };
 }