@memongo/memory-engine

MongoDB-native memory engine for Memongo. Use this package when you need direct access to search, graph, episodes, structured memory, procedures, sync, telemetry, reasoning chains, novelty detection, access tracking, memory consolidation, and retrieval internals.

Install

npm install @memongo/memory-engine

When to use this package

• You are building server-side infrastructure around Memongo.
• You need direct engine access instead of the HTTP API.
• You want the lowest-level supported memory primitives in this repo.

Example

import { getMemorySearchManager } from "@memongo/memory-engine"

const { manager } = await getMemorySearchManager({
	cfg,
	agentId: "main",
})

if (!manager) {
	throw new Error("Memongo memory unavailable")
}

const results = await manager.search("release notes")

HTTP reranking

memory.mongodb.reranking.model defaults to rerank-3. Select rerank-3-lite, rerank-2.5, or rerank-2.5-lite explicitly to use that model; the engine sends that name without a model fallback.

The rank window defaults to 20 results. Positive finite topN values are floored and capped at 1,000, including at the HTTP boundary for direct callers. A value between zero and one resolves to an empty window and skips reranking. Blank passages within the window are omitted from the request; results beyond the window remain overflow rather than being discarded. Provider failures retain the existing input-order fallback, or throw when strict mode is enabled.

Configured instruction text is prepended to the query with a newline. This does not establish instruction-following support for rerank-3. Token limits and truncation remain provider-managed; the engine's document-count guard does not measure tokens. Model availability and retrieval quality require separate live qualification. This route uses HTTP, not MongoDB's native $rerank stage.

Consolidation lease behavior

An exact inferred-fact replay ignores only its run IDs and leaves the stored fact unchanged: no revision, reinforcement, re-embedding accounting, cache invalidation or mutation audit. This no-op reflects the writer's read snapshot; a concurrent invalidation may already have committed when it returns. Changed rationale, source order, other compared fields or explicit lifecycle intents retain the existing write path. Invalidated or expired rows are not skipped, and a stale expected revision still fails.

Before writing quarantine entries, structured facts, graph entities, projection diagnostics, inferred facts, deduplication merges, pruning updates or event acknowledgements, consolidation checks and renews its current run lease in the same MongoDB transaction as the write. An expired or replaced lease aborts the run with ConsolidationLeaseLostError before that write. Effects committed while the lease was valid remain durable.

The check advances the expiry to the later of server time plus the configured lease duration or the previous expiry plus one millisecond. This makes the lease check a modifying write, including when two checks occur within the same millisecond or the previous expiry is ahead of server time.

For finite lease durations of at least 3000ms, a heartbeat renews the lease during asynchronous work, including model calls, every third of the lease duration (up to the Node.js timer maximum). Shorter or non-finite durations do not start a timer. Renewal and content transactions are serialized; ticks coalesce while another transaction runs. An expired or replaced lease, an erasure conflict or another heartbeat failure blocks subsequent content writes and completion. A stalled event loop or a long transaction can still delay renewal beyond expiry. Timers are stopped and pending work is awaited before completion and on every post-claim exit. These checks remain separate from the tenant erasure fence. The initial lease claim and the batch recording incurred spend use the erasure fence without a run-lease check; spend recorded before lease loss is detected remains durable, while an earlier abort can skip the spend batch.

Memory intelligence modules

• mongodb-reasoning-chain.ts -- provenance chain traversal via $lookup on sourceEventIds
• mongodb-novelty.ts -- surprisal novelty detection using Atlas Vector Search centroid distance
• mongodb-access-tracker.ts -- AccessTracker with batched writes for memory access frequency
• mongodb-trust.ts -- computeImportanceDecay() with temporalScope-aware decay (permanent/ongoing memories never decay)
• mongodb-consolidator.ts -- offline consolidation agent (Dreamer) with rule-based pattern matching
• KB schema fields: wikiSource, vault, section for wiki source categorization

Most apps should use @memongo/memory-bridge or @memongo/client instead of calling the engine directly.

Access tracking and erasure

Production search captures tenant admission before reading and carries it through fallback searches into buffered access tracking. Raw history and canonical reinforcement flush sequentially in one fenced transaction per admitted epoch. Stale or malformed admission is discarded; ordinary write failures retain the original epoch and batch ID for retry.

The compatibility AccessTracker.recordAccess(target) call remains synchronous and starts admission for a new record intent immediately. flush() and close() await those pending admissions. To protect an earlier external read from erasure races, capture admission before that read and pass it as recordAccess(target, admission); the compatibility call cannot certify a read it did not admit. A token for another agent is rejected.

Existing time-series access_events collections are left intact. MongoDB cannot write them inside a transaction, so the tracker warns and skips raw history while retaining fenced canonical reinforcement. No automatic conversion or data deletion occurs. Ordinary sinks retain atomic raw and canonical writes.

