@pyxmate/memory 1.19.8 → 1.20.0

package/dist/index.d.ts

@@ -1,1435 +1,1472 @@
 import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, PrincipalContext as PrincipalContext$1, SensitivityLevel as SensitivityLevel$1, MemoryStats as MemoryStats$1, MemoryInsights as MemoryInsights$1, LineageParams as LineageParams$1, LineageResult as LineageResult$1, ReinforceParams as ReinforceParams$1, ReinforceResult as ReinforceResult$1, WikiLintReport as WikiLintReport$1, GraphRepairResult as GraphRepairResult$1, ExtractedImageMeta as ExtractedImageMeta$1, IngestEntity as IngestEntity$1, IngestRelationship as IngestRelationship$1, EntityExtractionResult as EntityExtractionResult$1, Topology as Topology$1, IngestEvent as IngestEvent$1, GraphEnrichEvent as GraphEnrichEvent$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1, CorrectionRecord as CorrectionRecord$1 } from '@pyx-memory/shared';
 export { documentContentSource, documentGraphSource, documentImageSource } from '@pyx-memory/shared';
-export { e as encodeListCursorToken, p as parseListCursorToken } from './data-plane-contract-CmosA5XV.js';
+export { e as encodeListCursorToken, p as parseListCursorToken } from './data-plane-contract-webbeMs5.js';
 
