jeopi-cli 16.2.14 → 16.2.17

package/dist/types/memories/okf.d.ts

@@ -0,0 +1,36 @@
+/** OKF v0.1 frontmatter fields. Only `type`/`title`/`description` are required. */
+export interface OkfFields {
+    type: string;
+    title: string;
+    description: string;
+    resource?: string;
+    tags?: readonly string[];
+    /** ISO 8601 datetime, e.g. `2026-07-02T10:00:00Z`. */
+    timestamp?: string;
+    /** Producer-specific extension fields (e.g. `thread_id`). */
+    extra?: Record<string, string | number>;
+}
+/** Render an OKF atom: YAML frontmatter followed by the markdown body. */
+export declare function renderOkfDocument(fields: OkfFields, body: string): string;
+/** Parsed frontmatter (undefined when absent/unparseable) plus the body. */
+export interface OkfDocumentParts {
+    frontmatter: Record<string, unknown> | undefined;
+    body: string;
+}
+/**
+ * Split an OKF document into frontmatter and body. Tolerant by design: text
+ * without a leading fence (legacy jeopi memory files, hand-edited files)
+ * returns the whole text as body with `frontmatter: undefined`, and a
+ * malformed YAML block still strips so prompt paths never leak fences.
+ */
+export declare function parseOkfDocument(text: string): OkfDocumentParts;
+/** Body of an OKF document with any leading frontmatter removed. */
+export declare function stripOkfFrontmatter(text: string): string;
+/**
+ * Validate a document against the OKF v0.1 rules the jeo-skills `okf` linter
+ * enforces: a leading `---` fence, a closing fence, and non-empty
+ * `type` / `title` / `description` fields. Returns an empty array when valid.
+ */
+export declare function validateOkfDocument(text: string): string[];
+/** Format a unix-seconds timestamp as the ISO 8601 string OKF expects. */
+export declare function okfTimestamp(unixSeconds?: number): string;

package/dist/types/memories/storage.d.ts

@@ -0,0 +1,110 @@
+import { Database } from "bun:sqlite";
+export interface MemoryThread {
+    id: string;
+    updatedAt: number;
+    rolloutPath: string;
+    cwd: string;
+    sourceKind: string;
+}
+export interface Stage1OutputRow {
+    threadId: string;
+    sourceUpdatedAt: number;
+    rawMemory: string;
+    rolloutSummary: string;
+    rolloutSlug: string | null;
+    generatedAt: number;
+    cwd: string;
+}
+export interface Stage1Claim {
+    threadId: string;
+    ownershipToken: string;
+    inputWatermark: number;
+    sourceUpdatedAt: number;
+    rolloutPath: string;
+    cwd: string;
+}
+export interface GlobalClaim {
+    ownershipToken: string;
+    inputWatermark: number;
+}
+export declare function openMemoryDb(dbPath: string): Database;
+export declare function closeMemoryDb(db: Database): void;
+export declare function clearMemoryData(db: Database): void;
+export declare function upsertThreads(db: Database, threads: MemoryThread[]): void;
+export declare function claimStage1Jobs(db: Database, params: {
+    nowSec: number;
+    threadScanLimit: number;
+    maxRolloutsPerStartup: number;
+    maxRolloutAgeDays: number;
+    minRolloutIdleHours: number;
+    leaseSeconds: number;
+    runningConcurrencyCap: number;
+    workerId: string;
+    excludeThreadIds?: string[];
+}): Stage1Claim[];
+export declare function enqueueGlobalWatermark(db: Database, sourceUpdatedAt: number, cwd: string, params?: {
+    forceDirtyWhenNotAdvanced?: boolean;
+}): void;
+export declare function markStage1SucceededWithOutput(db: Database, params: {
+    threadId: string;
+    ownershipToken: string;
+    sourceUpdatedAt: number;
+    rawMemory: string;
+    rolloutSummary: string;
+    rolloutSlug: string | null;
+    nowSec: number;
+    cwd: string;
+}): boolean;
+export declare function markStage1SucceededNoOutput(db: Database, params: {
+    threadId: string;
+    ownershipToken: string;
+    sourceUpdatedAt: number;
+    nowSec: number;
+    cwd: string;
+}): boolean;
+export declare function markStage1Failed(db: Database, params: {
+    threadId: string;
+    ownershipToken: string;
+    retryDelaySeconds: number;
+    reason: string;
+    nowSec: number;
+}): boolean;
+export declare function tryClaimGlobalPhase2Job(db: Database, params: {
+    workerId: string;
+    leaseSeconds: number;
+    nowSec: number;
+    cwd: string;
+}): {
+    kind: "claimed";
+    claim: GlobalClaim;
+} | {
+    kind: "skipped_not_dirty";
+} | {
+    kind: "skipped_running";
+};
+export declare function heartbeatGlobalJob(db: Database, params: {
+    ownershipToken: string;
+    leaseSeconds: number;
+    nowSec: number;
+    cwd: string;
+}): boolean;
+export declare function listStage1OutputsForGlobal(db: Database, limit: number, cwd: string): Stage1OutputRow[];
+export declare function markGlobalPhase2Succeeded(db: Database, params: {
+    ownershipToken: string;
+    newWatermark: number;
+    nowSec: number;
+    cwd: string;
+}): boolean;
+export declare function markGlobalPhase2Failed(db: Database, params: {
+    ownershipToken: string;
+    retryDelaySeconds: number;
+    reason: string;
+    nowSec: number;
+    cwd: string;
+}): boolean;
+export declare function markGlobalPhase2FailedUnowned(db: Database, params: {
+    retryDelaySeconds: number;
+    reason: string;
+    nowSec: number;
+    cwd: string;
+}): boolean;