Recall traces and erasure

Search and context-bundle operations pass admission captured before their source reads to the trace recorder. Trace inserts use that original epoch in a fenced transaction. Context-bundle admission touches the erasure gate in MongoDB; admission failure rejects the operation before filesystem or memory-source reads; trace failures after retrieval remain caught by the existing diagnostic logging paths.

The compatibility recordRecallTrace call without admission captures a new trace intent. It cannot certify an earlier external read; callers needing that guarantee must capture before reading and supply admission. Tokens belonging to another agent are rejected before privacy transformation or persistence. Query privacy modes and returned trace IDs retain their existing behavior.

Telemetry and erasure

Direct manager search telemetry uses admission captured before source reads, including query-clamp markers. Admitted telemetry inserts join a fenced transaction; failures stay asynchronous and produce a fixed warning, so they do not reject a finished search. KB admission failure prevents KB source reads. Every admitted telemetry write increments the per-user gate, so throughput under contention requires separate load evidence.

Legacy emitTelemetry calls retain their void return and capture a new diagnostic intent; they cannot certify an earlier external read. The existing session overload stays awaited by its caller and propagates insert failures. Disabled or sampled-out emissions do not touch MongoDB. Retained time-series telemetry sinks skip these non-session writes with a warning; conversion of retained data remains separate work.

searchV2 accepts original admission in its context and reuses it for input-clamp, throttle, and rewrite-clamp telemetry, including recursive backstops. Both search paths, context bundles, and relevance explanations pass the pre-read token. Relevance-explanation admission failure prevents source reads. External calls without admission retain new-intent telemetry and cannot certify an earlier external read.

Reranker and query-rewriter telemetry also inherit searchV2 admission. Their telemetry failures remain asynchronous, preserving provider results, fallback behavior, and strict provider errors. Direct leaf calls without admission retain new-intent telemetry and cannot certify an earlier external read. Provider error-log privacy and other diagnostic writers remain separate work.

Telemetry aggregation, cost-ledger failure, and all six manager recall-trace failure warnings retain fixed operation labels and finite numeric driver codes without serializing error text or payloads. These warnings do not add query digests. Their existing fallback results and asynchronous behavior are preserved. Other provider and planner error paths remain separate privacy work; errors implemented as proxies with throwing descriptor traps remain unsupported at this boundary.

Relevance report persistence carries the manager's original admission through legacy search, all eight V2 verdict branches, and relevance explain. The run and its artifacts commit sequentially with the gate serial in one transaction; local IDs, privacy transformations, and artifact serialization happen once before callback retries. Direct compatible callers without a token start a new intent at persistRun invocation and cannot certify an earlier external read. A failure during either insert rolls back both rows and the serial. An exhausted unknown-commit-result retry can still reject after commit; rejection alone does not establish absent rows. Best-effort search/explain callers preserve served results on persistence failure.

Cost-ledger recorders preserve the legacy void fire-and-forget API. Passing { admission } returns a promise and fences the counter upsert in the same transaction as its gate serial. Search and event/batch indexing pass their original admission; rejection is logged without changing their served result. Counts and timestamps are prepared once before transaction retries. Positive fractional counts still floor to zero and upsert, preserving prior behavior; zero/non-finite counts return without capturing admission. A no-options caller starts a new intent at recorder invocation and cannot certify earlier reads or provider work. Existing session-bound variants remain owned by their caller's transaction. Exhausted unknown-commit retries can reject after commit; callers do not retry the increment. Per-agent gate contention has not been load-tested.

Worker drains capture or validate one original admission before outbox repair, even for an empty queue. Their fingerprint prune, automatic consolidation job, expired-job dead-letter update and backlog telemetry each carry that admission. The entry read is a precondition; the modifying gate fence and same-session transaction protect each write against erasure advancing after entry. Prune and staging scheduling clocks advance after successful commit. Standalone admitted prune failures reject. The drain propagates stale-admission conflicts, but logs an ordinary prune failure and continues to the remaining preamble and claims; legacy operator prune remains best-effort. Timers, provider calls and local scheduling effects stay outside retryable transactions. Worker restart tails and cross-process timer coordination remain separate open work.

E98 worker preamble: the manager resolves the prune retention window and timestamp before the retryable transaction. The native retry check changes the environment after a first real update, forces the driver to replay the transaction, and verifies that only the originally eligible fingerprint is removed. Timer restart and wake admission are covered by the lifecycle checks below.