-/** Parameters for paginated entry listing. */
-interface MemoryListParams {
-    /** 1-based page number. Default: 1 */
-    page?: number;
-    /** Entries per page (1–100). Default: 20 */
-    limit?: number;
-    /**
-     * Opaque keyset-pagination token from a previous result's `nextCursor`.
-     * Guarantees exactly-once traversal even while strictly-newer entries
-     * are being written (offset/page pagination can repeat or skip there).
-     * A cursor is only valid for the same filter set that produced it.
-     * Mutually exclusive with `page` — supplying both is an error. Not a
-     * snapshot: rows backdated behind the cursor position can still appear.
-     */
-    cursor?: string;
+/** ISO 8601 timestamp string */
+type Timestamp = string;
+/** Unique agent identifier */
+type AgentId = string;
+
+/**
+ * Caller identity for ReBAC authorization.
+ *
+ * The canonical "subject" in Zanzibar terms — passed alongside requests so the
+ * memory layer can compute an AuthzPlan (visible namespaces + entry overrides)
+ * before any retrieval source fans out.
+ *
+ * Identity comes from authenticated request context (X-Tenant-Id / auth token
+ * claims), never from request bodies or multipart form fields. The legacy
+ * `userId` / `teamId` / `agentId` columns on MemoryEntry remain for audit and
+ * legacy filters but MUST NOT drive authorization decisions — they are
+ * collision-prone aliases (a service principal sharing an ID with a human
+ * user has no protection against confused-deputy attacks).
+ *
+ * Sensitivity / clearance is intentionally NOT on this object. It is a
+ * MAC-style classification, orthogonal to RBAC, and continues to be carried
+ * via the `X-Caller-Access-Level` header → `MemorySearchParams.maxSensitivity`.
+ * Conflating the two couples future changes (e.g. per-namespace classification
+ * rules) to identity propagation.
+ */
+interface PrincipalContext {
     /**
-     * Opt-in lifecycle-status filter. Omitted preserves today's behavior:
-     * active, superseded, and archived entries are all returned.
+     * Hard isolation boundary. Required even in single-tenant deployments —
+     * single-mode passes a stable sentinel (`SINGLE_TENANT_ID`) so authz code
+     * paths look identical regardless of mode.
      */
-    status?: 'active' | 'superseded' | 'archived';
-    /** Filter by memory type. */
-    type?: MemoryType$1;
-    /** Filter by agent ID. */
-    agentId?: string;
-    /** Filter by tenant ID for multi-tenant isolation. */
-    tenantId?: string;
-    /** Exact namespace scope. Excludes legacy tenant-root entries. */
-    namespaceId?: string;
+    tenantId: string;
     /**
-     * Calling principal. When supplied, list applies the AuthzPlan
-     * visibility filter so entries in forbidden namespaces never reach
-     * the response. Single-tenant / library-direct callers may omit it
-     * and get the legacy tenant-only scope.
+     * Stable subject ID (within the tenant). For humans this is the userId;
+     * for AI runtimes it is the agentId; for system actors it is a service
+     * identifier. Combined with `kind`, forms the Zanzibar subject coordinate
+     * `<kind>:<principalId>`.
      */
-    principal?: PrincipalContext$1;
-    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
-    maxSensitivity?: SensitivityLevel$1;
+    principalId: string;
     /**
-     * R1/R2 — opt-in list of `metadata._kind` values to include in the
-     * response. When omitted or empty, the default-set returns only entries
-     * with NO `_kind` system metadata (e.g. `_kind:'entity-summary'` rows
-     * are hidden). When supplied, the listed kinds are returned IN ADDITION
-     * to the default-set (additive, not replacement). See
-     * `docs/specs/topic-org-v025-f1-include-kinds/spec.md`.
+     * Subject namespace. Distinguishes humans from AI agents from internal
+     * services so a userId/agentId/serviceId collision cannot grant
+     * unintended access.
+     *  - `user`: human end user
+     *  - `agent`: AI runtime acting on a user's behalf or autonomously
+     *  - `service`: non-AI internal system (cron, ETL, admin tooling)
      */
-    includeKinds?: string[];
+    kind: 'user' | 'agent' | 'service';
 }
-/** Result of a paginated entry listing. */
-interface MemoryListResult {
-    entries: MemoryEntry$1[];
-    totalCount: number;
-    /** Present in page/offset mode only — a keyset traversal has no page number. */
-    page?: number;
-    limit: number;
-    /** Keyset token for the next page; null when this page is the last. */
-    nextCursor: string | null;
+/** Sentinel tenant ID used in single-tenant deployments. */
+declare const SINGLE_TENANT_ID = "_single";
+
+declare const MemoryType: {
+    readonly SHORT_TERM: "short-term";
+    readonly LONG_TERM: "long-term";
+    readonly WORKING: "working";
+    readonly EPISODIC: "episodic";
+    readonly SUMMARY: "summary";
+};
+type MemoryType = (typeof MemoryType)[keyof typeof MemoryType];
+declare const SensitivityLevel: {
+    readonly PUBLIC: "public";
+    readonly INTERNAL: "internal";
+    readonly SECRET: "secret";
+};
+type SensitivityLevel = (typeof SensitivityLevel)[keyof typeof SensitivityLevel];
+declare const RAGStrategy: {
+    readonly NAIVE: "naive";
+    readonly GRAPH: "graph";
+    readonly HYBRID: "hybrid";
+};
+type RAGStrategy = (typeof RAGStrategy)[keyof typeof RAGStrategy];
+/**
+ * Strategy identifiers that were public in earlier versions and have been
+ * removed. Server/SDK reject requests using these with a stable
+ * `strategy.deprecated:<name>` error code (not the generic "invalid
+ * strategy" message) so callers and dashboards can detect the removal
+ * cleanly across a version bump.
+ *
+ * v0.26: `agentic` removed (Codex pair: silent-catch in agentic.ts
+ * violated Production-ready; behavior subsumed by HybridRAGEngine).
+ */
+declare const DEPRECATED_RAG_STRATEGIES: ReadonlyMap<string, string>;
+declare const VectorProvider: {
+    readonly LANCEDB: "lancedb";
+};
+type VectorProvider = (typeof VectorProvider)[keyof typeof VectorProvider];
+declare const EmbeddingProviderName: {
+    readonly STUB: "stub";
+    /** @deprecated Vestigial — pyx-memory uses internal EmbeddingGemma embeddings. */
+    readonly ANTHROPIC: "anthropic";
+    /** @deprecated Vestigial — pyx-memory uses internal EmbeddingGemma embeddings. */
+    readonly OPENAI: "openai";
+    /** In-process ONNX model (default: EmbeddingGemma-300M). */
+    readonly LOCAL: "local";
+    /** Remote OpenAI-compatible embedding service (pyx-cloud shared, custom, etc.). */
+    readonly HTTP: "http";
+};
+type EmbeddingProviderName = (typeof EmbeddingProviderName)[keyof typeof EmbeddingProviderName];
+type GraphEnrichmentStatus = 'caller-provided' | 'extracted' | 'merged' | 'opted-out' | 'skipped-duplicate' | 'skipped-sensitive' | 'skipped-unprovisioned' | 'extracted-empty' | 'failed-graph-write' | 'failed-best-effort';
+interface GraphEnrichment {
+    status: GraphEnrichmentStatus;
+    provider?: 'http' | 'local' | 'none';
+    reason?: string;
+    action?: string;
 }
-/** Filters for temporal queries (queryAsOf, queryByEventTime). */
-interface TemporalQueryFilters {
-    type?: MemoryType$1;
-    agentId?: string;
-    source?: string;
-    limit?: number;
-    /**
-     * Number of matching rows to skip. Offset pages can shift under concurrent
-     * deletion; use cursor for a deletion-stable queryAsOf walk.
-     */
-    offset?: number;
+/**
+ * A caller-supplied relationship whose source or target name did not resolve to
+ * any entity in the same store call (after name normalization), so the edge was
+ * not written. Surfaced on the store response so the agent — not just the server
+ * log — can see which edges to re-send.
+ */
+interface DroppedGraphRelationship {
+    source: string;
+    target: string;
+    type: string;
+}
+type VectorStatus = 'pending' | 'stored' | 'skipped';
+/**
+ * Upper bound of a caller-declared `sessionOrdinal`: `n + 2` stays an exact
+ * integer, so the ±2 neighbor operator needs no runtime arithmetic guard.
+ */
+declare const SESSION_ORDINAL_MAX: number;
+declare function isSessionOrdinal(value: unknown): value is number;
+interface MemoryEntry {
+    id: string;
+    content: string;
+    type: MemoryType;
+    agentId?: AgentId;
+    sessionId?: string;
     /**
-     * Opaque keyset token for a deletion-stable queryAsOf walk. Derive it from
-     * the last returned entry with `encodeListCursorToken`; mutually exclusive
-     * with offset.
+     * Caller-declared turn coordinate inside `sessionId` (0 ≤ n ≤ SESSION_ORDINAL_MAX).
+     * Never inferred from timestamps or insertion order; unique per
+     * (tenant, namespace, session) while declared.
      */
-    cursor?: string;
-    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
-    maxSensitivity?: SensitivityLevel$1;
-}
-/** Filters for the chronological feed (`log`, Karpathy `log.md` primitive). */
-interface MemoryLogFilters {
-    /** Inclusive lower bound on `created_at` (ISO 8601). Cursor for "what's new since X". */
-    since?: string;
-    /** Maximum entries to return. The HTTP layer clamps to [1, 100]. */
-    limit?: number;
-    type?: MemoryType$1;
-    agentId?: string;
+    sessionOrdinal?: number;
+    metadata: Record<string, unknown>;
+    /** @deprecated Vestigial — embeddings are managed internally by the vector store. */
+    embedding?: number[];
+    createdAt: Timestamp;
+    /** SHA-256 hash of content for deduplication. */
+    contentHash?: string;
+    /** Importance score (1-10). */
+    importance?: number;
+    /** Number of times this entry has been accessed via search. */
+    accessCount?: number;
+    /** ISO timestamp of last access via search. */
+    lastAccessed?: string;
+    /** Parent entry ID for hierarchical storage (e.g., doc → section → chunk). */
+    parentId?: string;
+    /** Source identifier (e.g., filename, URL, session). */
     source?: string;
-    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
-    maxSensitivity?: SensitivityLevel$1;
-}
-/** Options for scoping operations to a specific tenant. */
-interface TenantScopeOptions {
+    /** When the event described by this memory occurred. */
+    eventTime?: string;
+    /** When this entry was ingested into the system. */
+    ingestTime?: string;
+    /** Sensitivity classification based on content analysis. */
+    sensitivity?: SensitivityLevel;
+    /** Whether the content field is encrypted at rest. */
+    encrypted?: boolean;
+    /** Number of graph entities written by this store call. Present on store responses. */
+    graphEntitiesWritten?: number;
+    /** Number of graph relationships written by this store call. Present on store responses. */
+    graphRelationshipsWritten?: number;
+    /** Count of caller relationships dropped because an endpoint name did not match any entity in the call. Present (and >0) only when edges were dropped. */
+    graphRelationshipsDropped?: number;
+    /** Up to 20 of the dropped relationships (source/target/type), so the agent can re-send them. Present only when edges were dropped. */
+    graphRelationshipsDroppedDetail?: DroppedGraphRelationship[];
+    /** Graph extraction/enrichment outcome for this store call. Present on graph-targeted store responses. */
+    graphEnrichment?: GraphEnrichment;
+    /** Store response vector outcome. Pending means SQLite is durable and vector indexing is eventually consistent. */
+    vectorStatus?: VectorStatus;
+    /** Tenant ID for multi-tenant isolation. */
     tenantId?: string;
-    /** Optional strict namespace coordinate for exact get/delete operations. */
+    /** User ID within the tenant. */
+    userId?: string;
+    /** Team/group ID within the tenant. */
+    teamId?: string;
+    /**
+     * Namespace ID — the primary protected resource for ReBAC authorization.
+     * `undefined` (NULL on the row) means the entry lives in the legacy
+     * "tenant-root" bucket and is visible to anyone with tenant access (the
+     * pre-ReBAC posture). Setting `namespaceId` opts the entry into AuthzPlan-
+     * based filtering, where visibility is computed from `authz_tuples` for
+     * the calling principal.
+     */
     namespaceId?: string;
     /**
-     * Graph count mode for stats(). Use raw on admin-health paths
-     * that should avoid the visible graph projection.
+     * When true, consolidation leaves this entry alone — it is never archived by
+     * decay and never merged (nor merged-into) by semantic deduplication. Use for
+     * stable anchor entries whose ID is referenced by external systems (e.g. a
+     * file-catalog row pointed at by another service's foreign key).
      */
-    graphVisibility?: 'visible' | 'raw';
+    pinned?: boolean;
     /**
-     * Calling principal. When supplied alongside or instead of tenantId,
-     * the operation applies the AuthzPlan visibility filter — get/delete
-     * will treat entries in forbidden namespaces as if they did not exist.
-     * Single-tenant / library-direct callers may omit it and get the
-     * legacy tenant-only scope.
+     * Lifecycle status (H8). Optional on write (absent means `'active'`), but
+     * every entry READ back from the store carries it explicitly — a caller can
+     * compare `entry.status === 'active'` without special-casing an absent field.
+     * `'active'` is a normal retrievable entry. `'superseded'` means a newer near-duplicate
+     * UPDATE replaced this one during consolidation. `'archived'` (1b) means decay
+     * retired it (no successor) — kept, strength 0, `deep`-tier only. All three
+     * are kept (history / lineage / deep recall) but `superseded`/`archived` are
+     * excluded from default/quick/medium search. Only `forget()` and exact-byte-
+     * duplicate collapse hard-delete. See `docs/H8-MEMORY-MODEL-DESIGN.md`.
      */
-    principal?: PrincipalContext$1;
-    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
-    maxSensitivity?: SensitivityLevel$1;
-}
-/** Abstract interface for memory systems (local or remote). */
-interface MemoryInterface {
-    initialize(): Promise<void>;
-    store(entry: StoreInput$1): Promise<MemoryEntry$1>;
-    search(params: MemorySearchParams$1): Promise<MemorySearchResult$1>;
-    /** List entries with SQL LIMIT/OFFSET pagination. */
-    list(params?: MemoryListParams): Promise<MemoryListResult>;
-    get(id: string, options?: TenantScopeOptions): Promise<MemoryEntry$1 | null>;
-    delete(id: string, options?: TenantScopeOptions): Promise<boolean>;
-    clearSession(sessionId: string, options?: TenantScopeOptions): Promise<number>;
-    stats(options?: TenantScopeOptions): Promise<MemoryStats$1>;
-    insights(options?: TenantScopeOptions): Promise<MemoryInsights$1>;
-    /** Query entries as they existed at a point in time (by ingest time). */
-    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters, options?: TenantScopeOptions): Promise<MemoryEntry$1[]>;
-    /** Read the time-ordered lineage of a graph fact or superseded entry chain. */
-    lineage(params: LineageParams$1): Promise<LineageResult$1>;
-    /** Reinforce memories that were actually used by the caller. */
-    reinforce(params: ReinforceParams$1): Promise<ReinforceResult$1>;
-    /** Query entries by event time range (when things actually happened). */
-    queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
-    shutdown(): Promise<void>;
-}
-/** Consolidation run result. */
-interface ConsolidationRunResult {
-    entriesProcessed: number;
-    entriesMerged: number;
-    entriesArchived: number;
-    durationMs: number;
-}
-/** Extended interface with lifecycle operations. Non-breaking for existing consumers. */
-interface ExtendedMemoryInterface extends MemoryInterface {
-    /** Run consolidation: score, dedup, decay, and summarize memories. */
-    consolidate(): Promise<ConsolidationRunResult>;
-    /** Soft-delete a memory with a reason (marks as archived). */
-    forget(id: string, reason?: string): Promise<boolean>;
-    /** Summarize a session's memories into a long-term entry. */
-    summarizeSession(sessionId: string): Promise<MemoryEntry$1 | null>;
+    status?: 'active' | 'superseded' | 'archived';
     /**
-     * Read-only memory-wide lint report (v0.18.0 Karpathy-wiki Item B):
-     * orphans, decay candidates, stale entries, dedup candidates. Pure
-     * projection — no writes.
+     * When `status==='superseded'`, the id of the newer entry that replaced this
+     * one — the backward link used by `Memory.lineage()` chain traversal. Cleared
+     * to NULL (never resurrected to active) if the successor is later forgotten.
      */
-    lint(options?: {
-        limit?: number;
-    }): Promise<WikiLintReport$1>;
-    /** Run decay on all entries, archiving those below threshold. */
-    runDecay(): Promise<number>;
-    /** Reindex the FTS5 full-text search index. */
-    reindex(): Promise<void>;
-    /** Delete all entries matching a source, cleaning up all stores. */
-    deleteBySource(source: string, options?: TenantScopeOptions): Promise<number>;
-    /** Repair stale graph references left by older delete paths or crashed cleanup. */
-    repairGraph(): Promise<GraphRepairResult$1>;
+    supersededByEntryId?: string;
     /**
-     * Chronological feed of memory entries (Karpathy `log.md` primitive).
-     * Cursor-based via `since` (created_at lower bound). No totalCount.
+     * @internal Hosted data-plane only. SHA-256 of the canonical caller store
+     * payload (server-stamped timestamps excluded), persisted for caller-id
+     * stores so a re-send of the same `metadata.dbRef.revision` can be
+     * classified as an idempotent no-op (digest match) or a
+     * `revision_reuse_conflict` (digest mismatch). Graph entities/relationships
+     * are part of the payload but not of the row, so the digest cannot be
+     * recomputed from stored state.
      */
-    log(filters?: MemoryLogFilters): Promise<MemoryEntry$1[]>;
+    payloadDigest?: string;
+}
+interface MemorySearchParams {
+    query: string;
+    type?: MemoryType;
+    agentId?: AgentId;
+    /** Optional caller session identifier used for in-process hygiene telemetry. */
+    sessionId?: string;
+    limit?: number;
+    strategy?: RAGStrategy;
+    /** Filter results to entries whose eventTime falls within [start, end] (ISO 8601). */
+    eventTimeRange?: [string, string];
+    /** Filter results to entries ingested before this cutoff (ISO 8601). Falls back to createdAt when ingestTime is null. */
+    asOf?: string;
     /**
-     * Synthesize a per-entity profile (Karpathy-wiki "wiki page" primitive).
-     * LLM-driven, caller-triggered. Stores a pinned `_kind:'entity-summary'`
-     * entry with `_search_visibility:'on-demand'` so it never enters the
-     * default retrieval pool. Re-running replaces the prior synthesis.
+     * Soft recency ANCHOR (ISO 8601) — never a filter. Candidates are ranked by
+     * proximity to this time instead of now, and conflicting assertions
+     * re-order around it. Resolving relative-time expressions ("two months
+     * ago", "3년 전") to an absolute timestamp is the CALLER's side of the
+     * agentic contract — language understanding never enters the engine. Wins
+     * over the query-text year parse (hybrid strategy).
      */
-    summarizeEntity(name: string): Promise<MemoryEntry$1>;
+    anchorTime?: string;
     /**
-     * Fetch a previously-synthesized entity profile. Returns `null` when no
-     * synthesis exists yet. O(1) — the read side of the amortized pattern.
+     * The category the user is asking to count/list (e.g. "fitness classes",
+     * "운동 수업", any language). Presence signals enumeration intent and supplies
+     * the category for graph resolution; the caller (which understands the user's
+     * language) sets it. When omitted, pyx falls back to a deterministic EN/KO
+     * marker detector.
      */
-    getEntitySynthesis(name: string): Promise<MemoryEntry$1 | null>;
-}
-
-/**
- * No-op {@link MemoryInterface} for hosts that run without a memory backend
- * (e.g. `MEMORY_URL` is unset). Every method returns a safe default, so the
- * rest of the system functions without branching on `memory == null`.
- *
- * Canonical single source: this lives in the SAME package as `MemoryInterface`,
- * so any method added to the interface fails THIS class's compile in the same
- * build. The null-object can never silently drift behind the contract — the
- * failure mode that left hand-rolled copies in downstream repos missing
- * `lineage`/`reinforce` after the interface grew them.
- *
- * `initialize()` emits a single `console.warn`; pass nothing else — it is a
- * pure null-object. Hosts wanting structured logging should log at the wiring
- * site where they choose `DisabledMemory` over a real client.
- */
-declare class DisabledMemory implements MemoryInterface {
-    initialize(): Promise<void>;
-    store(entry: StoreInput$1): Promise<MemoryEntry$1>;
-    search(): Promise<MemorySearchResult$1>;
-    list(params?: MemoryListParams): Promise<MemoryListResult>;
-    get(): Promise<MemoryEntry$1 | null>;
-    delete(): Promise<boolean>;
-    clearSession(): Promise<number>;
-    stats(): Promise<MemoryStats$1>;
-    insights(): Promise<MemoryInsights$1>;
-    queryAsOf(): Promise<MemoryEntry$1[]>;
-    lineage(): Promise<LineageResult$1>;
-    reinforce(): Promise<ReinforceResult$1>;
-    queryByEventTime(): Promise<MemoryEntry$1[]>;
-    shutdown(): Promise<void>;
-}
-
-/**
- * Callbacks for two-phase file enrichment. All callbacks are optional:
- *   - Image-rich PDF + describeImage only → describes images, no entity extraction
- *   - Image-rich PDF + describeImage + extractEntitiesV2 → describes + extracts
- *   - Text-only file + extractEntitiesV2 only → extracts from textWindows
- *   - Mixed file + both → describes images + extracts from both sources
- *
- * Without any callback, the ingest stream emits the server result with no
- * SDK-side enrichment. Server-side text/entity extraction may still run when
- * configured; image understanding still requires caller-provided
- * descriptions/hooks.
- */
-interface EnrichmentCallbacks {
+    enumerationConcept?: string;
+    /** Confidence threshold below which the system recommends abstention (0.0–1.0). Default: 0.3. */
+    abstentionThreshold?: number;
     /**
-     * Describe an image using LLM vision. Receives the raw image buffer and
-     * metadata. Required for image-bearing files; safe to omit for text-only
-     * uploads where the server emits zero images.
+     * Rerank with the cross-encoder before final truncation (hybrid strategy
+     * only). The pipeline retrieves and dedups a deeper candidate pool (≥50),
+     * scores it through the cross-encoder, then truncates to `limit` —
+     * reranking after truncation cannot change top-`limit` set membership.
+     * Forwarded by `MemoryClient.search` and the HTTP route; core enforces
+     * hybrid-only usage.
      */
-    describeImage?: (imageBuffer: ArrayBuffer, meta: ExtractedImageMeta$1) => Promise<string>;
+    enableRerank?: boolean;
     /**
-     * Entity-extraction callback. Receives text windows and image descriptions
-     * separately so callers can apply different prompts per source. Triggers
-     * the `X-Pyx-Enrichment-Capabilities: text_windows_v1` negotiation header
-     * on ingest.
+     * Iterative multi-hop candidate generation (hybrid strategy only). After the
+     * first retrieval pass, non-oracle bridge entities are mined from the top
+     * seed passages, a second dense+lexical pass is seeded by those bridges, and
+     * both passes' ranked lists are fused into a single RRF before scoring and
+     * (optional) rerank-then-truncate. Grows the candidate pool to surface
+     * later-hop passages the single-pass query misses. Deterministic: no
+     * query-time LLM, fixed bridge order. Default off keeps the pipeline
+     * byte-identical. EMBEDDED ONLY: `MemoryClient.search` rejects it (the HTTP
+     * API does not forward it).
      */
-    extractEntitiesV2?: (input: {
-        textWindows: string[];
-        imageDescriptions: string[];
-        mimeType: string;
-        filename: string;
-    }) => Promise<{
-        entities: IngestEntity$1[];
-        relationships: IngestRelationship$1[];
-    }>;
-}
-/**
- * Options for {@link MemoryClient.ingestFileEvents}. `signal` lets
- * long-running ingests (LLM enrichment + graph writes) be cancelled cleanly.
- *
- * `namespaceId` opts the upload into ReBAC AuthzPlan visibility — the server
- * thread the namespace through parsing → enrichment → store calls so the
- * resulting catalog row and chunk entries land in the named namespace
- * (server v0.17.4+; required when `requireNamespaceForTenantWrites=true`).
- */
-interface IngestFileOptions {
-    description?: string;
-    enrichment?: EnrichmentCallbacks;
-    signal?: AbortSignal;
-    namespaceId?: string;
+    enableMultiHop?: boolean;
     /**
-     * Stable logical document identity used for replaceable content, image,
-     * and graph projections. Requires `enrichment.extractEntitiesV2` so the
-     * client can negotiate text windows and complete the stable replacement.
+     * Explicit bridge entities for the second multi-hop pass, bypassing mining.
+     * EVAL ONLY — used by the benchmark oracle-ceiling probe to isolate fusion
+     * capacity from mining quality; never set on a production path. Ignored
+     * unless `enableMultiHop` is also set.
      */
-    documentKey?: string;
+    multiHopBridges?: string[];
     /**
-     * Migration-only pinned file-ingestion catalog for this document's first
-     * stable replacement. The server validates its exact scope and uses its
-     * bounded provenance to detach legacy graph references. Omit this after the
-     * stable anchor is established: the first pass may retire catalog-owned
-     * projections, so later revisions should use `documentKey` alone.
+     * Set false for a read-only search that does NOT bump access counts /
+     * lastAccessed on returned entries. Access feeds ranking (WEIGHT_ACCESS and
+     * the no-eventTime recency fallback), so a measurement that searches the
+     * store mutates what it measures — repeated benchmark runs over a persisted
+     * index drift. Default true (access tracking is the product's usage signal).
      */
-    catalogEntryId?: string;
-}
-/**
- * Options for {@link MemoryClient.graphEnrichFileEvents}. `documentKey` is the
- * caller's stable logical identity for the document whose graph is being
- * rebuilt — the server derives the graph anchor id from
- * (tenant, namespace, documentKey), so repeating the same key replaces the
- * document's graph references instead of multiplying them.
- *
- * `enrichment.extractEntitiesV2` is required: graph-only re-enrichment is
- * caller-extraction by definition (there is no server-side fallback).
- */
-interface GraphEnrichFileOptions {
-    documentKey: string;
+    trackAccess?: boolean;
     /**
-     * Migration-only pinned file-ingestion catalog for the first stable graph
-     * replacement. The server resolves it in the current tenant/namespace and
-     * detaches its bounded graph references. Omit it on later revisions once
-     * the `documentKey` anchor exists.
-     */
-    catalogEntryId?: string;
-    namespaceId?: string;
-    signal?: AbortSignal;
-    enrichment: EnrichmentCallbacks;
-}
-interface FileDownloadOptions {
-    /** Stable logical document identity used by documentKey-aware ingest. */
-    documentKey?: string;
-    /** Exact namespace containing the uploaded document. */
-    namespaceId?: string;
-}
-/**
- * Caller-supplied enrichment for the per-call store path. Mirrors
- * {@link EnrichmentCallbacks} for file ingest. When supplied, the SDK invokes
- * the callback and merges the result into the payload before POSTing. Without
- * a callback, server-side text/entity extraction can run only when the server
- * has an extraction brain configured; otherwise callers must pass graph data
- * or use caller-side hooks. Images always require caller-provided
- * descriptions/hooks.
- */
-interface StoreEnrichmentCallbacks {
-    /**
-     * Extract entities + relationships from `content`. The caller's LLM does
-     * the work; the SDK passes the result through {@link mergeExtractedEntities}
-     * (caller-wins, case-insensitive) before sending to the server.
-     *
-     * Skipped when `entry.extractEntities === false`. When
-     * `entry.extractEntities === true` but this callback is not supplied,
-     * `MemoryClient.store()` forwards the hint so the server-side extraction
-     * brain can run and loud-fail if it is not configured.
-     */
-    extractEntities?: (input: {
-        content: string;
-        metadata?: Record<string, unknown>;
-        signal?: AbortSignal;
-    }) => Promise<EntityExtractionResult$1>;
-}
-/** Options accepted by {@link MemoryClient.store}. */
-interface StoreOptions {
-    enrichment?: StoreEnrichmentCallbacks;
-    /** Propagated into the `extractEntities` callback and the underlying fetch. */
-    signal?: AbortSignal;
-    /** Stable logical request key. Reuse this exact value after a lost response. */
-    idempotencyKey?: string;
-}
-interface RequestAuthorityOptions {
-    /** Stable logical request key. Reuse this exact value after a lost response. */
-    idempotencyKey?: string;
-}
-/** Error thrown by MemoryClient when the server returns a non-success response. */
-declare class MemoryServerError extends Error {
-    readonly status: number;
-    /** Stable machine-readable discriminator returned by the memory server. */
-    readonly code?: string;
-    /** Exact HTTP Retry-After value returned by the memory server. */
-    readonly retryAfter?: string;
-    /** Retry delay normalized to seconds when Retry-After is parseable. */
-    readonly retryAfterSeconds?: number;
-    constructor(message: string, status: number, code?: string, retryAfter?: string);
-    /** True when the server returned HTTP 404 (not found). */
-    get isNotFound(): boolean;
-}
-interface MemoryClientOptions {
-    /** API key for authentication. */
-    apiKey?: string;
-    /** Additional headers to send with every request (e.g., X-Caller-Access-Level). */
-    defaultHeaders?: Record<string, string>;
-    /**
-     * Default per-request timeout in milliseconds. Without this, a wedged
-     * memory server (e.g. event-loop blocked by inference) makes every
-     * caller hang forever — that was the Korens demo wedge in 2026-04 where
-     * a 161-second pyx-memory stall propagated through the runtime to the
-     * browser. Defaults to 30 s, which is high enough that normal
-     * `/search` and `/stats` requests never hit it but low enough that a
-     * stuck server fails loudly.
-     *
-     * Only applied when the caller does NOT pass their own `signal` via
-     * RequestInit. Long-running operations (large `consolidate`, `reindex`,
-     * file ingest with enrichment) should pass their own AbortSignal —
-     * that signal fully replaces the default ceiling.
-     */
-    requestTimeoutMs?: number;
-}
-declare class MemoryClient implements ExtendedMemoryInterface {
-    protected baseUrl: string;
-    private readonly _authHeaders;
-    private readonly _requestTimeoutMs;
-    constructor(memoryUrl: string, apiKeyOrOptions?: string | MemoryClientOptions);
-    /** Encode a path segment to prevent URL injection */
-    private encodePathSegment;
-    private authorityHeaders;
-    private exactReadAuthority;
-    initialize(): Promise<void>;
-    store(entry: StoreInput$1, options?: StoreOptions): Promise<MemoryEntry$1>;
-    search(params: MemorySearchParams$1, authority?: RequestAuthorityOptions & Pick<TenantScopeOptions, 'tenantId' | 'namespaceId'>): Promise<MemorySearchResult$1>;
-    get(id: string, authority?: TenantScopeOptions & RequestAuthorityOptions): Promise<MemoryEntry$1 | null>;
-    delete(id: string, authority?: TenantScopeOptions & RequestAuthorityOptions): Promise<boolean>;
-    clearSession(sessionId: string): Promise<number>;
-    stats(options?: TenantScopeOptions): Promise<MemoryStats$1>;
-    insights(options?: TenantScopeOptions & RequestAuthorityOptions): Promise<MemoryInsights$1>;
-    /**
-     * Fetch the running server's topology snapshot (build variant, declared
-     * role, embedding location, active model profile). Round-trips the
-     * server's `GET /status` envelope through {@link fetchApi}, surfacing any
-     * non-success response as {@link MemoryServerError}. Auth-header
-     * forwarding is unchanged from other client methods even though `/status`
-     * is server-side public — the server simply ignores credentials on that
-     * route.
-     */
-    status(): Promise<Topology$1>;
-    shutdown(): Promise<void>;
-    list(params?: MemoryListParams, authority?: RequestAuthorityOptions & Pick<TenantScopeOptions, 'tenantId' | 'namespaceId'>): Promise<MemoryListResult>;
-    /**
-     * Native streaming file ingest. Yields typed {@link IngestEvent}s as the
-     * server (parsing/storing) and the SDK (enrichment/result) make progress.
-     *
-     * Wire contract: SDK POSTs with `Accept: application/x-ndjson`; the server
-     * MUST respond with NDJSON. There is no JSON fallback — older servers
-     * that emit `application/json` for this endpoint are not supported, and
-     * the SDK yields a terminal `error` event in that case.
-     *
-     * After the server's terminal `result`, the SDK runs its own enrichment
-     * phase (image-describe → entity-extract → `/enrich` POST), emitting
-     * progress + heartbeat events around each step, then yields the single
-     * terminal `result` event with the merged SDK + server result.
-     *
-     * Promise-shaped consumers should iterate the returned AsyncIterable and
-     * collect the terminal event; there is no separate `ingestFile()` Promise
-     * method by design (one wire format, one SDK method).
-     */
-    ingestFileEvents(file: File, options?: IngestFileOptions): AsyncIterable<IngestEvent$1>;
-    /**
-     * Graph-only re-enrichment for a document whose chunks are already stored
-     * and searchable but whose graph build failed. Uploads the original to
-     * `/api/memory/graph/enrich/file` (prepare-only — the server performs zero
-     * store/delete before the final graph write), runs the SAME enrichment
-     * callback engine as {@link ingestFileEvents}, then finalizes into one
-     * stable graph anchor keyed by `documentKey`. Repeating the same key
-     * replaces the document's graph references idempotently.
-     *
-     * The terminal `result` is a {@link GraphEnrichResult} event carrying the
-     * ACTUAL persisted graph counts; abort and failures yield a terminal
-     * `error` event instead (the server retains the pending session for retry).
-     */
-    graphEnrichFileEvents(file: File, options: GraphEnrichFileOptions): AsyncIterable<GraphEnrichEvent$1>;
-    /**
-     * POST a multipart body to an NDJSON streaming endpoint and relay its
-     * progress/heartbeat events. Returns the raw terminal `result` record, or
-     * null after yielding a terminal error (transport failure, server error
-     * event, non-NDJSON response, stream ending without a result). One
-     * implementation for both streaming surfaces so the wire protocol cannot
-     * fork.
+     * Retrieval EFFORT tier (H8 slice 1b) — admits candidates by activation
+     * strength BEFORE RRF fusion (like LLM thinking-mode depth): `quick` = the
+     * strongest (sharpest top), `medium` = strong+mid, `deep` = everything
+     * including cold + superseded + archived rows. **Omitted ⇒ byte-identical to
+     * pre-1b behavior** (no activation lookup; all rows admitted, superseded/
+     * archived hidden as in 1a). Strength rises only via `Memory.reinforce` (recall
+     * reinforces); idle alone never revives. See `docs/H8-MEMORY-MODEL-DESIGN.md`.
      */
-    private streamNdjsonUpload;
+    effort?: 'quick' | 'medium' | 'deep';
+    /** Maximum sensitivity level to include in results. Entries above this level are excluded. */
+    maxSensitivity?: SensitivityLevel;
+    /** Tenant ID for multi-tenant isolation. */
+    tenantId?: string;
+    /** User ID within the tenant. */
+    userId?: string;
+    /** Team/group ID within the tenant. */
+    teamId?: string;
     /**
-     * Run the SDK-side enrichment phase for an ingest result and yield the
-     * single terminal {@link IngestResultEvent} at the end. Skips work cleanly
-     * when the server emitted no enrichment block or the caller wired no
-     * callbacks. The callback work itself lives in
-     * {@link runEnrichmentCallbacks} — shared with the graph-only surface.
+     * Exact namespace requested by a trusted transport boundary. `Memory.search`
+     * validates it against the calling principal's AuthzPlan and compiles it to
+     * a singleton prefilter. Exact scope excludes legacy NULL rows.
      */
-    private completeIngestFileEvents;
+    namespaceId?: string;
     /**
-     * The ONE enrichment callback engine, shared by {@link ingestFileEvents}
-     * and {@link graphEnrichFileEvents}: fetches extracted images, invokes
-     * `describeImage` with bounded concurrency, invokes `extractEntitiesV2`
-     * exactly once, and POSTs `/files/{fileId}/enrich` — emitting progress and
-     * heartbeat events around each slow step. Throws on any failure; the
-     * purpose-specific wrappers translate that into their terminal error.
+     * AuthzPlan-derived visibility list. Populated internally by `Memory.search`
+     * after computing the plan from the calling principal — callers should
+     * NOT set this directly. Empty array means "no granted namespaces" (only
+     * legacy NULL-namespace entries are visible). `undefined` skips the
+     * filter (single-tenant / pre-ReBAC compat).
      *
-     * Legacy ingest keeps its existing partial add-on behavior. Graph-only and
-     * documentKey-aware full ingest may replace a prior graph only from a
-     * complete input set (no truncated text windows or undescribed images). A
-     * complete extractor result containing zero entities remains a valid clear.
-     */
-    private runEnrichmentCallbacks;
-    /**
-     * Race a Promise against a periodic heartbeat tick. Yields a heartbeat
-     * IngestEvent every {@link INGEST_EVENT_HEARTBEAT_MS} until the promise
-     * settles, then returns the resolved value (or rethrows). Lets callers
-     * keep upstream sockets alive through long LLM/HTTP work without
-     * coupling the heartbeat cadence to the work itself.
+     * Callers must not set this directly; use `namespaceId` for exact scope.
      */
-    private withSdkHeartbeats;
-    private normalizeActiveIngestStage;
-    private fileIngestResultFromEvent;
-    private ingestErrorEvent;
+    namespaceIds?: string[];
+    /** Strict namespace equality compiled internally from `namespaceId`. */
+    exactNamespaceId?: string;
     /**
-     * Get the download URL for an uploaded file.
-     * Returns a URL that serves the original file binary with proper Content-Type.
+     * AuthzPlan-derived list of strict-mode namespaces in the caller's
+     * tenant the principal CANNOT see (v0.17.0). Graph traversal MUST
+     * drop edges whose `namespace_id` matches the supplied set even when
+     * the surrounding KG node is otherwise reachable. Populated
+     * internally by `Memory.search` from `AuthzPlan.forbiddenStrict
+     * NamespaceIds` — callers should NOT set this directly.
      */
-    getFileDownloadUrl(filename: string, options?: FileDownloadOptions): string;
+    forbiddenStrictNamespaceIds?: string[];
+}
+interface MemorySearchResult {
+    entries: MemoryEntry[];
+    totalCount: number;
+    strategy: RAGStrategy;
+    /** Visible graph slice that supported the returned entries, when graph traversal contributed. */
+    graph?: GraphTraversalResult;
     /**
-     * Download an uploaded file by filename.
-     * Returns the raw Response (caller handles the body — arrayBuffer, blob, stream, etc.).
+     * Optional scored entries for ranked results. `score` is the fused RANK score
+     * (RRF + recency/importance/access priors) — good for ordering, NOT a relevance
+     * magnitude. `vectorSimilarity` is the raw dense query-similarity (LanceDB
+     * transformed-L2, 1/(1+distance)); null when the entry has no dense signal
+     * (FTS/graph-only). Surface vectorSimilarity, not score, as a "% match".
      */
-    downloadFile(filename: string, options?: FileDownloadOptions): Promise<Response>;
-    /** @deprecated Use {@link list} instead. Kept for backwards compatibility. */
-    listEntries(params?: {
-        page?: number;
-        limit?: number;
-    }): Promise<MemoryEntry$1[]>;
-    graphNodes(): Promise<GraphNode$1[]>;
-    graphEdges(): Promise<{
-        stats: {
-            nodeCount: number;
-            edgeCount: number;
-            rawNodeCount?: number;
-            rawEdgeCount?: number;
-        };
+    scoredEntries?: Array<{
+        entry: MemoryEntry;
+        score: number;
+        vectorSimilarity?: number | null;
     }>;
-    graphQuery(query: {
-        nodeId: string;
-        depth?: number;
-    }): Promise<GraphTraversalResult$1>;
-    consolidate(): Promise<ConsolidationRunResult>;
-    forget(id: string, reason?: string): Promise<boolean>;
-    summarizeSession(sessionId: string): Promise<MemoryEntry$1 | null>;
-    lint(options?: {
-        limit?: number;
-    }): Promise<WikiLintReport$1>;
-    runDecay(): Promise<number>;
-    reindex(): Promise<void>;
-    clearGraph(): Promise<number>;
-    repairGraph(): Promise<GraphRepairResult$1>;
-    deleteBySource(source: string, authority?: TenantScopeOptions): Promise<number>;
-    setFolder(from: string, to: string, options?: {
-        dryRun?: boolean;
-    }): Promise<{
-        from: string;
-        to: string;
-        updated: number;
-        dryRun: boolean;
-    }>;
-    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters, authority?: TenantScopeOptions): Promise<MemoryEntry$1[]>;
-    lineage(params: LineageParams$1, authority?: RequestAuthorityOptions): Promise<LineageResult$1>;
-    reinforce(params: ReinforceParams$1, authority?: RequestAuthorityOptions): Promise<ReinforceResult$1>;
-    log(filters?: MemoryLogFilters): Promise<MemoryEntry$1[]>;
-    queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
-    summarizeEntity(name: string): Promise<MemoryEntry$1>;
-    getEntitySynthesis(name: string): Promise<MemoryEntry$1 | null>;
-    /**
-     * v0.26 user-profile snapshot — upsert. The server derives `userId`
-     * from `X-User-Id` (caller wires it via `defaultHeaders` on the
-     * client constructor or per-request middleware); the body cannot
-     * override it. See spec §Requirements 10.
-     */
-    upsertUserProfile(input: {
-        namespaceId: string;
-        content: string;
-    }): Promise<{
-        updatedAt: string;
-        contentSize: number;
-    }>;
-    /**
-     * v0.26 user-profile snapshot — fetch by namespace. Returns `null` on
-     * HTTP 404 (`isNotFound`), rethrows any other non-2xx as
-     * `MemoryServerError`. Mirrors `get()`'s 404-to-null pattern so callers
-     * can branch on "no profile yet" without inspecting status codes.
-     */
-    getUserProfile(namespaceId: string): Promise<{
-        content: string;
-        updatedAt: string;
-        contentSize: number;
-    } | null>;
-    /**
-     * v0.28 correction-memory — record an explicit correction. POSTs to
-     * `/api/memory/corrections`; tenant is header-derived (server-side), so
-     * the body carries only the correction fields. Returns `{ id, createdAt }`.
-     */
-    recordCorrection(input: {
-        /** Omit in single-tenant deployments — corrections are stored namespace-free. */
-        namespaceId?: string;
-        whatWasWrong: string;
-        whatToDoInstead: string;
-        appliesWhen: string;
-        project?: string;
-        taskShape?: string;
-    }): Promise<{
-        id: string;
-        createdAt: string;
-    }>;
-    /**
-     * v0.28 correction-memory — fetch the corrections applicable to a task
-     * shape. GETs `/api/memory/corrections`; returns `[]` when none have
-     * positive overlap. pyx never auto-prepends — the agent owns inclusion.
-     */
-    fetchApplicableCorrections(input: {
-        /** Omit in single-tenant deployments — reads the namespace-free scope. */
-        namespaceId?: string;
-        taskShape: string;
-        project?: string;
-        limit?: number;
-    }): Promise<CorrectionRecord$1[]>;
-    /**
-     * H26 B-d — deterministic prospective due-scan: entries with
-     * `eventTime ∈ [from, from+windowDays]` (inclusive), eventTime ascending,
-     * no relevance ranking. `GET /api/memory/due`.
-     */
-    dueScan(input: {
-        windowDays: number;
-        from?: string;
-        /** Omit in single-tenant deployments. */
-        namespaceId?: string;
-        limit?: number;
-    }): Promise<MemoryEntry$1[]>;
-    protected fetchApi<T>(path: string, options?: RequestInit): Promise<T>;
-    /**
-     * Map fetch-layer rejections into a typed `MemoryServerError` so callers
-     * can react uniformly. AbortSignal.timeout fires a `TimeoutError`; the
-     * caller's signal generally fires an `AbortError`. Anything else (DNS,
-     * TCP reset, TLS) becomes a wrapped error with status 0.
-     */
-    private translateFetchError;
-    /** Parse and validate a JSON API response, throwing MemoryServerError on any failure. */
-    private parseApiResponse;
+    /** Confidence assessment for abstention. Present when search produces scored entries. */
+    confidence?: {
+        /** Overall confidence 0.0–1.0. */
+        confidence: number;
+        /** Whether the system recommends abstaining (confidence below threshold). */
+        shouldAbstain: boolean;
+        /** Raw signals used to compute confidence. */
+        signals: {
+            topScore: number;
+            scoreGap: number;
+            scoreStdDev: number;
+            resultCount: number;
+            aboveThresholdRatio: number;
+            scoreSeparation: number;
+        };
+    };
 }
-
-interface IngestionResult {
-    filename: string;
-    fileType: string;
-    chunks: number;
-    entryIds: string[];
-    totalCharacters: number;
+/** One version in a fact's history, as returned by {@link LineageResult}. */
+interface LineageVersion {
+    entryId: string;
+    /** The entry content carrying this version's value. */
+    value: string;
+    eventTime?: string;
+    ingestTime?: string;
+    status: 'active' | 'superseded' | 'archived';
+    /** Set when this version was superseded by a newer entry. */
+    supersededByEntryId?: string;
 }
-
-declare const DEFAULTS: {
-    readonly DATA_DIR: "./data";
-    readonly VECTOR_PROVIDER: "lancedb";
-    readonly MEMORY_SERVER_PORT: 7822;
-};
-declare const TAXONOMY_MAX_CATEGORIES = 10;
-declare const TAXONOMY_MAX_TOP_ENTITIES = 15;
-declare const TAXONOMY_MAX_SAMPLE_TOPICS = 8;
-declare const TAXONOMY_MAX_PROJECTS = 8;
-declare const MEMORY_PROJECT_LABEL_MAX_CHARS = 80;
-
-/** ISO 8601 timestamp string */
-type Timestamp = string;
-/** Unique agent identifier */
-type AgentId = string;
-
 /**
- * Caller identity for ReBAC authorization.
- *
- * The canonical "subject" in Zanzibar terms — passed alongside requests so the
- * memory layer can compute an AuthzPlan (visible namespaces + entry overrides)
- * before any retrieval source fans out.
- *
- * Identity comes from authenticated request context (X-Tenant-Id / auth token
- * claims), never from request bodies or multipart form fields. The legacy
- * `userId` / `teamId` / `agentId` columns on MemoryEntry remain for audit and
- * legacy filters but MUST NOT drive authorization decisions — they are
- * collision-prone aliases (a service principal sharing an ID with a human
- * user has no protection against confused-deputy attacks).
- *
- * Sensitivity / clearance is intentionally NOT on this object. It is a
- * MAC-style classification, orthogonal to RBAC, and continues to be carried
- * via the `X-Caller-Access-Level` header → `MemorySearchParams.maxSensitivity`.
- * Conflating the two couples future changes (e.g. per-namespace classification
- * rules) to identity propagation.
+ * Query for the evolution of a fact (H8 `Memory.lineage`). Provide either a
+ * `subject` (+ optional `relation`) for graph-backed subject/relation lineage,
+ * OR an `entryId` to walk the `supersededBy` chain (the only mode available
+ * without a graph store).
  */
-interface PrincipalContext {
-    /**
-     * Hard isolation boundary. Required even in single-tenant deployments —
-     * single-mode passes a stable sentinel (`SINGLE_TENANT_ID`) so authz code
-     * paths look identical regardless of mode.
-     */
-    tenantId: string;
-    /**
-     * Stable subject ID (within the tenant). For humans this is the userId;
-     * for AI runtimes it is the agentId; for system actors it is a service
-     * identifier. Combined with `kind`, forms the Zanzibar subject coordinate
-     * `<kind>:<principalId>`.
-     */
-    principalId: string;
-    /**
-     * Subject namespace. Distinguishes humans from AI agents from internal
-     * services so a userId/agentId/serviceId collision cannot grant
-     * unintended access.
-     *  - `user`: human end user
-     *  - `agent`: AI runtime acting on a user's behalf or autonomously
-     *  - `service`: non-AI internal system (cron, ETL, admin tooling)
-     */
-    kind: 'user' | 'agent' | 'service';
+interface LineageParams {
+    subject?: string;
+    relation?: string;
+    entryId?: string;
+    /** Current version as of this time (newest version with eventTime ≤ asOf). */
+    asOf?: string;
+    eventTimeRange?: [string, string];
+    /** Return only versions strictly older than the version holding this value. */
+    beforeValue?: string;
+    limit?: number;
+}
+interface LineageResult {
+    subject?: string;
+    relation?: string;
+    /** Event-time ascending (oldest → newest). */
+    versions: LineageVersion[];
+    /** Which path answered — honest provenance (graph conflict-group vs supersededBy chain). */
+    source: 'graph' | 'chain';
 }
-/** Sentinel tenant ID used in single-tenant deployments. */
-declare const SINGLE_TENANT_ID = "_single";
-
-declare const MemoryType: {
-    readonly SHORT_TERM: "short-term";
-    readonly LONG_TERM: "long-term";
-    readonly WORKING: "working";
-    readonly EPISODIC: "episodic";
-    readonly SUMMARY: "summary";
-};
-type MemoryType = (typeof MemoryType)[keyof typeof MemoryType];
-declare const SensitivityLevel: {
-    readonly PUBLIC: "public";
-    readonly INTERNAL: "internal";
-    readonly SECRET: "secret";
-};
-type SensitivityLevel = (typeof SensitivityLevel)[keyof typeof SensitivityLevel];
-declare const RAGStrategy: {
-    readonly NAIVE: "naive";
-    readonly GRAPH: "graph";
-    readonly HYBRID: "hybrid";
-};
-type RAGStrategy = (typeof RAGStrategy)[keyof typeof RAGStrategy];
 /**
- * Strategy identifiers that were public in earlier versions and have been
- * removed. Server/SDK reject requests using these with a stable
- * `strategy.deprecated:<name>` error code (not the generic "invalid
- * strategy" message) so callers and dashboards can detect the removal
- * cleanly across a version bump.
- *
- * v0.26: `agentic` removed (Codex pair: silent-catch in agentic.ts
- * violated Production-ready; behavior subsumed by HybridRAGEngine).
+ * Explicit recall-usefulness signal for {@link MemorySearchParams} `reinforce`.
+ * `context_included` = surfaced into the working context (small η); `cited` =
+ * the agent actually used it in its answer (medium η); `explicit_positive` =
+ * user/agent marked it useful (large η). Mere top-k return is NOT a signal
+ * (determinism + "returned ≠ used") — only an explicit `reinforce()` call moves
+ * strength.
  */
-declare const DEPRECATED_RAG_STRATEGIES: ReadonlyMap<string, string>;
-declare const VectorProvider: {
-    readonly LANCEDB: "lancedb";
-};
-type VectorProvider = (typeof VectorProvider)[keyof typeof VectorProvider];
-declare const EmbeddingProviderName: {
-    readonly STUB: "stub";
-    /** @deprecated Vestigial — pyx-memory uses internal EmbeddingGemma embeddings. */
-    readonly ANTHROPIC: "anthropic";
-    /** @deprecated Vestigial — pyx-memory uses internal EmbeddingGemma embeddings. */
-    readonly OPENAI: "openai";
-    /** In-process ONNX model (default: EmbeddingGemma-300M). */
-    readonly LOCAL: "local";
-    /** Remote OpenAI-compatible embedding service (pyx-cloud shared, custom, etc.). */
-    readonly HTTP: "http";
-};
-type EmbeddingProviderName = (typeof EmbeddingProviderName)[keyof typeof EmbeddingProviderName];
-type GraphEnrichmentStatus = 'caller-provided' | 'extracted' | 'merged' | 'opted-out' | 'skipped-duplicate' | 'skipped-sensitive' | 'skipped-unprovisioned' | 'extracted-empty' | 'failed-graph-write' | 'failed-best-effort';
-interface GraphEnrichment {
-    status: GraphEnrichmentStatus;
-    provider?: 'http' | 'local' | 'none';
-    reason?: string;
-    action?: string;
+type ReinforceSignal = 'context_included' | 'cited' | 'explicit_positive';
+interface ReinforceParams {
+    entryIds: string[];
+    signal: ReinforceSignal;
+    /** When the recall happened — epoch-ms, or full ISO-8601 WITH timezone. Date-only / tz-free is rejected. Defaults to the activation clock. */
+    at?: string | number;
+}
+interface ReinforceResult {
+    /** Per-entry post-reinforce activation. Entries absent from the store are omitted. */
+    updated: Array<{
+        entryId: string;
+        strength: number;
+        tier: 'quick' | 'medium' | 'deep';
+    }>;
+}
+interface SourceEvidence {
+    /** Memory entry that produced this graph fact. */
+    memoryEntryId: string;
+    /** Data tenant of the source entry. `null` = single-tenant / legacy data. */
+    tenantId?: string | null;
+    /** Namespace of the source memory entry. `null` = legacy / tenant-root. */
+    namespaceId?: string | null;
+    /** Optional source identifier copied from the memory entry or caller. */
+    source?: string;
+    /** Optional content hash copied from the memory entry or caller. */
+    contentHash?: string;
+    /** Optional short text evidence for the graph fact. */
+    snippet?: string;
+    /** When this evidence was recorded. */
+    createdAt?: Timestamp;
 }
-/**
- * A caller-supplied relationship whose source or target name did not resolve to
- * any entity in the same store call (after name normalization), so the edge was
- * not written. Surfaced on the store response so the agent — not just the server
- * log — can see which edges to re-send.
- */
-interface DroppedGraphRelationship {
+declare const StoreTarget: {
+    readonly SQLITE: "sqlite";
+    readonly VECTOR: "vector";
+    readonly GRAPH: "graph";
+};
+type StoreTarget = (typeof StoreTarget)[keyof typeof StoreTarget];
+/** Agent-provided entity for graph storage. */
+interface IngestEntity {
+    /** Entity name (e.g., "Alice", "TypeScript"). */
+    name: string;
+    /** Entity type — freeform, agent decides (e.g., "PERSON", "TOOL"). */
+    type: string;
+    /** Stable canonical identifier. Defaults to a deterministic name+type id. */
+    canonicalId?: string;
+    /** Source evidence for this graph node. Defaults to the containing memory entry. */
+    sourceEvidence?: SourceEvidence[];
+    /** Optional properties to attach to the graph node. */
+    properties?: Record<string, unknown>;
+}
+/** Agent-provided relationship for graph storage. */
+interface IngestRelationship {
+    /** Source entity name (must match an entity in the entities array). */
     source: string;
+    /** Target entity name (must match an entity in the entities array). */
     target: string;
+    /** Relationship type — freeform, agent decides (e.g., "WORKS_AT", "USES"). */
     type: string;
+    /** Source evidence for this graph edge. Defaults to the containing memory entry. */
+    sourceEvidence?: SourceEvidence[];
+    /** Optional properties to attach to the graph edge. */
+    properties?: Record<string, unknown>;
 }
-type VectorStatus = 'pending' | 'stored' | 'skipped';
-interface MemoryEntry {
+/**
+ * How `Memory.store()` should react when the graph write fails.
+ * - `throw` (default, since v0.13.0): propagate the failure so the caller
+ *   knows the graph is incomplete. Honest contract: a graph write either
+ *   commits or fails loudly. Silent partial-loss was the v0.12.2 bug that
+ *   masked 91/92 dropped entities.
+ * - `best-effort`: swallow the error and log a warning; the entry is still
+ *   considered ingested in SQLite/vector. Use only when you genuinely don't
+ *   need the graph slice and a transient neo4j blip shouldn't fail ingest.
+ */
+type GraphFailureMode = 'throw' | 'best-effort';
+/** Store input: what the agent sends to Memory.store(). */
+type StoreInput = Omit<MemoryEntry, 'id' | 'createdAt'> & {
+    id?: string;
+    createdAt?: string;
+    /** Storage targets. Default: ["sqlite", "vector"]. */
+    targets?: StoreTarget[];
+    /** Agent-provided entities for graph storage. */
+    entities?: IngestEntity[];
+    /** Agent-provided relationships for graph storage. */
+    relationships?: IngestRelationship[];
+    /** Override graph entity extraction for this store call. */
+    extractEntities?: boolean;
+    /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
+    graphFailureMode?: GraphFailureMode;
+};
+/**
+ * `Memory.expand()` input (eng-pull FD2): `baseEntryIds` is the caller's
+ * declared context in ITS order (dedupe set only; ids need not resolve);
+ * `anchorEntryIds` ⊆ base, in the caller's priority order.
+ */
+type ExpandParams = {
+    baseEntryIds: string[];
+    anchorEntryIds: string[];
+};
+type ExpandAnchorStatus = {
     id: string;
-    content: string;
-    type: MemoryType;
-    agentId?: AgentId;
+    status: 'expanded';
+    sessionId: string;
+    sessionOrdinal: number;
+} | {
+    id: string;
+    status: 'not_expandable';
+    reason: 'not_found' | 'not_active' | 'no_ordinal';
+};
+/** `added` = full entries in admission order (±1 then ±2 per anchor, anchors in request order). */
+interface ExpandResult {
+    added: MemoryEntry[];
+    anchors: ExpandAnchorStatus[];
+}
+interface MemoryIngestRequest {
+    content?: string;
+    type?: MemoryType;
+    metadata?: Record<string, unknown>;
+    agentId?: string;
     sessionId?: string;
-    metadata: Record<string, unknown>;
-    /** @deprecated Vestigial — embeddings are managed internally by the vector store. */
-    embedding?: number[];
-    createdAt: Timestamp;
-    /** SHA-256 hash of content for deduplication. */
-    contentHash?: string;
+    sessionOrdinal?: number;
+    /** Storage targets. Default: ["sqlite", "vector"]. */
+    targets?: StoreTarget[];
+    /** Agent-provided entities for graph storage. */
+    entities?: IngestEntity[];
+    /** Agent-provided relationships for graph storage. */
+    relationships?: IngestRelationship[];
+    /** Override graph entity extraction for this ingest request. */
+    extractEntities?: boolean;
+    /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
+    graphFailureMode?: GraphFailureMode;
     /** Importance score (1-10). */
     importance?: number;
-    /** Number of times this entry has been accessed via search. */
-    accessCount?: number;
-    /** ISO timestamp of last access via search. */
-    lastAccessed?: string;
-    /** Parent entry ID for hierarchical storage (e.g., doc → section → chunk). */
-    parentId?: string;
-    /** Source identifier (e.g., filename, URL, session). */
+    /** Source identifier (e.g., filename, URL). */
     source?: string;
-    /** When the event described by this memory occurred. */
+    /** When the event occurred (ISO timestamp). */
     eventTime?: string;
-    /** When this entry was ingested into the system. */
-    ingestTime?: string;
-    /** Sensitivity classification based on content analysis. */
-    sensitivity?: SensitivityLevel;
-    /** Whether the content field is encrypted at rest. */
-    encrypted?: boolean;
-    /** Number of graph entities written by this store call. Present on store responses. */
-    graphEntitiesWritten?: number;
-    /** Number of graph relationships written by this store call. Present on store responses. */
-    graphRelationshipsWritten?: number;
-    /** Count of caller relationships dropped because an endpoint name did not match any entity in the call. Present (and >0) only when edges were dropped. */
-    graphRelationshipsDropped?: number;
-    /** Up to 20 of the dropped relationships (source/target/type), so the agent can re-send them. Present only when edges were dropped. */
-    graphRelationshipsDroppedDetail?: DroppedGraphRelationship[];
-    /** Graph extraction/enrichment outcome for this store call. Present on graph-targeted store responses. */
-    graphEnrichment?: GraphEnrichment;
-    /** Store response vector outcome. Pending means SQLite is durable and vector indexing is eventually consistent. */
-    vectorStatus?: VectorStatus;
-    /** Tenant ID for multi-tenant isolation. */
-    tenantId?: string;
-    /** User ID within the tenant. */
-    userId?: string;
-    /** Team/group ID within the tenant. */
-    teamId?: string;
-    /**
-     * Namespace ID — the primary protected resource for ReBAC authorization.
-     * `undefined` (NULL on the row) means the entry lives in the legacy
-     * "tenant-root" bucket and is visible to anyone with tenant access (the
-     * pre-ReBAC posture). Setting `namespaceId` opts the entry into AuthzPlan-
-     * based filtering, where visibility is computed from `authz_tuples` for
-     * the calling principal.
-     */
-    namespaceId?: string;
-    /**
-     * When true, consolidation leaves this entry alone — it is never archived by
-     * decay and never merged (nor merged-into) by semantic deduplication. Use for
-     * stable anchor entries whose ID is referenced by external systems (e.g. a
-     * file-catalog row pointed at by another service's foreign key).
-     */
-    pinned?: boolean;
-    /**
-     * Lifecycle status (H8). Optional on write (absent means `'active'`), but
-     * every entry READ back from the store carries it explicitly — a caller can
-     * compare `entry.status === 'active'` without special-casing an absent field.
-     * `'active'` is a normal retrievable entry. `'superseded'` means a newer near-duplicate
-     * UPDATE replaced this one during consolidation. `'archived'` (1b) means decay
-     * retired it (no successor) — kept, strength 0, `deep`-tier only. All three
-     * are kept (history / lineage / deep recall) but `superseded`/`archived` are
-     * excluded from default/quick/medium search. Only `forget()` and exact-byte-
-     * duplicate collapse hard-delete. See `docs/H8-MEMORY-MODEL-DESIGN.md`.
-     */
-    status?: 'active' | 'superseded' | 'archived';
-    /**
-     * When `status==='superseded'`, the id of the newer entry that replaced this
-     * one — the backward link used by `Memory.lineage()` chain traversal. Cleared
-     * to NULL (never resurrected to active) if the successor is later forgotten.
-     */
-    supersededByEntryId?: string;
-    /**
-     * @internal Hosted data-plane only. SHA-256 of the canonical caller store
-     * payload (server-stamped timestamps excluded), persisted for caller-id
-     * stores so a re-send of the same `metadata.dbRef.revision` can be
-     * classified as an idempotent no-op (digest match) or a
-     * `revision_reuse_conflict` (digest mismatch). Graph entities/relationships
-     * are part of the payload but not of the row, so the digest cannot be
-     * recomputed from stored state.
-     */
-    payloadDigest?: string;
-}
-interface MemorySearchParams {
-    query: string;
-    type?: MemoryType;
-    agentId?: AgentId;
-    /** Optional caller session identifier used for in-process hygiene telemetry. */
-    sessionId?: string;
-    limit?: number;
-    strategy?: RAGStrategy;
-    /** Filter results to entries whose eventTime falls within [start, end] (ISO 8601). */
-    eventTimeRange?: [string, string];
-    /** Filter results to entries ingested before this cutoff (ISO 8601). Falls back to createdAt when ingestTime is null. */
-    asOf?: string;
-    /**
-     * Soft recency ANCHOR (ISO 8601) — never a filter. Candidates are ranked by
-     * proximity to this time instead of now, and conflicting assertions
-     * re-order around it. Resolving relative-time expressions ("two months
-     * ago", "3년 전") to an absolute timestamp is the CALLER's side of the
-     * agentic contract — language understanding never enters the engine. Wins
-     * over the query-text year parse (hybrid strategy).
-     */
-    anchorTime?: string;
-    /**
-     * The category the user is asking to count/list (e.g. "fitness classes",
-     * "운동 수업", any language). Presence signals enumeration intent and supplies
-     * the category for graph resolution; the caller (which understands the user's
-     * language) sets it. When omitted, pyx falls back to a deterministic EN/KO
-     * marker detector.
-     */
-    enumerationConcept?: string;
-    /** Confidence threshold below which the system recommends abstention (0.0–1.0). Default: 0.3. */
-    abstentionThreshold?: number;
-    /**
-     * Rerank with the cross-encoder before final truncation (hybrid strategy
-     * only). The pipeline retrieves and dedups a deeper candidate pool (≥50),
-     * scores it through the cross-encoder, then truncates to `limit` —
-     * reranking after truncation cannot change top-`limit` set membership.
-     * Forwarded by `MemoryClient.search` and the HTTP route; core enforces
-     * hybrid-only usage.
-     */
-    enableRerank?: boolean;
-    /**
-     * Iterative multi-hop candidate generation (hybrid strategy only). After the
-     * first retrieval pass, non-oracle bridge entities are mined from the top
-     * seed passages, a second dense+lexical pass is seeded by those bridges, and
-     * both passes' ranked lists are fused into a single RRF before scoring and
-     * (optional) rerank-then-truncate. Grows the candidate pool to surface
-     * later-hop passages the single-pass query misses. Deterministic: no
-     * query-time LLM, fixed bridge order. Default off keeps the pipeline
-     * byte-identical. EMBEDDED ONLY: `MemoryClient.search` rejects it (the HTTP
-     * API does not forward it).
-     */
-    enableMultiHop?: boolean;
-    /**
-     * Explicit bridge entities for the second multi-hop pass, bypassing mining.
-     * EVAL ONLY — used by the benchmark oracle-ceiling probe to isolate fusion
-     * capacity from mining quality; never set on a production path. Ignored
-     * unless `enableMultiHop` is also set.
-     */
-    multiHopBridges?: string[];
-    /**
-     * Set false for a read-only search that does NOT bump access counts /
-     * lastAccessed on returned entries. Access feeds ranking (WEIGHT_ACCESS and
-     * the no-eventTime recency fallback), so a measurement that searches the
-     * store mutates what it measures — repeated benchmark runs over a persisted
-     * index drift. Default true (access tracking is the product's usage signal).
-     */
-    trackAccess?: boolean;
-    /**
-     * Retrieval EFFORT tier (H8 slice 1b) — admits candidates by activation
-     * strength BEFORE RRF fusion (like LLM thinking-mode depth): `quick` = the
-     * strongest (sharpest top), `medium` = strong+mid, `deep` = everything
-     * including cold + superseded + archived rows. **Omitted ⇒ byte-identical to
-     * pre-1b behavior** (no activation lookup; all rows admitted, superseded/
-     * archived hidden as in 1a). Strength rises only via `Memory.reinforce` (recall
-     * reinforces); idle alone never revives. See `docs/H8-MEMORY-MODEL-DESIGN.md`.
-     */
-    effort?: 'quick' | 'medium' | 'deep';
-    /** Maximum sensitivity level to include in results. Entries above this level are excluded. */
-    maxSensitivity?: SensitivityLevel;
+    /** Optional deterministic ID for the entry (agent-provided). */
+    id?: string;
+    /** Parent entry ID for hierarchical storage (e.g., doc → section → chunk). */
+    parentId?: string;
+    /** When this entry was ingested (ISO timestamp). Default: now. */
+    ingestTime?: string;
     /** Tenant ID for multi-tenant isolation. */
     tenantId?: string;
     /** User ID within the tenant. */
     userId?: string;
     /** Team/group ID within the tenant. */
     teamId?: string;
-    /**
-     * Exact namespace requested by a trusted transport boundary. `Memory.search`
-     * validates it against the calling principal's AuthzPlan and compiles it to
-     * a singleton prefilter. Exact scope excludes legacy NULL rows.
-     */
+    /** Namespace ID — see `MemoryEntry.namespaceId`. */
     namespaceId?: string;
     /**
-     * AuthzPlan-derived visibility list. Populated internally by `Memory.search`
-     * after computing the plan from the calling principal — callers should
-     * NOT set this directly. Empty array means "no granted namespaces" (only
-     * legacy NULL-namespace entries are visible). `undefined` skips the
-     * filter (single-tenant / pre-ReBAC compat).
-     *
-     * Callers must not set this directly; use `namespaceId` for exact scope.
+     * Exclude this entry from consolidation (decay-archive and semantic dedup).
+     * See `MemoryEntry.pinned` for full semantics.
      */
-    namespaceIds?: string[];
-    /** Strict namespace equality compiled internally from `namespaceId`. */
-    exactNamespaceId?: string;
+    pinned?: boolean;
+}
+/**
+ * Agent-recorded explicit correction ("you did X wrong; do Y instead").
+ * `Memory.recordCorrection` writes one pinned, sqlite-only entry; pyx does
+ * pure structural retrieval with zero LLM / embedding on this path. Scope is
+ * `(tenantId, namespaceId)` + optional `project` — NOT per-user, because a
+ * correction about how to do X in this project is namespace-shared. No
+ * `confidence` field by design: ranking is overlap-then-recency only.
+ */
+interface CorrectionInput {
+    tenantId: string;
     /**
-     * AuthzPlan-derived list of strict-mode namespaces in the caller's
-     * tenant the principal CANNOT see (v0.17.0). Graph traversal MUST
-     * drop edges whose `namespace_id` matches the supplied set even when
-     * the surrounding KG node is otherwise reachable. Populated
-     * internally by `Memory.search` from `AuthzPlan.forbiddenStrict
-     * NamespaceIds` — callers should NOT set this directly.
+     * Namespace partition. Required in multi-tenant mode (the isolation
+     * boundary). Optional in single-tenant mode, where corrections are stored
+     * namespace-free (`namespace_id IS NULL`) exactly like ordinary writes.
      */
-    forbiddenStrictNamespaceIds?: string[];
+    namespaceId?: string;
+    /** What the agent did wrong (required free text). */
+    whatWasWrong: string;
+    /** The corrective instruction (required free text) — stored as `entry.content`. */
+    whatToDoInstead: string;
+    /** Applicability context the matcher scores task shapes against (required free text). */
+    appliesWhen: string;
+    /** Optional project scope — when set, the correction applies only to that project. */
+    project?: string;
+    /** Optional task-shape hint, stored for provenance; matching uses `appliesWhen`. */
+    taskShape?: string;
+    /** Optional agent id; defaults to the Memory instance's `agentId`. */
+    agentId?: string;
 }
-interface MemorySearchResult {
-    entries: MemoryEntry[];
-    totalCount: number;
-    strategy: RAGStrategy;
-    /** Visible graph slice that supported the returned entries, when graph traversal contributed. */
-    graph?: GraphTraversalResult;
+/** Input to `Memory.fetchApplicableCorrections`. */
+interface FetchCorrectionsInput {
+    tenantId: string;
+    /** Namespace partition; omit to read the namespace-free scope (single-tenant mode). */
+    namespaceId?: string;
+    /** Shape of the task about to run — scored against each correction's `appliesWhen`. */
+    taskShape: string;
+    /** Optional project filter — keeps only project-matching or project-absent rows. */
+    project?: string;
+    /** Max corrections to return. Default 5, hard cap 5. */
+    limit?: number;
+    /** Optional sensitivity cap for hosted/HTTP callers. Omitted preserves trusted in-process behavior. */
+    maxSensitivity?: SensitivityLevel;
+}
+/** Input to `Memory.dueScan` (H26 B-d — the one deterministic prospective primitive). */
+interface DueScanInput {
     /**
-     * Optional scored entries for ranked results. `score` is the fused RANK score
-     * (RRF + recency/importance/access priors) — good for ordering, NOT a relevance
-     * magnitude. `vectorSimilarity` is the raw dense query-similarity (LanceDB
-     * transformed-L2, 1/(1+distance)); null when the entry has no dense signal
-     * (FTS/graph-only). Surface vectorSimilarity, not score, as a "% match".
+     * Window start, ISO-8601. Defaults to the server's injected clock ("now").
+     * Benches and reproducible callers pass it explicitly.
      */
-    scoredEntries?: Array<{
-        entry: MemoryEntry;
-        score: number;
-        vectorSimilarity?: number | null;
-    }>;
-    /** Confidence assessment for abstention. Present when search produces scored entries. */
-    confidence?: {
-        /** Overall confidence 0.0–1.0. */
-        confidence: number;
-        /** Whether the system recommends abstaining (confidence below threshold). */
-        shouldAbstain: boolean;
-        /** Raw signals used to compute confidence. */
-        signals: {
-            topScore: number;
-            scoreGap: number;
-            scoreStdDev: number;
-            resultCount: number;
-            aboveThresholdRatio: number;
-            scoreSeparation: number;
-        };
-    };
+    from?: string;
+    /** Window length in fixed 24-hour periods, endpoints inclusive. Integer 1..370 — out-of-range is a loud error, never a clamp. */
+    windowDays: number;
+    /** Max entries returned. Default 20, hard cap 100. */
+    limit?: number;
+    /** Tenant scope; defaults to the Memory instance's tenant. */
+    tenantId?: string;
+    /** Explicit namespace scope (tenant-root rows stay visible). Overrides principal-derived visibility. */
+    namespaceId?: string;
+    /** Optional principal for namespace visibility (AuthzPlan), like search. */
+    principal?: PrincipalContext;
+    /** Optional sensitivity cap for hosted/HTTP callers; filtered in SQL before LIMIT. */
+    maxSensitivity?: SensitivityLevel;
 }
-/** One version in a fact's history, as returned by {@link LineageResult}. */
-interface LineageVersion {
-    entryId: string;
-    /** The entry content carrying this version's value. */
-    value: string;
-    eventTime?: string;
-    ingestTime?: string;
-    status: 'active' | 'superseded' | 'archived';
-    /** Set when this version was superseded by a newer entry. */
-    supersededByEntryId?: string;
+/** One applicable correction returned by `fetchApplicableCorrections`. */
+interface CorrectionRecord {
+    id: string;
+    whatWasWrong: string;
+    whatToDoInstead: string;
+    appliesWhen: string;
+    createdAt: string;
+    /** Overlap-coefficient score between the query `taskShape` and this row's `appliesWhen`. */
+    score: number;
 }
 /**
- * Query for the evolution of a fact (H8 `Memory.lineage`). Provide either a
- * `subject` (+ optional `relation`) for graph-backed subject/relation lineage,
- * OR an `entryId` to walk the `supersededBy` chain (the only mode available
- * without a graph store).
+ * Rolling graph-traversal telemetry (in-process, since boot). Watches the
+ * engine re-review triggers: depth-2 getNeighbors p95 latency / result size
+ * (hub explosion) and getAllEdges job duration.
  */
-interface LineageParams {
-    subject?: string;
-    relation?: string;
-    entryId?: string;
-    /** Current version as of this time (newest version with eventTime ≤ asOf). */
-    asOf?: string;
-    eventTimeRange?: [string, string];
-    /** Return only versions strictly older than the version holding this value. */
-    beforeValue?: string;
-    limit?: number;
-}
-interface LineageResult {
-    subject?: string;
-    relation?: string;
-    /** Event-time ascending (oldest → newest). */
-    versions: LineageVersion[];
-    /** Which path answered — honest provenance (graph conflict-group vs supersededBy chain). */
-    source: 'graph' | 'chain';
+interface GraphTelemetrySnapshot {
+    /** p95 latency (ms) of getNeighbors calls with depth >= 2; null until sampled. */
+    neighborsDepth2P95Ms: number | null;
+    /** p95 result node count of getNeighbors calls with depth >= 2; null until sampled. */
+    neighborsDepth2ResultP95: number | null;
+    /** Depth >= 2 samples in the rolling window (confidence for the p95s). */
+    neighborsDepth2SampleCount: number;
+    /** Duration (ms) of the most recent getAllEdges call; null until one ran. */
+    allEdgesLastMs: number | null;
 }
 /**
- * Explicit recall-usefulness signal for {@link MemorySearchParams} `reinforce`.
- * `context_included` = surfaced into the working context (small η); `cited` =
- * the agent actually used it in its answer (medium η); `explicit_positive` =
- * user/agent marked it useful (large η). Mere top-k return is NOT a signal
- * (determinism + "returned ≠ used") — only an explicit `reinforce()` call moves
- * strength.
+ * Since-boot usage-hygiene telemetry (in-process, serializable). Tracks whether
+ * callers provide event-time/graph context on store, whether searches miss, how
+ * reinforce is used, and whether sessions search before their first store.
  */
-type ReinforceSignal = 'context_included' | 'cited' | 'explicit_positive';
-interface ReinforceParams {
-    entryIds: string[];
-    signal: ReinforceSignal;
-    /** When the recall happened — epoch-ms, or full ISO-8601 WITH timezone. Date-only / tz-free is rejected. Defaults to the activation clock. */
-    at?: string | number;
+interface UsageHygieneSnapshot {
+    /** Total Memory.store calls observed since boot. */
+    storesTotal: number;
+    /** Store calls whose input carried eventTime. */
+    storesWithEventTime: number;
+    /** Store calls whose input carried caller-supplied entities or relationships. */
+    storesWithGraph: number;
+    /** Store calls by input type; missing type is counted as "long-term". */
+    storesByType: Record<string, number>;
+    /** Total Memory.search calls observed since boot. */
+    searchesTotal: number;
+    /** Completed searches that returned zero entries. */
+    searchesZeroResults: number;
+    /** Total Memory.reinforce calls observed since boot. */
+    reinforceTotal: number;
+    /** Total get_taxonomy_state (Memory.getTaxonomyState) calls observed since boot. */
+    taxonomyStateReadsTotal: number;
+    /** Total name_cluster (Memory.nameCluster) calls observed since boot. */
+    nameClusterCallsTotal: number;
+    /** Reinforce calls by signal value. */
+    reinforceBySignal: Record<string, number>;
+    /** Sessions where at least one search happened before the first store. */
+    searchBeforeFirstStoreSessions: number;
+    /** Sessions whose first observed hygiene event was a store. */
+    storeFirstSessions: number;
 }
-interface ReinforceResult {
-    /** Per-entry post-reinforce activation. Entries absent from the store are omitted. */
-    updated: Array<{
-        entryId: string;
-        strength: number;
-        tier: 'quick' | 'medium' | 'deep';
+interface MemoryStats {
+    totalEntries: number;
+    storageUsedBytes: number;
+    vectorCount: number;
+    recentAccessCount: number;
+    graphNodeCount?: number;
+    graphEdgeCount?: number;
+    /** Raw graph node count before tenant/ReBAC visibility filtering (raw stats mode only). */
+    graphRawNodeCount?: number;
+    /** Raw graph edge count before tenant/ReBAC visibility filtering (raw stats mode only). */
+    graphRawEdgeCount?: number;
+    /** Name of the active graph store ('neo4j', 'sqlite', or undefined if none). */
+    graphStore?: string;
+    /** Graph traversal telemetry; undefined when no graph store is active. */
+    graphTelemetry?: GraphTelemetrySnapshot;
+    /** Usage-hygiene telemetry since process boot. */
+    usageHygiene?: UsageHygieneSnapshot;
+    /** Whether the memory service is connected. False when using DisabledMemory. */
+    connected?: boolean;
+    /**
+     * Deferred-embed queue depth. The in-process core always reports it (0 when
+     * idle); absent means unknown (older server or disabled client), never 0.
+     */
+    pendingEmbeddings?: number;
+}
+interface MemoryInsightMetrics {
+    activeEntries: number;
+    retainedAdditions7d: number;
+    appliedRecalls: number;
+    reinforcedEntries: number;
+    retrievedEntries: number;
+    retrievals: number;
+    lastAppliedAt: string | null;
+    lastRetrievedAt: string | null;
+}
+interface MemoryProjectInsight extends MemoryInsightMetrics {
+    label: string;
+}
+/** Body-free, caller-visible aggregate for product status surfaces. */
+interface MemoryInsights {
+    generatedAt: string;
+    scope: 'connected_memory';
+    coverage: {
+        retainedAdditions: {
+            state: 'measured' | 'partial';
+            trackingSince: string | null;
+            trackedEntries: number;
+            totalEntries: number;
+            reason: string | null;
+        };
+        projectLabels: {
+            state: 'measured';
+        };
+        retrievalUsage: {
+            state: 'partial';
+            reason: string;
+        };
+        tokenEfficiency: {
+            state: 'not_instrumented';
+            reason: string;
+        };
+        contextAccuracy: {
+            state: 'not_instrumented';
+            reason: string;
+        };
+    };
+    summary: {
+        activeEntries: number;
+        observedProjectLabels: number;
+        retainedAdditions7d: number | null;
+        trackedEntries: number;
+        appliedRecalls: number;
+        reinforcedEntries: number;
+        retrievedEntries: number;
+        retrievals: number;
+    };
+    projects: MemoryProjectInsight[];
+    other: MemoryInsightMetrics | null;
+    /** Most recently reinforced visible entries (≤5), labels only, never bodies. */
+    recentApplied?: Array<{
+        topic: string | null;
+        project: string | null;
+        at: string;
     }>;
 }
-interface SourceEvidence {
-    /** Memory entry that produced this graph fact. */
-    memoryEntryId: string;
-    /** Data tenant of the source entry. `null` = single-tenant / legacy data. */
-    tenantId?: string | null;
-    /** Namespace of the source memory entry. `null` = legacy / tenant-root. */
-    namespaceId?: string | null;
-    /** Optional source identifier copied from the memory entry or caller. */
-    source?: string;
-    /** Optional content hash copied from the memory entry or caller. */
-    contentHash?: string;
-    /** Optional short text evidence for the graph fact. */
-    snippet?: string;
-    /** When this evidence was recorded. */
-    createdAt?: Timestamp;
+interface GraphRepairResult {
+    staleEdgesDeleted: number;
+    staleNodeRefsRemoved: number;
+    orphanNodesDeleted: number;
 }
-declare const StoreTarget: {
-    readonly SQLITE: "sqlite";
-    readonly VECTOR: "vector";
-    readonly GRAPH: "graph";
-};
-type StoreTarget = (typeof StoreTarget)[keyof typeof StoreTarget];
-/** Agent-provided entity for graph storage. */
-interface IngestEntity {
-    /** Entity name (e.g., "Alice", "TypeScript"). */
+interface GraphNode {
+    id: string;
     name: string;
-    /** Entity type — freeform, agent decides (e.g., "PERSON", "TOOL"). */
     type: string;
-    /** Stable canonical identifier. Defaults to a deterministic name+type id. */
     canonicalId?: string;
-    /** Source evidence for this graph node. Defaults to the containing memory entry. */
     sourceEvidence?: SourceEvidence[];
-    /** Optional properties to attach to the graph node. */
-    properties?: Record<string, unknown>;
+    properties: Record<string, unknown>;
+    memoryEntryIds: string[];
 }
-/** Agent-provided relationship for graph storage. */
-interface IngestRelationship {
-    /** Source entity name (must match an entity in the entities array). */
-    source: string;
-    /** Target entity name (must match an entity in the entities array). */
-    target: string;
-    /** Relationship type — freeform, agent decides (e.g., "WORKS_AT", "USES"). */
+interface GraphRelationship {
+    id: string;
+    sourceId: string;
+    targetId: string;
     type: string;
-    /** Source evidence for this graph edge. Defaults to the containing memory entry. */
     sourceEvidence?: SourceEvidence[];
-    /** Optional properties to attach to the graph edge. */
-    properties?: Record<string, unknown>;
+    properties: Record<string, unknown>;
+    memoryEntryId?: string;
+    /**
+     * Namespace_id provenance carried from the originating MemoryEntry.
+     * `null` (or absent) = legacy / tenant-root bucket. Foundation for the
+     * v0.17.0 strict traversal filter (the AuthzPlan compares this value
+     * edge-by-edge so KG dedupe at the node level can stay intact).
+     */
+    namespaceId?: string | null;
+}
+interface GraphTraversalResult {
+    nodes: GraphNode[];
+    relationships: GraphRelationship[];
+    paths: Array<{
+        nodeIds: string[];
+        relationshipIds: string[];
+    }>;
 }
 /**
- * How `Memory.store()` should react when the graph write fails.
- * - `throw` (default, since v0.13.0): propagate the failure so the caller
- *   knows the graph is incomplete. Honest contract: a graph write either
- *   commits or fails loudly. Silent partial-loss was the v0.12.2 bug that
- *   masked 91/92 dropped entities.
- * - `best-effort`: swallow the error and log a warning; the entry is still
- *   considered ingested in SQLite/vector. Use only when you genuinely don't
- *   need the graph slice and a transient neo4j blip shouldn't fail ingest.
+ * Memory.lint() report shape — Karpathy-wiki Item B (v0.18.0).
+ * Read-only projection composed from signals every owning module
+ * already exposes. Lives in shared so the HTTP client can hold the
+ * same type as core without re-declaring it.
  */
-type GraphFailureMode = 'throw' | 'best-effort';
-/** Store input: what the agent sends to Memory.store(). */
-type StoreInput = Omit<MemoryEntry, 'id' | 'createdAt'> & {
-    id?: string;
-    createdAt?: string;
-    /** Storage targets. Default: ["sqlite", "vector"]. */
-    targets?: StoreTarget[];
-    /** Agent-provided entities for graph storage. */
-    entities?: IngestEntity[];
-    /** Agent-provided relationships for graph storage. */
-    relationships?: IngestRelationship[];
-    /** Override graph entity extraction for this store call. */
-    extractEntities?: boolean;
-    /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
-    graphFailureMode?: GraphFailureMode;
-};
-interface MemoryIngestRequest {
-    content?: string;
-    type?: MemoryType;
-    metadata?: Record<string, unknown>;
+interface WikiLintReport {
+    orphans: GraphNode[];
+    decayCandidates: MemoryEntry[];
+    staleSyntheses: Array<{
+        entry: MemoryEntry;
+        reason: string;
+    }>;
+    dedupCandidates: Array<{
+        hash: string;
+        entryIds: string[];
+    }>;
+}
+
+/** Parameters for paginated entry listing. */
+interface MemoryListParams {
+    /** 1-based page number. Default: 1 */
+    page?: number;
+    /** Entries per page (1–100). Default: 20 */
+    limit?: number;
+    /**
+     * Opaque keyset-pagination token from a previous result's `nextCursor`.
+     * Guarantees exactly-once traversal even while strictly-newer entries
+     * are being written (offset/page pagination can repeat or skip there).
+     * A cursor is only valid for the same filter set that produced it.
+     * Mutually exclusive with `page` — supplying both is an error. Not a
+     * snapshot: rows backdated behind the cursor position can still appear.
+     */
+    cursor?: string;
+    /**
+     * Opt-in lifecycle-status filter. Omitted preserves today's behavior:
+     * active, superseded, and archived entries are all returned.
+     */
+    status?: 'active' | 'superseded' | 'archived';
+    /** Filter by memory type. */
+    type?: MemoryType$1;
+    /** Filter by agent ID. */
+    agentId?: string;
+    /** Filter by tenant ID for multi-tenant isolation. */
+    tenantId?: string;
+    /** Exact namespace scope. Excludes legacy tenant-root entries. */
+    namespaceId?: string;
+    /**
+     * Calling principal. When supplied, list applies the AuthzPlan
+     * visibility filter so entries in forbidden namespaces never reach
+     * the response. Single-tenant / library-direct callers may omit it
+     * and get the legacy tenant-only scope.
+     */
+    principal?: PrincipalContext$1;
+    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
+    maxSensitivity?: SensitivityLevel$1;
+    /**
+     * R1/R2 — opt-in list of `metadata._kind` values to include in the
+     * response. When omitted or empty, the default-set returns only entries
+     * with NO `_kind` system metadata (e.g. `_kind:'entity-summary'` rows
+     * are hidden). When supplied, the listed kinds are returned IN ADDITION
+     * to the default-set (additive, not replacement). See
+     * `docs/specs/topic-org-v025-f1-include-kinds/spec.md`.
+     */
+    includeKinds?: string[];
+}
+/** Result of a paginated entry listing. */
+interface MemoryListResult {
+    entries: MemoryEntry$1[];
+    totalCount: number;
+    /** Present in page/offset mode only — a keyset traversal has no page number. */
+    page?: number;
+    limit: number;
+    /** Keyset token for the next page; null when this page is the last. */
+    nextCursor: string | null;
+}
+/** Filters for temporal queries (queryAsOf, queryByEventTime). */
+interface TemporalQueryFilters {
+    type?: MemoryType$1;
     agentId?: string;
-    sessionId?: string;
-    /** Storage targets. Default: ["sqlite", "vector"]. */
-    targets?: StoreTarget[];
-    /** Agent-provided entities for graph storage. */
-    entities?: IngestEntity[];
-    /** Agent-provided relationships for graph storage. */
-    relationships?: IngestRelationship[];
-    /** Override graph entity extraction for this ingest request. */
-    extractEntities?: boolean;
-    /** Graph-failure handling. Default: "throw" (loud) — see GraphFailureMode. */
-    graphFailureMode?: GraphFailureMode;
-    /** Importance score (1-10). */
-    importance?: number;
-    /** Source identifier (e.g., filename, URL). */
     source?: string;
-    /** When the event occurred (ISO timestamp). */
-    eventTime?: string;
-    /** Optional deterministic ID for the entry (agent-provided). */
-    id?: string;
-    /** Parent entry ID for hierarchical storage (e.g., doc → section → chunk). */
-    parentId?: string;
-    /** When this entry was ingested (ISO timestamp). Default: now. */
-    ingestTime?: string;
-    /** Tenant ID for multi-tenant isolation. */
+    limit?: number;
+    /**
+     * Number of matching rows to skip. Offset pages can shift under concurrent
+     * deletion; use cursor for a deletion-stable queryAsOf walk.
+     */
+    offset?: number;
+    /**
+     * Opaque keyset token for a deletion-stable queryAsOf walk. Derive it from
+     * the last returned entry with `encodeListCursorToken`; mutually exclusive
+     * with offset.
+     */
+    cursor?: string;
+    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
+    maxSensitivity?: SensitivityLevel$1;
+}
+/** Filters for the chronological feed (`log`, Karpathy `log.md` primitive). */
+interface MemoryLogFilters {
+    /** Inclusive lower bound on `created_at` (ISO 8601). Cursor for "what's new since X". */
+    since?: string;
+    /** Maximum entries to return. The HTTP layer clamps to [1, 100]. */
+    limit?: number;
+    type?: MemoryType$1;
+    agentId?: string;
+    source?: string;
+    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
+    maxSensitivity?: SensitivityLevel$1;
+}
+/** Options for scoping operations to a specific tenant. */
+interface TenantScopeOptions {
     tenantId?: string;
-    /** User ID within the tenant. */
-    userId?: string;
-    /** Team/group ID within the tenant. */
-    teamId?: string;
-    /** Namespace ID — see `MemoryEntry.namespaceId`. */
+    /** Optional strict namespace coordinate for exact get/delete operations. */
     namespaceId?: string;
     /**
-     * Exclude this entry from consolidation (decay-archive and semantic dedup).
-     * See `MemoryEntry.pinned` for full semantics.
+     * Graph count mode for stats(). Use raw on admin-health paths
+     * that should avoid the visible graph projection.
      */
-    pinned?: boolean;
+    graphVisibility?: 'visible' | 'raw';
+    /**
+     * Calling principal. When supplied alongside or instead of tenantId,
+     * the operation applies the AuthzPlan visibility filter — get/delete
+     * will treat entries in forbidden namespaces as if they did not exist.
+     * Single-tenant / library-direct callers may omit it and get the
+     * legacy tenant-only scope.
+     */
+    principal?: PrincipalContext$1;
+    /** Maximum sensitivity level to include. Omitted preserves legacy behavior. */
+    maxSensitivity?: SensitivityLevel$1;
+}
+/** Abstract interface for memory systems (local or remote). */
+interface MemoryInterface {
+    initialize(): Promise<void>;
+    store(entry: StoreInput$1): Promise<MemoryEntry$1>;
+    search(params: MemorySearchParams$1): Promise<MemorySearchResult$1>;
+    /** List entries with SQL LIMIT/OFFSET pagination. */
+    list(params?: MemoryListParams): Promise<MemoryListResult>;
+    get(id: string, options?: TenantScopeOptions): Promise<MemoryEntry$1 | null>;
+    delete(id: string, options?: TenantScopeOptions): Promise<boolean>;
+    clearSession(sessionId: string, options?: TenantScopeOptions): Promise<number>;
+    stats(options?: TenantScopeOptions): Promise<MemoryStats$1>;
+    insights(options?: TenantScopeOptions): Promise<MemoryInsights$1>;
+    /** Query entries as they existed at a point in time (by ingest time). */
+    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters, options?: TenantScopeOptions): Promise<MemoryEntry$1[]>;
+    /** Read the time-ordered lineage of a graph fact or superseded entry chain. */
+    lineage(params: LineageParams$1): Promise<LineageResult$1>;
+    /** Reinforce memories that were actually used by the caller. */
+    reinforce(params: ReinforceParams$1): Promise<ReinforceResult$1>;
+    /** Query entries by event time range (when things actually happened). */
+    queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
+    shutdown(): Promise<void>;
+}
+/** Consolidation run result. */
+interface ConsolidationRunResult {
+    entriesProcessed: number;
+    entriesMerged: number;
+    entriesArchived: number;
+    durationMs: number;
+}
+/** Extended interface with lifecycle operations. Non-breaking for existing consumers. */
+interface ExtendedMemoryInterface extends MemoryInterface {
+    /** Run consolidation: score, dedup, decay, and summarize memories. */
+    consolidate(): Promise<ConsolidationRunResult>;
+    /** Soft-delete a memory with a reason (marks as archived). */
+    forget(id: string, reason?: string): Promise<boolean>;
+    /** Summarize a session's memories into a long-term entry. */
+    summarizeSession(sessionId: string): Promise<MemoryEntry$1 | null>;
+    /**
+     * Read-only memory-wide lint report (v0.18.0 Karpathy-wiki Item B):
+     * orphans, decay candidates, stale entries, dedup candidates. Pure
+     * projection — no writes.
+     */
+    lint(options?: {
+        limit?: number;
+    }): Promise<WikiLintReport$1>;
+    /** Run decay on all entries, archiving those below threshold. */
+    runDecay(): Promise<number>;
+    /** Reindex the FTS5 full-text search index. */
+    reindex(): Promise<void>;
+    /** Delete all entries matching a source, cleaning up all stores. */
+    deleteBySource(source: string, options?: TenantScopeOptions): Promise<number>;
+    /** Repair stale graph references left by older delete paths or crashed cleanup. */
+    repairGraph(): Promise<GraphRepairResult$1>;
+    /**
+     * Chronological feed of memory entries (Karpathy `log.md` primitive).
+     * Cursor-based via `since` (created_at lower bound). No totalCount.
+     */
+    log(filters?: MemoryLogFilters): Promise<MemoryEntry$1[]>;
+    /**
+     * Synthesize a per-entity profile (Karpathy-wiki "wiki page" primitive).
+     * LLM-driven, caller-triggered. Stores a pinned `_kind:'entity-summary'`
+     * entry with `_search_visibility:'on-demand'` so it never enters the
+     * default retrieval pool. Re-running replaces the prior synthesis.
+     */
+    summarizeEntity(name: string): Promise<MemoryEntry$1>;
+    /**
+     * Fetch a previously-synthesized entity profile. Returns `null` when no
+     * synthesis exists yet. O(1) — the read side of the amortized pattern.
+     */
+    getEntitySynthesis(name: string): Promise<MemoryEntry$1 | null>;
 }
+
 /**
- * Agent-recorded explicit correction ("you did X wrong; do Y instead").
- * `Memory.recordCorrection` writes one pinned, sqlite-only entry; pyx does
- * pure structural retrieval with zero LLM / embedding on this path. Scope is
- * `(tenantId, namespaceId)` + optional `project` — NOT per-user, because a
- * correction about how to do X in this project is namespace-shared. No
- * `confidence` field by design: ranking is overlap-then-recency only.
+ * No-op {@link MemoryInterface} for hosts that run without a memory backend
+ * (e.g. `MEMORY_URL` is unset). Every method returns a safe default, so the
+ * rest of the system functions without branching on `memory == null`.
+ *
+ * Canonical single source: this lives in the SAME package as `MemoryInterface`,
+ * so any method added to the interface fails THIS class's compile in the same
+ * build. The null-object can never silently drift behind the contract — the
+ * failure mode that left hand-rolled copies in downstream repos missing
+ * `lineage`/`reinforce` after the interface grew them.
+ *
+ * `initialize()` emits a single `console.warn`; pass nothing else — it is a
+ * pure null-object. Hosts wanting structured logging should log at the wiring
+ * site where they choose `DisabledMemory` over a real client.
  */
-interface CorrectionInput {
-    tenantId: string;
+declare class DisabledMemory implements MemoryInterface {
+    initialize(): Promise<void>;
+    store(entry: StoreInput$1): Promise<MemoryEntry$1>;
+    search(): Promise<MemorySearchResult$1>;
+    list(params?: MemoryListParams): Promise<MemoryListResult>;
+    get(): Promise<MemoryEntry$1 | null>;
+    delete(): Promise<boolean>;
+    clearSession(): Promise<number>;
+    stats(): Promise<MemoryStats$1>;
+    insights(): Promise<MemoryInsights$1>;
+    queryAsOf(): Promise<MemoryEntry$1[]>;
+    lineage(): Promise<LineageResult$1>;
+    reinforce(): Promise<ReinforceResult$1>;
+    queryByEventTime(): Promise<MemoryEntry$1[]>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Callbacks for two-phase file enrichment. All callbacks are optional:
+ *   - Image-rich PDF + describeImage only → describes images, no entity extraction
+ *   - Image-rich PDF + describeImage + extractEntitiesV2 → describes + extracts
+ *   - Text-only file + extractEntitiesV2 only → extracts from textWindows
+ *   - Mixed file + both → describes images + extracts from both sources
+ *
+ * Without any callback, the ingest stream emits the server result with no
+ * SDK-side enrichment. Server-side text/entity extraction may still run when
+ * configured; image understanding still requires caller-provided
+ * descriptions/hooks.
+ */
+interface EnrichmentCallbacks {
     /**
-     * Namespace partition. Required in multi-tenant mode (the isolation
-     * boundary). Optional in single-tenant mode, where corrections are stored
-     * namespace-free (`namespace_id IS NULL`) exactly like ordinary writes.
+     * Describe an image using LLM vision. Receives the raw image buffer and
+     * metadata. Required for image-bearing files; safe to omit for text-only
+     * uploads where the server emits zero images.
      */
-    namespaceId?: string;
-    /** What the agent did wrong (required free text). */
-    whatWasWrong: string;
-    /** The corrective instruction (required free text) — stored as `entry.content`. */
-    whatToDoInstead: string;
-    /** Applicability context the matcher scores task shapes against (required free text). */
-    appliesWhen: string;
-    /** Optional project scope — when set, the correction applies only to that project. */
-    project?: string;
-    /** Optional task-shape hint, stored for provenance; matching uses `appliesWhen`. */
-    taskShape?: string;
-    /** Optional agent id; defaults to the Memory instance's `agentId`. */
-    agentId?: string;
+    describeImage?: (imageBuffer: ArrayBuffer, meta: ExtractedImageMeta$1) => Promise<string>;
+    /**
+     * Entity-extraction callback. Receives text windows and image descriptions
+     * separately so callers can apply different prompts per source. Triggers
+     * the `X-Pyx-Enrichment-Capabilities: text_windows_v1` negotiation header
+     * on ingest.
+     */
+    extractEntitiesV2?: (input: {
+        textWindows: string[];
+        imageDescriptions: string[];
+        mimeType: string;
+        filename: string;
+    }) => Promise<{
+        entities: IngestEntity$1[];
+        relationships: IngestRelationship$1[];
+    }>;
 }
-/** Input to `Memory.fetchApplicableCorrections`. */
-interface FetchCorrectionsInput {
-    tenantId: string;
-    /** Namespace partition; omit to read the namespace-free scope (single-tenant mode). */
+/**
+ * Options for {@link MemoryClient.ingestFileEvents}. `signal` lets
+ * long-running ingests (LLM enrichment + graph writes) be cancelled cleanly.
+ *
+ * `namespaceId` opts the upload into ReBAC AuthzPlan visibility — the server
+ * thread the namespace through parsing → enrichment → store calls so the
+ * resulting catalog row and chunk entries land in the named namespace
+ * (server v0.17.4+; required when `requireNamespaceForTenantWrites=true`).
+ */
+interface IngestFileOptions {
+    description?: string;
+    enrichment?: EnrichmentCallbacks;
+    signal?: AbortSignal;
     namespaceId?: string;
-    /** Shape of the task about to run — scored against each correction's `appliesWhen`. */
-    taskShape: string;
-    /** Optional project filter — keeps only project-matching or project-absent rows. */
-    project?: string;
-    /** Max corrections to return. Default 5, hard cap 5. */
-    limit?: number;
-    /** Optional sensitivity cap for hosted/HTTP callers. Omitted preserves trusted in-process behavior. */
-    maxSensitivity?: SensitivityLevel;
-}
-/** Input to `Memory.dueScan` (H26 B-d — the one deterministic prospective primitive). */
-interface DueScanInput {
     /**
-     * Window start, ISO-8601. Defaults to the server's injected clock ("now").
-     * Benches and reproducible callers pass it explicitly.
+     * Stable logical document identity used for replaceable content, image,
+     * and graph projections. Requires `enrichment.extractEntitiesV2` so the
+     * client can negotiate text windows and complete the stable replacement.
      */
-    from?: string;
-    /** Window length in fixed 24-hour periods, endpoints inclusive. Integer 1..370 — out-of-range is a loud error, never a clamp. */
-    windowDays: number;
-    /** Max entries returned. Default 20, hard cap 100. */
-    limit?: number;
-    /** Tenant scope; defaults to the Memory instance's tenant. */
-    tenantId?: string;
-    /** Explicit namespace scope (tenant-root rows stay visible). Overrides principal-derived visibility. */
-    namespaceId?: string;
-    /** Optional principal for namespace visibility (AuthzPlan), like search. */
-    principal?: PrincipalContext;
-    /** Optional sensitivity cap for hosted/HTTP callers; filtered in SQL before LIMIT. */
-    maxSensitivity?: SensitivityLevel;
-}
-/** One applicable correction returned by `fetchApplicableCorrections`. */
-interface CorrectionRecord {
-    id: string;
-    whatWasWrong: string;
-    whatToDoInstead: string;
-    appliesWhen: string;
-    createdAt: string;
-    /** Overlap-coefficient score between the query `taskShape` and this row's `appliesWhen`. */
-    score: number;
+    documentKey?: string;
+    /**
+     * Migration-only pinned file-ingestion catalog for this document's first
+     * stable replacement. The server validates its exact scope and uses its
+     * bounded provenance to detach legacy graph references. Omit this after the
+     * stable anchor is established: the first pass may retire catalog-owned
+     * projections, so later revisions should use `documentKey` alone.
+     */
+    catalogEntryId?: string;
 }
 /**
- * Rolling graph-traversal telemetry (in-process, since boot). Watches the
- * engine re-review triggers: depth-2 getNeighbors p95 latency / result size
- * (hub explosion) and getAllEdges job duration.
+ * Options for {@link MemoryClient.graphEnrichFileEvents}. `documentKey` is the
+ * caller's stable logical identity for the document whose graph is being
+ * rebuilt — the server derives the graph anchor id from
+ * (tenant, namespace, documentKey), so repeating the same key replaces the
+ * document's graph references instead of multiplying them.
+ *
+ * `enrichment.extractEntitiesV2` is required: graph-only re-enrichment is
+ * caller-extraction by definition (there is no server-side fallback).
  */
-interface GraphTelemetrySnapshot {
-    /** p95 latency (ms) of getNeighbors calls with depth >= 2; null until sampled. */
-    neighborsDepth2P95Ms: number | null;
-    /** p95 result node count of getNeighbors calls with depth >= 2; null until sampled. */
-    neighborsDepth2ResultP95: number | null;
-    /** Depth >= 2 samples in the rolling window (confidence for the p95s). */
-    neighborsDepth2SampleCount: number;
-    /** Duration (ms) of the most recent getAllEdges call; null until one ran. */
-    allEdgesLastMs: number | null;
+interface GraphEnrichFileOptions {
+    documentKey: string;
+    /**
+     * Migration-only pinned file-ingestion catalog for the first stable graph
+     * replacement. The server resolves it in the current tenant/namespace and
+     * detaches its bounded graph references. Omit it on later revisions once
+     * the `documentKey` anchor exists.
+     */
+    catalogEntryId?: string;
+    namespaceId?: string;
+    signal?: AbortSignal;
+    enrichment: EnrichmentCallbacks;
+}
+interface FileDownloadOptions {
+    /** Stable logical document identity used by documentKey-aware ingest. */
+    documentKey?: string;
+    /** Exact namespace containing the uploaded document. */
+    namespaceId?: string;
 }
 /**
- * Since-boot usage-hygiene telemetry (in-process, serializable). Tracks whether
- * callers provide event-time/graph context on store, whether searches miss, how
- * reinforce is used, and whether sessions search before their first store.
+ * Caller-supplied enrichment for the per-call store path. Mirrors
+ * {@link EnrichmentCallbacks} for file ingest. When supplied, the SDK invokes
+ * the callback and merges the result into the payload before POSTing. Without
+ * a callback, server-side text/entity extraction can run only when the server
+ * has an extraction brain configured; otherwise callers must pass graph data
+ * or use caller-side hooks. Images always require caller-provided
+ * descriptions/hooks.
  */
-interface UsageHygieneSnapshot {
-    /** Total Memory.store calls observed since boot. */
-    storesTotal: number;
-    /** Store calls whose input carried eventTime. */
-    storesWithEventTime: number;
-    /** Store calls whose input carried caller-supplied entities or relationships. */
-    storesWithGraph: number;
-    /** Store calls by input type; missing type is counted as "long-term". */
-    storesByType: Record<string, number>;
-    /** Total Memory.search calls observed since boot. */
-    searchesTotal: number;
-    /** Completed searches that returned zero entries. */
-    searchesZeroResults: number;
-    /** Total Memory.reinforce calls observed since boot. */
-    reinforceTotal: number;
-    /** Total get_taxonomy_state (Memory.getTaxonomyState) calls observed since boot. */
-    taxonomyStateReadsTotal: number;
-    /** Total name_cluster (Memory.nameCluster) calls observed since boot. */
-    nameClusterCallsTotal: number;
-    /** Reinforce calls by signal value. */
-    reinforceBySignal: Record<string, number>;
-    /** Sessions where at least one search happened before the first store. */
-    searchBeforeFirstStoreSessions: number;
-    /** Sessions whose first observed hygiene event was a store. */
-    storeFirstSessions: number;
+interface StoreEnrichmentCallbacks {
+    /**
+     * Extract entities + relationships from `content`. The caller's LLM does
+     * the work; the SDK passes the result through {@link mergeExtractedEntities}
+     * (caller-wins, case-insensitive) before sending to the server.
+     *
+     * Skipped when `entry.extractEntities === false`. When
+     * `entry.extractEntities === true` but this callback is not supplied,
+     * `MemoryClient.store()` forwards the hint so the server-side extraction
+     * brain can run and loud-fail if it is not configured.
+     */
+    extractEntities?: (input: {
+        content: string;
+        metadata?: Record<string, unknown>;
+        signal?: AbortSignal;
+    }) => Promise<EntityExtractionResult$1>;
 }
-interface MemoryStats {
-    totalEntries: number;
-    storageUsedBytes: number;
-    vectorCount: number;
-    recentAccessCount: number;
-    graphNodeCount?: number;
-    graphEdgeCount?: number;
-    /** Raw graph node count before tenant/ReBAC visibility filtering (raw stats mode only). */
-    graphRawNodeCount?: number;
-    /** Raw graph edge count before tenant/ReBAC visibility filtering (raw stats mode only). */
-    graphRawEdgeCount?: number;
-    /** Name of the active graph store ('neo4j', 'sqlite', or undefined if none). */
-    graphStore?: string;
-    /** Graph traversal telemetry; undefined when no graph store is active. */
-    graphTelemetry?: GraphTelemetrySnapshot;
-    /** Usage-hygiene telemetry since process boot. */
-    usageHygiene?: UsageHygieneSnapshot;
-    /** Whether the memory service is connected. False when using DisabledMemory. */
-    connected?: boolean;
+/** Options accepted by {@link MemoryClient.store}. */
+interface StoreOptions {
+    enrichment?: StoreEnrichmentCallbacks;
+    /** Propagated into the `extractEntities` callback and the underlying fetch. */
+    signal?: AbortSignal;
+    /** Stable logical request key. Reuse this exact value after a lost response. */
+    idempotencyKey?: string;
+}
+interface RequestAuthorityOptions {
+    /** Stable logical request key. Reuse this exact value after a lost response. */
+    idempotencyKey?: string;
+}
+/** Error thrown by MemoryClient when the server returns a non-success response. */
+declare class MemoryServerError extends Error {
+    readonly status: number;
+    /** Stable machine-readable discriminator returned by the memory server. */
+    readonly code?: string;
+    /** Exact HTTP Retry-After value returned by the memory server. */
+    readonly retryAfter?: string;
+    /** Retry delay normalized to seconds when Retry-After is parseable. */
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, status: number, code?: string, retryAfter?: string);
+    /** True when the server returned HTTP 404 (not found). */
+    get isNotFound(): boolean;
+}
+interface MemoryClientOptions {
+    /** API key for authentication. */
+    apiKey?: string;
+    /** Additional headers to send with every request (e.g., X-Caller-Access-Level). */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Default per-request timeout in milliseconds. Without this, a wedged
+     * memory server (e.g. event-loop blocked by inference) makes every
+     * caller hang forever — that was the Korens demo wedge in 2026-04 where
+     * a 161-second pyx-memory stall propagated through the runtime to the
+     * browser. Defaults to 30 s, which is high enough that normal
+     * `/search` and `/stats` requests never hit it but low enough that a
+     * stuck server fails loudly.
+     *
+     * Only applied when the caller does NOT pass their own `signal` via
+     * RequestInit. Long-running operations (large `consolidate`, `reindex`,
+     * file ingest with enrichment) should pass their own AbortSignal —
+     * that signal fully replaces the default ceiling.
+     */
+    requestTimeoutMs?: number;
+}
+declare class MemoryClient implements ExtendedMemoryInterface {
+    protected baseUrl: string;
+    private readonly _authHeaders;
+    private readonly _requestTimeoutMs;
+    constructor(memoryUrl: string, apiKeyOrOptions?: string | MemoryClientOptions);
+    /** Encode a path segment to prevent URL injection */
+    private encodePathSegment;
+    private authorityHeaders;
+    private exactReadAuthority;
+    initialize(): Promise<void>;
+    store(entry: StoreInput$1, options?: StoreOptions): Promise<MemoryEntry$1>;
+    search(params: MemorySearchParams$1, authority?: RequestAuthorityOptions & Pick<TenantScopeOptions, 'tenantId' | 'namespaceId'>): Promise<MemorySearchResult$1>;
+    get(id: string, authority?: TenantScopeOptions & RequestAuthorityOptions): Promise<MemoryEntry$1 | null>;
+    delete(id: string, authority?: TenantScopeOptions & RequestAuthorityOptions): Promise<boolean>;
+    clearSession(sessionId: string): Promise<number>;
+    stats(options?: TenantScopeOptions): Promise<MemoryStats$1>;
+    insights(options?: TenantScopeOptions & RequestAuthorityOptions): Promise<MemoryInsights$1>;
+    /**
+     * Fetch the running server's topology snapshot (build variant, declared
+     * role, embedding location, active model profile). Round-trips the
+     * server's `GET /status` envelope through {@link fetchApi}, surfacing any
+     * non-success response as {@link MemoryServerError}. Auth-header
+     * forwarding is unchanged from other client methods even though `/status`
+     * is server-side public — the server simply ignores credentials on that
+     * route.
+     */
+    status(): Promise<Topology$1>;
+    shutdown(): Promise<void>;
+    list(params?: MemoryListParams, authority?: RequestAuthorityOptions & Pick<TenantScopeOptions, 'tenantId' | 'namespaceId'>): Promise<MemoryListResult>;
+    /**
+     * Native streaming file ingest. Yields typed {@link IngestEvent}s as the
+     * server (parsing/storing) and the SDK (enrichment/result) make progress.
+     *
+     * Wire contract: SDK POSTs with `Accept: application/x-ndjson`; the server
+     * MUST respond with NDJSON. There is no JSON fallback — older servers
+     * that emit `application/json` for this endpoint are not supported, and
+     * the SDK yields a terminal `error` event in that case.
+     *
+     * After the server's terminal `result`, the SDK runs its own enrichment
+     * phase (image-describe → entity-extract → `/enrich` POST), emitting
+     * progress + heartbeat events around each step, then yields the single
+     * terminal `result` event with the merged SDK + server result.
+     *
+     * Promise-shaped consumers should iterate the returned AsyncIterable and
+     * collect the terminal event; there is no separate `ingestFile()` Promise
+     * method by design (one wire format, one SDK method).
+     */
+    ingestFileEvents(file: File, options?: IngestFileOptions): AsyncIterable<IngestEvent$1>;
+    /**
+     * Graph-only re-enrichment for a document whose chunks are already stored
+     * and searchable but whose graph build failed. Uploads the original to
+     * `/api/memory/graph/enrich/file` (prepare-only — the server performs zero
+     * store/delete before the final graph write), runs the SAME enrichment
+     * callback engine as {@link ingestFileEvents}, then finalizes into one
+     * stable graph anchor keyed by `documentKey`. Repeating the same key
+     * replaces the document's graph references idempotently.
+     *
+     * The terminal `result` is a {@link GraphEnrichResult} event carrying the
+     * ACTUAL persisted graph counts; abort and failures yield a terminal
+     * `error` event instead (the server retains the pending session for retry).
+     */
+    graphEnrichFileEvents(file: File, options: GraphEnrichFileOptions): AsyncIterable<GraphEnrichEvent$1>;
+    /**
+     * POST a multipart body to an NDJSON streaming endpoint and relay its
+     * progress/heartbeat events. Returns the raw terminal `result` record, or
+     * null after yielding a terminal error (transport failure, server error
+     * event, non-NDJSON response, stream ending without a result). One
+     * implementation for both streaming surfaces so the wire protocol cannot
+     * fork.
+     */
+    private streamNdjsonUpload;
+    /**
+     * Run the SDK-side enrichment phase for an ingest result and yield the
+     * single terminal {@link IngestResultEvent} at the end. Skips work cleanly
+     * when the server emitted no enrichment block or the caller wired no
+     * callbacks. The callback work itself lives in
+     * {@link runEnrichmentCallbacks} — shared with the graph-only surface.
+     */
+    private completeIngestFileEvents;
+    /**
+     * The ONE enrichment callback engine, shared by {@link ingestFileEvents}
+     * and {@link graphEnrichFileEvents}: fetches extracted images, invokes
+     * `describeImage` with bounded concurrency, invokes `extractEntitiesV2`
+     * exactly once, and POSTs `/files/{fileId}/enrich` — emitting progress and
+     * heartbeat events around each slow step. Throws on any failure; the
+     * purpose-specific wrappers translate that into their terminal error.
+     *
+     * Legacy ingest keeps its existing partial add-on behavior. Graph-only and
+     * documentKey-aware full ingest may replace a prior graph only from a
+     * complete input set (no truncated text windows or undescribed images). A
+     * complete extractor result containing zero entities remains a valid clear.
+     */
+    private runEnrichmentCallbacks;
+    /**
+     * Race a Promise against a periodic heartbeat tick. Yields a heartbeat
+     * IngestEvent every {@link INGEST_EVENT_HEARTBEAT_MS} until the promise
+     * settles, then returns the resolved value (or rethrows). Lets callers
+     * keep upstream sockets alive through long LLM/HTTP work without
+     * coupling the heartbeat cadence to the work itself.
+     */
+    private withSdkHeartbeats;
+    private normalizeActiveIngestStage;
+    private fileIngestResultFromEvent;
+    private ingestErrorEvent;
     /**
-     * Deferred-embed queue depth. The in-process core always reports it (0 when
-     * idle); absent means unknown (older server or disabled client), never 0.
+     * Get the download URL for an uploaded file.
+     * Returns a URL that serves the original file binary with proper Content-Type.
      */
-    pendingEmbeddings?: number;
-}
-interface MemoryInsightMetrics {
-    activeEntries: number;
-    retainedAdditions7d: number;
-    appliedRecalls: number;
-    reinforcedEntries: number;
-    retrievedEntries: number;
-    retrievals: number;
-    lastAppliedAt: string | null;
-    lastRetrievedAt: string | null;
-}
-interface MemoryProjectInsight extends MemoryInsightMetrics {
-    label: string;
-}
-/** Body-free, caller-visible aggregate for product status surfaces. */
-interface MemoryInsights {
-    generatedAt: string;
-    scope: 'connected_memory';
-    coverage: {
-        retainedAdditions: {
-            state: 'measured' | 'partial';
-            trackingSince: string | null;
-            trackedEntries: number;
-            totalEntries: number;
-            reason: string | null;
-        };
-        projectLabels: {
-            state: 'measured';
-        };
-        retrievalUsage: {
-            state: 'partial';
-            reason: string;
-        };
-        tokenEfficiency: {
-            state: 'not_instrumented';
-            reason: string;
-        };
-        contextAccuracy: {
-            state: 'not_instrumented';
-            reason: string;
+    getFileDownloadUrl(filename: string, options?: FileDownloadOptions): string;
+    /**
+     * Download an uploaded file by filename.
+     * Returns the raw Response (caller handles the body — arrayBuffer, blob, stream, etc.).
+     */
+    downloadFile(filename: string, options?: FileDownloadOptions): Promise<Response>;
+    /** @deprecated Use {@link list} instead. Kept for backwards compatibility. */
+    listEntries(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<MemoryEntry$1[]>;
+    graphNodes(): Promise<GraphNode$1[]>;
+    graphEdges(): Promise<{
+        stats: {
+            nodeCount: number;
+            edgeCount: number;
+            rawNodeCount?: number;
+            rawEdgeCount?: number;
         };
-    };
-    summary: {
-        activeEntries: number;
-        observedProjectLabels: number;
-        retainedAdditions7d: number | null;
-        trackedEntries: number;
-        appliedRecalls: number;
-        reinforcedEntries: number;
-        retrievedEntries: number;
-        retrievals: number;
-    };
-    projects: MemoryProjectInsight[];
-    other: MemoryInsightMetrics | null;
-    /** Most recently reinforced visible entries (≤5), labels only, never bodies. */
-    recentApplied?: Array<{
-        topic: string | null;
-        project: string | null;
-        at: string;
     }>;
-}
-interface GraphRepairResult {
-    staleEdgesDeleted: number;
-    staleNodeRefsRemoved: number;
-    orphanNodesDeleted: number;
-}
-interface GraphNode {
-    id: string;
-    name: string;
-    type: string;
-    canonicalId?: string;
-    sourceEvidence?: SourceEvidence[];
-    properties: Record<string, unknown>;
-    memoryEntryIds: string[];
-}
-interface GraphRelationship {
-    id: string;
-    sourceId: string;
-    targetId: string;
-    type: string;
-    sourceEvidence?: SourceEvidence[];
-    properties: Record<string, unknown>;
-    memoryEntryId?: string;
+    graphQuery(query: {
+        nodeId: string;
+        depth?: number;
+    }): Promise<GraphTraversalResult$1>;
+    consolidate(): Promise<ConsolidationRunResult>;
+    forget(id: string, reason?: string): Promise<boolean>;
+    summarizeSession(sessionId: string): Promise<MemoryEntry$1 | null>;
+    lint(options?: {
+        limit?: number;
+    }): Promise<WikiLintReport$1>;
+    runDecay(): Promise<number>;
+    reindex(): Promise<void>;
+    clearGraph(): Promise<number>;
+    repairGraph(): Promise<GraphRepairResult$1>;
+    deleteBySource(source: string, authority?: TenantScopeOptions): Promise<number>;
+    setFolder(from: string, to: string, options?: {
+        dryRun?: boolean;
+    }): Promise<{
+        from: string;
+        to: string;
+        updated: number;
+        dryRun: boolean;
+    }>;
+    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters, authority?: TenantScopeOptions): Promise<MemoryEntry$1[]>;
+    lineage(params: LineageParams$1, authority?: RequestAuthorityOptions): Promise<LineageResult$1>;
+    reinforce(params: ReinforceParams$1, authority?: RequestAuthorityOptions): Promise<ReinforceResult$1>;
+    log(filters?: MemoryLogFilters): Promise<MemoryEntry$1[]>;
+    queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
+    summarizeEntity(name: string): Promise<MemoryEntry$1>;
+    getEntitySynthesis(name: string): Promise<MemoryEntry$1 | null>;
     /**
-     * Namespace_id provenance carried from the originating MemoryEntry.
-     * `null` (or absent) = legacy / tenant-root bucket. Foundation for the
-     * v0.17.0 strict traversal filter (the AuthzPlan compares this value
-     * edge-by-edge so KG dedupe at the node level can stay intact).
+     * v0.26 user-profile snapshot — upsert. The server derives `userId`
+     * from `X-User-Id` (caller wires it via `defaultHeaders` on the
+     * client constructor or per-request middleware); the body cannot
+     * override it. See spec §Requirements 10.
      */
-    namespaceId?: string | null;
-}
-interface GraphTraversalResult {
-    nodes: GraphNode[];
-    relationships: GraphRelationship[];
-    paths: Array<{
-        nodeIds: string[];
-        relationshipIds: string[];
-    }>;
-}
-/**
- * Memory.lint() report shape — Karpathy-wiki Item B (v0.18.0).
- * Read-only projection composed from signals every owning module
- * already exposes. Lives in shared so the HTTP client can hold the
- * same type as core without re-declaring it.
- */
-interface WikiLintReport {
-    orphans: GraphNode[];
-    decayCandidates: MemoryEntry[];
-    staleSyntheses: Array<{
-        entry: MemoryEntry;
-        reason: string;
+    upsertUserProfile(input: {
+        namespaceId: string;
+        content: string;
+    }): Promise<{
+        updatedAt: string;
+        contentSize: number;
     }>;
-    dedupCandidates: Array<{
-        hash: string;
-        entryIds: string[];
+    /**
+     * v0.26 user-profile snapshot — fetch by namespace. Returns `null` on
+     * HTTP 404 (`isNotFound`), rethrows any other non-2xx as
+     * `MemoryServerError`. Mirrors `get()`'s 404-to-null pattern so callers
+     * can branch on "no profile yet" without inspecting status codes.
+     */
+    getUserProfile(namespaceId: string): Promise<{
+        content: string;
+        updatedAt: string;
+        contentSize: number;
+    } | null>;
+    /**
+     * v0.28 correction-memory — record an explicit correction. POSTs to
+     * `/api/memory/corrections`; tenant is header-derived (server-side), so
+     * the body carries only the correction fields. Returns `{ id, createdAt }`.
+     */
+    recordCorrection(input: {
+        /** Omit in single-tenant deployments — corrections are stored namespace-free. */
+        namespaceId?: string;
+        whatWasWrong: string;
+        whatToDoInstead: string;
+        appliesWhen: string;
+        project?: string;
+        taskShape?: string;
+    }): Promise<{
+        id: string;
+        createdAt: string;
     }>;
+    /**
+     * v0.28 correction-memory — fetch the corrections applicable to a task
+     * shape. GETs `/api/memory/corrections`; returns `[]` when none have
+     * positive overlap. pyx never auto-prepends — the agent owns inclusion.
+     */
+    fetchApplicableCorrections(input: {
+        /** Omit in single-tenant deployments — reads the namespace-free scope. */
+        namespaceId?: string;
+        taskShape: string;
+        project?: string;
+        limit?: number;
+    }): Promise<CorrectionRecord$1[]>;
+    /**
+     * H26 B-d — deterministic prospective due-scan: entries with
+     * `eventTime ∈ [from, from+windowDays]` (inclusive), eventTime ascending,
+     * no relevance ranking. `GET /api/memory/due`.
+     */
+    dueScan(input: {
+        windowDays: number;
+        from?: string;
+        /** Omit in single-tenant deployments. */
+        namespaceId?: string;
+        limit?: number;
+    }): Promise<MemoryEntry$1[]>;
+    protected fetchApi<T>(path: string, options?: RequestInit): Promise<T>;
+    /**
+     * Map fetch-layer rejections into a typed `MemoryServerError` so callers
+     * can react uniformly. AbortSignal.timeout fires a `TimeoutError`; the
+     * caller's signal generally fires an `AbortError`. Anything else (DNS,
+     * TCP reset, TLS) becomes a wrapped error with status 0.
+     */
+    private translateFetchError;
+    /** Parse and validate a JSON API response, throwing MemoryServerError on any failure. */
+    private parseApiResponse;
+}
+
+interface IngestionResult {
+    filename: string;
+    fileType: string;
+    chunks: number;
+    entryIds: string[];
+    totalCharacters: number;
 }
 
+declare const DEFAULTS: {
+    readonly DATA_DIR: "./data";
+    readonly VECTOR_PROVIDER: "lancedb";
+    readonly MEMORY_SERVER_PORT: 7822;
+};
+declare const TAXONOMY_MAX_CATEGORIES = 10;
+declare const TAXONOMY_MAX_TOP_ENTITIES = 15;
+declare const TAXONOMY_MAX_SAMPLE_TOPICS = 8;
+declare const TAXONOMY_MAX_PROJECTS = 8;
+declare const MEMORY_PROJECT_LABEL_MAX_CHARS = 80;
+
 /**
  * Result shape returned by an LLM entity extractor — entities + relations.
  *
@@ -1866,6 +1903,8 @@ declare const MoveFailureReason: {
     readonly GRAPH_UPDATE_FAILED: "graph_update_failed";
     /** Compensation itself failed — manual intervention required. */
     readonly COMPENSATION_FAILED: "compensation_failed";
+    /** Target namespace already holds the entry's (session, ordinal) coordinate; nothing moved. */
+    readonly SESSION_ORDINAL_CONFLICT: "session_ordinal_conflict";
 };
 type MoveFailureReason = (typeof MoveFailureReason)[keyof typeof MoveFailureReason];
 /**
@@ -1893,4 +1932,4 @@ interface CreatePyxMemoryOptions {
 }
 declare function createPyxMemory(opts?: CreatePyxMemoryOptions): MemoryClient;
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, type CreatePyxMemoryOptions, DEFAULTS, DEPRECATED_RAG_STRATEGIES, DisabledMemory, type DroppedGraphRelationship, type DueScanInput, EmbeddingProviderName, type EnrichmentCallbacks, type EnrichmentPurpose, type EntityExtractionResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type FileDownloadOptions, type GraphEnrichEvent, type GraphEnrichFileOptions, type GraphEnrichPreparedEvent, type GraphEnrichResult, type GraphEnrichResultEvent, type GraphEnrichment, type GraphEnrichmentStatus, type GraphExtractionPayload, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, type GraphTelemetrySnapshot, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, type LineageParams, type LineageResult, type LineageVersion, MEMORY_PROJECT_LABEL_MAX_CHARS, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInsightMetrics, type MemoryInsights, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemoryProjectInsight, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, type ReinforceParams, type ReinforceResult, type ReinforceSignal, SINGLE_TENANT_ID, type SecretElevationAggregate, type SecretElevationNotice, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, TAXONOMY_MAX_CATEGORIES, TAXONOMY_MAX_PROJECTS, TAXONOMY_MAX_SAMPLE_TOPICS, TAXONOMY_MAX_TOP_ENTITIES, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, type UsageHygieneSnapshot, VectorProvider, type VectorStatus, type WikiLintReport, assertGraphExtractionPayload, createPyxMemory, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey, projectSearchResponseForMcp, secretElevationAggregate, secretElevationNoticeFor, withSecretElevationNotice };
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, type CorrectionInput, type CorrectionRecord, type CreatePyxMemoryOptions, DEFAULTS, DEPRECATED_RAG_STRATEGIES, DisabledMemory, type DroppedGraphRelationship, type DueScanInput, EmbeddingProviderName, type EnrichmentCallbacks, type EnrichmentPurpose, type EntityExtractionResult, type ExpandAnchorStatus, type ExpandParams, type ExpandResult, type ExtendedMemoryInterface, type FetchCorrectionsInput, type FileDownloadOptions, type GraphEnrichEvent, type GraphEnrichFileOptions, type GraphEnrichPreparedEvent, type GraphEnrichResult, type GraphEnrichResultEvent, type GraphEnrichment, type GraphEnrichmentStatus, type GraphExtractionPayload, type GraphFailureMode, type GraphNode, type GraphRelationship, type GraphRepairResult, type GraphTelemetrySnapshot, type GraphTraversalResult, type IngestEntity, type IngestErrorEvent, type IngestEvent, type IngestFileOptions, type IngestHeartbeatEvent, type IngestProgressEvent, type IngestRelationship, type IngestResultEvent, type IngestStage, type IngestionResult, type LineageParams, type LineageResult, type LineageVersion, MEMORY_PROJECT_LABEL_MAX_CHARS, MemoryClient, type MemoryClientOptions, type MemoryEntry, type MemoryIngestRequest, type MemoryInsightMetrics, type MemoryInsights, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemoryLogFilters, type MemoryProjectInsight, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, type MoveEntriesFilter, MoveFailureReason, type MoveResult, type MoveTarget, NamespaceIsolation, type PrincipalContext, RAGStrategy, type ReinforceParams, type ReinforceResult, type ReinforceSignal, SESSION_ORDINAL_MAX, SINGLE_TENANT_ID, type SecretElevationAggregate, type SecretElevationNotice, SensitivityLevel, type SourceEvidence, type StoreInput, StoreTarget, TAXONOMY_MAX_CATEGORIES, TAXONOMY_MAX_PROJECTS, TAXONOMY_MAX_SAMPLE_TOPICS, TAXONOMY_MAX_TOP_ENTITIES, type TemporalQueryFilters, type TenantScopeOptions, type Timestamp, type Topology, type TopologyExtractionProvider, type TopologyServiceVariant, type UsageHygieneSnapshot, VectorProvider, type VectorStatus, type WikiLintReport, assertGraphExtractionPayload, createPyxMemory, isSessionOrdinal, mergeExtractedEntities, normalizeGraphLabel, normalizeNameKey, projectSearchResponseForMcp, secretElevationAggregate, secretElevationNoticeFor, withSecretElevationNotice };