@remnic/core 1.0.0

package/dist/recall-state.d.ts

@@ -0,0 +1,113 @@
+import { RecallPlanMode, IdentityInjectionMode } from './types.js';
+
+interface LastRecallBudgetSummary {
+    requestedTopK?: number;
+    appliedTopK: number;
+    recallBudgetChars: number;
+    maxMemoryTokens: number;
+    qmdFetchLimit?: number;
+    qmdHybridFetchLimit?: number;
+    finalContextChars?: number;
+    truncated?: boolean;
+    includedSections?: string[];
+    omittedSections?: string[];
+}
+interface LastRecallSnapshot {
+    sessionKey: string;
+    recordedAt: string;
+    queryHash: string;
+    queryLen: number;
+    memoryIds: string[];
+    namespace?: string;
+    traceId?: string;
+    plannerMode?: RecallPlanMode;
+    requestedMode?: RecallPlanMode;
+    source?: string;
+    fallbackUsed?: boolean;
+    sourcesUsed?: string[];
+    budgetsApplied?: LastRecallBudgetSummary;
+    latencyMs?: number;
+    resultPaths?: string[];
+    policyVersion?: string;
+    identityInjectionMode?: IdentityInjectionMode | "none";
+    identityInjectedChars?: number;
+    identityInjectionTruncated?: boolean;
+}
+interface GraphRecallExpandedEntry {
+    path: string;
+    score: number;
+    namespace: string;
+    seed: string;
+    hopDepth: number;
+    decayedWeight: number;
+    graphType: "entity" | "time" | "causal";
+}
+declare function clampGraphRecallExpandedEntries(entries: unknown, maxEntries?: number): GraphRecallExpandedEntry[];
+interface TierMigrationCycleSummary {
+    trigger: "extraction" | "maintenance" | "manual";
+    scanned: number;
+    migrated: number;
+    promoted: number;
+    demoted: number;
+    limit: number;
+    dryRun: boolean;
+    skipped?: string;
+    errorCount?: number;
+}
+interface TierMigrationStatusSnapshot {
+    updatedAt: string;
+    lastCycle: TierMigrationCycleSummary | null;
+    totals: {
+        cycles: number;
+        scanned: number;
+        migrated: number;
+        promoted: number;
+        demoted: number;
+        errors: number;
+    };
+}
+declare class LastRecallStore {
+    private readonly statePath;
+    private readonly impressionsPath;
+    private state;
+    constructor(memoryDir: string);
+    load(): Promise<void>;
+    get(sessionKey: string): LastRecallSnapshot | null;
+    getMostRecent(): LastRecallSnapshot | null;
+    /**
+     * Persist last-recall snapshot and append an impression log entry.
+     * Does not store raw query text; uses a stable hash for correlation.
+     */
+    record(opts: {
+        sessionKey: string;
+        query: string;
+        memoryIds: string[];
+        namespace?: string;
+        traceId?: string;
+        plannerMode?: RecallPlanMode;
+        requestedMode?: RecallPlanMode;
+        source?: string;
+        fallbackUsed?: boolean;
+        sourcesUsed?: string[];
+        budgetsApplied?: LastRecallBudgetSummary;
+        latencyMs?: number;
+        resultPaths?: string[];
+        policyVersion?: string;
+        appendImpression?: boolean;
+        identityInjection?: {
+            mode: IdentityInjectionMode | "none";
+            injectedChars: number;
+            truncated: boolean;
+        };
+    }): Promise<void>;
+}
+declare class TierMigrationStatusStore {
+    private readonly statePath;
+    private state;
+    constructor(memoryDir: string);
+    load(): Promise<void>;
+    get(): TierMigrationStatusSnapshot;
+    recordCycle(summary: TierMigrationCycleSummary): Promise<void>;
+}
+
+export { type GraphRecallExpandedEntry, type LastRecallBudgetSummary, type LastRecallSnapshot, LastRecallStore, type TierMigrationCycleSummary, type TierMigrationStatusSnapshot, TierMigrationStatusStore, clampGraphRecallExpandedEntries };

package/dist/recall-state.js