package/dist/types/memory-backend/index.d.ts

@@ -0,0 +1,7 @@
+export type { MnemopiBackendConfig, MnemopiLlmMode, MnemopiProviderOptions, MnemopiScoping, } from "../mnemopi/config";
+export type { MnemopiMemoryEditOperation, MnemopiMemoryEditOptions, MnemopiMemoryEditResult, MnemopiSessionState, MnemopiSessionStateOptions, } from "../mnemopi/state";
+export * from "./local-backend";
+export * from "./off-backend";
+export * from "./resolve";
+export * from "./runtime";
+export * from "./types";

package/dist/types/memory-backend/local-backend.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryBackend } from "./types";
+/**
+ * Wraps the existing `memories/` module as a `MemoryBackend`.
+ *
+ * The rollout-summarisation pipeline (rollouts → SQLite → memory_summary.md) is
+ * delegated unchanged. On top of it, `save()` persists `learn`-tool lessons to
+ * `learned.md` (so `status()` reports `writable: true`); structured search is
+ * still unavailable.
+ */
+export declare const localBackend: MemoryBackend;

package/dist/types/memory-backend/off-backend.d.ts

@@ -0,0 +1,7 @@
+import type { MemoryBackend } from "./types";
+/**
+ * No-op memory backend.
+ *
+ * Selected when `memory.backend` is `"off"`.
+ */
+export declare const offBackend: MemoryBackend;

package/dist/types/memory-backend/resolve.d.ts

@@ -0,0 +1,16 @@
+import type { Settings } from "../config/settings";
+import type { MemoryBackend } from "./types";
+/**
+ * Pick the active memory backend for a Settings instance.
+ *
+ * Selection rules (single source of truth — every memory consumer routes
+ * through this):
+ *   - `memory.backend === "hindsight"`  → Hindsight remote memory
+ *   - `memory.backend === "mnemopi"`  → local Mnemopi SQLite memory
+ *   - `memory.backend === "local"`      → local rollout summary pipeline
+ *   - everything else                   → no-op
+ *
+ * `memories.enabled` remains accepted only as a legacy migration input. Once
+ * a config is loaded, `memory.backend` is the sole runtime selector.
+ */
+export declare function resolveMemoryBackend(settings: Settings): Promise<MemoryBackend>;

