@noir-ai/memory 1.0.0-beta.1

package/dist/index.d.ts

@@ -0,0 +1,803 @@
+import { ProjectId } from '@noir-ai/core';
+export { ProjectId } from '@noir-ai/core';
+import { Store } from '@noir-ai/store';
+import { EmbedFn } from '@noir-ai/context';
+export { EmbedFn, EmbedderConfig } from '@noir-ai/context';
+
+/**
+ * Known observation types (dev-flavored, DS-3). `lesson` is reserved for
+ * consolidation output (task t5); the others are user-supplied on save. This
+ * list is intentionally NOT a closed set: {@link MemoryType} also accepts any
+ * unknown string so forward-compatible / user-defined types round-trip through
+ * the store without a migration.
+ */
+declare const MEMORY_TYPES: readonly ["pattern", "preference", "architecture", "bug", "workflow", "fact", "decision", "lesson"];
+/**
+ * Open enum: one of {@link MEMORY_TYPES} OR any string. The `(string & {})`
+ * intersection preserves literal autocompletion for the known values while
+ * permitting arbitrary user-defined types (DS-3: unknown values accepted +
+ * stored). `lesson` is reserved for consolidation output.
+ */
+type MemoryType = (typeof MEMORY_TYPES)[number] | (string & {});
+/**
+ * Provenance of a capture. `'explicit'` = a deliberate `memory_save` (the v1
+ * default, DS-4). `'auto:<hook>'` = an opt-in Claude Code hooks template
+ * capture (e.g. `'auto:stop'`, `'auto:posttooluse'`); the template ships as
+ * files the user installs deliberately — never auto-wired by `noir init`/`sync`.
+ */
+type MemorySource = 'explicit' | `auto:${string}`;
+/**
+ * Default observation salience (spec §4.1). Applied by `MemoryEngine.save` when
+ * {@link SaveInput.importance} is omitted, and by consolidation when appending a
+ * derived `type:'lesson'` row. Shared via types.ts so save + consolidation agree
+ * on the baseline without a cross-module value import.
+ */
+declare const DEFAULT_IMPORTANCE = 0.5;
+/**
+ * The canonical memory row. Realized ON TOP of the store (DS-2): the full row
+ * lives in KV `memory:obs:<id>` (the authoritative source of truth — the line
+ * between it and the indexes is R4's mitigation), with
+ * `indexDoc({source:'memory'})` (FTS5) + `upsertVec({source:'memory'})`
+ * (sqlite-vec) as search indexes. `content` is NEVER truncated (DS-9) — the
+ * FTS snippet is only a preview window hydrated-around on recall.
+ */
+interface Observation {
+    /** Unique id (crypto.randomUUID()). Key into KV `memory:obs:<id>`. */
+    id: string;
+    /** Open enum (DS-3). `lesson` is reserved for consolidation output. */
+    type: MemoryType;
+    /** Full text — never truncated (DS-9). Indexed into FTS5 + embedded into vec0. */
+    content: string;
+    /** Canonical project id (NEVER a filesystem path — blueprint D6). */
+    project: ProjectId;
+    /** Host session id if known, else null. */
+    sessionId: string | null;
+    /** Created-at epoch millis. */
+    ts: number;
+    /** Bumped on recall hit (best-effort, single writer). */
+    lastAccessTs: number;
+    /** Salience 0..1 (default 0.5, applied at save time). */
+    importance: number;
+    /** User tags (no auto-LLM tagging in v1 — explicit only). */
+    concepts: string[];
+    /** Repo-relative paths mentioned. */
+    files: string[];
+    /** Capture provenance (DS-4). */
+    source: MemorySource;
+    /**
+     * Source observation ids, set ONLY on derived `type:'lesson'` rows produced
+     * by consolidation (task t5). Absent on user-saved observations. Originals
+     * are never mutated or deleted (append-only — reversible + auditable, DS-6).
+     */
+    provenance?: string[];
+}
+/**
+ * Input to {@link MemoryEngine.save} / the `memory_save` MCP tool. Only
+ * `content` is required; the engine applies defaults (`type`, `importance`,
+ * `source:'explicit'`, `ts`, `id`) at save time. No field here triggers a
+ * network or LLM call — capture is always local + free (DS-10).
+ */
+interface SaveInput {
+    /** Full text to remember. Required. */
+    content: string;
+    /** Open enum (DS-3); a default is applied at save time when omitted. */
+    type?: MemoryType;
+    /** User tags. */
+    concepts?: string[];
+    /** Repo-relative paths mentioned. */
+    files?: string[];
+    /** Salience 0..1 (defaults to 0.5 at save time). */
+    importance?: number;
+    /** Host session id (recorded when known). */
+    sessionId?: string;
+}
+/**
+ * Options for {@link MemoryEngine.recall} (the hybrid path). Mirrors the S6
+ * retriever's source-scoped search plus memory-side filters.
+ */
+interface RecallOptions {
+    /** Max results (default 10). */
+    limit?: number;
+    /** Filter to a single {@link MemoryType}. */
+    type?: MemoryType;
+    /** Filter to a single host session. */
+    sessionId?: string;
+}
+/** Options for {@link MemoryEngine.search} (the BM25-only instant path). */
+interface SearchOptions {
+    /** Max results (default 10). */
+    limit?: number;
+}
+/**
+ * A ranked recall/search hit. `content` is the FULL observation text hydrated
+ * from the authoritative KV row — never the truncated FTS snippet (DS-9).
+ * `score` is the RRF-fused rank score (recall, k=60) or the BM25 score
+ * (search); it is rank-based, not a normalized similarity.
+ */
+interface MemoryHit {
+    id: string;
+    type: MemoryType;
+    /** Full text — never truncated (DS-9). */
+    content: string;
+    /** RRF-fused rank score (recall) or BM25 score (search). */
+    score: number;
+    concepts: string[];
+    files: string[];
+    /** Created-at epoch millis (from the observation). */
+    ts: number;
+    importance: number;
+    source: MemorySource;
+}
+/**
+ * Per-session rollup, listed by {@link MemoryEngine.sessions}. Stored in KV
+ * `memory:sessions` as a per-project list (solo user v1 — A3).
+ */
+interface SessionInfo {
+    /** Host session id. */
+    id: string;
+    /** Canonical project id (NEVER a filesystem path — D6). */
+    project: ProjectId;
+    /** Number of observations in this session. */
+    count: number;
+    /** Epoch millis of the most recent observation in this session. */
+    lastTs: number;
+}
+/**
+ * Consolidation config block. Provider-EXPLICIT (blueprint D5/D6, DS-6): the
+ * provider is NEVER inferred from env-var presence — no explicit `provider`
+ * ⇒ {@link MemoryEngine.consolidate} refuses + logs
+ * (`{ok:false, reason:'no-provider'}`) and writes a `memory:consolidation:miss`
+ * KV audit entry. NEVER a silent paid call.
+ */
+interface ConsolidationConfig {
+    /** Master switch (default false). When false, `consolidate` is unregistered. */
+    enabled?: boolean;
+    /** Provider key, e.g. 'anthropic' | 'openai' | 'ollama'. Required to run. */
+    provider?: string;
+    /** Provider-specific model id. */
+    model?: string;
+    /** Restrict candidates to these types (default: every non-`lesson` type). */
+    types?: string[];
+}
+/**
+ * Runtime memory config consumed by the engine (the subset of the core
+ * `memory:` block that affects engine behavior). The full user-facing schema
+ * (capture / hooksTemplate / recall / consolidation) lives in
+ * `NoirConfigSchema.memory` (@noir-ai/core, task t6); this is its runtime
+ * projection. Defaults to `{}` ⇒ consolidation disabled (offline, free).
+ */
+interface MemoryConfig {
+    consolidation?: ConsolidationConfig;
+}
+/**
+ * Result of {@link MemoryEngine.forget}: the KV row removed + best-effort
+ * doc/vec purge (deleteDoc + deleteVec — A2's acceptable v1 behavior).
+ */
+interface ForgetResult {
+    /** Number of observations actually removed. */
+    deleted: number;
+    /** Ids passed to forget (echoed for the MCP envelope). */
+    ids: string[];
+}
+/** Options for {@link MemoryEngine.consolidate}. */
+interface ConsolidateOptions {
+    /** Restrict candidates to these types (overrides config). */
+    types?: string[];
+    /** Cap on candidate observations. */
+    limit?: number;
+}
+/**
+ * Result of {@link MemoryEngine.consolidate} (DS-6). Either a success appending
+ * one or more derived `type:'lesson'` rows (originals never mutated), or a
+ * documented refusal. A refusal is NEVER a crash and NEVER a silent paid call:
+ * `logged:true` records the miss so the user can see why nothing happened.
+ */
+type ConsolidationResult = {
+    ok: true;
+    lessons: Observation[];
+    from: string[];
+} | {
+    ok: false;
+    /** Why consolidation did not run. */
+    reason: 'no-provider' | 'model-unavailable' | 'no-candidates';
+    /** True once the miss has been written to the KV audit log. */
+    logged: boolean;
+};
+/**
+ * Snapshot returned by {@link MemoryEngine.status} (mirrors `ContextStatus` /
+ * `StoreStatus`). `observations` is a live read off the single writer handle.
+ */
+interface MemoryStatus {
+    ok: boolean;
+    /** Canonical project id (never a filesystem path — D6). */
+    projectId: string;
+    /** Number of observations (rows indexed with `source:'memory'`). */
+    observations: number;
+    /** True when the store handle is read-only (saves/forgets will refuse). */
+    degraded: boolean;
+}
+/**
+ * The memory engine — the `ctx.memory` service (the contract the daemon seam
+ * in task t4 types against, and tests mock). Constructed once per serve
+ * lifecycle from the daemon's store handle + the shared S6 `EmbedFn` (mirrors
+ * `ContextEngine` / `WorkflowEngine`). The daemon owns the single embedder and
+ * passes the SAME `EmbedFn` to both the context and memory engines — no
+ * embedder duplication (plan §Architecture).
+ *
+ * `consolidate` is OPTIONAL: registered only when consolidation is enabled AND
+ * a provider is configured (task t5, OQ-5). Its absence is the static signal
+ * that no LLM surface is wired (DS-6/D5).
+ *
+ * Single-writer discipline: the engine — like the context indexer — is the
+ * ONLY thing that writes `source:'memory'` rows through the injected handle; it
+ * never opens a second store connection (blueprint D6: in-process only, no
+ * sidecar).
+ */
+interface MemoryEngine {
+    /** Persist an observation (FTS5 + vec0 + KV `memory:obs:<id>`); returns the row. */
+    save(input: SaveInput): Promise<Observation>;
+    /**
+     * Hybrid recall: BM25 ∪ kNN fused by RRF (k=60), scoped to `source:'memory'`,
+     * + cheap regex entity-boost, hydrated from KV (DS-5/DS-9). Degrades to
+     * BM25-only when the embedder is unavailable.
+     */
+    recall(query: string, opts?: RecallOptions): Promise<MemoryHit[]>;
+    /** Instant BM25-only lookup scoped to `source:'memory'` (no embed cost). */
+    search(query: string, opts?: SearchOptions): Promise<MemoryHit[]>;
+    /** Per-session rollups from KV `memory:sessions`. */
+    sessions(): SessionInfo[];
+    /** Remove observations: KV row + best-effort doc/vec purge. */
+    forget(ids: string[]): ForgetResult;
+    /**
+     * Explicit consolidation job (DS-6). Provider-gated: refuses + logs if no
+     * provider is configured — NEVER a silent paid call. Appends derived
+     * `type:'lesson'` rows; originals are never mutated.
+     */
+    consolidate?(opts?: ConsolidateOptions): Promise<ConsolidationResult>;
+    /** State snapshot (mirrors `ContextStatus` / `StoreStatus`). */
+    status(): MemoryStatus;
+}
+
+/**
+ * Known host hook events Noir can capture (the four Claude Code hooks the v1
+ * template targets, DS-4 / spec §5). The list is intentionally NOT closed:
+ * {@link CaptureEventType} also accepts any unknown string so a future host's
+ * hook names round-trip through the mapper without a code change (mirrors the
+ * open-enum taxonomy in types.ts).
+ */
+declare const CAPTURE_HOOKS: readonly ["PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop"];
+/** One of {@link CAPTURE_HOOKS} OR any host-defined hook name (open enum). */
+type CaptureEventType = (typeof CAPTURE_HOOKS)[number] | (string & {});
+/**
+ * Hook events captured by DEFAULT (DS-4). Persist session-end summaries + the
+ * prompts a user submits; SKIP the noisy per-tool events (`PreToolUse` /
+ * `PostToolUse` fire on every tool call and would flood memory + leak tool
+ * inputs the user did not ask to remember). A user opts INTO tool-event capture
+ * by passing a custom {@link CapturePolicy.hooks}.
+ */
+declare const DEFAULT_CAPTURE_HOOKS: readonly CaptureEventType[];
+/**
+ * The default capture policy: capture {@link DEFAULT_CAPTURE_HOOKS} only. Used
+ * when {@link toSaveInput} is called with no `policy` argument. Host-neutral +
+ * conservative — the user owns the policy.
+ */
+declare const DEFAULT_CAPTURE_POLICY: CapturePolicy;
+/**
+ * The structured payload a host hook forwards. All fields optional — a hook
+ * populates whichever it has (a `Stop` hook carries a `summary`; a
+ * `UserPromptSubmit` hook carries the `prompt`; a tool hook carries `toolName`
+ * + `toolInput`). Unknown extra fields are tolerated (the mapper reads only the
+ * fields below), so a host can forward its raw stdin without shape-massaging.
+ */
+interface CapturePayload {
+    /** Tool name for tool hooks (e.g. `'Bash'`, `'Edit'`, `'Write'`). */
+    toolName?: string;
+    /** The tool's input object (e.g. `{ command: 'npm test' }`, `{ file_path }`). */
+    toolInput?: unknown;
+    /** The submitted prompt text (`UserPromptSubmit`). */
+    prompt?: string;
+    /** A session-end summary (`Stop`) — free text the host derived or was given. */
+    summary?: string;
+}
+/**
+ * A host-neutral capture event. Built by a host hook (or a `noir memory capture`
+ * CLI) from whatever the host emitted on stdin, then handed to
+ * {@link toSaveInput}. The shape is deliberately minimal + portable so it is not
+ * tied to Claude Code's stdin schema (a future host adapter translates its own
+ * payload into this).
+ *
+ * `project` is the CANONICAL project id (NEVER a filesystem path — blueprint
+ * D6); the capture command resolves it from `cwd` before constructing the event.
+ */
+interface CaptureEvent {
+    /** Hook event name (open enum — {@link CaptureEventType}). */
+    event_type: CaptureEventType;
+    /** Epoch millis of the event (host-supplied or `Date.now()` at capture). */
+    ts: number;
+    /** Host session id if known, else null (recorded on the observation). */
+    sessionId: string | null;
+    /** Canonical project identifier (NEVER a filesystem path — D6). */
+    project: ProjectId;
+    /** The event-specific fields (see {@link CapturePayload}). */
+    payload: CapturePayload;
+}
+/**
+ * An opinionated capture policy. Controls WHICH hook events are persisted when
+ * {@link toSaveInput} is called. Defaults to {@link DEFAULT_CAPTURE_POLICY}
+ * (session summaries + submitted prompts only). The user owns this — it is the
+ * one knob that keeps auto-capture from flooding memory (R3).
+ */
+interface CapturePolicy {
+    /**
+     * Hook events to capture. An event whose `event_type` is NOT in this list is
+     * skipped (`toSaveInput` returns `null`). Defaults to
+     * {@link DEFAULT_CAPTURE_HOOKS}.
+     */
+    hooks?: ReadonlyArray<CaptureEventType>;
+}
+/**
+ * Project a host-neutral {@link CaptureEvent} into a {@link SaveInput} ready for
+ * `MemoryEngine.save` / the `memory_save` MCP tool, OR return `null` when the
+ * policy says to skip this event (a noisy hook the user did not opt into, or an
+ * event with no usable content).
+ *
+ * The mapper is PURE: it reads no environment, holds no secrets, performs NO I/O
+ * and NO LLM call (capture is always local + free, DS-10). It applies the
+ * opinionated defaults from spec §5:
+ *   • only the policy's `hooks` are captured (default: Stop + UserPromptSubmit);
+ *   • content is built from the event's payload fields (summary / prompt / a
+ *     compact tool-call description);
+ *   • `type` is inferred lightly (a decision-shaped prompt → `'decision'`; a
+ *     tool hook → `'workflow'`; otherwise `'fact'`) — a heuristic the user can
+ *     override by editing the saved row;
+ *   • `files` is pulled best-effort from a tool input's `file_path`;
+ *   • `sessionId` is forwarded when present.
+ *
+ * Returning `null` is the documented "skip" signal — the caller (a capture
+ * command) MUST NOT treat it as an error; it is the policy working as intended.
+ *
+ * @param event  The host-neutral capture event.
+ * @param policy Capture policy (defaults to {@link DEFAULT_CAPTURE_POLICY}).
+ * @returns The {@link SaveInput}, or `null` to skip.
+ */
+declare function toSaveInput(event: CaptureEvent, policy?: CapturePolicy): SaveInput | null;
+/**
+ * Build the observation `content` for an event from its payload, or `null` when
+ * the payload carries nothing persistable. Per hook:
+ *   • `Stop` → `payload.summary` (a session-end summary); null when absent.
+ *   • `UserPromptSubmit` → `payload.prompt`; null when absent.
+ *   • tool hooks (`PreToolUse` / `PostToolUse`, or any `toolName`-bearing
+ *     event) → a compact {@link describeToolCall} line.
+ * Pure.
+ */
+declare function buildContent(event: CaptureEvent): string | null;
+/**
+ * Render a compact one-line description of a tool call for memory content, e.g.
+ * `"Ran Bash: npm test"` or `"Edited src/foo.ts"`. Returns `null` when the
+ * payload carries neither a toolName nor a toolInput. Pure + best-effort — it
+ * never throws on an unexpected toolInput shape (it renders what it can).
+ */
+declare function describeToolCall(payload: CapturePayload): string | null;
+/**
+ * Light type inference for a captured event (a heuristic — the user can override
+ * by editing the saved row; no LLM is involved, DS-10). Decision-shaped prompts
+ * → `'decision'`; tool hooks → `'workflow'`; otherwise `'fact'` (the engine's
+ * default type). Pure.
+ */
+declare function inferType(event: CaptureEvent): MemoryType;
+/**
+ * Extract repo-relative file paths from a tool input best-effort: the
+ * `file_path` field (Edit / Write / Read) when present. Returns `[]` when none.
+ * Pure; never throws on a non-object toolInput.
+ */
+declare function extractFiles(payload: CapturePayload): string[];
+/**
+ * The memory `source` provenance for a captured event: `'auto:<hook>'` (e.g.
+ * `'auto:stop'`, `'auto:posttooluse'`), lowercased so the bucket name is a
+ * stable identifier. Exported for a dedicated `noir memory capture` CLI (S9)
+ * that persists an event OUTSIDE the `memory_save` envelope and wants to tag
+ * provenance — the MCP `memory_save` path itself records `source:'explicit'`
+ * (SaveInput carries no source field by design).
+ */
+declare function captureSource(eventType: CaptureEventType): MemorySource;
+
+/**
+ * User-facing memory config shape — mirrors `NoirConfig['memory']` (the zod block
+ * @noir-ai/core ships, slice S7 / task t6). Declared LOCALLY with every field
+ * optional so this module type-checks WITHOUT a forward dependency on a core
+ * type (core never imports memory — no cycle; @noir-ai/core is not even
+ * consulted here), AND so a config with no `memory:` block (or a partial one)
+ * maps cleanly to a fully-disabled runtime config. The fully-resolved zod output
+ * is structurally assignable to this permissive shape, so the mapper accepts a
+ * `NoirConfig['memory']` directly.
+ */
+interface MemoryUserConfig {
+    /** Consolidation gate (provider-explicit — never silent paid, DS-6). */
+    consolidation?: {
+        /** Master switch (default false). When false, `consolidate` refuses + logs. */
+        enabled?: boolean;
+        /** Provider key, e.g. 'anthropic' | 'openai' | 'ollama'. Required to run. */
+        provider?: string;
+        /** Provider-specific model id. */
+        model?: string;
+        /** Restrict candidates to these types (default: every non-`lesson` type). */
+        types?: string[];
+    };
+}
+/**
+ * Resolve a user-facing {@link MemoryUserConfig} into the runtime
+ * {@link MemoryConfig} the memory engine (and `runConsolidation`) consume.
+ *
+ * - `undefined` / missing block ⇒ `{ consolidation: { enabled: false } }`
+ *   (consolidation disabled — the safe default; capture/store/retrieve stay
+ *   local + free. `runConsolidation` then refuses with `'no-provider'` + logs,
+ *   making NO paid call, blueprint D6).
+ * - A block whose `consolidation.enabled` is absent or `false` ⇒ the same
+ *   disabled default, regardless of any `provider`/`model` written alongside it
+ *   (the master switch is the first gate `runConsolidation` checks).
+ * - A block with `consolidation.enabled === true` + a `provider` ⇒ the provider
+ *   + optional `model`/`types` pass straight through; `runConsolidation` then
+ *   proceeds to its model-availability + candidate gates.
+ *
+ * `consolidation` is ALWAYS populated (with `enabled` defaulted) so consumers
+ * read `config.consolidation.enabled` without a separate undefined check —
+ * mirrors how `resolveModelConfig` normalizes `tiers`/`providers` to
+ * always-present objects.
+ *
+ * This mapper is a PURE projection — it copies fields through unchanged, NEVER
+ * infers a provider from env-var presence (DS-6), reads NO environment, holds NO
+ * secrets, and never throws. Whether a configured provider is actually USABLE is
+ * decided at call time inside `complete()` (S8, which re-reads env idempotently),
+ * NOT here.
+ */
+declare function resolveMemoryConfig(raw?: MemoryUserConfig): MemoryConfig;
+
+/**
+ * Per-call request shape passed to {@link MemoryModel.complete}. A structural
+ * subset of S8's `CompleteRequest` (provider-EXPLICIT; no `tools`/`stream` —
+ * single-shot only, blueprint D5). Defined locally so the memory package has no
+ * value-level dependency on `@noir-ai/model`; the daemon seam (t6) binds
+ * `complete(req, cfg)` into this shape, and tests inject a fake.
+ */
+interface MemoryCompleteRequest {
+    system?: string;
+    prompt: string;
+    /** Provider block name — explicit, NEVER env-inferred (D5/DS-6). */
+    provider: string;
+    /** Model id for this call. */
+    model: string;
+    maxTokens?: number;
+    /** Bounded task tier (DS-9). Selects a per-tier output cap; never a provider. */
+    tier?: 'draft' | 'title' | 'summarize' | 'consolidate';
+}
+/**
+ * The subset of S8's `CompleteResult` that consolidation consumes. `null` is
+ * first-class degradation (no provider resolvable at call time — the always-
+ * available offline path, D5); `{ok:false}` is an attempted-call failure.
+ */
+type MemoryCompleteResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: string;
+} | null;
+/**
+ * The optional S8 model injection. Its absence is the runtime signal that the
+ * bounded model layer is not wired (consolidation then refuses
+ * `'model-unavailable'` — the documented S7 stub, OQ-3/OQ-8). When present,
+ * `complete` is the SOLE LLM entry point and is reached ONLY after the provider
+ * gate passes (DS-6: never a silent paid call).
+ */
+interface MemoryModel {
+    complete(req: MemoryCompleteRequest): Promise<MemoryCompleteResult>;
+}
+/** Construction options for {@link MemoryEngineImpl} / {@link createMemoryEngine}. */
+interface MemoryEngineOptions {
+    /** The daemon's store handle — the ONLY storage surface used (single writer). */
+    store: Store;
+    /**
+     * Project root. Stored for API symmetry with {@link ContextEngine} and future
+     * path normalization; v1 stores {@link Observation.files} repo-relative as-is.
+     */
+    root: string;
+    /** Canonical project identifier (NEVER a filesystem path — blueprint D6). */
+    projectId: ProjectId;
+    /**
+     * The shared S6 embedder (the daemon resolves it once and passes the SAME
+     * `EmbedFn` to context + memory). A throw on `embed()` ⇒ the vec index is
+     * skipped for that observation (F8-style degradation — the row is still
+     * BM25-searchable via FTS5 + the authoritative KV row).
+     */
+    embed: EmbedFn;
+    /** Optional S8 model injection for consolidation (absent ⇒ consolidation refuses). */
+    model?: MemoryModel;
+    /** Runtime memory config (the consolidation gate). Defaults to `{}` (offline). */
+    config?: MemoryConfig;
+    /** True when `store` was opened read-only (the daemon-down fallback). */
+    storeDegraded?: boolean;
+}
+/**
+ * Noir's cross-session memory engine — the `ctx.memory` service. Constructed
+ * once per serve lifecycle (mirror `ContextEngine` / `WorkflowEngine`) from the
+ * daemon's store handle + the shared S6 `EmbedFn` + an optional S8 model.
+ * Implements the {@link MemoryEngine} contract; {@link get} is an extra public
+ * method (beyond the interface) for recall hydration + tests.
+ *
+ * `consolidate` is ALWAYS present on the class and self-gates on the configured
+ * provider; the daemon decides whether to register the `memory_consolidate` MCP
+ * tool from `config.memory.consolidation.enabled` (OQ-5). Its refusal paths are
+ * the documented stub behavior (spec §7) — never a crash, never a silent call.
+ */
+declare class MemoryEngineImpl implements MemoryEngine {
+    /** The daemon's single-writer store handle (possibly read-only). */
+    readonly store: Store;
+    /** Project root (stored for symmetry / future path normalization). */
+    readonly root: string;
+    /** Canonical project identifier (NEVER a filesystem path — D6). */
+    readonly projectId: ProjectId;
+    /**
+     * Persistent degradation flag (read-only store). Mutating ops throw a clear
+     * error upfront instead of letting the first write fail mid-run; reads
+     * (recall/search/sessions/status) keep working.
+     */
+    readonly degraded: boolean;
+    private readonly embed;
+    private readonly model;
+    private readonly config;
+    private chain;
+    constructor(opts: MemoryEngineOptions);
+    /** @inheritDoc MemoryEngine.save */
+    save(input: SaveInput): Promise<Observation>;
+    private saveInternal;
+    /**
+     * Write one observation to ALL three indexes in a single synchronous block:
+     * FTS5 (`indexDoc`, content searchable) + sqlite-vec (`upsertVec`, best-effort
+     * — skipped if the embedder or vec0 is unavailable, F8-style) + the
+     * authoritative KV row (`memory:obs:<id>`) + the id index + the sessions
+     * rollup. The `docs.meta` payload is the denormalized search projection
+     * (Observation minus content); the KV row is the source of truth (R4).
+     */
+    private indexObservation;
+    /**
+     * Hydrate the full {@link Observation} for `id` from the authoritative KV row.
+     * Returns `null` for an unknown / forgotten id. This is the only correct way
+     * to read an observation's complete `content` (DS-9).
+     */
+    get(id: string): Observation | null;
+    /** @inheritDoc MemoryEngine.recall */
+    recall(query: string, opts?: RecallOptions): Promise<MemoryHit[]>;
+    /** @inheritDoc MemoryEngine.search */
+    search(query: string, opts?: SearchOptions): Promise<MemoryHit[]>;
+    /**
+     * Hydrate a ranked id list into {@link MemoryHit}s from the authoritative KV
+     * row, applying the optional `type` / `sessionId` filters. Each hit carries
+     * the FULL `content` (DS-9). A ranked id with no KV row (a stale vec-only hit
+     * whose row was forgotten) is dropped — never emitted with partial data.
+     */
+    private hydrateHits;
+    /** @inheritDoc MemoryEngine.sessions */
+    sessions(): SessionInfo[];
+    /** @inheritDoc MemoryEngine.forget */
+    forget(ids: string[]): ForgetResult;
+    /** @inheritDoc MemoryEngine.consolidate */
+    consolidate(opts?: ConsolidateOptions): Promise<ConsolidationResult>;
+    private consolidateInternal;
+    /** @inheritDoc MemoryEngine.status */
+    status(): MemoryStatus;
+    /**
+     * Best-effort embedding: returns the vec, or `null` if the embedder is
+     * unavailable (`kind:'none'`, native load failure, provider error). A `null`
+     * vec skips `upsertVec` so the save still succeeds — the row is BM25-searchable
+     * + hydrated from KV (F8-style degradation).
+     */
+    private embedBestEffort;
+    /** Throw a clear, typed error when the store handle is read-only. */
+    private assertNotDegraded;
+    /**
+     * Single-flight serialization of async mutating ops (mirrors the context
+     * indexer's `serialized`). Forces `work` to run strictly after the previous
+     * queued op completes. A failed op does NOT poison the queue — the chain
+     * advances regardless, and the caller observes the real outcome via `result`.
+     */
+    private serialized;
+}
+/**
+ * Build a {@link MemoryEngineImpl} bound to a single store handle + the shared
+ * S6 embedder + an optional S8 model. Constructed once per serve lifecycle
+ * alongside the context + workflow engines. The daemon passes the SAME `embed`
+ * it resolved for S6 (no embedder duplication) and resolves the model via S8's
+ * `resolveModelConfig` only when `config.memory.consolidation.enabled` is set
+ * (provider-explicit — never a silent paid call, D6).
+ */
+declare function createMemoryEngine(opts: MemoryEngineOptions): MemoryEngineImpl;
+
+/** Default cap on consolidation candidates (spec §7.4 — deterministic selection). */
+declare const DEFAULT_CONSOLIDATE_LIMIT = 50;
+/**
+ * Single-shot consolidation instruction (D5: no tools, no loop). The lesson is
+ * free-text PROSE (not JSON): a lesson is a synthesized insight, and free-text
+ * avoids a JSON-parse/repair round on what is naturally unstructured output.
+ */
+declare const CONSOLIDATION_SYSTEM_PROMPT: string;
+/**
+ * Capabilities `runConsolidation` needs from the engine. The engine owns the
+ * store handle + the embedder; `indexDerived` is the callback that writes a
+ * derived observation to every index (embed → FTS5 + vec + KV + id index),
+ * reusing the engine's shared `indexObservation` path so a lesson lands exactly
+ * like a user-saved observation. Consolidation itself never touches the
+ * embedder or the write path directly — it builds the lesson row + hands it off.
+ */
+interface ConsolidationDeps {
+    /** The daemon's single-writer store handle (possibly read-only — D6). */
+    store: Store;
+    /** Optional S8 model injection; absent ⇒ `'model-unavailable'` refusal. */
+    model: MemoryModel | undefined;
+    /** Runtime memory config (the provider-explicit consolidation gate). */
+    config: MemoryConfig;
+    /** Canonical project identifier (NEVER a filesystem path — D6). */
+    projectId: ProjectId;
+    /**
+     * Write a derived lesson observation to all indexes. The engine implements
+     * this as `embedBestEffort(content)` then the shared `indexObservation(obs,
+     * vec)` — so the lesson is searchable (BM25 + vec) + hydrated from KV just
+     * like a user save.
+     */
+    indexDerived: (observation: Observation) => Promise<void>;
+}
+/**
+ * Run one explicit consolidation pass.
+ *
+ * Gate order (each refusal logs to `memory:consolidation:miss` and returns
+ * `logged:true`; NONE makes a paid call before its gate passes):
+ *  1. `no-provider` — consolidation not enabled OR no explicit `provider`
+ *     configured. The provider is NEVER inferred from env-var presence (D5/D6).
+ *  2. `model-unavailable` — enabled + provider set, but the S8 model injection
+ *     is absent OR no explicit `model` id is configured (the documented S7 stub,
+ *     OQ-3/OQ-8). Also the refusal when `complete()` returns `null` (provider
+ *     not resolvable at call time — e.g. key missing) OR `{ok:false}` (an
+ *     attempted call failed): both are wrapped as `'model-unavailable'`.
+ *  3. `no-candidates` — nothing matches the (optional) type filter / lookback,
+ *     OR the model returned empty text.
+ *
+ * On success: appends ONE derived `type:'lesson'` observation with
+ * `provenance:[candidate ids]` via `indexDerived`; originals are NEVER mutated
+ * (append-only — reversible + auditable, DS-6).
+ */
+declare function runConsolidation(deps: ConsolidationDeps, opts?: ConsolidateOptions): Promise<ConsolidationResult>;
+/**
+ * Gather consolidation candidates: observations with `type != 'lesson'`,
+ * newest-first, optionally restricted to `types`, capped at `limit`. Pure read
+ * off the id index + KV — no LLM, no clustering (spec §7.4). Exported so the
+ * deterministic selection is testable without a model.
+ */
+declare function gatherCandidates(store: Store, types: ReadonlyArray<string> | undefined, limit: number): Observation[];
+/**
+ * Serialize candidates into the consolidation prompt body (deterministic order,
+ * 1-indexed, with type + ts for the model's context). Pure.
+ */
+declare function serializeCandidates(candidates: ReadonlyArray<Observation>): string;
+/**
+ * De-duplicate + collect concept tags across the candidate set (becomes the
+ * derived lesson's `concepts`). Order is first-seen; pure.
+ */
+declare function dedupeConcepts(candidates: ReadonlyArray<Observation>): string[];
+
+/** The injected store handle + the shared S6 embedder (read-only pipeline). */
+interface RecallDeps {
+    /** The daemon's single-writer store handle (may be read-only — reads keep working). */
+    store: Store;
+    /** Query embedder. A throw on `embed(query)` ⇒ BM25-only degradation. */
+    embed: EmbedFn;
+}
+/** Internal outcome of {@link recallMemory} (the engine projects this to `MemoryHit[]`). */
+interface RecallMemoryResult {
+    /** Ranked, hydrated hits (FULL content — DS-9), truncated to `limit`. */
+    hits: MemoryHit[];
+    /** True when the kNN OR BM25 leg failed this call (honest per-query signal). */
+    degraded: boolean;
+    /** `'hybrid'` when the kNN leg ran, `'bm25-only'` when it was skipped. */
+    mode: 'hybrid' | 'bm25-only';
+}
+/**
+ * Cheap regex extraction of identifiers + file/path tokens from a query (NO LLM
+ * — DS-5). Two kinds of entity are collected, de-duplicated:
+ *
+ *   1. **Qualified tokens** — whitespace-delimited tokens that contain a `/`,
+ *      `.`, or `:` (e.g. `packages/memory/src/recall.ts`, `memory:obs`,
+ *      `MemoryEngine.save`). Kept whole + lowercased so they match an
+ *      observation's `files` / `concepts` exactly when it mentions the same path
+ *      or qualified name.
+ *   2. **Identifier subwords** — every token is also split at camelCase /
+ *      PascalCase / snake_case / kebab-case boundaries into lowercase subwords
+ *      (mirrors the index-side `explodeIdentifiers` convention from
+ *      `@noir-ai/context`), so a query for `ContextEngine` yields `context` +
+ *      `engine` and a query for `recall_memory` yields `recall` + `memory`.
+ *
+ * Tokens shorter than {@link MIN_ENTITY_LEN} and {@link STOPWORDS} are dropped
+ * to keep matching precise. Pure + deterministic.
+ */
+declare function extractEntities(query: string): string[];
+/**
+ * Run hybrid recall (BM25 ∪ kNN → RRF → entity-boost → KV hydration) scoped to
+ * `source:'memory'`. Read-only against the injected store; no second connection,
+ * no network, no LLM (blueprint D6).
+ *
+ * The returned hits carry the FULL `content` hydrated from the authoritative KV
+ * row (DS-9 — never the truncated FTS snippet). `degraded`/`mode` describe the
+ * actual outcome of THIS call: `mode:'bm25-only'` + `degraded:true` when the
+ * embedder was unavailable and recall fell back to BM25.
+ */
+declare function recallMemory(deps: RecallDeps, query: string, opts?: RecallOptions): Promise<RecallMemoryResult>;
+
+/** Per-observation authoritative-row key prefix; value is the full {@link Observation}. */
+declare const OBS_PREFIX = "memory:obs:";
+/** KV key holding the per-project {@link SessionInfo} rollup list. */
+declare const SESSIONS_KEY = "memory:sessions";
+/** KV key holding the sorted list of all observation ids (status + candidates). */
+declare const INDEX_KEY = "memory:index";
+/** KV key holding the consolidation refusal audit log (DS-6: refuse + LOG). */
+declare const CONSOLIDATION_MISS_KEY = "memory:consolidation:miss";
+/** Build a `memory:obs:<id>` KV key. */
+declare function obsKey(id: string): string;
+/**
+ * Hydrate the FULL {@link Observation} for `id` from the authoritative KV row.
+ * Returns `null` when the id was never saved (or has been forgotten — the
+ * tombstone reads back as `null`). This is the ONLY correct way to read an
+ * observation's complete `content` (DS-9: never the truncated FTS snippet).
+ */
+declare function getObservation(store: Store, id: string): Observation | null;
+/** Write the authoritative full row (the source of truth — DS-2/R4). */
+declare function setObservation(store: Store, obs: Observation): void;
+/**
+ * Clear the authoritative KV row for `id` (tombstone — mirrors the context
+ * indexer's `persist(..., tombstones)` which writes `null`). The id MUST also
+ * be dropped from {@link INDEX_KEY} and the session rollup by the caller so the
+ * index stays consistent (see engine.ts `forget`).
+ */
+declare function clearObservation(store: Store, id: string): void;
+/** All observation ids currently tracked (insertion order). Empty array if none. */
+declare function getObservationIds(store: Store): string[];
+/** Overwrite the full id list (used by `save`/`forget` after an atomic RMW). */
+declare function setObservationIds(store: Store, ids: string[]): void;
+/** The per-project {@link SessionInfo} rollup list (empty array if none). */
+declare function getSessions(store: Store): SessionInfo[];
+/** Overwrite the sessions rollup (used by the RMW helpers below). */
+declare function setSessions(store: Store, sessions: SessionInfo[]): void;
+/**
+ * Increment the rollup for `sessionId` (inserting a new entry when first seen),
+ * bumping `lastTs` to the max. RMW — call within the engine's serialized/sync KV
+ * block so two concurrent saves cannot lose an increment.
+ */
+declare function bumpSession(store: Store, sessionId: string, project: SessionInfo['project'], ts: number): void;
+/**
+ * Decrement the rollup for `sessionId`, dropping the entry when it reaches zero
+ * so a forgotten observation cleans up its own empty session. RMW — call within
+ * the engine's serialized/sync KV block. No-op for an unknown session.
+ */
+declare function decrementSession(store: Store, sessionId: string): void;
+/**
+ * One recorded consolidation refusal. `reason` is the documented
+ * {@link ConsolidationResult} refusal cause; `provider` is recorded when a
+ * provider WAS configured but the run still refused (e.g. the S8 layer was
+ * unavailable), so the user can see exactly why nothing happened.
+ */
+interface ConsolidationMiss {
+    /** Epoch millis of the refusal. */
+    ts: number;
+    /** Documented refusal reason (`'no-provider' | 'model-unavailable' | 'no-candidates'`). */
+    reason: string;
+    /** Provider key, when one was configured (absent for the no-provider case). */
+    provider?: string;
+}
+/** The full refusal audit log (newest appended last). Empty array if none. */
+declare function getConsolidationMisses(store: Store): ConsolidationMiss[];
+/**
+ * Append a refusal record to the audit log. RMW — called ONLY from the engine's
+ * serialized `consolidate`, so the append cannot race itself. DS-6: a refusal is
+ * never silent — the miss is recorded so the user can see why no lesson was
+ * written (and that NO paid call was made).
+ */
+declare function appendConsolidationMiss(store: Store, miss: ConsolidationMiss): void;
+
+export { CAPTURE_HOOKS, CONSOLIDATION_MISS_KEY, CONSOLIDATION_SYSTEM_PROMPT, type CaptureEvent, type CaptureEventType, type CapturePayload, type CapturePolicy, type ConsolidateOptions, type ConsolidationConfig, type ConsolidationDeps, type ConsolidationMiss, type ConsolidationResult, DEFAULT_CAPTURE_HOOKS, DEFAULT_CAPTURE_POLICY, DEFAULT_CONSOLIDATE_LIMIT, DEFAULT_IMPORTANCE, type ForgetResult, INDEX_KEY, MEMORY_TYPES, type MemoryCompleteRequest, type MemoryCompleteResult, type MemoryConfig, type MemoryEngine, MemoryEngineImpl, type MemoryEngineOptions, type MemoryHit, type MemoryModel, type MemorySource, type MemoryStatus, type MemoryType, type MemoryUserConfig, OBS_PREFIX, type Observation, type RecallDeps, type RecallMemoryResult, type RecallOptions, SESSIONS_KEY, type SaveInput, type SearchOptions, type SessionInfo, appendConsolidationMiss, buildContent, bumpSession, captureSource, clearObservation, createMemoryEngine, decrementSession, dedupeConcepts, describeToolCall, extractEntities, extractFiles, gatherCandidates, getConsolidationMisses, getObservation, getObservationIds, getSessions, inferType, obsKey, recallMemory, resolveMemoryConfig, runConsolidation, serializeCandidates, setObservation, setObservationIds, setSessions, toSaveInput };