@@ -0,0 +1,12 @@
+import {
+  LastRecallStore,
+  TierMigrationStatusStore,
+  clampGraphRecallExpandedEntries
+} from "./chunk-HG2NKWR2.js";
+import "./chunk-KWBU5S5U.js";
+export {
+  LastRecallStore,
+  TierMigrationStatusStore,
+  clampGraphRecallExpandedEntries
+};
+//# sourceMappingURL=recall-state.js.map

package/dist/recall-state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/recall-tokenization.d.ts

@@ -0,0 +1,4 @@
+declare function normalizeRecallTokens(value: string, extraStopWords?: string[]): string[];
+declare function countRecallTokenOverlap(queryTokens: Set<string>, value: string | undefined, extraStopWords?: string[]): number;
+
+export { countRecallTokenOverlap, normalizeRecallTokens };

package/dist/recall-tokenization.js

@@ -0,0 +1,9 @@
+import {
+  countRecallTokenOverlap,
+  normalizeRecallTokens
+} from "./chunk-DT5TVLJE.js";
+export {
+  countRecallTokenOverlap,
+  normalizeRecallTokens
+};
+//# sourceMappingURL=recall-tokenization.js.map

package/dist/recall-tokenization.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/reconstruct.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Memory reconstruction (E-Mem-inspired).
+ *
+ * Scans recalled memories for entity references that lack context
+ * in the recall set, then identifies candidates for targeted retrieval.
+ */
+/**
+ * Find entity names mentioned in recalled snippets that are known entities
+ * but not represented in the recalled entity refs.
+ *
+ * Uses word-boundary matching to avoid false positives from substring overlap
+ * (e.g., "person-alice" inside "person-alice-chen").
+ */
+declare function findUnresolvedEntityRefs(recalledSnippets: string[], recalledEntityRefs: string[], knownEntities: string[]): string[];
+
+export { findUnresolvedEntityRefs };

package/dist/reconstruct.js

@@ -0,0 +1,7 @@
+import {
+  findUnresolvedEntityRefs
+} from "./chunk-X7XN6YU4.js";
+export {
+  findUnresolvedEntityRefs
+};
+//# sourceMappingURL=reconstruct.js.map

package/dist/reconstruct.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/release-changelog.d.ts

@@ -0,0 +1,7 @@
+interface PromoteUnreleasedChangelogOptions {
+    version: string;
+    date: string;
+}
+declare function promoteUnreleasedChangelog(changelog: string, options: PromoteUnreleasedChangelogOptions): string;
+
+export { type PromoteUnreleasedChangelogOptions, promoteUnreleasedChangelog };

package/dist/release-changelog.js

