@agents-eco/agentic-memory 0.1.0

package/dist/ltm.js

@@ -0,0 +1,144 @@
+import { Graph } from "./graph.js";
+const DEFAULT_LTM_CONFIG = {
+    decayRate: 0.01,
+    minImportance: 0.1,
+    maxNodes: 10000,
+};
+/**
+ * Long-Term Memory (LTM) — persistent graph-based memory.
+ *
+ * Stores memories as nodes in a graph with typed relationships.
+ * Supports decay (forgetting), reinforcement (remembering), and
+ * hybrid search (vector + keyword + graph traversal).
+ */
+export class LongTermMemory {
+    graph;
+    config;
+    constructor(config, embedding) {
+        this.config = { ...DEFAULT_LTM_CONFIG, ...config };
+        this.graph = new Graph(embedding);
+    }
+    setEmbeddingBackend(backend) {
+        this.graph.setEmbeddingBackend(backend);
+    }
+    // ── Store ───────────────────────────────────────────
+    /** Add a memory to LTM */
+    async add(content, type, importance = 0.5, metadata = {}) {
+        // Enforce max nodes — remove least important if at capacity
+        if (this.graph.getNodeCount() >= this.config.maxNodes) {
+            this.pruneWeakest(Math.floor(this.config.maxNodes * 0.1));
+        }
+        return this.graph.addNode(content, type, importance, metadata);
+    }
+    /** Create a relationship between two memories */
+    link(sourceId, targetId, relation, weight = 0.5) {
+        return this.graph.addEdge(sourceId, targetId, relation, weight);
+    }
+    /** Store a fact — semantic memory with entity extraction */
+    async addFact(content, entities = [], importance = 0.6) {
+        const factNode = await this.add(content, "semantic", importance);
+        const entityNodes = [];
+        for (const entity of entities) {
+            // Check if entity already exists
+            const existing = this.findEntity(entity);
+            if (existing) {
+                this.graph.addEdge(factNode.id, existing.id, "mentioned_in");
+                this.graph.reinforceNode(existing.id);
+                entityNodes.push(existing);
+            }
+            else {
+                const entityNode = await this.add(entity, "entity", 0.4);
+                this.graph.addEdge(factNode.id, entityNode.id, "mentioned_in");
+                entityNodes.push(entityNode);
+            }
+        }
+        return { node: factNode, entityNodes };
+    }
+    /** Store an episode — episodic memory from a conversation turn */
+    async addEpisode(content, importance = 0.5, previousEpisodeId) {
+        const node = await this.add(content, "episodic", importance);
+        if (previousEpisodeId) {
+            this.graph.addEdge(previousEpisodeId, node.id, "leads_to", 0.8);
+        }
+        return node;
+    }
+    /** Store an observation */
+    async addObservation(content, importance = 0.5) {
+        return this.add(content, "observation", importance);
+    }
+    /** Store a goal */
+    async addGoal(content, importance = 0.8) {
+        return this.add(content, "goal", importance);
+    }
+    // ── Retrieve ────────────────────────────────────────
+    /** Search LTM with hybrid search */
+    async search(query, options) {
+        return this.graph.search(query, options);
+    }
+    /** Get a specific memory by ID */
+    get(id) {
+        return this.graph.getNode(id);
+    }
+    /** Get all memories of a specific type */
+    getByType(type) {
+        return this.graph.getAllNodes().filter((n) => n.type === type);
+    }
+    /** Get related memories via graph traversal */
+    getRelated(nodeId, depth = 2) {
+        return this.graph.traverse(nodeId, depth).filter((n) => n.id !== nodeId);
+    }
+    /** Get neighbors of a node with a specific relation */
+    getNeighbors(nodeId, relation) {
+        return this.graph.getNeighbors(nodeId, relation);
+    }
+    /** Find an entity node by name (case-insensitive) */
+    findEntity(name) {
+        const lower = name.toLowerCase();
+        return this.graph
+            .getAllNodes()
+            .find((n) => n.type === "entity" && n.content.toLowerCase() === lower);
+    }
+    // ── Maintenance ─────────────────────────────────────
+    /** Apply decay to all memories */
+    decay() {
+        return this.graph.applyDecay(this.config.decayRate, this.config.minImportance);
+    }
+    /** Reinforce a memory (accessed/recalled) */
+    reinforce(id, boost = 0.05) {
+        this.graph.reinforceNode(id, boost);
+    }
+    /** Remove a memory */
+    remove(id) {
+        return this.graph.removeNode(id);
+    }
+    /** Get graph statistics */
+    stats() {
+        const nodes = this.graph.getAllNodes();
+        const byType = {};
+        for (const n of nodes) {
+            byType[n.type] = (byType[n.type] ?? 0) + 1;
+        }
+        return {
+            nodes: this.graph.getNodeCount(),
+            edges: this.graph.getEdgeCount(),
+            byType,
+        };
+    }
+    // ── Serialization ───────────────────────────────────
+    getState() {
+        return this.graph.getState();
+    }
+    loadState(nodes, edges) {
+        this.graph.loadState(nodes, edges);
+    }
+    // ── Private ─────────────────────────────────────────
+    pruneWeakest(count) {
+        const nodes = this.graph
+            .getAllNodes()
+            .sort((a, b) => a.importance - b.importance);
+        for (let i = 0; i < Math.min(count, nodes.length); i++) {
+            this.graph.removeNode(nodes[i].id);
+        }
+    }
+}
+//# sourceMappingURL=ltm.js.map