Manual extraction captures admission before scoped event reads and carries it through job creation and duplicate recovery. The insert and recovery use separate fenced transactions: duplicate-key errors escape the first callback before recovery starts. Recovery reads and any failed-job retry use the original session/epoch; an explicitly different stored epoch rejects. Legacy failed jobs acquire the current request epoch when requeued, while legacy pending/running jobs retain their existing lease-time upgrade. Local run contexts and worker wakes happen after the transaction result, with the original token. Remaining writer inventory work stays separate.

Worker startup and every wake validate the original request epoch before installing or replacing an interval. Single writes, batches, and manual extraction also carry the local generation captured before admission reads or queue delay; stop advances that generation, clears pending wakes and the interval, and waits for the latest owned worker promise. Pending wakes preserve explicit admission and prefer the newer epoch. Interval callbacks retain their token, generation, and timer identity; stale callbacks cannot cancel a newer interval. Ordinary startup validation errors retain a same-request retry interval. A manager retired by foreign erasure stays idle until a fresh local write or a new boot. These local timer checks supplement the per-write transaction fences; they do not make stop and cross-process erasure atomic, promise exact timer ordering, or prevent a genuinely fresh write from starting between local stop and erasure.

Public manager procedure writes capture admission before the dynamic leaf import and reject an entry belonging to another agent. Procedure persistence, revision history, indexing accounting, cache cleanup, and mutation audit then share the original gate transaction. A revision race starts a fresh transaction under the same original token, with at most three CAS attempts; each attempt derives its time from the revision it reads so supersession intervals cannot be inverted by a frozen earlier clock. Database-only audit IDs and clocks from aborted attempts never commit. Admitted calls reject a simultaneously supplied session and have no standalone direct-write fallback. Cache, cost, and audit failures roll back this admitted write. Existing session-only derived/consolidation calls and non-admitted direct leaf calls preserve their existing behavior. The change covers public procedure writes, while other lifecycle and legacy direct writers remain separate work.

Public writeStructuredMemory captures the original erasure admission before loading the writer. The admitted transaction covers canonical writes, revision snapshots, cache invalidation, indexing accounting, and mutation audit; quarantine disposition instead commits the gate and its quarantine row together. Failures propagate and roll back that transaction, with no standalone fallback. The driver's existing transient transaction retry reuses the original admission and re-evaluates per-attempt write clocks; explicit valid-time and expiration dates are preserved. Sequential quarantine deduplication remains unchanged; concurrent deduplication and unlabeled duplicate-key insert races are not addressed here. Direct non-admitted writers and quarantine promotion retain their existing behavior. Unknown commit outcomes, Atlas failover, and load behavior require separate validation.

By-handle structured and procedure updates capture the manager owner’s original admission before reading the target and carry it into the admitted writer. A foreign owner or token is rejected; an erased epoch cannot patch a recreated target. A target deleted after the initial read fails with the existing stale-revision conflict (actual revision 0 denotes an absent target), rather than being recreated. Structured patches held by injection classification still commit quarantine before returning the quarantine error. Quarantine promotion and writes without admission retain their separate documented limits.

Public structured and procedure invalidation captures the original owner admission before loading the leaf. Canonical invalidation, revision history, cache cleanup, and mutation audit share its transaction, and cache or audit errors abort it. Each callback retry reconstructs its snapshot state and clock under the same original token; procedure revision races retain their existing three-attempt outer CAS limit. A current already-invalidated handle remains a semantic no-op and commits one gate serial increment. Admitted invalidation rejects an external session and has no direct-write fallback. Existing non-admitted and session-only callers retain their behavior.

Public structured feedback captures and validates original owner admission before loading its leaf. Corrections and irrelevance delegate that token to the admitted update and invalidation paths. Confirmation writes its counter, cache cleanup, and content-bearing mutation audit in one fenced transaction, with sequential awaited operations and fresh callback state on retry. Quarantined corrections still commit their held content before returning the quarantine error. A missing confirmation target returns null, changes no content or cache, and commits one gate serial increment. Direct non-admitted feedback retains its existing detached-audit behavior.

Public procedure outcome reports validate owner and capture original admission before loading the leaf. The counter and date, cache cleanup, and content-bearing audit commit in one fenced transaction; errors abort it. Callback retries rebuild their state and clock and do not double-count an aborted increment. Outcome reports retain the existing operational behavior: they do not advance or require the handle revision and may count an invalidated procedure. A missing target returns null and commits one gate serial increment without content or cache changes. Concurrent reports contend on the per-agent gate; throughput and Atlas failover remain unmeasured. Direct non-admitted outcome calls and the separate legacy recordProcedureOutcome helper retain their existing behavior.