@@ -0,0 +1,30 @@
+// src/release-changelog.ts
+function promoteUnreleasedChangelog(changelog, options) {
+  const unreleasedMarker = "## [Unreleased]";
+  const unreleasedIndex = changelog.indexOf(unreleasedMarker);
+  if (unreleasedIndex === -1) {
+    throw new Error("CHANGELOG.md is missing the Unreleased section");
+  }
+  const afterMarker = changelog.slice(unreleasedIndex + unreleasedMarker.length);
+  const nextSectionMatch = afterMarker.match(/\n## \[/);
+  const unreleasedEnd = nextSectionMatch == null ? changelog.length : unreleasedIndex + unreleasedMarker.length + (nextSectionMatch.index ?? 0);
+  const before = changelog.slice(0, unreleasedIndex + unreleasedMarker.length);
+  const unreleasedBody = changelog.slice(unreleasedIndex + unreleasedMarker.length, unreleasedEnd);
+  const after = changelog.slice(unreleasedEnd);
+  if (unreleasedBody.trim().length === 0) {
+    return changelog;
+  }
+  const normalizedVersion = options.version.replace(/^v/i, "");
+  const normalizedBody = unreleasedBody.replace(/^\n+/, "").replace(/\n+$/, "");
+  const releaseSection = `
+
+## [v${normalizedVersion}] - ${options.date}
+
+${normalizedBody}
+`;
+  return `${before}${releaseSection}${after}`;
+}
+export {
+  promoteUnreleasedChangelog
+};
+//# sourceMappingURL=release-changelog.js.map

package/dist/release-changelog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/release-changelog.ts"],"sourcesContent":["export interface PromoteUnreleasedChangelogOptions {\n  version: string;\n  date: string;\n}\n\nexport function promoteUnreleasedChangelog(\n  changelog: string,\n  options: PromoteUnreleasedChangelogOptions,\n): string {\n  const unreleasedMarker = \"## [Unreleased]\";\n  const unreleasedIndex = changelog.indexOf(unreleasedMarker);\n  if (unreleasedIndex === -1) {\n    throw new Error(\"CHANGELOG.md is missing the Unreleased section\");\n  }\n\n  const afterMarker = changelog.slice(unreleasedIndex + unreleasedMarker.length);\n  const nextSectionMatch = afterMarker.match(/\\n## \\[/);\n  const unreleasedEnd =\n    nextSectionMatch == null\n      ? changelog.length\n      : unreleasedIndex + unreleasedMarker.length + (nextSectionMatch.index ?? 0);\n\n  const before = changelog.slice(0, unreleasedIndex + unreleasedMarker.length);\n  const unreleasedBody = changelog.slice(unreleasedIndex + unreleasedMarker.length, unreleasedEnd);\n  const after = changelog.slice(unreleasedEnd);\n\n  if (unreleasedBody.trim().length === 0) {\n    return changelog;\n  }\n\n  const normalizedVersion = options.version.replace(/^v/i, \"\");\n  const normalizedBody = unreleasedBody.replace(/^\\n+/, \"\").replace(/\\n+$/, \"\");\n  const releaseSection = `\\n\\n## [v${normalizedVersion}] - ${options.date}\\n\\n${normalizedBody}\\n`;\n  return `${before}${releaseSection}${after}`;\n}\n"],"mappings":";AAKO,SAAS,2BACd,WACA,SACQ;AACR,QAAM,mBAAmB;AACzB,QAAM,kBAAkB,UAAU,QAAQ,gBAAgB;AAC1D,MAAI,oBAAoB,IAAI;AAC1B,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AAEA,QAAM,cAAc,UAAU,MAAM,kBAAkB,iBAAiB,MAAM;AAC7E,QAAM,mBAAmB,YAAY,MAAM,SAAS;AACpD,QAAM,gBACJ,oBAAoB,OAChB,UAAU,SACV,kBAAkB,iBAAiB,UAAU,iBAAiB,SAAS;AAE7E,QAAM,SAAS,UAAU,MAAM,GAAG,kBAAkB,iBAAiB,MAAM;AAC3E,QAAM,iBAAiB,UAAU,MAAM,kBAAkB,iBAAiB,QAAQ,aAAa;AAC/F,QAAM,QAAQ,UAAU,MAAM,aAAa;AAE3C,MAAI,eAAe,KAAK,EAAE,WAAW,GAAG;AACtC,WAAO;AAAA,EACT;AAEA,QAAM,oBAAoB,QAAQ,QAAQ,QAAQ,OAAO,EAAE;AAC3D,QAAM,iBAAiB,eAAe,QAAQ,QAAQ,EAAE,EAAE,QAAQ,QAAQ,EAAE;AAC5E,QAAM,iBAAiB;AAAA;AAAA,OAAY,iBAAiB,OAAO,QAAQ,IAAI;AAAA;AAAA,EAAO,cAAc;AAAA;AAC5F,SAAO,GAAG,MAAM,GAAG,cAAc,GAAG,KAAK;AAC3C;","names":[]}

package/dist/relevance.d.ts

@@ -0,0 +1,18 @@
+declare class RelevanceStore {
+    private readonly statePath;
+    private state;
+    constructor(memoryDir: string);
+    load(): Promise<void>;
+    /**
+     * Record a thumbs up/down for a memory ID.
+     * This is intentionally lightweight; it should never block agent execution.
+     */
+    record(memoryId: string, vote: "up" | "down", note?: string): Promise<void>;
+    /**
+     * Convert feedback into a small score adjustment.
+     * Intended to be used as a tie-breaker/soft bias, not a hard filter.
+     */
+    adjustment(memoryId: string): number;
+}
+
+export { RelevanceStore };

package/dist/relevance.js

@@ -0,0 +1,8 @@
+import {
+  RelevanceStore
+} from "./chunk-BRK4ODMI.js";
+import "./chunk-KWBU5S5U.js";
+export {
+  RelevanceStore
+};
+//# sourceMappingURL=relevance.js.map

