@snoai/memory 0.0.0-stage → 1.0.0

package/dist/index-DL8AVj0Z.d.ts

@@ -0,0 +1,571 @@
+import { z } from "zod";
+import { CHUNKING_VERSION, DEFAULT_AGGREGATION_CONFIG, DEFAULT_CHUNK_CONFIG, HEAD_EXTRACT_MIN_CONTENT_TOKENS, HEAD_EXTRACT_OVERLAP_DROP_RATIO, HEAD_EXTRACT_TOKEN_BUDGET } from "@snoai/chunking";
+import { LOCAL_EMBEDDING_MODEL } from "@snoai/embedder";
+//#region config/index.d.ts
+/** Maximum wait for sidecar requests and resource cleanup during shutdown. */
+declare const MEMORY_SHUTDOWN_TIMEOUT_MS: number;
+/**
+ * Final result floor, applied to the POST-scoring-pipeline score (after the
+ * multiplicative shrinker chain: importance, length-norm, time-decay,
+ * retention). That chain routinely compresses a genuinely relevant match to
+ * 0.03-0.06 once a memory ages past its decay half-life — a real, expected
+ * production scenario, not an edge case. The old value (0.37) was calibrated
+ * against the PRE-shrinker fused score scale and silently rejected almost
+ * all real recall once shrinkers applied (confirmed 2026-07-05 scoring-
+ * pipeline audit). 0 matches the only value ever proven end-to-end
+ * (LoCoMo stratified-100, 86%, `evals/locomo/outputs/stratified-100-20260705-002827`);
+ * shipped and tested must be the same config. Re-introducing a nonzero floor
+ * needs fresh measured data post the A2/A3 fixes below, not a guess.
+ */
+declare const DEFAULT_MIN_SCORE = 0;
+/** Hard floor applied before any score amplification in the pipeline. See
+ * `DEFAULT_MIN_SCORE` — same reasoning, same fix. */
+declare const DEFAULT_HARD_MIN_SCORE = 0;
+/** Default importance score for new memories (0.0–1.0) */
+declare const DEFAULT_IMPORTANCE = .7;
+/** Default scope for memories without explicit scope */
+declare const DEFAULT_SCOPE = "global";
+/** Default embedding vector dimension (Voyage AI 1024-d) */
+declare const VECTOR_DIMENSION_DEFAULT = 1024;
+/** Plugin version identifier */
+declare const PLUGIN_VERSION = "0.9.74";
+/** Production sno.ai host origin used by @snoai/observability. */
+declare const SNO_OBSERVE_DEFAULT_BASE_URL = "https://www.sno.ai";
+/** Default observability agent id for OpenClaw plugin emits. */
+declare const SNO_OBSERVE_DEFAULT_AGENT_ID = "openclaw";
+/** Bounded lifecycle observe flush — enough headroom for the SDK to complete one HTTP POST batch. */
+declare const SNO_OBSERVE_FLUSH_TIMEOUT_MS = 8e3;
+/** Default top-K results returned from search */
+declare const DEFAULT_TOP_K = 10;
+/** Default and minimum character-estimated token budgets for one recall result. */
+declare const DEFAULT_RECALL_TOKEN_BUDGET = 7e3;
+declare const MIN_RECALL_TOKEN_BUDGET = 5e3;
+/** Weight for vector (semantic) branch in hybrid score fusion */
+declare const DEFAULT_VECTOR_WEIGHT = .7;
+/** Weight for BM25 (keyword) branch in hybrid score fusion */
+declare const DEFAULT_BM25_WEIGHT = .3;
+/** Initial candidate pool size for precision recall search */
+declare const CANDIDATE_POOL_SIZE = 64;
+/**
+ * Hard ceiling for candidate pool expansion. Also the retrieval limit `memory_recall` asks for,
+ * so it bounds how much of a live store one answer can see. Raised 100 → 512 on 2026-09-06 (owner
+ * order): atomic rows are small and many, and at 100 a 159-row live store served 76 rows per
+ * question, cutting live to-dos the question asked for; at 512 the whole store came back for
+ * 3,476 tokens, half the recall token budget. Raised again 512 -> 2048 on 2026-09-15: the pool is
+ * `max(candidatePoolSize, limit * 2)` clamped here, so at 512 a caller asking for more than 256
+ * memories silently got fewer, and the ceiling — not the ranking — decided what the model saw.
+ */
+declare const MAX_CANDIDATE_POOL_SIZE = 2048;
+/**
+ * How many candidates one `memory_recall` call retrieves and ranks.
+ *
+ * Split from `MAX_CANDIDATE_POOL_SIZE` on 2026-09-15. The tool used to ask for that ceiling
+ * directly, so raising the ceiling to let auto-recall inject more memories would also have made
+ * every tool call fuse and rerank four times as many rows for a result the token packer bounds
+ * at `DEFAULT_RECALL_TOKEN_BUDGET` anyway. This keeps the tool's cost where it was measured.
+ */
+declare const MAX_RECALL_TOOL_CANDIDATES = 512;
+/**
+ * How many of a subject's live profile and state rows, most similar first, the REM replace wave
+ * pairs each such row with (PRD 140 REQ-8). A persona's live profile holds 72–107 rows (measured
+ * 2026-09-07), so 128 reaches every row of one subject; it catches what the write-time cap below
+ * leaves out.
+ */
+declare const ARRIVAL_RETIREMENT_CANDIDATE_CAP = 128;
+/**
+ * How many older live profile and state rows of the project, most similar first, a newly
+ * written row is judged against at write time, one conflict-adjudication call per pair (PRD 140
+ * REQ-2). A measured correction pair was its subject's most similar pair (0.688 against 0.495–0.618
+ * for the others, 2026-09-23); a target outside this cap is left to the REM replace wave.
+ */
+declare const ARRIVAL_RETIREMENT_JUDGED_CANDIDATE_CAP = 10;
+/**
+ * Measurement-only overrides for the block 210 retrieval-breadth experiment.
+ *
+ * Both are OFF unless the named environment variable is set, and neither is
+ * reachable from the plugin configuration schema, so a deployed plugin cannot
+ * turn them on: the experiment harness sets them on the process it starts and
+ * nothing else does. They exist because the runtime and the schema both stop
+ * the candidate pool at `MAX_CANDIDATE_POOL_SIZE`, which makes the pool-200
+ * cell impossible to run at all without one enabling edit (PRD 210 DEC-1).
+ *
+ * Read at call time, not at import time, so a harness that sets the variable
+ * after this module loads still gets the value it asked for.
+ */
+declare function experimentCandidatePoolOverride(): number | undefined;
+/** True only while the block 210 experiment harness has asked for MMR off. */
+declare function experimentMmrDisabled(): boolean;
+/**
+ * Maximum aggregation evidence rows materialized into one recall result.
+ * Derived from the largest measured population (290) plus ~10% headroom, then raised with the
+ * candidate pool ceiling on 2026-09-06 so a whole-population read can serve past that ceiling.
+ * This bounds the synchronous storage read; a separate token budget bounds
+ * the serialized tool result.
+ */
+declare const MAX_AGGREGATION_ROWS = 640;
+/**
+ * Token budget for the aggregation payload ONE consumer receives.
+ *
+ * Derived, and every number is a measurement. The answering engine's context is 64K tokens (owner,
+ * 2026-08-14, raised from 32K with the Qwen 3.8 rollout); half is reserved for the question, the
+ * surrounding prompt and the answer, leaving 32K for recalled evidence. Measured with
+ * `dev-scripts/census-aggregation-payload.mts` against the largest real store
+ * (`academic_researcher_weekly`, 138 active profile/episodic rows): the ENTIRE population renders in
+ * 43,699 characters ~= 10,925 tokens, a sixth of the context. A complete aggregation is therefore
+ * the ordinary case on real data, not an aspiration.
+ *
+ * The HALF is the load-bearing part, not the literal number. When the context moved to 64K this
+ * constant did not move with it for one commit, and a budget that stays put while its derivation
+ * doubles silently becomes a quarter of the context — a tightening nobody decided and nobody would
+ * find. That is the same shape as defect 2 below. If the context changes again, this changes.
+ *
+ * Known trade, stated rather than discovered later: widening this window is what raised aggregation
+ * from 0.045 to 0.744 on 2026-08-13, and it is also what dropped FAA 0.647 -> 0.600 in the same
+ * run, because retired rows the old ceiling had hidden came back into view. The answer to that is
+ * REM removing them (PRD 30/40), never a smaller recall window — shrinking this to protect FAA
+ * re-severs the counting path, which is the defect this constant exists to record.
+ *
+ * This replaces three ceilings that stacked on one path and severed it. Measured on the full
+ * benchmark run of 2026-08-13: 30 counting questions scored 0.045 mean with 28 of them exactly
+ * 0.000, while the same personas' other 60 questions scored 0.748. The model was not wrong — asked
+ * for a week of steps it answered "14,392 steps (recorded on June 7). No other step data is logged
+ * for the rest of the week", because 8 rows of 138 reached it. A model cannot total rows it was
+ * never shown. The three were:
+ *
+ *   1. `MAX_AGGREGATION_OUTPUT_ROWS = 8` — no derivation anywhere; 5.8% of a population handed to a
+ *      question whose entire job is to total that population.
+ *   2. `MAX_AGGREGATION_TOOL_RESULT_CHARS = 16_384` — a unit error. 16,384 was the OLD 16K context
+ *      in TOKENS, applied as a CHARACTER count, binding 3-4x tighter than it read.
+ *   3. Charging each consumer for the other's copy: the budget measured `JSON.stringify(result)`,
+ *      which carries every row twice — once rendered, once in `memories` — while the OpenClaw host
+ *      reads only the rendered text and the eval reads only `memories`.
+ *
+ * So this budget is counted in tokens, against the larger of the two consumer views, never a sum.
+ */
+declare const MAX_AGGREGATION_RESULT_TOKENS = 32768;
+/** Pool size = max(candidatePoolSize, limit * PRECISION_RECALL_POOL_SIZE_FACTOR) */
+declare const PRECISION_RECALL_POOL_SIZE_FACTOR = 2;
+/** Enable age-based retrieval scoring only when explicitly requested. */
+declare const TEMPORAL_WEIGHTING_DEFAULT: boolean;
+/** Recency boost half-life in days (entries this old get 50% boost) */
+declare const RECENCY_HALF_LIFE_DAYS = 14;
+/** Additive recency boost magnitude */
+declare const RECENCY_WEIGHT = .1;
+/** Maximum allowed recency weight */
+declare const RECENCY_WEIGHT_MAX = .5;
+/** Base multiplier for importance weighting (score * (base + importance * base)) */
+declare const IMPORTANCE_WEIGHT_BASE = .7;
+/**
+ * Reference text length for log normalization (longer texts penalized).
+ * 0 disables the stage (see `applyLengthNormalization`'s early-return).
+ * Disabled 2026-07-05: confirmed actively harmful, not just miscalibrated —
+ * it demotes memories by parent-document verbosity, not by how much of the
+ * matched chunk is relevant, and was the dominant compressor feeding the
+ * MMR scale-mismatch bug (see MMR_LAMBDA below). Anchor value 500 (chars)
+ * also never matched the chunk geometry (256-448 tokens) it was scoring.
+ */
+declare const LENGTH_NORM_ANCHOR = 0;
+/** Time decay half-life in days */
+declare const TIME_DECAY_HALF_LIFE_DAYS = 60;
+/** Minimum time decay multiplier (floor for very old entries) */
+declare const TIME_DECAY_FLOOR = .6;
+/** Dynamic memories use a shorter half-life when temporal decay is enabled */
+declare const TEMPORAL_DYNAMIC_HALF_LIFE_DIVISOR = 3;
+/**
+ * Relevance vs diversity tradeoff for MMR (0.7 = 70% relevance, 30% diversity).
+ * `applyMmrDiversity` normalizes the relevance term to [0,1] (batch-max) before
+ * applying this weight — without that normalization, the shrinker chain above
+ * compresses relevance so far below the [0,1] cosine-similarity diversity term
+ * that this ratio was moot (diversity always won). Fixed 2026-07-05.
+ */
+declare const MMR_LAMBDA = .7;
+/** Weight for fusion score in rerank blend */
+declare const RERANK_BLEND_VECTOR = .3;
+/** Weight for cross-encoder score in rerank blend */
+declare const RERANK_BLEND_CROSS = .7;
+/** Fusion-score weight in local cosine-blend rerank */
+declare const LIGHTWEIGHT_FUSION_WEIGHT = .7;
+/** Cosine-similarity weight in local cosine-blend rerank */
+declare const LIGHTWEIGHT_COSINE_WEIGHT = .3;
+/** Default rerank model identifier */
+declare const DEFAULT_RERANK_MODEL = "rerank-2";
+/** Default timeout for rerank API calls in milliseconds */
+declare const DEFAULT_RERANK_TIMEOUT_MS = 15e3;
+/**
+ * How many rerank batches may be in flight at once. A candidate pool of
+ * `MAX_CANDIDATE_POOL_SIZE` divided by a provider's per-request batch limit is 11 requests for
+ * TEI, and sending them one after another put `DEFAULT_RERANK_TIMEOUT_MS` on the clock 11 times
+ * over. Four is what the Sno GPU serves concurrently at near-linear 4x (owner-measured
+ * 2026-08-17); the first failing wave still ends the whole rerank, so a wedged reranker costs one
+ * timeout rather than one per batch.
+ */
+declare const DEFAULT_RERANK_BATCH_CONCURRENCY = 4;
+/**
+ * Texts per HTTP request, applied whatever `rerankMaxCandidates` allows out in total: that one
+ * is the operator's budget, this one is the transport's own per-request limit.
+ *
+ * Confirmed 2026-09-14 against the deployed self-hosted ranker, which answers a 51-text request
+ * with `{"error":"too many texts: max 50, got 51"}`. Such a deployment rejects an over-limit
+ * batch outright rather than truncating it, and the retriever files that HTTP 400 as "reranker
+ * unavailable" — so getting this wrong degrades every call to raw fusion order with no visible
+ * error.
+ *
+ * It binds every provider, not only the self-hosted one it was measured against. Making it
+ * conditional on the configured provider name put the guarantee in a deploy script instead of
+ * in the code. Hosted providers (voyage, jina, pinecone, dashscope) document much higher
+ * limits, so holding them to this one only sends more, smaller requests, which the rerank waves
+ * already run four at a time.
+ */
+declare const DEFAULT_TEI_RERANK_MAX_CANDIDATES = 50;
+/**
+ * THE per-record token ceiling, and the only number of its kind in this repository (owner
+ * ruling 2026-09-14). One stored memory record, one embedder input, one rerank candidate,
+ * one row rendered into an aggregation answer: each is at most this many tokens, counted by
+ * the embedder's own tokenizer (`Embedder.countTokens`), never estimated from characters.
+ * Why one number: the local ONNX embedder silently truncates past its context window, the
+ * Sno reranker silently truncates past its own, and a record longer than either scores on
+ * its first half only — measured 2026-09-14, a claim placed past the cut ranked 0.0001.
+ * The reranker's window is shared with the query and a fixed instruction, so this ceiling
+ * must leave that room. It does NOT leave it by itself: a record at this ceiling plus any
+ * query at all is already past the reranker's window, which is why the rerank path cuts the
+ * request copy of a candidate down to what the query leaves, inside this same number.
+ * The two tokenizers are no longer one vocabulary either — the deployed ranking model is not
+ * the embedder's model (measured 2026-09-14), so a count taken here is an estimate of the
+ * ranker's count, and the ranker's own refusal is the only exact measure.
+ * Extraction is told to split anything longer (skill `extract-atomic-memory`); the store
+ * refuses a longer record outright. Every other size in this file that describes a piece
+ * of a record derives from this constant — do not write its value, or a fraction of it, as
+ * a literal anywhere else.
+ */
+declare const DEFAULT_MAX_CONTEXT_TOKENS = 512;
+/**
+ * Tokens the ranking model's own prompt template adds to a pair, on top of the query and the
+ * document. Measured against the deployed endpoint 2026-09-14: a 509-token pair is accepted
+ * and reported back as 512 input tokens, and a 510-token pair is refused as 513.
+ */
+declare const RERANK_PROMPT_TEMPLATE_TOKENS = 3;
+/** Maximum lines per chunk before forcing an earlier split at a line boundary */
+declare const DEFAULT_MAX_LINES_PER_CHUNK = 50;
+/** Default list query page size */
+declare const DEFAULT_LIST_LIMIT = 50;
+/**
+ * Maximum allowed list query page size; also caps each search branch
+ * (`memory-store-search-api.ts` clamps both the semantic and the keyword branch to it), so it
+ * stays >= the pool ceiling. Derived, not written: left at a literal 512 when the pool ceiling
+ * went 512 -> 2048 on 2026-09-15, every branch silently returned at most 512 candidates while
+ * retrieval asked for up to 2048, and the ceiling decided what ranking never saw.
+ */
+declare const MAX_LIST_LIMIT: typeof MAX_CANDIDATE_POOL_SIZE;
+/** Maximum number of to-dos prepended to one recall result */
+declare const MAX_RECALLED_TODOS = 50;
+declare const MAX_RECALLED_TODO_TOKENS = 1e3;
+/**
+ * Ceiling for chunk-level fetch budgets (semantic/keyword chunk search).
+ * Deliberately independent of MAX_LIST_LIMIT: memory-level wrappers overfetch
+ * chunks (limit * 8) so one high-recall parent cannot collapse parent diversity.
+ */
+declare const MAX_CHUNK_FETCH_LIMIT = 4096;
+/** Batch size for bulk delete operations (respects SQLite ~32k bind-param limit) */
+declare const DELETE_BATCH_SIZE = 500;
+/** Default limit for forget-query similarity search */
+declare const FORGET_QUERY_DEFAULT_LIMIT = 10;
+/** Minimum score threshold for forget-query matches */
+declare const FORGET_QUERY_MIN_SCORE = .8;
+/**
+ * Minimum age of the newest backup before another is taken (1 day). A backup is a full copy of
+ * the store, so an hourly cadence cost a 1.7 GB store 40 GB of disk a day.
+ */
+declare const BACKUP_INTERVAL_MS = 864e5;
+/** Number of backup files to retain before rotation */
+declare const BACKUP_RETENTION_COUNT = 6;
+/**
+ * Share of the backup volume that must stay free. Before a backup is written the oldest backups are
+ * deleted until the copy fits above this floor, and again afterwards if the volume is still under
+ * it; the newest backup is always kept, and when even that is not enough the backup is skipped.
+ */
+declare const BACKUP_MIN_FREE_DISK_RATIO = .1;
+/** How often the maintenance timer wakes to see which jobs are due (1 hour). */
+declare const MAINTENANCE_TICK_MS = 36e5;
+/** Full-page integrity sweep (1 hour). */
+declare const INTEGRITY_CHECK_INTERVAL_MS = 36e5;
+/** Usage-telemetry outbox drain and quarantine cleanup (1 hour). */
+declare const USAGE_OUTBOX_INTERVAL_MS = 36e5;
+/** Pruning of expired recall/inject usage events (1 hour). */
+declare const USAGE_EVENT_RETENTION_INTERVAL_MS = 36e5;
+/** Full-text index segment merge (1 hour). */
+declare const FTS_MERGE_INTERVAL_MS = 36e5;
+/** Query-planner statistics refresh (1 hour). */
+declare const PLANNER_STATISTICS_INTERVAL_MS = 36e5;
+/**
+ * How often the automatic REM trigger is evaluated (1 hour). Evaluating is only a check: REM
+ * itself runs on its own daily schedule and volume rule in src/sidecar/rem-trigger.ts.
+ */
+declare const REM_TRIGGER_CHECK_INTERVAL_MS = 36e5;
+/** Embedder LRU cache max entries */
+declare const CACHE_SIZE = 256;
+/** Embedder LRU cache TTL in milliseconds (30 minutes) */
+declare const CACHE_TTL_MS = 18e5;
+/** Kill switch file check interval in milliseconds */
+declare const KILL_SWITCH_CACHE_TTL_MS = 100;
+/** Cost estimate cache TTL in milliseconds */
+declare const COST_ESTIMATE_CACHE_TTL_MS = 5e3;
+/** Max sessions tracked in LRU map */
+declare const MAX_TRACKED_SESSIONS = 100;
+/** Max recall history entries per session */
+declare const MAX_SESSION_RECALL_ENTRIES = 200;
+/** Default number of recent messages to read from a session file */
+declare const DEFAULT_SESSION_MESSAGE_COUNT = 15;
+/** Chunk size for reading last JSON line from session files */
+declare const LAST_JSON_LINE_CHUNK_BYTES = 4096;
+/** Token budget per session-summary chunk sent to the model */
+declare const SESSION_SUMMARY_CHUNK_TOKENS = 4096;
+/**
+ * Total token budget for a session-summary transcript before chunking. Message count is bounded
+ * upstream but per-message text is not, so a handful of very large messages can otherwise produce
+ * an effectively unlimited number of chunks. The most-recent portion is kept (drop-oldest).
+ */
+declare const SESSION_SUMMARY_MAX_INPUT_TOKENS = 32768;
+/**
+ * Hard cap on sequential model calls in one reset-time session-summary capture. Backstops the input
+ * budget so a single capture can never run indefinitely even if the pre-chunk budget has a gap. At
+ * the default 30s per-chunk timeout this bounds a capture to roughly SESSION_SUMMARY_MAX_CHUNKS × 30s.
+ */
+declare const SESSION_SUMMARY_MAX_CHUNKS = 8;
+/** Transcript budget shared by an atomic window and its preceding context. */
+declare const ATOMIC_EXTRACTION_MAX_INPUT_TOKENS = 4096;
+declare const ATOMIC_ENRICHMENT_OUTPUT_TOKEN_BUDGET = 1400;
+/**
+ * Output cap of one capture call. The capture reply lists every claim and then every fact with
+ * its quote, roughly 70 tokens per fact; at 4,096 a 35-turn session replayed as one turn hit the
+ * cap and lost the whole window (43 of 272 LoCoMo sessions, measured 2026-09-13). A window is
+ * split by turns when a reply truncates, so a single long turn (a pasted document, a replayed
+ * session) has only this cap between it and total loss. Sized from the budget, not the failure:
+ * the prompt (skill, calendar reference, response schema, dictionaries) is about 10K tokens, the
+ * transcript at most ATOMIC_EXTRACTION_MAX_INPUT_TOKENS, and the model serves a 64K context, so
+ * 16,384 keeps the whole call near 30K; the longest LoCoMo session (40 messages, ~100 facts)
+ * needs about 10K, which 8,192 only just covered.
+ */
+declare const ATOMIC_CAPTURE_OUTPUT_TOKEN_BUDGET = 16384;
+/**
+ * Wall time one capture call is given. The generic client timeout is what an installation sets
+ * for short judgments (30s by default, 60s on the LoCoMo VM) and does not know this call's output
+ * budget, so raising the budget silently made the call unfinishable: measured 2026-09-20, four
+ * sessions produced `LlmClientTerminalError category=timeout` at 60s after 105-130s of work and
+ * stored nothing. Sized from the budget at the extraction model's measured ~60 output tokens per
+ * second, with the same headroom the budget carries.
+ */
+declare const ATOMIC_CAPTURE_TIMEOUT_MS = 3e5;
+/** Minimum text length for CJK content to be captured */
+declare const CAPTURE_MIN_LENGTH_CJK = 4;
+/** Minimum text length for non-CJK content to be captured */
+declare const CAPTURE_MIN_LENGTH_STANDARD = 10;
+/** Maximum character length of auto-recall query before truncation */
+declare const DEFAULT_AUTO_RECALL_MAX_QUERY_LENGTH = 2e3;
+/** Maximum emoji count before content is rejected as noise */
+declare const CAPTURE_MAX_EMOJI_COUNT = 3;
+/** Minimum trimmed text length before content is classified as noise */
+declare const NOISE_MIN_TEXT_LENGTH = 5;
+/**
+ * Whether ambient-learning requires a text to match the `MEMORY_TRIGGERS` regex
+ * whitelist (e.g. `i prefer`, `my X is Y`, `we decided`, `remember`, ...).
+ *
+ * When `true`, texts lacking any trigger keyword are dropped — high precision,
+ * low recall. The bench corpus exposes the cost: teach turns like
+ *   "My team lead at Anthropic is Maya Patel"  (fails `my\s+\w+\s+is` — 4 words)
+ *   "My go-to coffee is an oat milk latte"     (fails — "go-to" has hyphen)
+ *   "My teammates on Glacier are Jin ..."      (fails — "are" not "is")
+ * were silently dropped, contributing 5 of 7 missing probes at 53%.
+ *
+ * When `false`, only length / noise / prompt-injection filters apply.
+ * Content-hash dedup in the store keeps volume bounded.
+ *
+ * Bench history:
+ *   - true  → 53% (post-runtime-fix baseline).
+ *   - false → TBD (under evaluation 2026-04-17).
+ */
+declare const AMBIENT_LEARNING_REQUIRE_TRIGGER_MATCH: boolean;
+/**
+ * Top-K memories injected into the agent's prepend context at
+ * `before_agent_start`. Higher values expose more facts but increase
+ * prompt size + reranker workload.
+ *
+ * Bench history (LoCoMo mid, 50 rows, isolated sessions, 2026-04-22):
+ *   - 5 → 52% (original default) — too many R3 refusals on specific-date/object
+ *     queries because the answer memory wasn't ranked in the top 5.
+ *   - 15 → 66% (+14pp) — opens the budget for list/count/temporal queries.
+ *     Peak score; the remaining failures are memories ranked beyond 15 or
+ *     wrong-content retrievals (architectural, not budget).
+ *   - 25 → 64% (−2pp vs 15) — wider top-k dilutes with noise; agent surfaces
+ *     adjacent-but-wrong memories.
+ *
+ * 2026-04-27 (commit 6a3ab60): raised to 20 — the Round-B chunked retrieval
+ * pipeline tightened candidate quality enough that the K=15→20 dilution risk
+ * noted above no longer dominated, and the wider budget caught list/count/
+ * temporal queries whose answer ranked 16-20 on conv0.
+ *
+ * 2026-07-02: re-tightened to 10 after the RETRIEVAL_CHUNK_PROFILE migration
+ * (target 384→512, max 448→1536) ballooned per-question prompts to ~123k
+ * chars and the score fell to 58%. That large-chunk profile was itself
+ * reverted the next day (`RETRIEVAL_STORAGE_CHUNK_PROFILE` back to
+ * 256/384/448/32, validated 86% on 2026-07-03) — but this constant was never
+ * reverted alongside it, leaving it stuck compensating for a regression that
+ * no longer exists.
+ *
+ * 2026-07-05: reverted to 20 to match. The shipped default must equal what
+ * the eval harness actually validates (`run-eval.sh` pins `recallTopK: 20`;
+ * the 86% run above used it) — production and eval must not diverge.
+ */
+declare const AUTO_RECALL_INJECTION_TOP_K = 20;
+/**
+ * Lean recall top-K — the lower-cost alternative surfaced in onboarding copy.
+ * Pre-512-geometry history (K=15 lean vs K=20 default, LoCoMo conv0 74-fact
+ * corpus, 4-run avg ±0.88pp): 86.25% correctness, ~9.3M prompt tokens /
+ * 400 QAs, ~25% cheaper than the then-default K=20.
+ *
+ * 2026-07-02: rescaled 15 → 8 alongside the default's 20 → 10 for a
+ * large-chunk profile that was itself reverted the next day. 2026-07-05:
+ * reverted to 15 alongside AUTO_RECALL_INJECTION_TOP_K's 10 → 20 revert,
+ * restoring the original ~0.75 lean:default ratio.
+ *
+ * This constant is the source of truth for the "Lean N" token in
+ * `openclaw.plugin.json` uiHints and the Path A install nudge.
+ * The plugin configuration test
+ * pins all four surfaces to this constant.
+ */
+declare const AUTO_RECALL_LEAN_TOP_K = 15;
+/** Default number of recent messages used for reflection input */
+declare const DEFAULT_REFLECTION_MESSAGE_COUNT = 120;
+/** Maximum input characters for reflection prompt */
+declare const DEFAULT_REFLECTION_MAX_INPUT_CHARS = 24e3;
+/** Timeout for individual reflection LLM calls in milliseconds */
+declare const DEFAULT_REFLECTION_TIMEOUT_MS = 2e4;
+/** Maximum error reminder entries included in reflection prompt */
+declare const DEFAULT_REFLECTION_ERROR_REMINDER_MAX_ENTRIES = 3;
+/** Session TTL in reflection tracking map (30 minutes) */
+declare const DEFAULT_REFLECTION_SESSION_TTL_MS: number;
+/** Maximum sessions tracked in reflection state */
+declare const DEFAULT_REFLECTION_MAX_TRACKED_SESSIONS = 200;
+/** Maximum chars scanned for error signals in conversation */
+declare const DEFAULT_REFLECTION_ERROR_SCAN_MAX_CHARS = 8e3;
+/** Maximum invariant entries extracted from a single reflection */
+declare const REFLECTION_MAX_INVARIANTS = 8;
+/** Maximum derived delta entries extracted from a single reflection */
+declare const REFLECTION_MAX_DERIVED = 10;
+/** Cosine similarity threshold above which a reflection is considered duplicate */
+declare const REFLECTION_DEDUP_THRESHOLD = .97;
+/** Minimum score for dedup similarity search (low to catch near-dupes) */
+declare const REFLECTION_DEDUP_MIN_SCORE = .1;
+/** Importance score assigned to stored reflection entries */
+declare const REFLECTION_IMPORTANCE = .75;
+/** Maximum filename collision retries for reflection FS output */
+declare const REFLECTION_MAX_FILENAME_ATTEMPTS = 10;
+/** Cache TTL for loaded reflection slices in milliseconds */
+declare const REFLECTION_SLICE_CACHE_TTL_MS = 15e3;
+/** Maximum age for derived deltas to be included in context (2 hours) */
+declare const REFLECTION_DERIVED_MAX_AGE_MS = 72e5;
+/**
+ * Minimum cosine score for `handleProfileMerge` to fire an unconditional merge
+ * on an identity row. NO dedup LLM gate runs after this — the threshold is
+ * the only filter — so it must be tight enough that "plausibly related"
+ * identity facts do not get merged together. Matched to the compaction
+ * clustering bar.
+ */
+declare const PROFILE_MERGE_THRESHOLD = .88;
+declare const RETRIEVAL_STORAGE_CHUNK_PROFILE: {
+  readonly minTokens: number;
+  readonly targetTokens: number;
+  readonly maxTokens: number;
+  readonly overlapTokens: number;
+};
+/** Minimum tokens per chunk before merge (mirrors RETRIEVAL_STORAGE_CHUNK_PROFILE). */
+declare const CHUNK_MIN_TOKENS: typeof RETRIEVAL_STORAGE_CHUNK_PROFILE.minTokens;
+/** Target tokens per chunk (mirrors RETRIEVAL_STORAGE_CHUNK_PROFILE). */
+declare const CHUNK_TARGET_TOKENS: typeof RETRIEVAL_STORAGE_CHUNK_PROFILE.targetTokens;
+/** Max tokens per chunk before split (mirrors RETRIEVAL_STORAGE_CHUNK_PROFILE). */
+declare const CHUNK_MAX_TOKENS: typeof RETRIEVAL_STORAGE_CHUNK_PROFILE.maxTokens;
+/** Overlap tokens between adjacent chunks (mirrors RETRIEVAL_STORAGE_CHUNK_PROFILE). */
+declare const CHUNK_OVERLAP_TOKENS: typeof RETRIEVAL_STORAGE_CHUNK_PROFILE.overlapTokens;
+/** Tokenizer mode used by the chunker (mirrors DEFAULT_CHUNK_CONFIG.tokenizerMode). */
+declare const CHUNK_TOKENIZER_MODE: typeof DEFAULT_CHUNK_CONFIG.tokenizerMode;
+/**
+ * Diagnostic threshold for intra-memory chunk cosine similarity (PRD §8.1).
+ * Pairs above this score are flagged as redundant during eval / introspection.
+ */
+declare const INTRA_MEMORY_COSINE_THRESHOLD = .92;
+/** Alias for VECTOR_DIMENSION_DEFAULT — the embedder output dimension. */
+declare const EMBEDDER_DIM: typeof VECTOR_DIMENSION_DEFAULT;
+/** Default embedder provider id stamped into chunk provenance. */
+declare const EMBEDDER_PROVIDER_DEFAULT: "local-onnx";
+/**
+ * Default embedder model id stamped into chunk provenance.
+ *
+ * Codex 2026-04-30 (batch-C C1): the previous hard-coded
+ * `qwen3-embedding-4b@1024` did not match the actual local default
+ * (`LOCAL_EMBEDDING_MODEL`, the bundled local embedding model), which would
+ * mislabel every default-provider chunk in eval traces. Tracking the
+ * embedder package's constant keeps provenance honest by construction.
+ */
+declare const EMBEDDER_MODEL_DEFAULT: typeof LOCAL_EMBEDDING_MODEL;
+/** SQL window cap on chunks per parent memory (prevents parent flooding). */
+declare const MAX_CHUNKS_PER_PARENT = 16;
+/** Per-hit bonus for repeated chunk hits inside one parent. */
+declare const MULTI_HIT_BONUS_PER_HIT: typeof DEFAULT_AGGREGATION_CONFIG.multiHitBonusPerHit;
+/** Cap on the cumulative multi-hit bonus per parent. */
+declare const MULTI_HIT_BONUS_CAP: typeof DEFAULT_AGGREGATION_CONFIG.multiHitBonusCap;
+/** Per-pair bonus for adjacent chunk hits within one parent. */
+declare const ADJACENCY_BONUS_PER_PAIR: typeof DEFAULT_AGGREGATION_CONFIG.adjacencyBonusPerPair;
+/** Cap on the cumulative adjacency bonus per parent. */
+declare const ADJACENCY_BONUS_CAP: typeof DEFAULT_AGGREGATION_CONFIG.adjacencyBonusCap;
+/** Invariant: bonusTotalInvariant >= MULTI_HIT_BONUS_CAP + ADJACENCY_BONUS_CAP. */
+declare const BONUS_TOTAL_INVARIANT: typeof DEFAULT_AGGREGATION_CONFIG.bonusTotalInvariant;
+/**
+ * Number of preceding chunks pulled into a snippet window.
+ *
+ * Override (not the package default) — LoCoMo eval showed multi-fact
+ * questions that span 4+ messages were partially answered when the window
+ * was 1 (e.g. "what events has Caroline done to help children" landed on
+ * mentorship but missed the school-speech chunk two messages away). Bumped
+ * to 2 paired with the head-extract metadata-preserve fix (2026-05-01).
+ * A later LoCoMo `3/3` trial improved mid-50 but regressed full conv0 by
+ * adding nearby distractors, so the stable default remains `2/2`.
+ */
+declare const SNIPPET_NEIGHBOR_BEFORE = 2;
+/** Number of following chunks pulled into a snippet window. See above. */
+declare const SNIPPET_NEIGHBOR_AFTER = 2;
+/** When false, retrieval traces are not written. Eval harness flips this on. */
+declare const EVAL_TRACE_ENABLED: boolean;
+/** Filename for the per-eval-run config snapshot. */
+declare const EVAL_CONFIG_SNAPSHOT_FILENAME: "config-snapshot.json";
+/** Filename for per-QA retrieval traces emitted during eval runs. */
+declare const EVAL_QA_TRACES_FILENAME: "qa_traces.jsonl";
+/** Multiplicative penalty applied to unreturned candidates after rerank. */
+declare const LIGHTWEIGHT_RERANK_PENALTY = .8;
+/** Maximum tokens kept in a sanitized FTS5 MATCH expression. */
+declare const FTS_QUERY_TOKEN_CAP = 50;
+type RecallLifecycleConfigShape = {
+  retentionScorer: boolean;
+  tierPromoter: boolean;
+  autoRecallAccessTracking: boolean;
+  traceEnabled: boolean;
+  tierFloorMode: "bare" | "withFloor";
+  tierPromotionTopK: number;
+  accessRateLimitMs: number;
+  accessCountCeiling: number;
+};
+/**
+ * Zod schema for the `recallLifecycle` config block. The whole block defaults
+ * to `{}` so existing configs without it continue to parse and behave
+ * bit-for-bit identically to the pre-Phase-0 baseline.
+ *
+ * Spec: openspec/changes/mem-lifecycle/specs/config/spec.md.
+ */
+declare const recallLifecycleSchema: z.ZodType<RecallLifecycleConfigShape, unknown>;
+/** Inferred config shape for the `recallLifecycle` block. */
+type RecallLifecycleConfig = z.infer<typeof recallLifecycleSchema>;
+/**
+ * Resolved default `recallLifecycle` config. Use in code paths that need a
+ * literal default object instead of re-parsing the schema each time.
+ */
+declare const DEFAULT_RECALL_LIFECYCLE: RecallLifecycleConfig;
+//#endregion
+export { DEFAULT_VECTOR_WEIGHT as $, REFLECTION_MAX_FILENAME_ATTEMPTS as $t, DEFAULT_BM25_WEIGHT as A, MAX_RECALLED_TODOS as At, DEFAULT_REFLECTION_ERROR_SCAN_MAX_CHARS as B, NOISE_MIN_TEXT_LENGTH as Bt, CHUNK_MAX_TOKENS as C, experimentCandidatePoolOverride as Cn, MAINTENANCE_TICK_MS as Ct, CHUNK_TOKENIZER_MODE as D, MAX_CHUNKS_PER_PARENT as Dt, CHUNK_TARGET_TOKENS as E, MAX_CANDIDATE_POOL_SIZE as Et, DEFAULT_MAX_LINES_PER_CHUNK as F, MEMORY_SHUTDOWN_TIMEOUT_MS as Ft, DEFAULT_REFLECTION_TIMEOUT_MS as G, RECENCY_HALF_LIFE_DAYS as Gt, DEFAULT_REFLECTION_MAX_TRACKED_SESSIONS as H, PLUGIN_VERSION as Ht, DEFAULT_MIN_SCORE as I, MIN_RECALL_TOKEN_BUDGET as It, DEFAULT_RERANK_TIMEOUT_MS as J, REFLECTION_DEDUP_MIN_SCORE as Jt, DEFAULT_RERANK_BATCH_CONCURRENCY as K, RECENCY_WEIGHT as Kt, DEFAULT_RECALL_LIFECYCLE as L, MMR_LAMBDA as Lt, DEFAULT_IMPORTANCE as M, MAX_RECALL_TOOL_CANDIDATES as Mt, DEFAULT_LIST_LIMIT as N, MAX_SESSION_RECALL_ENTRIES as Nt, COST_ESTIMATE_CACHE_TTL_MS as O, MAX_CHUNK_FETCH_LIMIT as Ot, DEFAULT_MAX_CONTEXT_TOKENS as P, MAX_TRACKED_SESSIONS as Pt, DEFAULT_TOP_K as Q, REFLECTION_MAX_DERIVED as Qt, DEFAULT_RECALL_TOKEN_BUDGET as R, MULTI_HIT_BONUS_CAP as Rt, CHUNKING_VERSION as S, VECTOR_DIMENSION_DEFAULT as Sn, LIGHTWEIGHT_RERANK_PENALTY as St, CHUNK_OVERLAP_TOKENS as T, recallLifecycleSchema as Tn, MAX_AGGREGATION_ROWS as Tt, DEFAULT_REFLECTION_MESSAGE_COUNT as U, PRECISION_RECALL_POOL_SIZE_FACTOR as Ut, DEFAULT_REFLECTION_MAX_INPUT_CHARS as V, PLANNER_STATISTICS_INTERVAL_MS as Vt, DEFAULT_REFLECTION_SESSION_TTL_MS as W, PROFILE_MERGE_THRESHOLD as Wt, DEFAULT_SESSION_MESSAGE_COUNT as X, REFLECTION_DERIVED_MAX_AGE_MS as Xt, DEFAULT_SCOPE as Y, REFLECTION_DEDUP_THRESHOLD as Yt, DEFAULT_TEI_RERANK_MAX_CANDIDATES as Z, REFLECTION_IMPORTANCE as Zt, CACHE_TTL_MS as _, TEMPORAL_WEIGHTING_DEFAULT as _n, KILL_SWITCH_CACHE_TTL_MS as _t, ARRIVAL_RETIREMENT_JUDGED_CANDIDATE_CAP as a, RERANK_PROMPT_TEMPLATE_TOKENS as an, EVAL_QA_TRACES_FILENAME as at, CAPTURE_MIN_LENGTH_CJK as b, USAGE_EVENT_RETENTION_INTERVAL_MS as bn, LIGHTWEIGHT_COSINE_WEIGHT as bt, ATOMIC_ENRICHMENT_OUTPUT_TOKEN_BUDGET as c, SESSION_SUMMARY_CHUNK_TOKENS as cn, FORGET_QUERY_MIN_SCORE as ct, AUTO_RECALL_LEAN_TOP_K as d, SNIPPET_NEIGHBOR_AFTER as dn, HEAD_EXTRACT_MIN_CONTENT_TOKENS as dt, REFLECTION_MAX_INVARIANTS as en, DELETE_BATCH_SIZE as et, BACKUP_INTERVAL_MS as f, SNIPPET_NEIGHBOR_BEFORE as fn, HEAD_EXTRACT_OVERLAP_DROP_RATIO as ft, CACHE_SIZE as g, TEMPORAL_DYNAMIC_HALF_LIFE_DIVISOR as gn, INTRA_MEMORY_COSINE_THRESHOLD as gt, BONUS_TOTAL_INVARIANT as h, SNO_OBSERVE_FLUSH_TIMEOUT_MS as hn, INTEGRITY_CHECK_INTERVAL_MS as ht, ARRIVAL_RETIREMENT_CANDIDATE_CAP as i, RERANK_BLEND_VECTOR as in, EVAL_CONFIG_SNAPSHOT_FILENAME as it, DEFAULT_HARD_MIN_SCORE as j, MAX_RECALLED_TODO_TOKENS as jt, DEFAULT_AUTO_RECALL_MAX_QUERY_LENGTH as k, MAX_LIST_LIMIT as kt, ATOMIC_EXTRACTION_MAX_INPUT_TOKENS as l, SESSION_SUMMARY_MAX_CHUNKS as ln, FTS_MERGE_INTERVAL_MS as lt, BACKUP_RETENTION_COUNT as m, SNO_OBSERVE_DEFAULT_BASE_URL as mn, IMPORTANCE_WEIGHT_BASE as mt, ADJACENCY_BONUS_PER_PAIR as n, REM_TRIGGER_CHECK_INTERVAL_MS as nn, EMBEDDER_MODEL_DEFAULT as nt, ATOMIC_CAPTURE_OUTPUT_TOKEN_BUDGET as o, RETRIEVAL_STORAGE_CHUNK_PROFILE as on, EVAL_TRACE_ENABLED as ot, BACKUP_MIN_FREE_DISK_RATIO as p, SNO_OBSERVE_DEFAULT_AGENT_ID as pn, HEAD_EXTRACT_TOKEN_BUDGET as pt, DEFAULT_RERANK_MODEL as q, RECENCY_WEIGHT_MAX as qt, AMBIENT_LEARNING_REQUIRE_TRIGGER_MATCH as r, RERANK_BLEND_CROSS as rn, EMBEDDER_PROVIDER_DEFAULT as rt, ATOMIC_CAPTURE_TIMEOUT_MS as s, RecallLifecycleConfig as sn, FORGET_QUERY_DEFAULT_LIMIT as st, ADJACENCY_BONUS_CAP as t, REFLECTION_SLICE_CACHE_TTL_MS as tn, EMBEDDER_DIM as tt, AUTO_RECALL_INJECTION_TOP_K as u, SESSION_SUMMARY_MAX_INPUT_TOKENS as un, FTS_QUERY_TOKEN_CAP as ut, CANDIDATE_POOL_SIZE as v, TIME_DECAY_FLOOR as vn, LAST_JSON_LINE_CHUNK_BYTES as vt, CHUNK_MIN_TOKENS as w, experimentMmrDisabled as wn, MAX_AGGREGATION_RESULT_TOKENS as wt, CAPTURE_MIN_LENGTH_STANDARD as x, USAGE_OUTBOX_INTERVAL_MS as xn, LIGHTWEIGHT_FUSION_WEIGHT as xt, CAPTURE_MAX_EMOJI_COUNT as y, TIME_DECAY_HALF_LIFE_DAYS as yn, LENGTH_NORM_ANCHOR as yt, DEFAULT_REFLECTION_ERROR_REMINDER_MAX_ENTRIES as z, MULTI_HIT_BONUS_PER_HIT as zt };