Public quarantine rejection captures original owner admission before reading the entry. Its decision and audit use two separate fenced transactions under that token. The decision remains durable when an ordinary audit failure returns auditError; a stale erasure admission propagates ERASURE_GATE_CONFLICT, including when erasure occurs between the committed decision and audit. Stale admission takes precedence over not-found or already-reviewed errors. Each decision callback rebuilds lease checks, timestamps, and status CAS on retry; live promotion leases remain protected. A successful rejection commits two gate serial increments; a failed audit commits only the decision increment. Direct non-admitted rejection retains its existing behavior. Promotion admission is described below; throughput, Atlas failover and unknown commit outcomes remain unmeasured.

Structured-write quarantine admission resolves and stores the same scope and scopeRef as canonical writing, so deduplication separates derived user, tenant, session and workspace partitions. Promotion also restores a stored candidate's sessionId. A missing required coordinate rejects before quarantine insertion. Rows with user, tenant, session or workspace scope but no nonblank scopeRef cannot be promoted or reclaimed: they return a conflict without changing the row, and rejection remains available. Legacy workspace fallback rows are also held because their original workspace cannot be recovered. Agent and global legacy identities remain derivable. Resubmit ambiguous content with an explicit scopeRef; no automatic backfill runs. Promotion still does not carry session-TTL configuration or every original structured-entry field. Concurrent quarantine deduplication remains unaddressed.

Public quarantine promotion captures admission before reading the review row. Claim, canonical write, finalization and decision audit are separate fenced transactions sharing that original token. A stale admission takes precedence over missing, reviewed or leased entries; a gate conflict at any later stage rejects the request, including after the canonical transaction has committed. This is a staged operation, not one atomic transaction. The canonical transaction includes cache invalidation, embedding-cost accounting and its mutation audit: a failure rolls it back and a separate fenced revert returns the claim to the pending queue. A gate conflict skips that revert. If a compensating revert fails, its error replaces the original writer error, preserving the existing loss of that cause.

A successful rejection that recovers an expired promotion claim returns memoryMayRemain: true, even if its audit write fails. A partial promotion may already have written structured memory; the flag discloses that possibility and does not confirm existence or erasure. Ordinary pending rejection and successful promotion omit the flag. The client receipt also exposes the existing finalizeError field.

An ordinary finalization failure still returns finalizeError with the canonical memory committed and the claim recoverable; an ordinary decision-audit failure returns auditError with the decision durable. These diagnostic fields apply the existing recognized-credential redactor before entering caller receipts; finalization audit metadata uses the same sanitized message. Ordinary diagnostic wording and the redactor's existing partial masks are preserved. A fresh successful promotion commits four gate serial increments and two audit records. A thrown finalization or decision-audit failure commits three increments; a finalization matching zero rows still commits its stage and totals four. A canonical transaction failure followed by a successful revert commits two increments. The existing 120-second lease and claim filters remain: they do not establish exclusive ownership after lease expiry or make repeated promotion side effects idempotent. Direct internal promotion calls without admission retain their legacy behavior. Atlas search/embedding execution, failover, unknown commit outcomes, concurrent expired-lease promoters and throughput remain outside this validation.

Public self-edit captures original owner admission before reading the block or loading the leaf. Replace, append and prepend run their complete merge, protected-block check and structured write in one fenced transaction. Append and prepend reread the agent-owned block on callback retries; replace needs no merge read. Canonical memory, revision history, cache invalidation, embedding-cost accounting and mutation audit commit together, or all roll back on error. Injection-shaped user content can instead commit a quarantine receipt under the same fence, leaving the canonical block unchanged; protected persona and instruction blocks still reject the merged value. Stale admission and wrong-owner tokens fail before content operations. A successful canonical edit or quarantine disposition commits one gate serial increment.

The public path uses the session owned by the database client and does not mix a separately supplied client into its transaction. Direct internal self-edit calls without admission retain their existing client transaction and deferred-side-effect behavior. Merging an invalidated owner row remains compatible with existing behavior. Per-agent contention, arbitrary malformed stored content, concurrent load, natural failover, unknown commit results and Atlas embedding execution remain outside this validation.

Public filesystem sync captures original owner admission before reading file metadata or disk sources. Each changed file replaces its chunks and completing metadata in one fenced transaction under that token. Chunk operations and metadata dates rebuild on callback retry; disk reads, chunking and progress callbacks stay outside. Stale memory and admitted session cleanup use the same token, so an old enumeration cannot delete a fresh post-erasure replacement. Erasure conflicts and malformed gates propagate through per-file and session error handlers; other file failures retain the existing partial-result behavior. Admitted writes never downgrade to the standalone or oversized-transaction fallback.

Filesystem listing permits a missing default memory directory only at its initial lstat. An error during recursive listing, or any error for a configured extra path, rejects the whole listing. Sync then reports incomplete enumeration and skips all stale cleanup, including session cleanup, until the source or configuration is repaired. A genuinely absent default root remains eligible for cleanup; this does not detect missing workspace ancestors or unavailable mounts. The existing diagnostic warning and file-read failure behavior remain separate concerns.

