hoomanjs 1.18.0 → 1.18.1

package/dist/core/memory/ltm/tools.d.ts

@@ -0,0 +1,21 @@
+import type { JSONValue } from "@strands-agents/sdk";
+import type { LongTermMemoryStore } from "./store.js";
+export declare function create(ltm: LongTermMemoryStore): (import("@strands-agents/sdk").InvokableTool<{
+    content: string;
+    type: "task" | "fact" | "preference" | "episodic" | "semantic";
+    importance?: number | undefined;
+    tags?: string[] | undefined;
+    entities?: string[] | undefined;
+}, JSONValue> | import("@strands-agents/sdk").InvokableTool<{
+    query: string;
+    types?: ("task" | "fact" | "preference" | "episodic" | "semantic")[] | undefined;
+    k?: number | undefined;
+}, JSONValue> | import("@strands-agents/sdk").InvokableTool<{
+    id: string;
+    content: string;
+    tags?: string[] | undefined;
+    entities?: string[] | undefined;
+}, JSONValue> | import("@strands-agents/sdk").InvokableTool<{
+    id: string;
+    reason?: string | undefined;
+}, JSONValue>)[];

package/dist/core/memory/ltm/tools.js

@@ -0,0 +1,127 @@
+import { tool } from "@strands-agents/sdk";
+import { z } from "zod";
+const StoreTypes = [
+    "fact",
+    "preference",
+    "task",
+];
+const SearchTypes = [
+    "fact",
+    "preference",
+    "task",
+    "episodic",
+    "semantic",
+];
+function toJsonValue(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function resolveScope(context) {
+    const userId = context?.agent.appState.get("userId");
+    if (typeof userId !== "string" || userId.trim().length === 0) {
+        throw new Error("Long-term memory tools require `userId` in agent appState.");
+    }
+    return { userId };
+}
+export function create(ltm) {
+    return [
+        tool({
+            name: "store_memory",
+            description: "Store important long-term memory. Only use for reusable facts, preferences, or tasks.",
+            inputSchema: z.object({
+                content: z.string().min(1).describe("Compressed memory content"),
+                type: z.enum(StoreTypes),
+                importance: z.number().min(0).max(1).optional(),
+                tags: z.array(z.string()).optional(),
+                entities: z.array(z.string()).optional(),
+            }),
+            callback: async (input, context) => {
+                const scope = resolveScope(context);
+                const result = await ltm.store({
+                    content: input.content,
+                    type: input.type,
+                    importance: input.importance,
+                    tags: input.tags,
+                    entities: input.entities,
+                    dedupe: true,
+                }, scope);
+                return toJsonValue({
+                    id: result.id,
+                    merged: result.merged,
+                    memory: result.memory,
+                });
+            },
+        }),
+        tool({
+            name: "search_memory",
+            description: "Search relevant past memory for context. Use only if additional context is needed.",
+            inputSchema: z.object({
+                query: z.string().min(1).describe("What to search for"),
+                types: z.array(z.enum(SearchTypes)).optional(),
+                k: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(20)
+                    .optional()
+                    .describe("Number of results (default 5, max 20)"),
+            }),
+            callback: async (input, context) => {
+                const scope = resolveScope(context);
+                const memories = await ltm.search({
+                    query: input.query,
+                    scope,
+                    types: input.types,
+                    limit: input.k,
+                    reinforce: true,
+                });
+                return toJsonValue({
+                    count: memories.length,
+                    memories,
+                });
+            },
+        }),
+        tool({
+            name: "update_memory",
+            description: "Update or correct an existing memory. Prefer this over deleting.",
+            inputSchema: z.object({
+                id: z.string().min(1),
+                content: z.string().min(1),
+                tags: z.array(z.string()).optional(),
+                entities: z.array(z.string()).optional(),
+            }),
+            callback: async (input) => {
+                const memory = await ltm.update({
+                    id: input.id,
+                    content: input.content,
+                    tags: input.tags,
+                    entities: input.entities,
+                });
+                return toJsonValue({
+                    id: memory.id,
+                    memory,
+                });
+            },
+        }),
+        tool({
+            name: "archive_memory",
+            description: "Mark memory as no longer relevant without deleting it.",
+            inputSchema: z.object({
+                id: z.string().min(1),
+                reason: z.string().optional(),
+            }),
+            callback: async (input) => {
+                const memory = await ltm.archive({
+                    id: input.id,
+                    status: "archived",
+                });
+                return toJsonValue({
+                    id: memory.id,
+                    status: memory.status,
+                    reason: input.reason ?? null,
+                    memory,
+                });
+            },
+        }),
+    ];
+}
+//# sourceMappingURL=tools.js.map

package/dist/core/memory/ltm/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../../../src/core/memory/ltm/tools.ts"],"names":[],"mappings":"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"}

package/dist/core/memory/ltm/types.d.ts

@@ -0,0 +1,79 @@
+export type MemoryStatus = "active" | "archived" | "superseded" | "deleted";
+export type MemoryType = "fact" | "preference" | "task" | "episodic" | "semantic";
+export interface Memory {
+    id: string;
+    userId: string;
+    type: MemoryType;
+    status: MemoryStatus;
+    content: string;
+    embedding?: number[];
+    metadata: {
+        createdAt: number;
+        updatedAt?: number;
+        lastAccessedAt?: number;
+        importance: number;
+        strength: number;
+        confidence?: number;
+        accessCount: number;
+        version: number;
+        source: "user" | "assistant" | "system" | "inferred";
+        tags?: string[];
+        entities?: string[];
+        supersededBy?: string;
+        relatedTo?: string[];
+    };
+}
+export type MemorySource = Memory["metadata"]["source"];
+export interface LongTermMemoryScope {
+    userId: string;
+}
+export interface LongTermMemoryOptions {
+    halfLifeMs?: number;
+    reinforcementStep?: number;
+    dedupeThreshold?: number;
+}
+export interface StoreMemoryInput {
+    content: string;
+    type: MemoryType;
+    importance?: number;
+    confidence?: number;
+    tags?: string[];
+    entities?: string[];
+    relatedTo?: string[];
+    source?: MemorySource;
+    dedupe?: boolean;
+}
+export interface SearchMemoryInput {
+    query: string;
+    scope: LongTermMemoryScope;
+    types?: MemoryType[];
+    limit?: number;
+    includeArchived?: boolean;
+    reinforce?: boolean;
+}
+export interface SearchMemoryResult extends Memory {
+    distance?: number | null;
+    effectiveStrength: number;
+}
+export interface UpdateMemoryInput {
+    id: string;
+    content: string;
+    type?: MemoryType;
+    status?: MemoryStatus;
+    importance?: number;
+    confidence?: number;
+    tags?: string[];
+    entities?: string[];
+    relatedTo?: string[];
+    supersededBy?: string;
+}
+export interface ArchiveMemoryInput {
+    id: string;
+    status?: Extract<MemoryStatus, "archived" | "superseded" | "deleted">;
+    supersededBy?: string;
+}
+export interface StoreMemoryResult {
+    id: string;
+    merged: boolean;
+    memory: Memory;
+}

package/dist/core/memory/ltm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/memory/ltm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/memory/ltm/types.ts"],"names":[],"mappings":""}

package/dist/core/memory/ltm/utils.d.ts

@@ -0,0 +1,40 @@
+import type { Where } from "chromadb";
+import type { LongTermMemoryScope, Memory, MemorySource, MemoryStatus, MemoryType } from "./types.js";
+export declare const DEFAULT_HALF_LIFE_MS: number;
+export declare const DEFAULT_REINFORCEMENT_STEP = 0.1;
+export declare const DEFAULT_DEDUPE_THRESHOLD = 0.92;
+export type ChromaMemoryMetadata = {
+    userId: string;
+    type: MemoryType;
+    status: MemoryStatus;
+    importance: number;
+    strength: number;
+    accessCount: number;
+    confidence: number | null;
+    createdAt: number;
+    updatedAt: number | null;
+    lastAccessedAt: number | null;
+    version: number;
+    source: MemorySource;
+    /** Omitted when empty: Chroma rejects `[]` for list metadata values. */
+    tags?: string[];
+    entities?: string[];
+    relatedTo?: string[];
+    supersededBy: string | null;
+};
+export declare function clampSearchLimit(limit?: number): number;
+export declare function clampUnitInterval(value: number, fallback: number): number;
+export declare function similarity(left: string, right: string): number;
+export declare function getEffectiveStrength(metadata: Pick<Memory["metadata"], "createdAt" | "lastAccessedAt" | "strength">, halfLifeMs: number): number;
+export declare function toChromaMetadata(memory: Memory): ChromaMemoryMetadata;
+export declare function toMemory(id: string, content: string, metadata: ChromaMemoryMetadata | null | undefined): Memory;
+export declare function buildWhere(scope: LongTermMemoryScope, options?: {
+    status?: MemoryStatus;
+    includeArchived?: boolean;
+    types?: MemoryType[];
+}): Where;
+export declare function chromaClientArgsFromUrl(urlString: string): {
+    host: string;
+    port?: number;
+    ssl: boolean;
+};

package/dist/core/memory/ltm/utils.js

@@ -0,0 +1,145 @@
+export const DEFAULT_HALF_LIFE_MS = 1000 * 60 * 60 * 24 * 30;
+export const DEFAULT_REINFORCEMENT_STEP = 0.1;
+export const DEFAULT_DEDUPE_THRESHOLD = 0.92;
+const DEFAULT_SEARCH_LIMIT = 5;
+const MAX_SEARCH_LIMIT = 20;
+export function clampSearchLimit(limit) {
+    const value = Math.trunc(limit ?? DEFAULT_SEARCH_LIMIT);
+    return Math.min(Math.max(value, 1), MAX_SEARCH_LIMIT);
+}
+export function clampUnitInterval(value, fallback) {
+    if (!Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.min(1, Math.max(0, value));
+}
+function asStringArray(value) {
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === "string");
+    }
+    if (typeof value === "string" && value.length > 0) {
+        return [value];
+    }
+    return undefined;
+}
+function normalizeText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s]/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+export function similarity(left, right) {
+    const a = normalizeText(left);
+    const b = normalizeText(right);
+    if (!a || !b) {
+        return 0;
+    }
+    if (a === b) {
+        return 1;
+    }
+    const shorter = a.length <= b.length ? a : b;
+    const longer = a.length > b.length ? a : b;
+    const containment = longer.includes(shorter)
+        ? shorter.length / longer.length
+        : 0;
+    const tokensA = new Set(a.split(" "));
+    const tokensB = new Set(b.split(" "));
+    let intersection = 0;
+    for (const token of tokensA) {
+        if (tokensB.has(token)) {
+            intersection += 1;
+        }
+    }
+    const union = new Set([...tokensA, ...tokensB]).size;
+    const jaccard = union === 0 ? 0 : intersection / union;
+    return Math.max(containment, jaccard);
+}
+export function getEffectiveStrength(metadata, halfLifeMs) {
+    const reference = metadata.lastAccessedAt ?? metadata.createdAt;
+    const age = Math.max(0, Date.now() - reference);
+    return metadata.strength * Math.exp(-age / halfLifeMs);
+}
+export function toChromaMetadata(memory) {
+    const tags = (memory.metadata.tags ?? []).filter((t) => t.length > 0);
+    const entities = (memory.metadata.entities ?? []).filter((t) => t.length > 0);
+    const relatedTo = (memory.metadata.relatedTo ?? []).filter((t) => t.length > 0);
+    const meta = {
+        userId: memory.userId,
+        type: memory.type,
+        status: memory.status,
+        importance: memory.metadata.importance,
+        strength: memory.metadata.strength,
+        accessCount: memory.metadata.accessCount,
+        confidence: memory.metadata.confidence ?? null,
+        createdAt: memory.metadata.createdAt,
+        updatedAt: memory.metadata.updatedAt ?? null,
+        lastAccessedAt: memory.metadata.lastAccessedAt ?? null,
+        version: memory.metadata.version,
+        source: memory.metadata.source,
+        supersededBy: memory.metadata.supersededBy ?? null,
+    };
+    if (tags.length > 0) {
+        meta.tags = tags;
+    }
+    if (entities.length > 0) {
+        meta.entities = entities;
+    }
+    if (relatedTo.length > 0) {
+        meta.relatedTo = relatedTo;
+    }
+    return meta;
+}
+export function toMemory(id, content, metadata) {
+    const createdAt = Number(metadata?.createdAt ?? Date.now());
+    return {
+        id,
+        userId: metadata?.userId ?? "",
+        type: (metadata?.type ?? "semantic"),
+        status: (metadata?.status ?? "active"),
+        content,
+        metadata: {
+            createdAt,
+            updatedAt: metadata?.updatedAt ?? undefined,
+            lastAccessedAt: metadata?.lastAccessedAt ?? undefined,
+            importance: clampUnitInterval(Number(metadata?.importance ?? 0.7), 0.7),
+            strength: Number(metadata?.strength ?? 0.5),
+            confidence: metadata?.confidence == null
+                ? undefined
+                : clampUnitInterval(Number(metadata.confidence), 1),
+            accessCount: Number(metadata?.accessCount ?? 0),
+            version: Number(metadata?.version ?? 1),
+            source: (metadata?.source ?? "assistant"),
+            tags: asStringArray(metadata?.tags),
+            entities: asStringArray(metadata?.entities),
+            supersededBy: metadata?.supersededBy ?? undefined,
+            relatedTo: asStringArray(metadata?.relatedTo),
+        },
+    };
+}
+export function buildWhere(scope, options) {
+    // Chroma v3: top-level `where` must have exactly one key (field predicate or $and/$or).
+    const parts = [{ userId: scope.userId }];
+    const statusFilter = options?.includeArchived
+        ? options.status
+        : (options?.status ?? "active");
+    if (statusFilter !== undefined) {
+        parts.push({ status: statusFilter });
+    }
+    if (options?.types?.length) {
+        parts.push({ type: { $in: options.types } });
+    }
+    if (parts.length === 1) {
+        return parts[0];
+    }
+    return { $and: parts };
+}
+export function chromaClientArgsFromUrl(urlString) {
+    const url = new URL(urlString);
+    return {
+        host: url.hostname,
+        port: url.port ? Number(url.port) : undefined,
+        ssl: url.protocol === "https:",
+    };
+}
+//# sourceMappingURL=utils.js.map