package/dist/ltm.js.map

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

package/dist/manager.d.ts

@@ -0,0 +1,92 @@
+import { ShortTermMemory } from "./stm.js";
+import { LongTermMemory } from "./ltm.js";
+import type { AgenticMemoryConfig, MemoryNode, MemoryNodeType, MemoryRelation, SearchResult, SearchOptions, STMEntry } from "./types.js";
+/**
+ * AgenticMemory — unified memory manager combining STM and LTM.
+ *
+ * Handles:
+ * - Adding memories to STM (working context)
+ * - Consolidating important STM entries into LTM (graph)
+ * - Hybrid search across both STM and LTM
+ * - Automatic persistence via storage backend
+ * - Decay and reinforcement of LTM nodes
+ *
+ * Usage:
+ * ```ts
+ * // Local backend (no API key needed)
+ * const memory = new AgenticMemory({ backend: "local" });
+ *
+ * // Voyage AI backend (high-quality embeddings)
+ * const memory = new AgenticMemory({ backend: "voyage", voyageApiKey: "pa-..." });
+ *
+ * await memory.add("User's name is Alice", "semantic", 0.8);
+ * const results = await memory.search("What is the user's name?");
+ * ```
+ */
+export declare class AgenticMemory {
+    readonly stm: ShortTermMemory;
+    readonly ltm: LongTermMemory;
+    private embedding;
+    private storage;
+    private config;
+    private loaded;
+    private lastEpisodeId;
+    constructor(config: AgenticMemoryConfig);
+    /** Load persisted graph from storage */
+    load(): Promise<void>;
+    /** Save current state to storage */
+    save(): Promise<void>;
+    /**
+     * Add a memory. Goes to STM first, then consolidates to LTM based on importance.
+     * High-importance items (>= 0.6) are immediately added to LTM as well.
+     */
+    add(content: string, type?: MemoryNodeType, importance?: number, metadata?: Record<string, unknown>): Promise<{
+        stmEntry: STMEntry;
+        ltmNode?: MemoryNode;
+    }>;
+    /** Add a conversation turn (episodic memory with temporal linking) */
+    addEpisode(content: string, importance?: number): Promise<{
+        stmEntry: STMEntry;
+        ltmNode: MemoryNode;
+    }>;
+    /** Add a fact with entity extraction */
+    addFact(content: string, entities?: string[], importance?: number): Promise<{
+        node: MemoryNode;
+        entityNodes: MemoryNode[];
+    }>;
+    /** Add an observation */
+    addObservation(content: string, importance?: number): Promise<MemoryNode>;
+    /** Add a goal */
+    addGoal(content: string, importance?: number): Promise<MemoryNode>;
+    /** Create a relationship between two LTM nodes */
+    link(sourceId: string, targetId: string, relation: MemoryRelation, weight?: number): import("./types.js").MemoryEdge | null;
+    /**
+     * Search across both STM and LTM.
+     * STM results are boosted by recency, LTM results by graph connectivity.
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Get recent context from STM */
+    getRecentContext(n?: number): STMEntry[];
+    /** Build a context string suitable for injection into a system prompt */
+    buildContext(query?: string): Promise<string>;
+    /**
+     * Consolidate STM into LTM.
+     * Moves important STM entries into the LTM graph and creates relationships.
+     */
+    consolidate(minImportance?: number): Promise<number>;
+    /** Apply decay to LTM (call periodically) */
+    decay(): Promise<string[]>;
+    /** Get memory statistics */
+    stats(): {
+        stm: number;
+        ltm: {
+            nodes: number;
+            edges: number;
+            byType: Record<string, number>;
+        };
+    };
+    /** Clear all memory (STM + LTM) */
+    clear(): Promise<void>;
+    private ensureLoaded;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI1C,OAAO,KAAK,EACV,mBAAmB,EAGnB,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,aAAa,EACb,QAAQ,EAET,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa;IACxB,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAAqB;gBAE9B,MAAM,EAAE,mBAAmB;IAyBvC,wCAAwC;IAClC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B,oCAAoC;IAC9B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB3B;;;OAGG;IACG,GAAG,CACP,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,cAA2B,EACjC,UAAU,GAAE,MAAY,EACxB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC;IAexD,sEAAsE;IAChE,UAAU,CACd,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,MAAY,GACvB,OAAO,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC;IAUvD,wCAAwC;IAClC,OAAO,CACX,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,EAAO,EACvB,UAAU,GAAE,MAAY,GACvB,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;IAO3D,yBAAyB;IACnB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAOpF,iBAAiB;IACX,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY,GAAG,OAAO,CAAC,UAAU,CAAC;IAO7E,kDAAkD;IAClD,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM;IAMlF;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAqD7E,kCAAkC;IAClC,gBAAgB,CAAC,CAAC,GAAE,MAAU,GAAG,QAAQ,EAAE;IAI3C,yEAAyE;IACnE,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgCnD;;;OAGG;IACG,WAAW,CAAC,aAAa,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IA4C/D,6CAA6C;IACvC,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAShC,4BAA4B;IAC5B,KAAK,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;SAAE,CAAA;KAAE;IAO/F,mCAAmC;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YASd,YAAY;CAK3B"}

package/dist/manager.js

@@ -0,0 +1,284 @@
+import { ShortTermMemory } from "./stm.js";
+import { LongTermMemory } from "./ltm.js";
+import { LocalEmbedding } from "./embeddings/local.js";
+import { VoyageEmbedding } from "./embeddings/voyage.js";
+import { LocalStorage } from "./storage/local.js";
+/**
+ * AgenticMemory — unified memory manager combining STM and LTM.
+ *
+ * Handles:
+ * - Adding memories to STM (working context)
+ * - Consolidating important STM entries into LTM (graph)
+ * - Hybrid search across both STM and LTM
+ * - Automatic persistence via storage backend
+ * - Decay and reinforcement of LTM nodes
+ *
+ * Usage:
+ * ```ts
+ * // Local backend (no API key needed)
+ * const memory = new AgenticMemory({ backend: "local" });
+ *
+ * // Voyage AI backend (high-quality embeddings)
+ * const memory = new AgenticMemory({ backend: "voyage", voyageApiKey: "pa-..." });
+ *
+ * await memory.add("User's name is Alice", "semantic", 0.8);
+ * const results = await memory.search("What is the user's name?");
+ * ```
+ */
+export class AgenticMemory {
+    stm;
+    ltm;
+    embedding;
+    storage;
+    config;
+    loaded = false;
+    lastEpisodeId;
+    constructor(config) {
+        this.config = config;
+        // Initialize embedding backend
+        if (config.embedding) {
+            this.embedding = config.embedding;
+        }
+        else if (config.backend === "voyage") {
+            if (!config.voyageApiKey) {
+                throw new Error("voyageApiKey is required when backend is 'voyage'");
+            }
+            this.embedding = new VoyageEmbedding(config.voyageApiKey, config.voyageModel);
+        }
+        else {
+            this.embedding = new LocalEmbedding();
+        }
+        // Initialize storage backend
+        this.storage = config.storage ?? new LocalStorage(config.storageDir, config.namespace);
+        // Initialize STM and LTM
+        this.stm = new ShortTermMemory(config.stm);
+        this.ltm = new LongTermMemory(config.ltm, this.embedding);
+    }
+    // ── Load / Save ─────────────────────────────────────
+    /** Load persisted graph from storage */
+    async load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        const data = await this.storage.load();
+        if (data) {
+            this.ltm.loadState(data.nodes, data.edges);
+            if (data.stm) {
+                this.stm.load(data.stm);
+            }
+        }
+    }
+    /** Save current state to storage */
+    async save() {
+        const { nodes, edges } = this.ltm.getState();
+        const stm = this.stm.serialize();
+        const serialized = {
+            nodes,
+            edges,
+            stm,
+            metadata: {
+                version: "0.1.0",
+                savedAt: new Date().toISOString(),
+                nodeCount: nodes.length,
+                edgeCount: edges.length,
+            },
+        };
+        await this.storage.save(serialized);
+    }
+    // ── Add Memories ────────────────────────────────────
+    /**
+     * Add a memory. Goes to STM first, then consolidates to LTM based on importance.
+     * High-importance items (>= 0.6) are immediately added to LTM as well.
+     */
+    async add(content, type = "episodic", importance = 0.5, metadata = {}) {
+        await this.ensureLoaded();
+        // Always add to STM
+        const stmEntry = this.stm.add(content, type, importance, metadata);
+        // High-importance items go directly to LTM too
+        let ltmNode;
+        if (importance >= 0.6) {
+            ltmNode = await this.ltm.add(content, type, importance, metadata);
+        }
+        return { stmEntry, ltmNode };
+    }
+    /** Add a conversation turn (episodic memory with temporal linking) */
+    async addEpisode(content, importance = 0.5) {
+        await this.ensureLoaded();
+        const stmEntry = this.stm.add(content, "episodic", importance);
+        const ltmNode = await this.ltm.addEpisode(content, importance, this.lastEpisodeId);
+        this.lastEpisodeId = ltmNode.id;
+        return { stmEntry, ltmNode };
+    }
+    /** Add a fact with entity extraction */
+    async addFact(content, entities = [], importance = 0.6) {
+        await this.ensureLoaded();
+        this.stm.add(content, "semantic", importance);
+        return this.ltm.addFact(content, entities, importance);
+    }
+    /** Add an observation */
+    async addObservation(content, importance = 0.5) {
+        await this.ensureLoaded();
+        this.stm.add(content, "observation", importance);
+        return this.ltm.addObservation(content, importance);
+    }
+    /** Add a goal */
+    async addGoal(content, importance = 0.8) {
+        await this.ensureLoaded();
+        this.stm.add(content, "goal", importance);
+        return this.ltm.addGoal(content, importance);
+    }
+    /** Create a relationship between two LTM nodes */
+    link(sourceId, targetId, relation, weight) {
+        return this.ltm.link(sourceId, targetId, relation, weight);
+    }
+    // ── Search / Retrieve ───────────────────────────────
+    /**
+     * Search across both STM and LTM.
+     * STM results are boosted by recency, LTM results by graph connectivity.
+     */
+    async search(query, options) {
+        await this.ensureLoaded();
+        const limit = options?.limit ?? 5;
+        // Search LTM (graph-based)
+        const ltmResults = await this.ltm.search(query, {
+            ...options,
+            limit: limit + 5, // fetch extra for merging
+        });
+        // Search STM (keyword-based)
+        const stmEntries = this.stm.search(query, limit);
+        const stmResults = stmEntries.map((entry) => ({
+            node: {
+                id: entry.id,
+                content: entry.content,
+                type: entry.type,
+                importance: entry.importance,
+                accessCount: 0,
+                lastAccessed: entry.createdAt,
+                createdAt: entry.createdAt,
+                metadata: { ...entry.metadata, source: "stm" },
+            },
+            score: entry.importance + 0.3, // STM recency boost
+            method: "keyword",
+        }));
+        // Merge and deduplicate (prefer LTM if same content)
+        const seen = new Set();
+        const merged = [];
+        // Interleave: STM first (more recent), then LTM
+        for (const r of stmResults) {
+            const key = r.node.content.slice(0, 100).toLowerCase();
+            if (!seen.has(key)) {
+                seen.add(key);
+                merged.push(r);
+            }
+        }
+        for (const r of ltmResults) {
+            const key = r.node.content.slice(0, 100).toLowerCase();
+            if (!seen.has(key)) {
+                seen.add(key);
+                merged.push(r);
+            }
+        }
+        return merged
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+    }
+    /** Get recent context from STM */
+    getRecentContext(n = 5) {
+        return this.stm.getRecent(n);
+    }
+    /** Build a context string suitable for injection into a system prompt */
+    async buildContext(query) {
+        await this.ensureLoaded();
+        const parts = [];
+        // STM context
+        const stmContext = this.stm.buildContext();
+        if (stmContext) {
+            parts.push(stmContext);
+        }
+        // LTM context (if query provided, search; otherwise get recent important)
+        if (query) {
+            const ltmResults = await this.ltm.search(query, { limit: 5, includeRelated: true });
+            if (ltmResults.length > 0) {
+                const lines = ltmResults.map((r) => {
+                    let line = `- [${r.node.type}] ${r.node.content}`;
+                    if (r.related && r.related.length > 0) {
+                        const relatedStr = r.related.map((n) => n.content).join("; ");
+                        line += ` (related: ${relatedStr})`;
+                    }
+                    return line;
+                });
+                parts.push(`Long-term memories:\n${lines.join("\n")}`);
+            }
+        }
+        return parts.join("\n\n");
+    }
+    // ── Consolidation ───────────────────────────────────
+    /**
+     * Consolidate STM into LTM.
+     * Moves important STM entries into the LTM graph and creates relationships.
+     */
+    async consolidate(minImportance = 0.4) {
+        await this.ensureLoaded();
+        const candidates = this.stm.getConsolidationCandidates(minImportance);
+        if (candidates.length === 0)
+            return 0;
+        let consolidated = 0;
+        const consolidatedIds = new Set();
+        let prevNodeId;
+        for (const entry of candidates) {
+            // Check if similar content already exists in LTM
+            const existing = await this.ltm.search(entry.content, { limit: 1, minScore: 0.85 });
+            if (existing.length > 0) {
+                // Reinforce existing memory instead of duplicating
+                this.ltm.reinforce(existing[0].node.id, 0.1);
+                consolidatedIds.add(entry.id);
+                continue;
+            }
+            // Add to LTM
+            const node = await this.ltm.add(entry.content, entry.type, entry.importance, entry.metadata);
+            // Link sequential entries
+            if (prevNodeId) {
+                this.ltm.link(prevNodeId, node.id, "leads_to", 0.6);
+            }
+            prevNodeId = node.id;
+            consolidatedIds.add(entry.id);
+            consolidated++;
+        }
+        // Remove consolidated entries from STM
+        this.stm.remove(consolidatedIds);
+        // Auto-save after consolidation
+        await this.save();
+        return consolidated;
+    }
+    // ── Maintenance ─────────────────────────────────────
+    /** Apply decay to LTM (call periodically) */
+    async decay() {
+        await this.ensureLoaded();
+        const removed = this.ltm.decay();
+        if (removed.length > 0) {
+            await this.save();
+        }
+        return removed;
+    }
+    /** Get memory statistics */
+    stats() {
+        return {
+            stm: this.stm.size(),
+            ltm: this.ltm.stats(),
+        };
+    }
+    /** Clear all memory (STM + LTM) */
+    async clear() {
+        this.stm.clear();
+        this.ltm.loadState([], []);
+        this.lastEpisodeId = undefined;
+        await this.save();
+    }
+    // ── Private ─────────────────────────────────────────
+    async ensureLoaded() {
+        if (!this.loaded) {
+            await this.load();
+        }
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/manager.js.map

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

package/dist/stm.d.ts

@@ -0,0 +1,40 @@
+import type { STMConfig, STMEntry, MemoryNodeType } from "./types.js";
+/**
+ * Short-Term Memory (STM) — the agent's working context.
+ *
+ * Holds recent, high-relevance items in a bounded buffer.
+ * Items decay and get evicted based on TTL and capacity.
+ * Important items are promoted to LTM during consolidation.
+ */
+export declare class ShortTermMemory {
+    private entries;
+    private config;
+    constructor(config?: Partial<STMConfig>);
+    /** Add an entry to STM */
+    add(content: string, type?: MemoryNodeType, importance?: number, metadata?: Record<string, unknown>): STMEntry;
+    /** Get all current STM entries */
+    getAll(): STMEntry[];
+    /** Get entries above an importance threshold */
+    getImportant(minImportance?: number): STMEntry[];
+    /** Get the most recent N entries */
+    getRecent(n?: number): STMEntry[];
+    /** Search STM by keyword */
+    search(query: string, limit?: number): STMEntry[];
+    /** Get entries ready for consolidation to LTM (important + accessed enough) */
+    getConsolidationCandidates(minImportance?: number): STMEntry[];
+    /** Remove specific entries (after consolidation to LTM) */
+    remove(ids: Set<string>): void;
+    /** Clear all STM entries */
+    clear(): void;
+    /** Get current size */
+    size(): number;
+    /** Build a context string from STM for injection into prompts */
+    buildContext(): string;
+    /** Serialize STM for persistence */
+    serialize(): STMEntry[];
+    /** Load STM from serialized data */
+    load(entries: STMEntry[]): void;
+    private pruneExpired;
+    private evict;
+}
+//# sourceMappingURL=stm.d.ts.map

package/dist/stm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stm.d.ts","sourceRoot":"","sources":["../src/stm.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOtE;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,MAAM,CAAY;gBAEd,MAAM,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC;IAIvC,0BAA0B;IAC1B,GAAG,CACD,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,cAA2B,EACjC,UAAU,GAAE,MAAY,EACxB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,QAAQ;IAoBX,kCAAkC;IAClC,MAAM,IAAI,QAAQ,EAAE;IAKpB,gDAAgD;IAChD,YAAY,CAAC,aAAa,GAAE,MAAY,GAAG,QAAQ,EAAE;IAKrD,oCAAoC;IACpC,SAAS,CAAC,CAAC,GAAE,MAAU,GAAG,QAAQ,EAAE;IAKpC,4BAA4B;IAC5B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,QAAQ,EAAE;IAoBpD,+EAA+E;IAC/E,0BAA0B,CAAC,aAAa,GAAE,MAAY,GAAG,QAAQ,EAAE;IAInE,2DAA2D;IAC3D,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI;IAI9B,4BAA4B;IAC5B,KAAK,IAAI,IAAI;IAIb,uBAAuB;IACvB,IAAI,IAAI,MAAM;IAKd,iEAAiE;IACjE,YAAY,IAAI,MAAM;IAQtB,oCAAoC;IACpC,SAAS,IAAI,QAAQ,EAAE;IAIvB,oCAAoC;IACpC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAI;IAO/B,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,KAAK;CAYd"}