Filesystem replacement and stale cleanup now select chunks with startLine present within the existing namespace. Current filesystem writers supply this field; separately materialized event and conversation-window chunks omit it and survive cleanup. Unknown rows without it are retained. This is a contract for current producers, not general provenance: imported or mixed rows with the field remain deletable, including null. Path-only event upserts and namespace-scoped window upserts can still match a conversation-sourced file row in a same-path pair; typed projection identity and legacy migration remain separate work. No schema or index changes are included.

The internal conversation-window projector selects events from the requested agent, session, scope and scope reference. Its upsert matches the existing window path within that partition and source:"conversation", preserving the row ID and untouched embedding on reprojection. Missing or null imported event partition fields are excluded. There is no in-repository production caller. This filter does not distinguish conversation-sourced filesystem chunks, remove stale windows, refresh embeddings, fence erasure or prevent concurrent duplicate inserts. Typed projection identity, legacy repair and production wiring remain separate work.

The consolidator phase-two similarity probe excludes invalidated rows in the vector prefilter and rechecks owner, scope, state, inference origin and expiry on the returned full document. An inferred or invalidated lookalike cannot force a NOOP that discards new observed evidence. Existing non-invalidated legacy behavior and ADD fallback remain. The five-neighbor candidate limit can still cause duplicate additions after filtering; deployed index readiness, real ANN behavior and later prune authority are separate validation work.

A procedure write that changes an invalidated row to the effective active state clears its old validity end and invalidation reason. Changed procedure writes retain their existing new start time, and the invalidated revision keeps its original end. An absent state key preserves the stored state; a present state: undefined retains the existing active default. Procedure entries expose no validity-date overrides. Already-processed source receipts, imported active end dates, existing zombie rows and expiry-reader behavior remain separate work.

Writing an existing invalidated structured row with the effective active state opens a new validity window at the supplied validFrom or the write time. It removes an unspecified validTo and the stale invalidation reason. The old invalidated revision retains its recorded end date. Explicit validity bounds remain caller-controlled, including past or future assertions; this change adds no backdate restriction. Ordinary active re-mentions keep their earliest start, and omitted expiry does not clear stored expiry. Current-only search serves the current row; previous intervals remain accessible through revision history. Existing zombie rows and extractor reactivation policy are separate work.

Direct internal sync calls without admission retain their existing transaction and fallback behavior, including optional agent ownership. Manager sync continues to disable transcript-file ingestion. Joined sync calls share the in-flight request, and a genuinely fresh post-reopen request can import the surviving disk files. The later KB refresh captures its own new intent; the filesystem change does not close all sync-tail or erasure-policy work. Per-agent contention, filesystem erasure policy, search convergence, load, natural failover and unknown commit outcomes remain unmeasured.

Profile synthesis, active-slate hydration, discovery projections, and context bundles carry the manager admission captured before source reads. Their success and failure diagnostics reuse that token; the bundle passes it to nested readers and its own final telemetry. Profile, slate, and bundle telemetry stays asynchronous and best-effort. Discovery-run and telemetry rows commit together in one fenced transaction, with failures caught outside the callback. Stale diagnostic writes cannot recreate rows after erasure; returned read content remains best-effort and is not a transaction snapshot. Direct leaf calls without admission preserve their existing new-intent behavior and cannot certify earlier external reads.

Public single and batch event writes reuse their original admission for lane-coverage and ingest-run diagnostics. Each tail uses its own fenced transaction; stale or failed diagnostics leave the already durable canonical receipt successful. Counts, run status, and duration are prepared before callback retries. A fresh successful call commits two additional gate serial increments for those diagnostics; empty batch tails retain their existing guards. Direct diagnostic helpers without a session keep their legacy behavior. Chunk projection and queued episode derivation have additional original-admission fences described below. Direct legacy projection helpers and cache cleanup remain separate work; these changes do not close all event-write tails or establish throughput or failover guarantees.

Queued episode derivation carries the original event-write admission through selection and materialization. Summarization and episode document preparation stay outside retries; the episode upsert and persisted-ID readback share a fenced transaction. Cap cleanup, projection diagnostics, and selected event markers use separate fences under that same token, preventing stale cleanup from deleting fresh episodes or marking reimported events. Admitted duplicate-key errors propagate; legacy materialization retains its existing retry. Kind and owner checks run before source reads, while malformed epochs fail at the first fence. Queued episodic coverage reuses that same token in a separate final fence; failed coverage preserves the committed episode and markers. Direct helper calls without admission and the short-lived negative memo retain their existing behavior and remain separate work. This does not establish two-process, load, failover, or complete writer-inventory acceptance.