package/dist/core/memory/ltm/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../src/core/memory/ltm/utils.ts"],"names":[],"mappings":"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"}

package/dist/core/memory/stm/flat-file-storage.d.ts

@@ -0,0 +1,27 @@
+import type { Snapshot, SnapshotLocation, SnapshotManifest, SnapshotStorage } from "@strands-agents/sdk";
+/**
+ * Snapshot storage with a flat per-session layout:
+ * `<baseDir>/<sessionId>/snapshot_latest.json`.
+ */
+export declare class FlatFileStorage implements SnapshotStorage {
+    private readonly baseDir;
+    constructor(baseDir: string);
+    saveSnapshot(params: {
+        location: SnapshotLocation;
+        snapshotId: string;
+        isLatest: boolean;
+        snapshot: Snapshot;
+    }): Promise<void>;
+    loadSnapshot(params: {
+        location: SnapshotLocation;
+        snapshotId?: string;
+    }): Promise<Snapshot | null>;
+    listSnapshotIds(): Promise<string[]>;
+    deleteSession(params: {
+        sessionId: string;
+    }): Promise<void>;
+    loadManifest(): Promise<SnapshotManifest>;
+    saveManifest(): Promise<void>;
+    private sessionDir;
+    private snapshotPath;
+}

package/dist/core/memory/stm/flat-file-storage.js