package/dist/relevance.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/rerank.d.ts

@@ -0,0 +1,57 @@
+interface RerankCandidate {
+    id: string;
+    originalIndex: number;
+}
+interface RerankScore {
+    id: string;
+    score: number;
+}
+interface RerankCacheEntry {
+    expiresAtMs: number;
+    rankedIds: string[];
+}
+declare class RerankCache {
+    private entries;
+    get(key: string): string[] | null;
+    set(key: string, rankedIds: string[], ttlMs: number): void;
+}
+/**
+ * Parse a rerank response (JSON) and return candidates sorted by score.
+ *
+ * Rules:
+ * - Unknown IDs in the response are ignored.
+ * - Candidates missing from the response keep relative order after scored ones.
+ * - Stable tie-breaker: originalIndex ascending.
+ */
+declare function parseRerankResponse(raw: string, candidates: RerankCandidate[]): Array<RerankCandidate & {
+    score?: number;
+}>;
+declare function rerankLocalOrNoop(opts: {
+    query: string;
+    candidates: Array<{
+        id: string;
+        snippet: string;
+    }>;
+    local: {
+        chatCompletion: (messages: Array<{
+            role: string;
+            content: string;
+        }>, options?: {
+            maxTokens?: number;
+            temperature?: number;
+            timeoutMs?: number;
+            operation?: string;
+            priority?: "recall-critical" | "background";
+        }) => Promise<{
+            content: string;
+        } | null>;
+    };
+    enabled: boolean;
+    timeoutMs: number;
+    maxCandidates: number;
+    cache?: RerankCache;
+    cacheEnabled: boolean;
+    cacheTtlMs: number;
+}): Promise<string[] | null>;
+
+export { RerankCache, type RerankCacheEntry, type RerankCandidate, type RerankScore, parseRerankResponse, rerankLocalOrNoop };

package/dist/rerank.js

@@ -0,0 +1,11 @@
+import {
+  RerankCache,
+  parseRerankResponse,
+  rerankLocalOrNoop
+} from "./chunk-C7VW7C3F.js";
+export {
+  RerankCache,
+  parseRerankResponse,
+  rerankLocalOrNoop
+};
+//# sourceMappingURL=rerank.js.map

package/dist/rerank.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/resolve-provider-secret.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolve a provider API key from various OpenClaw formats.
+ *
+ * Resolution order:
+ * 1. Plain-text string → returned immediately
+ * 2. Gateway's resolveApiKeyForProvider → handles all secret ref formats
+ * 3. Environment variable fallback (PROVIDER_NAME_API_KEY)
+ * 4. undefined → provider is skipped in the fallback chain
+ */
+declare function resolveProviderApiKey(providerId: string, apiKeyValue: unknown, gatewayConfig?: unknown, agentDir?: string): Promise<string | undefined>;
+/**
+ * Clear the resolution cache (useful for testing or key rotation).
+ */
+declare function clearSecretCache(): void;
+
+export { clearSecretCache, resolveProviderApiKey };

package/dist/resolve-provider-secret.js

@@ -0,0 +1,11 @@
+import {
+  clearSecretCache,
+  resolveProviderApiKey
+} from "./chunk-LU3GQNDQ.js";
+import "./chunk-MARWOCVP.js";
+import "./chunk-KWBU5S5U.js";
+export {
+  clearSecretCache,
+  resolveProviderApiKey
+};
+//# sourceMappingURL=resolve-provider-secret.js.map

package/dist/resolve-provider-secret.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/resume-bundles.d.ts