Public event-write chunk projection reuses the original admission. Chunk upserts and projected markers commit together; marker errors or batch item failures roll back the projection while preserving successful canonical receipts with chunkCreated:false. A separate fence records an ok run with committed new chunks, or a failed run with zero items; projection throws now receive that failure diagnostic when its fence can commit. Direct projection helpers retain their existing behavior. Direct projection helpers and legacy cache cleanup remain separate admission work.

Public event writes pass their original admission into coalesced legacy-cache cleanup. Admitted coalescing keys include the epoch, so a fresh post-erasure write gets its own leading cleanup. Each leading or trailing cleanup runs in a separate original-token transaction; stale cleanup cannot delete fresh rows, and errors abort the gate increment before being logged outside the callback. Wrong-kind or wrong-owner admission logs and returns before scheduling, preserving already durable receipts. Cleanup remains asynchronous, and pending timers are not drained or canceled by this change. Direct scheduling without admission retains its legacy key and unfenced behavior. Search no longer uses these legacy cache rows; this is lifecycle protection, not evidence of better retrieval. Per-agent contention, real timer timing, two-process behavior and failover remain unmeasured.

The exported projectChunksFromEvents repair helper accepts an optional original admission. Without one it captures new intent at entry; both paths validate the owner and open epoch before reading events. Each event’s chunk and marker share a transaction under that token, and counts advance only after commit. A later event failure preserves earlier committed events and records their count in a separate fenced failure diagnostic before rethrowing; gate conflicts skip that diagnostic. Success diagnostics are best-effort, so their failure now leaves completed repair successful. Empty retries add no projection transaction or diagnostic. The manager’s batch repair retains its transactional batch semantics; its worker retry behavior is described below. Direct projection helpers remain separate contracts; per-event transaction cost, chosen-ID replacement within the same epoch, cross-process behavior and failover remain unmeasured.

Writer inventory check (development)

The mutation inventory and its reviewer evidence are maintained outside the release tree. They remain audit evidence, not a release or CI gate. This release does not establish complete writer coverage.

This is an inventory and drift check, not proof of admission or transaction correctness. Line numbers are display locations; the full source hash invalidates prior approvals after any file edit. Getters/setters, implicit coercion, tagged templates, await thenables and invisible runtime dispatch are outside the explicit-call model. Apps, other packages, operational scripts and .mjs test helpers are not certified by the engine production input policy. The discovery policy currently includes only .ts and .mjs; other source extensions and symlink targets need an explicit policy extension. Inheritance overrides, class field/static-block ownership and getter bodies are not resolved as separate call-graph targets. Fence correctness, legacy caller contracts, schema/operator authority and cross-process coverage remain separate review and runtime work.

Consolidation's near-duplicate prune now invalidates the selected physical row at its observed revision through the structured lifecycle operation. The original admission and consolidation lease fence the transaction, which records the old revision, closes its validity, invalidates query cache rows and inserts the audit record together. A stale, missing or already invalidated loser is uncounted; rows without an integer revision or a concrete owner/scope/type/key are retained. This path does not require the logical unique index to pin its target. Pruning authority between inferred and observed memories and a winner changed after selection remain separate work. When a successful prune retires its driving fact, that inner scan stops; a retained driver can continue to prune later duplicates. Local tests inject ANN results; they do not establish native Atlas retrieval behavior.

After extraction-outbox repair, each existing worker drain attempts one batch of up to 500 unprojected canonical events using the drain’s original admission. An ordinary repair failure leaves the batch unprojected and permits the later worker sweeps to continue; an erasure conflict stops that drain. Startup retains its full repair drain. This covers failed projections whose extraction pending marker was already cleared, as well as events without an extraction marker. The existing worker wakes and sweep interval provide retry opportunities while the worker remains active; manual local drain tests do not establish wall-clock latency. A persistently failing first batch can block later event repairs, and path-only projection identity remains separate work.

LLM deduplication merges the selected keeper and invalidates the selected loser through canonical revision operations in the original admission-and-lease transaction. Both physical rows must remain active at their observed identities and revisions; a stale or replaced row, quarantined synthesis, or failed side effect rolls the pair back. A successful merge ends the current inner scan so a second union cannot overwrite the first from an old snapshot. The keeper retains existing canonical same-value reinforcement behavior, and a changed value opens a new validity interval. Local tests inject model responses and ANN candidates and do not measure model or retrieval quality. Legacy rows without usable revisions are retained; source authority, expiry changes after selection and generation-bound history remain separate work.

Repeated-evidence promotion applies the existing event lifecycle filter when discovering supporting events, preparing their guard and validating that guard in the persistence session. Invalidated, not-yet-valid or expired support cannot promote a candidate through those reads. Legacy missing dates and explicit null invalidation ends retain their existing open-window behavior. A support change between discovery and preparation, or between preparation and persistence, is rechecked. A raw support mutation after the transaction snapshot and the originating-event caller contract remain separate validation work.