@@ -0,0 +1,63 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Snapshot storage with a flat per-session layout:
+ * `<baseDir>/<sessionId>/snapshot_latest.json`.
+ */
+export class FlatFileStorage {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    async saveSnapshot(params) {
+        const path = this.snapshotPath(params.location, params.snapshotId);
+        await mkdir(join(this.sessionDir(params.location.sessionId)), {
+            recursive: true,
+        });
+        await writeFile(path, JSON.stringify(params.snapshot, null, 2), "utf8");
+    }
+    async loadSnapshot(params) {
+        const path = this.snapshotPath(params.location, params.snapshotId);
+        try {
+            const raw = await readFile(path, "utf8");
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async listSnapshotIds() {
+        // Flat storage only tracks one mutable snapshot.
+        return [];
+    }
+    async deleteSession(params) {
+        await rm(this.sessionDir(params.sessionId), {
+            recursive: true,
+            force: true,
+        });
+    }
+    async loadManifest() {
+        return {
+            schemaVersion: "1.0",
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    async saveManifest() {
+        // No-op: flat storage doesn't persist manifest metadata.
+    }
+    sessionDir(sessionId) {
+        return join(this.baseDir, sessionId);
+    }
+    snapshotPath(location, snapshotId) {
+        if (snapshotId && snapshotId !== "latest") {
+            return join(this.sessionDir(location.sessionId), `snapshot_${snapshotId}.json`);
+        }
+        return join(this.sessionDir(location.sessionId), "snapshot_latest.json");
+    }
+}
+//# sourceMappingURL=flat-file-storage.js.map

package/dist/core/memory/stm/flat-file-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat-file-storage.js","sourceRoot":"","sources":["../../../../src/core/memory/stm/flat-file-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC;;;GAGG;AACH,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAAG,CAAC;IAEhD,KAAK,CAAC,YAAY,CAAC,MAKlB;QACC,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QACnE,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE;YAC5D,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC;QACH,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,MAGlB;QACC,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACzC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAa,CAAC;QACrC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IACE,KAAK,YAAY,KAAK;gBACtB,MAAM,IAAI,KAAK;gBACf,KAAK,CAAC,IAAI,KAAK,QAAQ,EACvB,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,iDAAiD;QACjD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,MAA6B;QAC/C,MAAM,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE;YAC1C,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,OAAO;YACL,aAAa,EAAE,KAAK;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,yDAAyD;IAC3D,CAAC;IAEO,UAAU,CAAC,SAAiB;QAClC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACvC,CAAC;IAEO,YAAY,CAClB,QAA0B,EAC1B,UAAmB;QAEnB,IAAI,UAAU,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;YAC1C,OAAO,IAAI,CACT,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EACnC,YAAY,UAAU,OAAO,CAC9B,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC,CAAC;IAC3E,CAAC;CACF"}

package/dist/core/memory/stm/index.d.ts

@@ -0,0 +1,13 @@
+import { SessionManager, SummarizingConversationManager } from "@strands-agents/sdk";
+import { LazySessionManager } from "./lazy-session-manager.js";
+export declare function create(sessionId?: string): {
+    plugins: LazySessionManager[];
+    conversationManager: SummarizingConversationManager;
+    sessionManager?: undefined;
+} | {
+    sessionManager: SessionManager;
+    conversationManager: SummarizingConversationManager;
+    plugins?: undefined;
+};
+export { LazySessionManager } from "./lazy-session-manager.js";
+export type { LazySessionManagerConfig } from "./lazy-session-manager.js";

package/dist/core/memory/stm/index.js

@@ -0,0 +1,24 @@
+import { SessionManager, SummarizingConversationManager, } from "@strands-agents/sdk";
+import { sessionsPath } from "../../utils/paths.js";
+import { FlatFileStorage } from "./flat-file-storage.js";
+import { LazySessionManager } from "./lazy-session-manager.js";
+export function create(sessionId) {
+    const conversationManager = new SummarizingConversationManager({
+        summaryRatio: 0.5,
+        preserveRecentMessages: 5,
+    });
+    const storage = new FlatFileStorage(sessionsPath());
+    if (!sessionId) {
+        return {
+            plugins: [new LazySessionManager({ storage })],
+            conversationManager,
+        };
+    }
+    const sessionManager = new SessionManager({
+        sessionId,
+        storage: { snapshot: storage },
+    });
+    return { sessionManager, conversationManager };
+}
+export { LazySessionManager } from "./lazy-session-manager.js";
+//# sourceMappingURL=index.js.map

package/dist/core/memory/stm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/memory/stm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,8BAA8B,GAC/B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,MAAM,UAAU,MAAM,CAAC,SAAkB;IACvC,MAAM,mBAAmB,GAAG,IAAI,8BAA8B,CAAC;QAC7D,YAAY,EAAE,GAAG;QACjB,sBAAsB,EAAE,CAAC;KAC1B,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC,YAAY,EAAE,CAAC,CAAC;IAEpD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO;YACL,OAAO,EAAE,CAAC,IAAI,kBAAkB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;YAC9C,mBAAmB;SACpB,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,GAAG,IAAI,cAAc,CAAC;QACxC,SAAS;QACT,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE;KAC/B,CAAC,CAAC;IAEH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,CAAC;AACjD,CAAC;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/core/memory/stm/lazy-session-manager.d.ts

@@ -0,0 +1,37 @@
+import { type LocalAgent, type Plugin, type SnapshotStorage } from "@strands-agents/sdk";
+export type LazySessionManagerConfig = {
+    /** Pluggable snapshot backend (e.g. `FileStorage`). */
+    storage: SnapshotStorage;
+    /** Fallback session id when `appState` does not provide one. Defaults to `"default-session"`. */
+    defaultSessionId?: string;
+    /** `appState` key used to derive the active session id. Defaults to `"sessionId"`. */
+    appStateKey?: string;
+    /** Scope id passed through to the storage backend. Defaults to `"agent"`. */
+    scopeId?: string;
+};
+/**
+ * Short-term memory plugin that resolves the active session id at invocation
+ * time from `agent.appState` instead of binding it once at construction.
+ *
+ * Designed for long-lived agents that fan out to many independent
+ * conversations (e.g. a daemon routing notifications from multiple chat
+ * channels). Persistence is delegated to a `SnapshotStorage` so any backend
+ * (filesystem, S3, custom) works.
+ */
+export declare class LazySessionManager implements Plugin {
+    private readonly storage;
+    private readonly defaultSessionId;
+    private readonly appStateKey;
+    private readonly scopeId;
+    constructor(config: LazySessionManagerConfig);
+    get name(): string;
+    initAgent(agent: LocalAgent): void;
+    /** Removes the persisted history for the given session, if present. */
+    deleteSession(sessionId: string): Promise<void>;
+    private location;
+    private resolveSessionId;
+    private restore;
+    private save;
+    private captureRuntimeState;
+    private restoreRuntimeState;
+}