@@ -0,0 +1,66 @@
+type ResumeBundleSource = "tool_result" | "cli" | "system" | "manual";
+interface ResumeBundle {
+    schemaVersion: 1;
+    bundleId: string;
+    recordedAt: string;
+    sessionKey: string;
+    source: ResumeBundleSource;
+    scope: string;
+    summary: string;
+    objectiveStateSnapshotRefs?: string[];
+    workProductEntryRefs?: string[];
+    commitmentEntryRefs?: string[];
+    keyFacts?: string[];
+    nextActions?: string[];
+    riskFlags?: string[];
+    metadata?: Record<string, string>;
+}
+interface ResumeBundleStatus {
+    enabled: boolean;
+    rootDir: string;
+    bundlesDir: string;
+    bundles: {
+        total: number;
+        valid: number;
+        invalid: number;
+        bySource: Partial<Record<ResumeBundleSource, number>>;
+        latestBundleId?: string;
+        latestRecordedAt?: string;
+        latestSessionKey?: string;
+    };
+    latestBundle?: ResumeBundle;
+    invalidBundles: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+declare function resolveResumeBundleDir(memoryDir: string, overrideDir?: string): string;
+declare function validateResumeBundle(raw: unknown): ResumeBundle;
+declare function buildResumeBundleFromState(options: {
+    memoryDir: string;
+    sessionKey: string;
+    bundleId: string;
+    recordedAt: string;
+    scope: string;
+    source?: ResumeBundleSource;
+    transcriptEnabled?: boolean;
+    objectiveStateMemoryEnabled?: boolean;
+    objectiveStateStoreDir?: string;
+    creationMemoryEnabled?: boolean;
+    workProductLedgerDir?: string;
+    commitmentLedgerEnabled?: boolean;
+    commitmentLedgerDir?: string;
+    maxRefsPerStore?: number;
+}): Promise<ResumeBundle>;
+declare function recordResumeBundle(options: {
+    memoryDir: string;
+    resumeBundleDir?: string;
+    bundle: ResumeBundle;
+}): Promise<string>;
+declare function getResumeBundleStatus(options: {
+    memoryDir: string;
+    resumeBundleDir?: string;
+    enabled: boolean;
+}): Promise<ResumeBundleStatus>;
+
+export { type ResumeBundle, type ResumeBundleSource, type ResumeBundleStatus, buildResumeBundleFromState, getResumeBundleStatus, recordResumeBundle, resolveResumeBundleDir, validateResumeBundle };

package/dist/resume-bundles.js

@@ -0,0 +1,27 @@
+import {
+  buildResumeBundleFromState,
+  getResumeBundleStatus,
+  recordResumeBundle,
+  resolveResumeBundleDir,
+  validateResumeBundle
+} from "./chunk-QANCTXQF.js";
+import "./chunk-CULXMQJH.js";
+import "./chunk-UV2FO7J4.js";
+import "./chunk-LOBRX7VD.js";
+import "./chunk-YRMVARQP.js";
+import "./chunk-FYIYMQ5N.js";
+import "./chunk-ISY75RLM.js";
+import "./chunk-Z5LAYHGJ.js";
+import "./chunk-MARWOCVP.js";
+import "./chunk-DT5TVLJE.js";
+import "./chunk-KWBU5S5U.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+export {
+  buildResumeBundleFromState,
+  getResumeBundleStatus,
+  recordResumeBundle,
+  resolveResumeBundleDir,
+  validateResumeBundle
+};
+//# sourceMappingURL=resume-bundles.js.map

package/dist/resume-bundles.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/retrieval-agents.d.ts