New structured revision snapshots retain the original document’s structuredId and use a deterministic identity derived from its typed BSON _id and revision. Deleting and recreating a logical memory key therefore starts a distinct snapshot identity. Same-generation duplicate handling stays unchanged. Current structured history reads the current document first, then selects revisions whose raw structuredId equals that document’s BSON _id before applying the history limit. If the current document is absent, history is empty. Legacy and earlier-generation snapshots stay in storage but are hidden from current history; no backfill runs. Procedure history, what-changed projections and mixed old/new writer rollout remain separate work. Numeric BSON identity equivalence and explicit manual reuse of a physical _id are not covered by this binding; the two reads do not promise a linearizable latest view.

Procedure creation audits record the same payload used for the insert, including canonical fields and creation defaults. Their changed-field list follows the existing audit convention that excludes _id, createdAt and updatedAt; the generated MongoDB _id is not part of the payload. No-op replays still emit no audit, and updates retain their existing audit behavior.

Structured creation uses insert-only fields after a missing read. If another writer created the identity first, the existing revision-conflict retry rereads that row and follows the normal update and snapshot path. Each attempt resets the audit payload so a failed update followed by creation cannot retain the deleted row’s merged source IDs. Local sessionless race tests cover these cases; a real transaction race and retry exhaustion under sustained contention remain unmeasured.

Same-value structured reinforcement increments the stored counter without assigning an incoming counter to that same path. Its audit uses the counter returned by the atomic update, including for concurrent sessionless writers; the old audit value remains the earlier observed row. Creation and changed-value writes retain their existing explicit-counter behavior and equality rules. Retryable findOneAndUpdate can copy the full document on replica-set nodes despite the narrow returned projection; workload cost and sharded deployment behavior remain unmeasured.

Structured writes compare state, salience, temporal scope and source reliability using the effective defaults they persist. Repeating an otherwise unchanged fact with these fields omitted reinforces its current revision. Materializing defaults on a legacy row that lacks them creates one revision; a subsequent identical write reinforces it. Omitting a stored non-default still counts as a change. Source-event and provenance comparisons retain their existing behavior.

Near-duplicate prune and LLM deduplication skip pairs where only one fact has provenance.origin: "llm-inference". An unverified inference cannot retire an observed fact or contribute synthesized content to its merge. Pairs with the same inference classification retain the existing newer-fact rule; missing origin retains legacy observed classification. Corroboration-based promotion, the freshness of a retained prune winner after selection and real similarity incidence remain separate work. Local tests inject ANN scores and model responses.

Consolidator conflict resolution prepares contradiction decisions before filtering the replacement candidate. A candidate dropped by similarity or quality filtering does not retire the existing fact. An accepted replacement and its prepared retirements commit together in the original admission and lease transaction, including audits, revision history and cache invalidation. A missing active replacement, failed side effect or stale retirement target aborts both operations and leaves the event retryable. Direct standalone resolution and the extraction job’s candidate selection remain separate work.

After derived promotion, contradiction checks require an active, current, unexpired persisted source fact matching the prepared value and a valid revision. A skipped promotion without a matching persisted active fact cannot retire another fact; inactive sources are excluded. The background worker and direct derived-promotion path enable this check; pre-promotion consolidation keeps its separate atomic source validation. The source revision is checked again at retirement; this does not establish protection against every external write after a transaction snapshot.

Search lane failures and exact procedural backstop warnings omit raw error text and retain only the fixed lane label and finite numeric error code. Strict failure propagation, lane outcome metadata and the original error delivered to onPathFailure remain unchanged; public error metadata and hook-failure warnings retain separate privacy limitations.

Conversation evidence and turn-precision event searches retain successful vector or text results when the sibling aggregation fails in non-strict mode. The failed branch appears under phase:conversation-evidence:turn-vector or the corresponding text/turn-precision name in lane outcomes and the readiness hook. If every attempted branch fails, the existing parent failure path runs; strict mode rejects any failed branch. Both branches settle before return, so failure latency can increase; the thrown error is the first failed branch in input order. The existing filters, freshness checks, scoring, and budgets still apply. Direct calls without a working failure hook log only a branch label and finite error code. Raw error messages remain in outcome metadata and hooks.

