@illuma-ai/agents 1.1.25 → 1.3.0

package/dist/types/graphs/MultiAgentGraph.d.ts

@@ -45,6 +45,11 @@ export declare class MultiAgentGraph extends StandardGraph {
      * Used by auto-continuation to know which agent's context to preserve after handoff.
      */
     private lastActiveAgentId;
+    /**
+     * Registry for async handoff execution.
+     * Enables autonomous orchestration: spawn children non-blocking,
+     * orchestrator stays alive to reason and collect results when ready.
+     */
     /**
      * When set, the graph routes START to this agent instead of the default starting nodes.
      * Enables multi-turn resumption: follow-up messages go to the agent that last handled
@@ -109,6 +114,31 @@ export declare class MultiAgentGraph extends StandardGraph {
      * @param sourceAgentName - The human-readable name of the source agent
      */
     private createTransferToolsForEdge;
+    /**
+     * Builds orchestration guidance injected into the system message of agents
+     * that have handoff or transfer tools (i.e., orchestrator agents).
+     *
+     * Implements two orchestration primitives:
+     * - Execution bias guidance injected into the system prompt
+     * - Multi-round autonomous execution for dependent tasks
+     *
+     * Handoff tools are synchronous (browser-tool callback pattern): spawn the
+     * child, await completion, return the real text as the tool output. Parallel
+     * handoff tool calls in one turn run concurrently via LangGraph's ToolNode,
+     * so independent children run in parallel without explicit orchestration.
+     *
+     * @param childDescs - Display names (with optional descriptions) of child agents
+     * @param toolCount - Number of handoff/transfer tools available
+     */
+    private buildOrchestratorGuidance;
+    /**
+     * Builds subagent context instructions injected into child agents that are
+     * handoff destinations. This tells the child agent it is a subagent with
+     * a focused task.
+     *
+     * @param orchestratorName - Display name of the parent orchestrator agent
+     */
+    private buildChildAgentContext;
     /**
      * Builds a meaningful default description for a transfer tool when no explicit
      * edge.description is provided. Uses the destination agent's name and description
@@ -129,9 +159,10 @@ export declare class MultiAgentGraph extends StandardGraph {
     private createHandoffTools;
     /**
      * Create handoff tools for an edge (handles multiple destinations).
-     * Each handoff tool invokes the child agent's compiled subgraph inline,
-     * extracts the final AI message text, truncates it, and returns it as
-     * a string (which becomes a ToolMessage in the parent's context).
+     * Each handoff tool spawns the child agent's compiled subgraph asynchronously
+     * and returns immediately. The orchestrator uses `collect_results` to retrieve
+     * outputs and `check_agents` to monitor status — a push-based autonomous
+     * orchestration pattern.
      *
      * @param edge - The graph edge defining the handoff
      * @param sourceAgentId - The ID of the parent/supervisor agent
@@ -148,7 +179,7 @@ export declare class MultiAgentGraph extends StandardGraph {
     /**
      * Truncate handoff result using head/tail strategy (60/40 split).
      * Preserves the beginning (key findings) and end (conclusions).
-     * Matches the TaskTool.truncateResult pattern from Ranger.
+     * Matches the TaskTool.truncateResult pattern used by host orchestrators.
      * @param result - The full result text
      * @param maxChars - Maximum allowed characters
      */
@@ -163,6 +194,20 @@ export declare class MultiAgentGraph extends StandardGraph {
      * Create a complete agent subgraph (similar to createReactAgent)
      */
     private createAgentSubgraph;
+    /**
+     * BFS from `rootAgentId` across sequence + transfer edges (NOT handoff edges).
+     * Returns the set of agents reachable in this agent's "local workflow".
+     */
+    private computeReachableViaNonHandoff;
+    /**
+     * Build a compiled scoped StateGraph containing `agentIds` as nodes, rooted
+     * at `rootAgentId`. Linear sequence edges where both endpoints are in scope
+     * are wired directly; nodes with no outgoing in-scope edges route to END.
+     *
+     * Each node is wrapped around the per-agent `createAgentNode` compiled
+     * workflow (agent + tools loop) to preserve isolated tool context.
+     */
+    private buildScopedSubgraph;
     /**
      * Detects if the current agent is receiving a handoff and processes the messages accordingly.
      * Returns filtered messages with the transfer tool call/message removed, plus any instructions,
@@ -176,22 +221,17 @@ export declare class MultiAgentGraph extends StandardGraph {
      * @returns Object with filtered messages, extracted instructions, source agent, and parallel siblings
      */
     /**
-     * Prepare messages for a handoff child agent.
-     *
-     * Handles two problems:
-     * 1. **Orphaned tool_use**: The parent's AI message contains a `tool_use` block
-     *    for the handoff tool itself, with no matching `tool_result`. Providers
-     *    (Bedrock/Anthropic) reject this.
-     * 2. **Paired tool_use/tool_result in history**: The child may not have the same
-     *    tools as the parent. Bedrock requires `toolConfig` when tool_use/tool_result
-     *    blocks exist in the message history. Compacting these into text summaries
-     *    avoids the requirement and reduces context bloat.
-     *
-     * Strategy:
-     * - Remove orphaned tool_use blocks (no matching tool_result)
-     * - Compact paired tool_use/tool_result interactions into text summaries
+     * Prepare messages for a handoff child agent. See
+     * {@link prepareHandoffMessagesUtil} for the full implementation and
+     * semantics — this static method is a thin delegate preserved for
+     * backward compatibility with existing call sites and unit tests.
      */
     static prepareHandoffMessages(messages: BaseMessage[]): BaseMessage[];
+    /**
+     * Build an isolated message context for a downstream scoped-subgraph
+     * node. See {@link prepareIsolatedChildMessagesUtil} for details.
+     */
+    static prepareIsolatedChildMessages(messages: BaseMessage[]): BaseMessage[];
     private processTransferReception;
     /**
      * Create the multi-agent workflow with handoffs, transfers, and sequences

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

@@ -1,2 +1,3 @@
 export * from './Graph';
 export * from './MultiAgentGraph';
+export * from './HandoffRegistry';

package/dist/types/graphs/phases/flushLoop.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Agentic tool-execution loop for the memory-flush reflection turn.
+ *
+ * Extracted from {@link runMemoryFlush} so the loop primitive is
+ * testable in isolation and reusable from any reflection-style phase
+ * that wants "invoke → execute tool_calls → feed results back → repeat".
+ *
+ * Design:
+ * - Bounded iterations — caller passes `maxIterations` (default
+ *   {@link DEFAULT_MAX_FLUSH_ITERATIONS}). The loop exits as soon as
+ *   the model stops emitting `tool_calls`, hits the cap, or the reply
+ *   matches {@link SILENT_REPLY_TOKEN}.
+ * - Rich result — returns iteration count, attempted/successful
+ *   appends, per-tool errors, silent-reply flag, and raw final text.
+ *   The caller logs this; nothing is swallowed.
+ * - Self-contained tool execution — does not depend on LangGraph's
+ *   ToolNode or any graph runtime. The only contract is the
+ *   LangChain v0.3 `StructuredToolInterface.invoke(args)` shape.
+ * - Tool errors are captured as {@link ToolMessage}s with the raw
+ *   JSON error, so the model can read them and self-correct (e.g.
+ *   retry with a different path if the schema rejected its first
+ *   attempt).
+ */
+import { AIMessage, type BaseMessage } from '@langchain/core/messages';
+import type { StructuredToolInterface } from '@langchain/core/tools';
+/** Minimal model contract the loop needs. */
+export interface InvokableModel {
+    invoke(messages: BaseMessage[], options?: any): Promise<AIMessage>;
+}
+export interface FlushLoopParams {
+    model: InvokableModel;
+    tools: StructuredToolInterface[];
+    /** Initial messages — typically [SystemMessage, HumanMessage]. */
+    initialMessages: BaseMessage[];
+    /** Upper bound on model.invoke() calls. Default 8. */
+    maxIterations?: number;
+    /**
+     * Optional debug hook — called once per iteration with `{ i, ai, toolCalls }`.
+     * Use for INFO-level tracing during rollout; pass `undefined` in prod.
+     */
+    onIteration?: (event: {
+        i: number;
+        ai: AIMessage;
+        toolCalls: ToolCallLike[];
+    }) => void;
+}
+/** Shape LangChain emits on AIMessage.tool_calls (duck-typed). */
+export interface ToolCallLike {
+    name: string;
+    args: Record<string, unknown>;
+    id?: string;
+}
+export interface ToolErrorRecord {
+    iteration: number;
+    toolName: string;
+    toolCallId?: string;
+    error: string;
+    /** Raw args the model passed — useful for diagnosing schema drift. */
+    args?: Record<string, unknown>;
+}
+export interface FlushLoopResult {
+    /** Number of model.invoke() calls actually made. */
+    iterations: number;
+    /** Every `memory_append` tool_call the model emitted across all iterations. */
+    appendsAttempted: number;
+    /** How many of those returned `{ ok: true, ... }`. */
+    appendsSucceeded: number;
+    /** Tool errors the model saw (and may have reacted to). */
+    toolErrors: ToolErrorRecord[];
+    /** True if the final AIMessage text matched {@link SILENT_REPLY_TOKEN}. */
+    silentReply: boolean;
+    /** Whether the loop stopped because it hit `maxIterations`. */
+    hitIterationCap: boolean;
+    /** Final AIMessage content as plain text (best-effort). */
+    finalText: string;
+    /** Full message transcript — useful for debugging / tests. */
+    messages: BaseMessage[];
+}
+/**
+ * Extract a flat text string from any AIMessage content shape
+ * (string, array of content blocks, etc).
+ */
+export declare function extractText(message: AIMessage): string;
+/**
+ * Parse a tool result string. Memory tools return JSON with
+ * `{ ok: boolean, error?: string, path?: string }`. Non-JSON payloads
+ * are treated as opaque success strings.
+ */
+export declare function parseToolResult(raw: string): {
+    ok: boolean;
+    error?: string;
+    path?: string;
+};
+/**
+ * Bind a tool array to a model if `bindTools` exists on the model.
+ * Exported so the caller (runMemoryFlush) can do it once and pass the
+ * bound model in, keeping this loop free of LangChain model-specific
+ * extensions.
+ */
+export declare function bindToolsIfSupported(model: any, tools: StructuredToolInterface[]): InvokableModel;
+/**
+ * Run the agentic reflection loop until the model stops emitting
+ * tool_calls, the iteration cap is hit, or the final reply matches
+ * {@link SILENT_REPLY_TOKEN}.
+ */
+export declare function runFlushLoop(params: FlushLoopParams): Promise<FlushLoopResult>;

package/dist/types/graphs/phases/memoryFlushPhase.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Memory flush phase — trigger logic + reflection invocation.
+ *
+ * Ported from upstream's post-turn flush handler. The agent is re-invoked
+ * with a reflection system prompt and the `memory_append` tool unlocked;
+ * it writes notes to its future self, then the graph returns to normal.
+ *
+ * This module is INTENTIONALLY decoupled from the specific graph runtime —
+ * it exposes pure functions (`shouldFlushMemory`) plus a runner that takes
+ * the model as a parameter, so the same logic works from `createAgentNode`,
+ * `MultiAgentGraph`, or a future graph backend that wants to override
+ * flush behaviour.
+ *
+ * The agentic tool-execution loop (invoke → run tool_calls → feed results
+ * back → repeat until stop) lives in {@link ./flushLoop}. This module wires
+ * it up: build tools, resolve prompts, flip the phase, call the loop,
+ * shape the rich result.
+ */
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { MEMORY_PHASE_FLUSHING, MEMORY_PHASE_NORMAL } from '@/memory/constants';
+import type { MemoryConfig } from '@/memory/types';
+import { type ToolErrorRecord } from './flushLoop';
+export interface ShouldFlushInput {
+    currentTokens: number;
+    windowTokens: number;
+    reserveFloorTokens?: number;
+    softThresholdTokens?: number;
+}
+/**
+ * Pure trigger function: fires when the current context is within
+ * `softThreshold + reserveFloor` tokens of the model window. Matches
+ * upstream's formula.
+ */
+export declare function shouldFlushMemory(input: ShouldFlushInput): boolean;
+export interface RunFlushParams {
+    model: BaseChatModel;
+    memory: MemoryConfig;
+    /** A compact summary of the conversation — last N turns, not raw history. */
+    conversationSummary: string;
+    /**
+     * Accessor the graph runtime uses to expose the current phase to the
+     * append tool. The runner sets this to `memory_flushing` for the duration
+     * of the reflection turn and restores it on exit.
+     */
+    setPhase: (phase: typeof MEMORY_PHASE_NORMAL | typeof MEMORY_PHASE_FLUSHING) => void;
+    /**
+     * @deprecated No longer used — the 8-path canonical-document model
+     * does not date-stamp files. Kept in the params shape for one release
+     * so host's callers don't break on the type signature.
+     */
+    timezone?: string;
+    /**
+     * @deprecated Same as `timezone` — unused in the canonical-document model.
+     */
+    nowMs?: number;
+    /** Override for the agentic-loop iteration cap. */
+    maxIterations?: number;
+    /**
+     * Optional per-iteration callback for structured debug logging.
+     * Caller is expected to demote this to debug once the rollout is stable.
+     */
+    onIteration?: (event: {
+        i: number;
+        toolCallCount: number;
+        toolNames: string[];
+    }) => void;
+}
+export interface RunFlushResult {
+    /** Did the flush actually run (false if disabled via config). */
+    ran: boolean;
+    /** Model.invoke() iterations actually performed. */
+    iterations?: number;
+    /** Total `memory_append` calls the model emitted. */
+    appendsAttempted?: number;
+    /** Subset that returned `{ ok: true }` from the backend. */
+    appendsSucceeded?: number;
+    /** Tool errors the model saw during the flush — surfaced for logging. */
+    toolErrors?: ToolErrorRecord[];
+    /** Final text reply equalled SILENT_REPLY_TOKEN (`NO_REPLY`). */
+    silentReply?: boolean;
+    /** Loop hit its iteration cap with tool_calls still pending. */
+    hitIterationCap?: boolean;
+    /** Final text reply from the last AIMessage. */
+    finalText?: string;
+    /** Error message if the flush threw. */
+    error?: string;
+}
+/**
+ * Run the reflection turn. The model is re-invoked with just the flush
+ * prompt + compact summary + the append tool unlocked. We intentionally
+ * drop the full history — the prompt tells the agent to write notes based
+ * on what it learned, not to continue the conversation.
+ *
+ * The loop keeps invoking the model until it stops emitting tool_calls,
+ * hits the iteration cap, or replies with {@link SILENT_REPLY_TOKEN}. Each
+ * `memory_append` tool_call is executed against the pgvector backend and
+ * the result (success path or error) is fed back as a ToolMessage so the
+ * model can self-correct (e.g. retry with a valid path).
+ */
+export declare function runMemoryFlush(params: RunFlushParams): Promise<RunFlushResult>;

package/dist/types/index.d.ts

@@ -15,6 +15,13 @@ export * from './tools/AskUser';
 export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/search';
+export * from './tools/memory';
+export * from './memory';
+export { MEMORY_FLUSH_SYSTEM_PROMPT } from './prompts/memoryFlushPrompt';
+export { shouldFlushMemory, runMemoryFlush, } from './graphs/phases/memoryFlushPhase';
+export type { RunFlushParams, RunFlushResult, } from './graphs/phases/memoryFlushPhase';
+export { runFlushLoop, bindToolsIfSupported, extractText as extractFlushText, parseToolResult as parseFlushToolResult, } from './graphs/phases/flushLoop';
+export type { FlushLoopParams, FlushLoopResult, ToolCallLike, ToolErrorRecord, } from './graphs/phases/flushLoop';
 export * from './schemas';
 export * from './nodes';
 export * from './common';

package/dist/types/memory/__tests__/mockBackend.d.ts

@@ -0,0 +1,40 @@
+/**
+ * In-memory mock implementation of {@link MemoryBackend} — for unit tests.
+ *
+ * Enforces the SAME invariants as the real pgvector store so behavior
+ * tests can run without Postgres:
+ *
+ *   - writes validate path + scope via `assertWritablePath`
+ *   - agent-tier paths store with `userId = null`
+ *   - user-tier paths store with the caller's `userId`
+ *   - reads apply the layered filter
+ *       agent_id = $scope.agentId
+ *       AND (user_id IS NULL OR user_id = $scope.userId)
+ *   - UPSERT key is `(agentId, userId, path)` with NULL collisions
+ *     (so `NULLS NOT DISTINCT` semantics are reproduced in-memory)
+ */
+import type { MemoryAppendInput, MemoryBackend, MemoryEntry, MemoryGetOptions, MemoryHealth, MemoryReadResult, MemoryScope, MemorySearchOptions } from '../types';
+interface Row {
+    id: string;
+    agentId: string;
+    /** null for agent-tier rows; caller id for user-tier rows. */
+    userId: string | null;
+    /** Latest writer — provenance, tracked even on agent-tier rows. */
+    lastUserId: string | null;
+    path: string;
+    content: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export declare class MockMemoryBackend implements MemoryBackend {
+    readonly kind: "vector";
+    private rows;
+    private seq;
+    search(scope: MemoryScope, query: string, opts?: MemorySearchOptions): Promise<MemoryEntry[]>;
+    get(scope: MemoryScope, opts: MemoryGetOptions): Promise<MemoryReadResult | null>;
+    append(scope: MemoryScope, input: MemoryAppendInput): Promise<void>;
+    health(): Promise<MemoryHealth>;
+    /** Test-only introspection. */
+    allRows(): readonly Row[];
+}
+export {};

package/dist/types/memory/citations.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Citation decoration — Phase 2.
+ *
+ * Ported from upstream `extensions/memory-core/src/tools.citations.ts`.
+ * Decorates memory_search hits with `[path#L{start}-L{end}]` markers so
+ * the model can attribute claims back to specific memory files when it
+ * uses them in its answer.
+ *
+ * Since our backend stores files as single rows (not line-chunked), we
+ * compute line ranges from the returned content block on the fly:
+ *   - `startLine` = 1 (line 1 of the file)
+ *   - `endLine`   = total number of lines in the block
+ * This matches upstream's output format exactly while keeping the pg
+ * schema chunk-free.
+ */
+export type MemoryCitationsMode = 'on' | 'off' | 'auto';
+export declare const DEFAULT_CITATIONS_MODE: MemoryCitationsMode;
+export declare function resolveMemoryCitationsMode(raw: string | undefined | null): MemoryCitationsMode;
+export interface CitationCandidate {
+    path: string;
+    content: string;
+    startLine?: number;
+    endLine?: number;
+    citation?: string;
+}
+/**
+ * Decorate each hit with a citation marker. Mirrors upstream's behavior:
+ * appends `\n\nSource: <citation>` to the content and sets `citation`.
+ * When `include=false`, clears any existing citation field.
+ */
+export declare function decorateCitations<T extends CitationCandidate>(hits: T[], include: boolean): T[];
+/**
+ * Whether citations should be emitted for this call.
+ *
+ * Upstream keys `auto` off the session type (direct/group/channel). In
+ * Phase 1 we only have direct chat, so `auto` => `on`. Callers that
+ * later distinguish session types can pass `mode` explicitly.
+ */
+export declare function shouldIncludeCitations(mode: MemoryCitationsMode): boolean;

package/dist/types/memory/compositeBackend.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Composite memory backend — the architectural seam for a future graph layer.
+ *
+ * Today, memory is pgvector only. Tomorrow, a Graphiti or Neo4j-agent-memory
+ * adapter can implement the same {@link MemoryBackend} interface and be
+ * composed with the vector store here — without touching the tool
+ * definitions, prompts, or host wiring.
+ *
+ * Fan-out strategy (simple on purpose for Phase 1):
+ * - `search`: query every backend in parallel, merge, dedupe by id, sort by
+ *   score, cap at maxResults. Graph hits and vector hits are interleaved by
+ *   score — the LLM sees one ranked list.
+ * - `get`: the vector store owns file paths; graph stores don't. First
+ *   backend that returns a non-null result wins. In practice this will almost
+ *   always be the vector store, since append paths live there.
+ * - `append`: fan out to every backend. Vector store persists the note,
+ *   graph backend runs its own extraction pipeline. An append failure in any
+ *   single backend is surfaced — we fail loud rather than silently dropping
+ *   writes.
+ */
+import type { MemoryAppendInput, MemoryBackend, MemoryEntry, MemoryGetOptions, MemoryHealth, MemoryReadResult, MemoryScope, MemorySearchOptions } from './types';
+export declare class CompositeMemoryBackend implements MemoryBackend {
+    readonly kind: "composite";
+    private readonly backends;
+    constructor(backends: MemoryBackend[]);
+    search(scope: MemoryScope, query: string, opts?: MemorySearchOptions): Promise<MemoryEntry[]>;
+    get(scope: MemoryScope, opts: MemoryGetOptions): Promise<MemoryReadResult | null>;
+    append(scope: MemoryScope, input: MemoryAppendInput): Promise<void>;
+    health(): Promise<MemoryHealth>;
+}

package/dist/types/memory/constants.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Autonomous memory — shared constants.
+ *
+ * Single source of truth for defaults, limits, and magic strings used across
+ * the memory store, tools, flush phase, and tests. Changing a value here
+ * changes it everywhere — no hunting through files.
+ */
+/** Default embedding provider when {@link process.env.MEMORY_EMBEDDINGS_PROVIDER} is unset. */
+export declare const DEFAULT_MEMORY_PROVIDER: "bedrock";
+/** Default embedding model (Titan v2 — AWS-native, 6× cheaper than Cohere v4). */
+export declare const DEFAULT_MEMORY_MODEL = "amazon.titan-embed-text-v2:0";
+/** Default vector width (Titan v2 supports 256 / 512 / 1024). */
+export declare const DEFAULT_MEMORY_DIMENSIONS = 1024;
+/** Default Postgres table name; can be overridden via env for dev/prod sharing. */
+export declare const DEFAULT_MEMORY_TABLE = "agent_memories";
+/** Default Postgres schema. */
+export declare const DEFAULT_MEMORY_SCHEMA = "public";
+/** Phase values used by the flush-phase gate. */
+export declare const MEMORY_PHASE_NORMAL = "normal";
+export declare const MEMORY_PHASE_FLUSHING = "memory_flushing";
+/**
+ * Search defaults — aligned with upstream's upstream defaults.
+ *
+ * Sources:
+ * - `upstream reference` → maxResults=6
+ * - `upstream reference` → maxInjectedChars=4000
+ *
+ * Keeping these in lockstep with upstream means the mandatory-recall tool
+ * description, budget clamps, and eval corpora line up with upstream's
+ * tuning — we inherit their calibration instead of re-tuning from scratch.
+ */
+export declare const DEFAULT_MAX_SEARCH_RESULTS = 6;
+export declare const DEFAULT_MIN_SCORE = 0.1;
+export declare const DEFAULT_MAX_INJECTED_CHARS = 4000;
+/** Hybrid retrieval weights — 70% vector cosine, 30% BM25 / ts_rank text score. */
+export declare const HYBRID_VECTOR_WEIGHT = 0.7;
+export declare const HYBRID_TEXT_WEIGHT = 0.3;
+/**
+ * Phase 2 rerank defaults — ported from upstream.
+ *
+ * Sources:
+ * - `upstream reference` → lambda=0.7
+ * - `upstream reference` → halfLifeDays=30
+ *
+ * Both features are opt-in (enabled=false by default) — the Phase 2
+ * features are layered on top of hybrid search and don't change default
+ * behavior for callers that upgrade in place.
+ */
+export declare const DEFAULT_MMR_ENABLED = false;
+export declare const DEFAULT_MMR_LAMBDA = 0.7;
+export declare const DEFAULT_TEMPORAL_DECAY_ENABLED = false;
+export declare const DEFAULT_TEMPORAL_DECAY_HALF_LIFE_DAYS = 30;
+export declare const DEFAULT_RECALL_TRACKING_ENABLED = false;
+export declare const DEFAULT_CITATIONS_MODE: "auto";
+/**
+ * Flush trigger margins (token counts) — aligned with upstream upstream.
+ *
+ * Sources:
+ * - `upstream reference` → softThreshold=4000
+ * - `upstream reference` → reserveFloor=20000
+ */
+export declare const DEFAULT_FLUSH_SOFT_THRESHOLD_TOKENS = 4000;
+export declare const DEFAULT_FLUSH_RESERVE_FLOOR_TOKENS = 20000;
+/** Hard cap on append calls per flush phase — prevents runaway writes. */
+export declare const DEFAULT_MAX_APPENDS_PER_FLUSH = 20;
+/**
+ * Hard cap on agentic loop iterations inside {@link runMemoryFlush}.
+ *
+ * Each iteration = one model.invoke() followed by execution of any
+ * `memory_append` tool_calls it emits. Mirrors upstream's flush-plan
+ * loop cap; 8 is enough for ~2–3 reflections of batched notes while
+ * protecting against runaway cycles if the model refuses to stop.
+ */
+export declare const DEFAULT_MAX_FLUSH_ITERATIONS = 8;
+/** Path prefix enforced on every append. Paths outside this are rejected. */
+export declare const MEMORY_PATH_PREFIX = "memory/";
+/** Tool names — kept as constants so server code + tests never drift. */
+export declare const MEMORY_SEARCH_TOOL_NAME = "memory_search";
+export declare const MEMORY_GET_TOOL_NAME = "memory_get";
+export declare const MEMORY_APPEND_TOOL_NAME = "memory_append";
+/**
+ * Mandatory-recall description — the single most load-bearing line in the
+ * whole memory system. Do not soften, shorten, or reword without an eval run.
+ *
+ * Ported VERBATIM from upstream `extensions/memory-core/src/tools.ts:186`.
+ * The wiki/corpus clause is retained even though Phase 1 doesn't ship
+ * compiled-wiki supplements — keeping the string identical means upstream's
+ * eval corpora remain drop-in valid.
+ */
+export declare const MEMORY_SEARCH_DESCRIPTION: string;
+/**
+ * Ported VERBATIM from upstream `extensions/memory-core/src/tools.ts:322`.
+ */
+export declare const MEMORY_GET_DESCRIPTION: string;
+/**
+ * `memory_append` tool description.
+ *
+ * Phase 1 historically wrote to a single date-keyed file
+ * (`memory/YYYY-MM-DD.md`), ported verbatim from upstream. That scheme
+ * is now replaced by an 8-path canonical whitelist — see
+ * {@link ./paths.MEMORY_ALL_PATHS}. The tool description no longer
+ * names a specific file; the flush-turn prompt renders the full rubric
+ * inline so the model sees every writable path at inference time.
+ */
+export declare const MEMORY_APPEND_DESCRIPTION: string;
+/**
+ * Reply token that signals the flush turn produced no user-visible output.
+ * Ported VERBATIM from upstream `src/auto-reply/tokens.ts:4`.
+ */
+export declare const SILENT_REPLY_TOKEN = "NO_REPLY";
+/**
+ * Placeholder replaced at flush time with the rendered path-rubric for
+ * the caller's scope. See `renderPathsRubric()` in `./paths.ts` and
+ * `resolveFlushPrompts()` in `../prompts/memoryFlushPrompt.ts`.
+ *
+ * Kept as a unique sentinel so `replaceAll` is safe even if the rubric
+ * content happens to contain regex metacharacters.
+ */
+export declare const FLUSH_PROMPT_RUBRIC_PLACEHOLDER = "{{MEMORY_PATHS_RUBRIC}}";
+export declare const DEFAULT_MEMORY_FLUSH_PROMPT: string;
+export declare const DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT: string;

package/dist/types/memory/embeddings.d.ts

@@ -0,0 +1,15 @@
+export type EmbeddingProviderKind = 'bedrock' | 'openai';
+export interface EmbeddingProvider {
+    readonly kind: EmbeddingProviderKind;
+    readonly model: string;
+    readonly dimensions: number;
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+}
+/**
+ * Lazy singleton accessor. Same idiom as host's
+ * `getSharedSummaryBedrockClient()`.
+ */
+export declare function getMemoryEmbedder(): EmbeddingProvider;
+/** Test hook — drops the cached embedder so the next call re-reads env. */
+export declare function resetMemoryEmbedder(): void;

package/dist/types/memory/factory.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Factory for building a memory backend from environment variables.
+ *
+ * Called once at startup by host's singleton (`api/server/services/memoryStore.js`).
+ * Returns `null` — never throws — when required env vars are missing, so
+ * agents with `memory_enabled=true` still run, just without memory. Host
+ * logs a single warning on boot instead of crashing.
+ */
+import { Pool } from 'pg';
+import { type RecallTracker } from './recallTracking';
+import type { MemoryBackend } from './types';
+export interface BuildMemoryBackendResult {
+    backend: MemoryBackend;
+    pool: Pool;
+    /** Phase 2 — shared recall tracker bound to the same pool/migration. */
+    recallTracker: RecallTracker;
+}
+/**
+ * Try to build a configured memory backend. Returns null when the required
+ * env vars are absent — caller should log a single "memory disabled" warning
+ * and continue. Never throws on missing config.
+ */
+export declare function buildMemoryBackendFromEnv(): Promise<BuildMemoryBackendResult | null>;

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

@@ -0,0 +1,21 @@
+/** Public entry point for the memory package. */
+export * from './types';
+export * from './constants';
+export * from './paths';
+export { PgvectorMemoryStore } from './pgvectorStore';
+export type { PgvectorStoreOptions } from './pgvectorStore';
+export { CompositeMemoryBackend } from './compositeBackend';
+export { getMemoryEmbedder, resetMemoryEmbedder } from './embeddings';
+export type { EmbeddingProvider, EmbeddingProviderKind } from './embeddings';
+export { runMemoryMigration } from './migrate';
+export type { MigrationOptions } from './migrate';
+export { buildMemoryBackendFromEnv } from './factory';
+export type { BuildMemoryBackendResult } from './factory';
+export { mmrRerank, applyMMRToMemoryHits, DEFAULT_MMR_CONFIG, tokenize, jaccardSimilarity, textSimilarity, computeMMRScore, } from './mmr';
+export type { MMRConfig, MMRItem } from './mmr';
+export { applyTemporalDecayToHits, applyTemporalDecayToScore, calculateTemporalDecayMultiplier, parseMemoryDateFromPath, isEvergreenMemoryPath, DEFAULT_TEMPORAL_DECAY_CONFIG, } from './temporalDecay';
+export type { TemporalDecayConfig, DecayCandidate } from './temporalDecay';
+export { decorateCitations, resolveMemoryCitationsMode, shouldIncludeCitations, } from './citations';
+export type { MemoryCitationsMode, CitationCandidate } from './citations';
+export { PgvectorRecallTracker, NullRecallTracker, RECALL_TABLE, } from './recallTracking';
+export type { RecallTracker, RecallRecordParams } from './recallTracking';

package/dist/types/memory/migrate.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Idempotent schema install + vector-dimension safety check.
+ *
+ * Called once at agents-library startup by host's `memoryStore.js` singleton
+ * factory. Safe to call multiple times — every statement is `IF NOT EXISTS`.
+ */
+import type { Pool } from 'pg';
+export interface MigrationOptions {
+    pool: Pool;
+    table?: string;
+    /** If true, skip the live embedder probe (tests). */
+    skipEmbedderProbe?: boolean;
+}
+export declare function runMemoryMigration(opts: MigrationOptions): Promise<void>;