package/dist/types/memory-backend/runtime.d.ts

@@ -0,0 +1,4 @@
+import type { AgentSession } from "../session/agent-session";
+import type { MemoryBackendOperationContext, MemoryRuntimeContext } from "./types";
+export declare function createMemoryRuntimeContext(context: MemoryBackendOperationContext): MemoryRuntimeContext;
+export declare function createSessionMemoryRuntimeContext(session: AgentSession, agentDir: string, cwd: string): MemoryRuntimeContext;

package/dist/types/memory-backend/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Memory backend abstraction.
+ *
+ * Backends are mutually exclusive — `await resolveMemoryBackend(settings)` returns
+ * exactly one. Implementations MUST be self-contained: they own the per-session
+ * state they create in `start()` and tear it down on `clear()`.
+ */
+import type { AgentMessage } from "jeopi-agent-core";
+import type { ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
+import type { HindsightSessionState } from "../hindsight/state";
+import type { MnemopiSessionState } from "../mnemopi/state";
+import type { AgentSession } from "../session/agent-session";
+export type MemoryBackendId = "off" | "local" | "hindsight" | "mnemopi";
+export interface MemoryBackendStatus {
+    backend: MemoryBackendId;
+    active: boolean;
+    writable: boolean;
+    searchable: boolean;
+    scope?: string;
+    retainBank?: string;
+    recallBanks?: string[];
+    workingCount?: number;
+    episodicCount?: number;
+    tripleCount?: number;
+    lastMemory?: string;
+    lastRecall?: boolean;
+    database?: string;
+    message?: string;
+    error?: string;
+}
+export interface MemoryBackendSearchOptions {
+    limit?: number;
+    /** Best-effort abort signal. Backends may only observe it before/after an underlying recall call. */
+    signal?: AbortSignal;
+}
+export interface MemoryBackendSearchItem {
+    id?: string;
+    content: string;
+    source?: string;
+    timestamp?: string;
+    score?: number;
+}
+export interface MemoryBackendSearchResult {
+    backend: MemoryBackendId;
+    query: string;
+    count: number;
+    items: MemoryBackendSearchItem[];
+    message?: string;
+}
+export interface MemoryBackendSaveInput {
+    content: string;
+    context?: string;
+    source?: string;
+    importance?: number;
+}
+export interface MemoryBackendSaveResult {
+    backend: MemoryBackendId;
+    stored: number;
+    ids?: string[];
+    queued?: boolean;
+    message?: string;
+}
+export interface MemoryBackendOperationContext {
+    agentDir: string;
+    cwd: string;
+    session?: AgentSession;
+}
+export interface MemoryRuntimeContext {
+    status(): Promise<MemoryBackendStatus>;
+    search(query: string, options?: MemoryBackendSearchOptions): Promise<MemoryBackendSearchResult>;
+    save(input: string | MemoryBackendSaveInput): Promise<MemoryBackendSaveResult>;
+}
+export interface MemoryBackendStartOptions {
+    session: AgentSession;
+    settings: Settings;
+    modelRegistry: ModelRegistry;
+    agentDir: string;
+    taskDepth: number;
+    parentHindsightSessionState?: HindsightSessionState;
+    parentMnemopiSessionState?: MnemopiSessionState;
+}
+export interface MemoryBackend {
+    readonly id: MemoryBackendId;
+    /**
+     * Wire any background work or session subscriptions for this backend.
+     *
+     * Called once per agent session at startup. Implementations MUST be
+     * non-throwing: failures should be logged and swallowed so a misconfigured
+     * memory backend cannot break the agent loop.
+     */
+    start(options: MemoryBackendStartOptions): void | Promise<void>;
+    /**
+     * Markdown injected as the system-prompt append section.
+     * Returned on every prompt rebuild via `refreshBaseSystemPrompt()`.
+     */
+    buildDeveloperInstructions(agentDir: string, settings: Settings, session?: AgentSession): Promise<string | undefined>;
+    /** Wipe all persisted state for this backend (slash `/memory clear`). */
+    clear(agentDir: string, cwd: string, session?: AgentSession): Promise<void>;
+    /** Force consolidation/retain to happen now (slash `/memory enqueue`). */
+    enqueue(agentDir: string, cwd: string, session?: AgentSession): Promise<void>;
+    /** Structured state for UI, slash commands, and extensions. */
+    status?(context: MemoryBackendOperationContext): Promise<MemoryBackendStatus>;
+    /** Explicit user-facing semantic/lexical search. */
+    search?(context: MemoryBackendOperationContext, query: string, options?: MemoryBackendSearchOptions): Promise<MemoryBackendSearchResult>;
+    /** Explicit user-facing save operation. */
+    save?(context: MemoryBackendOperationContext, input: MemoryBackendSaveInput): Promise<MemoryBackendSaveResult>;
+    /** Render backend-specific memory statistics as markdown (`/memory stats`). */
+    stats?(agentDir: string, cwd: string, session?: AgentSession): Promise<string | undefined>;
+    /** Render backend-specific memory diagnostics as markdown (`/memory diagnose`). */
+    diagnose?(agentDir: string, cwd: string, session?: AgentSession): Promise<string | undefined>;
+    /**
+     * Optional hook to inject a backend-specific block into the current turn's
+     * system prompt before the agent starts generating.
+     *
+     * This is the only place a backend can affect the very first answer of a
+     * fresh session. The returned text is appended to the already-built base
+     * system prompt for this turn only; callers may separately cache it and
+     * surface it through `buildDeveloperInstructions()` on later rebuilds.
+     */
+    beforeAgentStartPrompt?(session: AgentSession, promptText: string): Promise<string | undefined>;
+    /**
+     * Optional hook to splice extra context into a compaction summarization.
+     *
+     * Called from the compaction call site before the LLM summary is requested.
+     * Returning a string appends one entry to the compaction's `extraContext`
+     * list (which becomes part of the summarization prompt). Return `undefined`
+     * to inject nothing — the local backend takes this branch because its
+     * summary is already part of the system prompt.
+     */
+    preCompactionContext?(messages: AgentMessage[], settings: Settings, session?: AgentSession): Promise<string | undefined>;
+}

package/dist/types/mnemopi/backend.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryBackend } from "../memory-backend/types";
+import type { AgentSession } from "../session/agent-session";
+export declare const mnemopiBackend: MemoryBackend;
+export declare function getMnemopiDbDirForTests(session: AgentSession): string | undefined;