When mongoSearch cannot consume an embedding because the request capacity is spent or reserved, non-strict searches use the existing lexical path and trace embedding budget exhausted. A real empty fusion result still ends the waterfall. Strict searches reject embedding-capacity degradation; an expired request deadline keeps its existing empty behavior. The JS merge path retains its concurrently running lexical result. Direct vector/fusion leaves keep empty degradation unless the internal capacity hook is supplied. Each automated vector stage consumes its own embedding budget on warmup retries, including nested fusion inputs. Retry capacity denial retains the existing strict rejection or lexical fallback in mongoSearch; other retry callers keep empty degradation. Aggregation admission is charged before retry embedding admission, and first-attempt stage construction can charge an embedding even when execution is later refused, so these counters are conservative rather than exact billing. This does not eliminate embeddings across fallback queries or account for explain executions.

In searchV2, a supplied structuredScope.type takes precedence over an inferred type. A supplied referenceScope.source or category suppresses both inferred KB source and category constraints; supplied tags still apply. Without either explicit KB choice, planner inference is retained. Direct engine calls preserve the existing truthy checks, so empty strings act as absent values; HTTP validation rejects empty filter strings. This changes filter precedence only, not lane selection, state, or current-only policy.

Structured search with currentOnly now honors a non-empty requested state or state array together with the existing validity window. Without a requested state, or with an empty array, it keeps the active default. Direct internal calls combining currentOnly with invalidated now filter invalidated rows by that window instead of returning active rows. The searchV2 invalidated-state exception and non-current searches keep their existing behavior. This guarantees predicate composition, not that every superseded row has a closed validity window.

Default hybrid searchV2 requests with neither Vector Search nor Atlas Search capability now reach the existing ordinary $text fallback for chunk lanes. The resolved identity, source, lifecycle, and expiry filters still apply; a usable ordinary text index is required. Explicit vector-only mode keeps its no-query empty behavior in this case. Strict benchmark mode now rejects the required fallback instead of reporting a successful empty hybrid lane. The opt-in session and evidence-mirror lanes remain skipped without either Atlas capability. A missing ordinary index still follows the existing warning-and-empty behavior outside strict mode.

Plain queries without retrieval signals prioritize structured memory before procedures within the three primary lanes, while retaining the dedicated high-salience lane. Procedures keep their exact-match and sparse-result semantic backstops. Those backstops can add reads, and non-exact procedures may remain unsearched when other lanes return enough results. This makes ordinary facts reachable; it does not establish an accuracy improvement. Equal-score lane ordering also changes for other tied plans.

KB JS merge waits for both search lanes to settle. Outside strict mode, a successful lane survives a sibling failure with its existing lane scores, threshold and result cap; the failed branch is reported through the lane-failure hook. If the surviving lane has no passing results, the existing recovery continues without rerunning that fulfilled lane. Both failures keep the existing waterfall. Strict mode rejects a failed branch after both settle, using the first failed branch in input order. Waiting can increase failure latency; existing server processing limits are unchanged. Raw errors remain available to hooks and in older waterfall diagnostics.

Exact procedure-alias searches now supply the existing user-search maxTimeMS processing limit to find. The normal timeout mode uses the configured value or 10,000 ms default; MongoDB driver CSOT configurations can replace the command value with their remaining timeout. This is not a client wall-clock or complete-cursor deadline, and the find is still outside the aggregation-only budget.

Direct KB searches now derive the reference for an explicit scope using the existing identity resolver. Explicit references still win; omitted scope keeps the legacy agent partition, even with a session key or a different default-scope setting. Session scope needs a session coordinate or reference; user and tenant scopes need an explicit reference through HTTP. The API returns 400 for an invalid non-empty scope string or these missing coordinates. Scoped-key authorization remains unchanged and still requires an explicit allowed reference. Wrongly typed scopes retain the existing lenient handling.

Trusted or admin global and workspace searches now target their requested shared partitions instead of the agent's synced corpus. Normal file sync populates only the agent partition, so those searches can return empty unless direct engine KB ingestion populated the requested partition. Workspace derivation uses the manager's workspace; direct ingest using another workspace needs an explicit reference. Existing SDK and MCP KB inputs require an explicit reference for session searches; HTTP also accepts sessionId or sessionKey, with sessionId winning. This changes reference resolution, not the scopeRef-only shared-corpus filter.

The published internal projectConversationWindows helper captures erasure admission before selecting session events and commits each window with that original token. An optional admission lets callers protect work begun earlier. Foreign or stale admission is rejected, including after an erase cycle reopens the gate; retry fresh work with a newly captured token. Empty calls can initialize the gate. Windows commit individually, so ordinary mid-run failures can leave earlier windows committed. This helper requires transaction-capable MongoDB, as the other fenced writers do; standalone writes have no fallback.

With an opted-in searchBudget.maxWallMs, unused reserved aggregation and embedding capacity also expires before consumption. Denied consumption marks the budget exhausted without spending that capacity; the existing release returns unused reservations. This check prevents new reserved dispatch after the deadline. It does not cancel an in-flight query or establish a complete request wall-clock limit.