@@ -0,0 +1,129 @@
+import { QmdSearchResult } from './types.js';
+import { QmdClient } from './qmd.js';
+import './port-C1GZFv8h.js';
+
+/**
+ * Parallel Specialized Retrieval (v9.1 — ASMR-inspired)
+ *
+ * Replaces single-pass hybrid search with three parallel specialized agents:
+ *
+ *   1. DirectFactAgent  — entity-first lookup via entity filename index (<5ms)
+ *   2. ContextualAgent  — existing hybridSearch (same cost as current single-pass)
+ *   3. TemporalAgent    — temporal index prefilter + recency scoring (<10ms)
+ *
+ * All agents run via Promise.all(), so total latency = max(agents), not sum.
+ * No new LLM inference is introduced — agents reuse existing search primitives.
+ *
+ * Graceful degradation: any agent error/timeout does not block the others.
+ *
+ * References:
+ *   - Supermemory ASMR: https://blog.supermemory.ai/...
+ *   - Spec: docs/ideas/parallel-specialized-retrieval.md
+ */
+
+type SearchAgentSource = "direct" | "contextual" | "temporal";
+interface ParallelSearchResult extends QmdSearchResult {
+    /** Which retrieval agent produced this result. */
+    agentSource: SearchAgentSource;
+}
+/** Source-based weights applied during merge. Higher = higher confidence/precision. */
+declare const PARALLEL_AGENT_WEIGHTS: Record<SearchAgentSource, number>;
+/**
+ * Decide whether a given agent should run for this query.
+ * Agent 1 (direct) is the only one that may be skipped — when the query
+ * contains no proper-noun-like tokens, entity lookups will return nothing.
+ * Agents 2 (contextual) and 3 (temporal) always run.
+ */
+declare function shouldRunAgent(agent: SearchAgentSource, query: string, knownEntityCount: number): boolean;
+/**
+ * Direct Facts Agent — entity-first retrieval.
+ *
+ * Reads entity filenames from the entities directory and scores them by
+ * keyword overlap with the query. Returns matching entity file paths as
+ * QmdSearchResult[]. Zero LLM inference; pure file I/O.
+ *
+ * Cost: readdir on entities/ + filename scoring. Typically <5ms.
+ *
+ */
+declare function runDirectAgent(query: string, memoryDir: string, maxResults?: number): Promise<ParallelSearchResult[]>;
+/**
+ * Temporal Agent — recency-focused retrieval.
+ *
+ * Uses the temporal index (index_time.json) to find memories from the
+ * recent time window derived from the query (default: last 7 days).
+ * Combines recency decay with query-filename token overlap so results stay
+ * relevant to the query content, not just recency. Zero LLM inference; File I/O + math.
+ *
+ * Cost: read index_time.json + date range scan. Typically <10ms.
+ */
+declare function runTemporalAgent(query: string, memoryDir: string, maxResults?: number, 
+/** Optional candidate set from query-aware prefilter. Applied BEFORE the top-K cap so
+ * in-scope entries are not displaced by newer out-of-scope entries. */
+candidatePaths?: Set<string> | null): Promise<ParallelSearchResult[]>;
+/**
+ * Contextual Agent — broad semantic/hybrid search.
+ *
+ * Delegates to the existing hybridSearch (BM25 + vector). Same cost as the
+ * current single-pass retrieval — this agent introduces no additional LLM calls.
+ */
+declare function runContextualAgent(query: string, qmd: QmdClient, collection: string | undefined, maxResults: number, signal?: AbortSignal): Promise<ParallelSearchResult[]>;
+/**
+ * Merge pre-computed direct and temporal agent results with contextual results.
+ *
+ * This is the merge half of augmentWithDirectAndTemporal. Expose it separately so
+ * callers that started agents concurrently with the contextual search (for true
+ * parallel latency) can merge after all three complete, without re-running agents.
+ *
+ * Handles the same cases as augmentWithDirectAndTemporal:
+ * - Returns contextual unchanged (no reweighting) when both agents return nothing
+ * - Applies maxResults cap in all paths
+ * - Populates snippets for results discovered only by specialized agents
+ */
+declare function mergeWithAgentResults(contextualResults: QmdSearchResult[], directResults: ParallelSearchResult[], temporalResults: ParallelSearchResult[], weights: Record<SearchAgentSource, number>, maxResults: number): Promise<QmdSearchResult[]>;
+/**
+ * Augment a set of contextual (hybridSearch) results with direct and temporal
+ * agent results, returning a merged, deduplicated list.
+ *
+ * **Test helper** — production recall uses the inline orchestrator path which
+ * passes namespace-specific directories to each agent. This function uses a
+ * simplified single-directory contract suitable for unit tests.
+ *
+ * Direct and temporal agents run in parallel, then all three are merged with
+ * configurable weights.
+ *
+ * Contextual weight is always applied to `contextualResults` so scoring is
+ * consistent regardless of whether direct/temporal agents return anything.
+ *
+ * Snippets: snippets from contextual results are preserved during merge. For
+ * results discovered only by direct/temporal agents (no contextual match),
+ * the first ~200 chars of the file are read as a fallback preview so downstream
+ * formatters and rerankers have content to work with, not just a path.
+ */
+declare function augmentWithDirectAndTemporal(query: string, memoryDir: string, contextualResults: QmdSearchResult[], weights: Record<SearchAgentSource, number>, maxPerAgent: number, maxResults: number, 
+/** Optional candidate set from query-aware prefilter (time/tag scoped). Agents' results are
+ * filtered to this set when provided so recall stays within the operator-specified scope. */
+candidatePaths?: Set<string> | null): Promise<QmdSearchResult[]>;
+interface ParallelRetrievalOptions {
+    collection?: string;
+    maxResults?: number;
+    signal?: AbortSignal;
+    /** If true, skip the contextual agent (hybridSearch is already running externally). */
+    skipContextual?: boolean;
+    /** Max results per agent (capped before merge). */
+    maxResultsPerAgent?: number;
+    /** Override default agent weights. Falls back to PARALLEL_AGENT_WEIGHTS when absent. */
+    agentWeights?: Record<SearchAgentSource, number>;
+}
+/**
+ * Run parallel specialized retrieval agents and merge results.
+ *
+ * When `skipContextual` is true, only the direct and temporal agents run.
+ * This is the intended usage inside the orchestrator, where hybridSearch
+ * already runs as the primary search — we augment with the cheap extra agents.
+ *
+ * Total latency = max(agent_latencies), not sum.
+ * Agent errors are isolated — others still return results.
+ */
+declare function parallelRetrieval(query: string, qmd: QmdClient, memoryDir: string, options?: ParallelRetrievalOptions): Promise<QmdSearchResult[]>;
+
+export { PARALLEL_AGENT_WEIGHTS, type ParallelRetrievalOptions, type ParallelSearchResult, type SearchAgentSource, augmentWithDirectAndTemporal, mergeWithAgentResults, parallelRetrieval, runContextualAgent, runDirectAgent, runTemporalAgent, shouldRunAgent };