package/dist/types/mnemopi/config.d.ts

@@ -0,0 +1,60 @@
+import type { MnemopiOptions } from "jeopi-mnemopi";
+import type { Settings } from "../config/settings";
+export type MnemopiLlmMode = "none" | "smol" | "remote";
+export type MnemopiScoping = "global" | "per-project" | "per-project-tagged";
+export type MnemopiProviderOptions = Pick<MnemopiOptions, "noEmbeddings" | "embeddingModel" | "embeddingApiUrl" | "embeddingApiKey" | "llm" | "debug">;
+export interface MnemopiBackendConfig {
+    dbPath: string;
+    baseBank?: string;
+    bank: string;
+    globalBank?: string;
+    retainBank?: string;
+    recallBanks?: readonly string[];
+    scoping?: MnemopiScoping;
+    autoRecall: boolean;
+    autoRetain: boolean;
+    polyphonicRecall: boolean;
+    enhancedRecall: boolean;
+    proactiveLinking: boolean;
+    retainEveryNTurns: number;
+    recallLimit: number;
+    recallContextTurns: number;
+    recallMaxQueryChars: number;
+    injectionTokenLimit: number;
+    debug: boolean;
+    providerOptions: MnemopiProviderOptions;
+    llmMode: MnemopiLlmMode;
+    llmBaseUrl?: string;
+    llmApiKey?: string;
+    llmModel?: string;
+}
+export declare function loadMnemopiConfig(settings: Settings, agentDir: string): MnemopiBackendConfig;
+export interface MnemopiBankScope {
+    baseBank: string;
+    bank: string;
+    globalBank: string;
+    retainBank: string;
+    recallBanks: readonly string[];
+}
+/**
+ * Resolve write/recall banks for a session.
+ *
+ * Mnemopi has no tag-filtered recall, so `per-project-tagged` maps to a
+ * project-local write bank plus a shared recall-visible bank. The project
+ * bank is derived purely from {@link cwd} — see {@link projectBank} for the
+ * stability contract.
+ */
+export declare function computeMnemopiBankScope(configured: string | undefined, cwd: string, scoping: MnemopiScoping): MnemopiBankScope;
+/**
+ * Discover sibling banks under `<dbDir>/banks/` whose `working_memory` rows
+ * all carry the active `cwd` in `metadata_json.$.cwd`, and add those safe
+ * single-cwd banks to the recall set. This rescues memories stranded by a
+ * previous, less-stable bank derivation (#2412) without recalling mixed-cwd
+ * legacy banks wholesale under per-project isolation.
+ *
+ * Robust by design: a missing banks directory, unreadable bank dir, or
+ * corrupt SQLite file is silently skipped. Scanning is capped at
+ * {@link LEGACY_BANK_SCAN_LIMIT} to bound startup cost.
+ */
+export declare function extendRecallWithLegacyBanks(resolved: readonly string[], dbPath: string, cwd: string): readonly string[];
+export declare function truncateApproxTokens(text: string, tokenLimit: number): string;

package/dist/types/mnemopi/embed-client.d.ts

@@ -0,0 +1,53 @@
+import { type SpawnedSubprocess, type WorkerHandle } from "../subprocess/worker-client";
+import type { MnemopiEmbedModelId, MnemopiEmbedWorkerInbound, MnemopiEmbedWorkerOutbound } from "./embed-protocol";
+/**
+ * Parent-side handle for the mnemopi embeddings subprocess. The runtime
+ * implementation is a Bun child process so `onnxruntime-node`'s NAPI
+ * constructor + finalizer never run inside the main agent address space —
+ * those destructors segfault Bun on Windows when mnemopi's local embedding
+ * provider loads fastembed in the main process (issue #3031; the mnemopi
+ * sibling of the tiny-model fix from #1606 / #1607).
+ */
+export type MnemopiEmbedWorkerHandle = WorkerHandle<MnemopiEmbedWorkerInbound, MnemopiEmbedWorkerOutbound>;
+/**
+ * Hidden subcommand on the main CLI that boots the mnemopi embeddings worker
+ * in the spawned subprocess. Kept in sync with the dispatch in `cli.ts`.
+ */
+export declare const MNEMOPI_EMBED_WORKER_ARG = "__omp_worker_mnemopi_embed";
+/**
+ * Spawn the mnemopi embeddings worker as a subprocess. Exported for tests and
+ * the smoke probe; production callers go through {@link spawnMnemopiEmbedWorker}.
+ * The child inherits the parent env verbatim — fastembed honours `HF_HUB_*`,
+ * `HTTPS_PROXY`, etc., and our `loadFastembed()` reads the same `OMP_*`
+ * runtime-install knobs the parent uses.
+ */
+export declare function createMnemopiEmbedSubprocess(): SpawnedSubprocess<MnemopiEmbedWorkerOutbound>;
+/**
+ * Per-model wrapper produced by {@link MnemopiEmbedClient.initialize}.
+ * `embed()` round-trips one batch of texts through the worker subprocess and
+ * yields the resulting vectors in a single asynchronous batch — fastembed's
+ * own iterator was emitting batches that we collect on the child side anyway,
+ * and serializing per-batch over IPC would not improve throughput.
+ */
+export interface MnemopiSubprocessEmbeddingModel {
+    embed(texts: string[], batchSize?: number): AsyncIterable<number[][]>;
+}
+export declare class MnemopiEmbedClient {
+    #private;
+    constructor(spawnWorker?: () => MnemopiEmbedWorkerHandle);
+    /**
+     * Load the named fastembed model inside the subprocess. Resolves to a
+     * thin wrapper whose `embed()` round-trips through the same worker, or
+     * `null` when the worker cannot init the model (missing peer, native
+     * load failure, etc.). Multiple calls with the same model reuse the
+     * single in-flight worker; calling with a different model loads it on
+     * the child without restarting the process.
+     */
+    initialize(model: MnemopiEmbedModelId, cacheDir: string | undefined): Promise<MnemopiSubprocessEmbeddingModel | null>;
+    terminate(): Promise<void>;
+}
+export declare const mnemopiEmbedClient: MnemopiEmbedClient;
+export declare function shutdownMnemopiEmbedClient(): Promise<void>;
+export declare function smokeTestMnemopiEmbedWorker({ timeoutMs, }?: {
+    timeoutMs?: number;
+}): Promise<void>;