package/dist/retrieval-agents.js

@@ -0,0 +1,23 @@
+import {
+  PARALLEL_AGENT_WEIGHTS,
+  augmentWithDirectAndTemporal,
+  mergeWithAgentResults,
+  parallelRetrieval,
+  runContextualAgent,
+  runDirectAgent,
+  runTemporalAgent,
+  shouldRunAgent
+} from "./chunk-GPGBSNKM.js";
+import "./chunk-V3RXWQIE.js";
+import "./chunk-KWBU5S5U.js";
+export {
+  PARALLEL_AGENT_WEIGHTS,
+  augmentWithDirectAndTemporal,
+  mergeWithAgentResults,
+  parallelRetrieval,
+  runContextualAgent,
+  runDirectAgent,
+  runTemporalAgent,
+  shouldRunAgent
+};
+//# sourceMappingURL=retrieval-agents.js.map

package/dist/retrieval-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/retrieval.d.ts

@@ -0,0 +1,19 @@
+interface QueryExpansionOptions {
+    maxQueries: number;
+    minTokenLen: number;
+}
+interface RuntimeRetrievalPolicy {
+    recencyWeight?: number;
+}
+declare function applyRuntimeRetrievalPolicy(base: {
+    recencyWeight: number;
+}, runtime: RuntimeRetrievalPolicy | null): {
+    recencyWeight: number;
+};
+/**
+ * Cheap, deterministic query expansion.
+ * Produces additional queries biased toward the most salient tokens in the input.
+ */
+declare function expandQuery(query: string, options: QueryExpansionOptions): string[];
+
+export { type QueryExpansionOptions, type RuntimeRetrievalPolicy, applyRuntimeRetrievalPolicy, expandQuery };

package/dist/retrieval.js

@@ -0,0 +1,10 @@
+import {
+  applyRuntimeRetrievalPolicy,
+  expandQuery
+} from "./chunk-G3AG3KZN.js";
+import "./chunk-QCCCQT3O.js";
+export {
+  applyRuntimeRetrievalPolicy,
+  expandQuery
+};
+//# sourceMappingURL=retrieval.js.map

package/dist/retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/sanitize.d.ts

@@ -0,0 +1,9 @@
+type SanitizeResult = {
+    clean: boolean;
+    text: string;
+    violations: string[];
+};
+declare function sanitizeMemoryContent(text: string): SanitizeResult;
+declare function isSafeMemoryContent(text: string): boolean;
+
+export { type SanitizeResult, isSafeMemoryContent, sanitizeMemoryContent };