package/dist/types/mnemopi/embed-protocol.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Wire types between the parent (`MnemopiEmbedClient`) and the local
+ * embeddings subprocess. The parent owns the subprocess lifecycle (graceful
+ * work, hard `SIGKILL` on shutdown); the protocol carries no explicit close
+ * handshake — once the parent decides to terminate, it signals the OS to reap
+ * the child so `onnxruntime-node`'s NAPI finalizer never runs in the main
+ * agent address space (it crashes Bun on Windows shutdown — issue #3031, the
+ * mnemopi sibling of the tiny-model fix from #1606/#1607). See
+ * `embed-client.ts` for the spawn/kill glue.
+ */
+/** Identifier of the fastembed model the worker should load (e.g. `fast-bge-base-en-v1.5`). */
+export type MnemopiEmbedModelId = string;
+export type MnemopiEmbedWorkerInbound = {
+    type: "ping";
+    id: string;
+} | {
+    type: "init";
+    id: string;
+    model: MnemopiEmbedModelId;
+    cacheDir?: string;
+} | {
+    type: "embed";
+    id: string;
+    model: MnemopiEmbedModelId;
+    cacheDir?: string;
+    texts: string[];
+    batchSize?: number;
+};
+export type MnemopiEmbedWorkerOutbound = {
+    type: "pong";
+    id: string;
+} | {
+    type: "ready";
+    id: string;
+} | {
+    type: "vectors";
+    id: string;
+    vectors: number[][];
+} | {
+    type: "error";
+    id: string;
+    error: string;
+} | {
+    type: "log";
+    level: "debug" | "warn" | "error";
+    msg: string;
+    meta?: Record<string, unknown>;
+};
+export interface MnemopiEmbedTransport {
+    send(message: MnemopiEmbedWorkerOutbound): void;
+    onMessage(handler: (message: MnemopiEmbedWorkerInbound) => void): () => void;
+}

package/dist/types/mnemopi/embed-worker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Mnemopi local-embeddings worker. Loaded inside the dedicated subprocess
+ * spawned by `embed-client.ts` (re-entered through the agent CLI's hidden
+ * `__omp_worker_mnemopi_embed` selector). The whole point of this module is
+ * that `loadFastembed()` — and therefore `onnxruntime-node`'s NAPI
+ * constructor + finalizer — only ever runs in this child address space. The
+ * parent `SIGKILL`s us on shutdown so the destructor that crashes Bun on
+ * Windows shutdown (issue #3031, mnemopi sibling of #1606/#1607) never runs
+ * in either process.
+ */
+import type { MnemopiEmbedTransport } from "./embed-protocol";
+export declare function startMnemopiEmbedWorker(transport: MnemopiEmbedTransport): void;

package/dist/types/mnemopi/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./backend";
+export * from "./config";
+export * from "./state";

package/dist/types/mnemopi/state.d.ts

@@ -0,0 +1,130 @@
+import type { AgentMessage } from "jeopi-agent-core";
+import type * as MnemopiNs from "jeopi-mnemopi";
+import type { Mnemopi, RecallResult } from "jeopi-mnemopi";
+import type * as MnemopiCoreNs from "jeopi-mnemopi/core";
+import type { AgentSession } from "../session/agent-session";
+import type { MnemopiBackendConfig } from "./config";
+/**
+ * Lazily load `jeopi-mnemopi` (memoized) and route fastembed loads
+ * through the dedicated embeddings subprocess. The override is installed once
+ * — before any consumer gets the chance to call `embed()` — so
+ * `onnxruntime-node`'s NAPI constructor + finalizer never run inside the
+ * agent's address space (issue #3031). Test seams that swap the initializer
+ * with `setLocalModelInitializerForTests` still win because both go through
+ * the same module-level slot.
+ */
+export declare function loadMnemopi(): Promise<typeof MnemopiNs>;
+/** Lazily load `jeopi-mnemopi/core` (memoized). */
+export declare function loadMnemopiCore(): Promise<typeof MnemopiCoreNs>;
+/** Sync access for code below an async boundary that already awaited {@link loadMnemopi}. */
+export declare function requireMnemopi(): typeof MnemopiNs;
+/** Sync access for code below an async boundary that already awaited {@link loadMnemopiCore}. */
+export declare function requireMnemopiCore(): typeof MnemopiCoreNs;
+interface MnemopiScopedMemory {
+    bank: string;
+    memory: Mnemopi;
+}
+type MnemopiRememberInput = Parameters<Mnemopi["remember"]>[0];
+type MnemopiRememberOptions = Parameters<Mnemopi["remember"]>[1];
+export type MnemopiMemoryEditOperation = "update" | "forget" | "invalidate";
+export interface MnemopiMemoryEditOptions {
+    content?: string;
+    importance?: number;
+    replacementId?: string;
+}
+export interface MnemopiMemoryEditResult {
+    status: "updated" | "deleted" | "invalidated" | "not_found";
+    bank?: string;
+    store?: "working" | "episodic";
+}
+export declare function getMnemopiSessionState(session: AgentSession | undefined): MnemopiSessionState | undefined;
+export declare function setMnemopiSessionState(session: AgentSession, state: MnemopiSessionState | undefined): MnemopiSessionState | undefined;
+export interface MnemopiSessionStateOptions {
+    sessionId: string;
+    config: MnemopiBackendConfig;
+    session: AgentSession;
+    aliasOf?: MnemopiSessionState;
+    lastRetainedTurn?: number;
+    hasRecalledForFirstTurn?: boolean;
+}
+export declare class MnemopiSessionState {
+    sessionId: string;
+    readonly config: MnemopiBackendConfig;
+    readonly session: AgentSession;
+    readonly memory: Mnemopi;
+    readonly globalMemory?: Mnemopi;
+    readonly aliasOf?: MnemopiSessionState;
+    private readonly scoped;
+    lastRetainedTurn: number;
+    hasRecalledForFirstTurn: boolean;
+    lastRecallSnippet?: string;
+    unsubscribe?: () => void;
+    constructor(options: MnemopiSessionStateOptions);
+    setSessionId(sessionId: string): void;
+    resetConversationTracking(): void;
+    getScopedRecallTargets(): readonly MnemopiScopedMemory[];
+    getScopedRetainTarget(): MnemopiScopedMemory;
+    editScopedMemory(op: MnemopiMemoryEditOperation, id: string, options?: MnemopiMemoryEditOptions): MnemopiMemoryEditResult;
+    formatScopedRecallWithIds(results: readonly RecallResult[]): string;
+    collectScopedRecallResults(query: string): Promise<RecallResult[]>;
+    recallResultsScoped(query: string): Promise<RecallResult[]>;
+    formatScopedRecallContext(results: readonly RecallResult[], format?: "bullet" | "json"): string | undefined;
+    formatContextScoped(results: readonly RecallResult[], format?: "bullet" | "json"): string;
+    rememberInScope(memory: MnemopiRememberInput, options?: MnemopiRememberOptions): string | undefined;
+    rememberScoped(memory: MnemopiRememberInput, options?: MnemopiRememberOptions): string | undefined;
+    recallForContext(query: string): Promise<string | undefined>;
+    beforeAgentStartPrompt(promptText: string): Promise<string | undefined>;
+    recallForCompaction(messages: AgentMessage[]): Promise<string | undefined>;
+    maybeRetainOnAgentEnd(_messages: AgentMessage[]): Promise<void>;
+    forceRetainCurrentSession(): Promise<void>;
+    retainMessages(messages: Array<{
+        role: string;
+        content: string;
+    }>, sourceId: string): Promise<void>;
+    attachSessionListeners(): void;
+    maybeRecallOnAgentStart(): Promise<void>;
+    /**
+     * Drain in-flight fact extraction and run beam consolidation on every owned
+     * bank, after capturing the current transcript. Mirrors the manual
+     * `/memory enqueue` slash command, but stops short of closing the DBs so
+     * callers can keep using the state. {@link dispose} composes this with the
+     * close step so normal session shutdown promotes working memory to
+     * episodic/gists/graph automatically (see issue #2320).
+     *
+     * Aliased subagent states share `scoped` (and therefore the actual SQLite
+     * banks) with their parent. `consolidate()` deliberately does NOT
+     * short-circuit on `aliasOf`: `forceRetainCurrentSession` already guards
+     * itself, and an explicit `/memory enqueue` invoked from within a subagent
+     * still needs to flush extractions and sleep the parent's shared banks —
+     * otherwise enqueue would report success while leaving the subagent's
+     * retained memories unconsolidated until the parent eventually shuts down
+     * (PR #2327 review).
+     */
+    consolidate(): Promise<void>;
+    /**
+     * Release the per-session resources. Defaults to running {@link consolidate}
+     * before closing handles so normal session shutdown promotes working memory
+     * into long-term storage. Callers that are about to delete the DB files —
+     * e.g. `mnemopiBackend.clear` — pass `{ consolidate: false }` to skip the
+     * extraction/sleep pass, since spending tokens on memories that will be
+     * wiped on the next line is wasted work (PR #2327 review).
+     *
+     * `timeoutMs` caps how long the consolidate await blocks the caller
+     * (the user-visible `/quit` / `/exit` shutdown path passes this so
+     * dispose returns within a UX budget — issue #3641). When the cap is
+     * hit, dispose returns immediately and detaches the still-in-flight
+     * consolidate; the SQLite handles are closed in the background once
+     * the consolidate settles so writes never race a closed handle, and
+     * any pending embeddings are SIGKILL'd along with the embed worker
+     * (a tolerable loss — working memory rows are durable; only the
+     * episodic promotion / embedding for the LAST few turns is skipped,
+     * and `maybeRetainOnAgentEnd` has already retained earlier turns).
+     */
+    dispose(options?: {
+        consolidate?: boolean;
+        timeoutMs?: number;
+    }): Promise<void>;
+}
+export declare function getMnemopiScopedDbPaths(config: MnemopiBackendConfig): readonly string[];
+export declare function getMnemopiScopedBanks(config: MnemopiBackendConfig): readonly string[];
+export {};