@aigne/core 1.72.0-beta.2 → 1.72.0-beta.23

package/lib/cjs/prompt/compact/compactor.d.ts

@@ -0,0 +1,7 @@
+import { AIAgent, type AIAgentOptions } from "../../agents/ai-agent.js";
+import type { CompactContent, CompactorInput } from "./types.js";
+export interface CreateCompactorOptions extends AIAgentOptions<CompactorInput, CompactContent> {
+}
+export declare class AISessionCompactor extends AIAgent<CompactorInput, CompactContent> {
+    constructor(options?: CreateCompactorOptions);
+}

package/lib/cjs/prompt/compact/compactor.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AISessionCompactor = void 0;
+const zod_1 = require("zod");
+const ai_agent_js_1 = require("../../agents/ai-agent.js");
+const type_utils_js_1 = require("../../utils/type-utils.js");
+const COMPACTOR_INSTRUCTIONS = `\
+You are a conversation summarizer. Your task is to create a concise but comprehensive summary of the conversation history provided.
+
+## Conversation history
+
+${"```"}yaml alt="previous-summary"
+{{ previousSummary | yaml.stringify }}
+${"```"}
+
+
+${"```"}yaml alt="conversation-histories"
+{{ messages | yaml.stringify }}
+${"```"}
+
+## Guidelines
+
+1. Preserve key information, decisions, and context that would be needed for future conversation continuity
+2. Include important facts, names, dates, and specific details mentioned
+3. Summarize the user's goals and preferences expressed in the conversation
+4. Note any pending tasks or follow-up items
+5. Keep the summary focused and avoid unnecessary verbosity
+6. Write in a neutral, factual tone
+
+Output a single summary that captures the essence of the conversation.`;
+class AISessionCompactor extends ai_agent_js_1.AIAgent {
+    constructor(options) {
+        super({
+            name: "SessionCompactor",
+            description: "Generates conversation summaries for session compaction",
+            inputSchema: zod_1.z.object({
+                previousSummary: (0, zod_1.optional)(zod_1.z.array(zod_1.z.string()).describe("List of previous conversation summaries")),
+                messages: zod_1.z.array(zod_1.z.any()),
+            }),
+            outputSchema: zod_1.z.object({
+                summary: zod_1.z.string().describe("A comprehensive summary of the conversation history"),
+            }),
+            instructions: COMPACTOR_INSTRUCTIONS,
+            taskRenderMode: "hide",
+            ...(0, type_utils_js_1.omitBy)(options ?? {}, (v) => (0, type_utils_js_1.isNil)(v)),
+            session: {
+                mode: "disabled",
+            },
+        });
+    }
+}
+exports.AISessionCompactor = AISessionCompactor;

package/lib/cjs/prompt/compact/session-memory-extractor.d.ts

@@ -0,0 +1,7 @@
+import { AIAgent, type AIAgentOptions } from "../../agents/ai-agent.js";
+import type { MemoryExtractorInput, MemoryExtractorOutput } from "./types.js";
+export interface CreateSessionMemoryExtractorOptions extends AIAgentOptions<MemoryExtractorInput, MemoryExtractorOutput> {
+}
+export declare class AISessionMemoryExtractor extends AIAgent<MemoryExtractorInput, MemoryExtractorOutput> {
+    constructor(options?: CreateSessionMemoryExtractorOptions);
+}

package/lib/cjs/prompt/compact/session-memory-extractor.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AISessionMemoryExtractor = void 0;
+const zod_1 = require("zod");
+const ai_agent_js_1 = require("../../agents/ai-agent.js");
+const type_utils_js_1 = require("../../utils/type-utils.js");
+const EXTRACTOR_INSTRUCTIONS = `\
+You are a session memory fact extractor. Your task is to extract facts that help continue THIS SESSION's work.
+
+**Key Principle**: Extract WORK CONTEXT (tasks, decisions, blockers), NOT PROJECT DOCUMENTATION (tech stack, code structure, implementation details).
+
+Session memory is for remembering:
+- What we're trying to accomplish
+- Why we made certain choices
+- What problems we encountered
+- Important context for continuing the work
+
+Session memory is NOT for documenting:
+- What the code does (visible in code)
+- How the project is structured (can explore directly)
+- What technologies are used (obvious from files)
+
+## User Memory Facts (Long-term, cross-session)
+
+${"```"}yaml alt="user-memory-facts"
+{{ existingUserFacts | yaml.stringify }}
+${"```"}
+
+## Existing Session Memory Facts
+
+${"```"}yaml alt="existing-facts"
+{{ existingFacts | yaml.stringify }}
+${"```"}
+
+## Recent Conversation
+
+${"```"}yaml alt="recent-messages"
+{{ messages | yaml.stringify }}
+${"```"}
+
+## Guidelines
+
+1. **Avoid duplicating User Memory (CRITICAL)**:
+   - User Memory contains long-term, cross-session facts about the user
+   - DO NOT extract facts that are already covered in User Memory
+   - Focus on session-specific information that User Memory doesn't capture
+   - Example: If User Memory has "User prefers TypeScript", don't add "User is using TypeScript" to session memory
+
+2. **Output only changes (CRITICAL)**:
+   - Only output facts that need to be added or updated
+   - DO NOT output facts that already exist and don't need changes
+   - Each label in newFacts must be unique
+   - When a label already exists in session memory:
+     - Include it in newFacts ONLY if conversation provides new information to update it
+     - Omit it from newFacts if it doesn't need changes
+
+3. **What to extract** (Session context, NOT project documentation):
+   - **Current tasks and goals**: What the user is trying to accomplish in this session
+   - **Important decisions**: Key choices made and WHY (not just WHAT was chosen)
+   - **Session-specific constraints**: Temporary requirements or limitations for this work
+   - **Blockers and context**: Issues encountered and relevant background
+   - **Session-specific user preferences**: Only if different from User Memory for this session
+
+4. **What NOT to extract** (Can be inferred from code or documentation):
+   - ❌ Tech stack details (e.g., "Project uses React") - obvious from package.json
+   - ❌ Code structure facts (e.g., "Code is in /src") - can be seen directly
+   - ❌ Implementation details (e.g., "Function X does Y") - visible in code
+   - ❌ Architecture documentation - should be in actual docs, not memory
+   - ❌ Generic project facts that don't help with current work
+
+5. **When to output a fact in newFacts**:
+   - **New fact**: Learning something new about current work context not in existing session memory
+   - **Updated fact**: New information about current tasks or decisions
+   - **DO NOT output**: Facts already in session memory, facts covered by User Memory, or obvious code facts
+   - Example: Extract "User is fixing the memory duplication bug to optimize token usage" ✓
+   - Example: Don't extract "Project uses TypeScript" ❌ (obvious from code)
+
+6. **Remove outdated facts** by including their labels in removeFacts:
+   - Facts that are no longer relevant to current session
+   - Facts that have been superseded by new information
+
+7. **Label naming conventions**:
+   - Use short, descriptive, kebab-case labels
+   - Focus on: "task-*" (current tasks), "decision-*" (key decisions), "ctx-*" (context), "blocker-*" (blockers)
+   - Examples: "task-fix-memory-bug", "decision-use-incremental-updates", "ctx-working-on-compact-module", "blocker-type-error"
+
+8. **Fact content guidelines**:
+   - Write concise, actionable facts (1-2 sentences max)
+   - Focus on WHY and WHAT (goals, decisions, context), not HOW (implementation details)
+   - Information should help continue the work, not document the codebase
+
+9. **Extraction criteria**:
+   - Only extract if there's clear, explicit information in the conversation
+   - The information should be useful for continuing the current work
+   - Don't make assumptions or infer beyond what's stated
+   - When in doubt about whether something changed, don't output it
+
+Output only the new or updated facts in newFacts, and any labels to remove in removeFacts.`;
+class AISessionMemoryExtractor extends ai_agent_js_1.AIAgent {
+    constructor(options) {
+        super({
+            name: "SessionMemoryExtractor",
+            description: "Extracts and maintains session memory facts from conversations",
+            inputSchema: zod_1.z.object({
+                existingUserFacts: (0, zod_1.optional)(zod_1.z
+                    .array(zod_1.z.object({
+                    label: zod_1.z.string(),
+                    fact: zod_1.z.string(),
+                    confidence: (0, zod_1.optional)(zod_1.z.number()),
+                    tags: (0, zod_1.optional)(zod_1.z.array(zod_1.z.string())),
+                }))
+                    .describe("User memory facts (long-term, cross-session) to avoid duplication")),
+                existingFacts: (0, zod_1.optional)(zod_1.z
+                    .array(zod_1.z.object({
+                    label: zod_1.z.string(),
+                    fact: zod_1.z.string(),
+                    confidence: (0, zod_1.optional)(zod_1.z.number()),
+                    tags: (0, zod_1.optional)(zod_1.z.array(zod_1.z.string())),
+                }))
+                    .describe("Existing session memory facts for context and deduplication")),
+                messages: zod_1.z.array(zod_1.z.any()).describe("Recent conversation messages"),
+            }),
+            outputSchema: zod_1.z.object({
+                newFacts: zod_1.z
+                    .array(zod_1.z.object({
+                    label: zod_1.z.string().describe("Short, semantic label for the fact"),
+                    fact: zod_1.z.string().describe("The fact content"),
+                    confidence: (0, zod_1.optional)(zod_1.z.number().min(0).max(1).describe("Confidence score (0-1)")),
+                    tags: (0, zod_1.optional)(zod_1.z.array(zod_1.z.string()).describe("Classification tags")),
+                }))
+                    .describe("Facts to add or update in session memory. Only include facts that are new or need updates. Do not include unchanged facts."),
+                removeFacts: (0, zod_1.optional)(zod_1.z.array(zod_1.z.string()).describe("Labels of facts to remove from memory")),
+            }),
+            instructions: EXTRACTOR_INSTRUCTIONS,
+            taskRenderMode: "hide",
+            ...(0, type_utils_js_1.omitBy)(options ?? {}, (v) => (0, type_utils_js_1.isNil)(v)),
+            session: {
+                mode: "disabled",
+            },
+        });
+    }
+}
+exports.AISessionMemoryExtractor = AISessionMemoryExtractor;

package/lib/cjs/prompt/compact/types.d.ts

@@ -0,0 +1,336 @@
+import type { Agent, Message } from "../../agents/agent.js";
+import type { ChatModelInputMessage } from "../../agents/chat-model.js";
+/**
+ * Session mode type
+ */
+export type SessionMode = "auto" | "disabled";
+/**
+ * Default session mode
+ */
+export declare const DEFAULT_SESSION_MODE: SessionMode;
+/**
+ * Default compaction mode
+ */
+export declare const DEFAULT_COMPACT_MODE: "auto";
+/**
+ * Default maximum tokens before triggering compaction
+ */
+export declare const DEFAULT_MAX_TOKENS = 80000;
+/**
+ * Default ratio of maxTokens to reserve for keeping recent messages
+ */
+export declare const DEFAULT_KEEP_RECENT_RATIO = 0.5;
+/**
+ * Default async mode for compaction
+ */
+export declare const DEFAULT_COMPACT_ASYNC = true;
+/**
+ * Content structure for history entries
+ */
+export interface EntryContent {
+    input?: unknown;
+    output?: unknown;
+    messages?: ChatModelInputMessage[];
+}
+/**
+ * Output structure from the compactor agent
+ */
+export interface CompactContent extends Message {
+    summary: string;
+    /**
+     * Last Agent Skill content in the session
+     * Preserved across compactions to maintain skill instructions
+     */
+    lastAgentSkill?: {
+        content: string;
+    };
+}
+/**
+ * Input structure for the compactor agent
+ */
+export interface CompactorInput extends Message {
+    previousSummary?: string[];
+    messages: ChatModelInputMessage[];
+}
+/**
+ * Type alias for a compactor agent
+ */
+export type Compactor = Agent<CompactorInput, CompactContent>;
+/**
+ * Configuration for session compaction
+ */
+export interface CompactConfig {
+    /**
+     * Compaction mode
+     * @default DEFAULT_COMPACT_MODE ("auto")
+     */
+    mode?: "auto" | "disabled";
+    /**
+     * Maximum tokens before triggering compaction
+     * @default DEFAULT_MAX_TOKENS (80000)
+     */
+    maxTokens?: number;
+    /**
+     * Ratio of maxTokens to reserve for keeping recent messages (0-1)
+     *
+     * Defines what portion of maxTokens budget should be allocated for
+     * preserving recent conversation history without compaction.
+     *
+     * @default 0.5 (50% of maxTokens)
+     * @example 0.5 means if maxTokens=80000, keep up to 40000 tokens of recent messages
+     */
+    keepRecentRatio?: number;
+    /**
+     * Whether to perform compaction asynchronously
+     * @default DEFAULT_COMPACT_ASYNC (true)
+     */
+    async?: boolean;
+    /**
+     * Agent that generates summaries from conversation entries
+     * Input: { entries: EntryContent[] }
+     * Output: { summary: string }
+     */
+    compactor?: Compactor;
+}
+/**
+ * Default ratio of maxTokens to allocate for user memory
+ */
+export declare const DEFAULT_MEMORY_RATIO = 0.04;
+/**
+ * Default query limit for loading memory facts
+ */
+export declare const DEFAULT_MEMORY_QUERY_LIMIT = 200;
+/**
+ * Content structure for a single memory fact
+ *
+ * Used by both session memory and user memory to store learned facts.
+ * Each fact is stored as an individual AFSEntry with metadata at the AFSEntry level.
+ *
+ * Storage paths:
+ * - Session Memory:
+ *   - List: /by-session/:sessionId/@metadata/memory
+ *   - Create: /by-session/:sessionId/@metadata/memory/new
+ *   - Read: /by-session/:sessionId/@metadata/memory/:memoryId
+ * - User Memory:
+ *   - List: /by-user/:userId/@metadata/memory
+ *   - Create: /by-user/:userId/@metadata/memory/new
+ *   - Read: /by-user/:userId/@metadata/memory/:memoryId
+ *
+ * @example
+ * AFSEntry<MemoryFact> {
+ *   id: "fact-001",           // AFSEntry ID (auto-generated)
+ *   userId: "user-001",
+ *   agentId: "assistant",      // which agent learned this fact
+ *   sessionId: "session-123",  // which session it was learned from (if applicable)
+ *   createdAt: Date,
+ *   content: {
+ *     label: "pref-package-manager",  // semantic label for this fact
+ *     fact: "User prefers using pnpm",
+ *     confidence: 0.9,
+ *     tags: ["preference", "tooling"]
+ *   }
+ * }
+ */
+export interface MemoryFact {
+    /**
+     * Semantic label for this fact (short, human-readable)
+     * Used for updates and deletions to uniquely identify facts
+     * @example "pref-package-manager", "skill-typescript", "proj-main-language"
+     */
+    label: string;
+    /**
+     * The fact content (text description)
+     */
+    fact: string;
+    /**
+     * Confidence score (0-1)
+     * Higher values indicate more certain facts
+     * @default 1.0
+     */
+    confidence?: number;
+    /**
+     * Classification tags for the fact
+     * @example ['preference', 'technical', 'project-specific']
+     */
+    tags?: string[];
+}
+/**
+ * Input structure for the memory extractor agent
+ */
+export interface MemoryExtractorInput extends Message {
+    /**
+     * User memory facts (long-term, cross-session) to avoid duplication
+     */
+    existingUserFacts?: MemoryFact[];
+    /**
+     * Existing session memory facts (for context and deduplication)
+     */
+    existingFacts?: MemoryFact[];
+    /**
+     * Recent conversation messages to extract facts from
+     */
+    messages: ChatModelInputMessage[];
+}
+/**
+ * Output structure from the memory extractor agent
+ */
+export interface MemoryExtractorOutput extends Message {
+    /**
+     * New or updated facts from the conversation
+     * Only include facts that need to be added or updated
+     * Do not include unchanged facts that already exist
+     */
+    newFacts: MemoryFact[];
+    /**
+     * Fact labels to remove from existing memory
+     * Each string should match a label in existingFacts
+     * @example ["pref-package-manager", "skill-old-framework"]
+     */
+    removeFacts?: string[];
+}
+/**
+ * Type alias for a memory extractor agent
+ */
+export type MemoryExtractor = Agent<MemoryExtractorInput, MemoryExtractorOutput>;
+/**
+ * Default session memory mode
+ */
+export declare const DEFAULT_SESSION_MEMORY_MODE: "auto";
+/**
+ * Default async mode for session memory extraction
+ */
+export declare const DEFAULT_SESSION_MEMORY_ASYNC = true;
+/**
+ * Metadata for tracking session memory extraction progress
+ *
+ * This metadata is stored in each memory entry's metadata field.
+ * When extracting new facts, the latestEntryId is recorded in the metadata
+ * to track which history entries have been processed.
+ */
+export interface SessionMemoryMetadata {
+    /**
+     * ID of the last extracted history entry
+     * Used to determine which entries still need processing
+     */
+    latestEntryId?: string;
+}
+/**
+ * Default user memory mode
+ */
+export declare const DEFAULT_USER_MEMORY_MODE: "auto";
+/**
+ * Default async mode for user memory consolidation
+ */
+export declare const DEFAULT_USER_MEMORY_ASYNC = true;
+/**
+ * Input structure for the user memory extractor agent
+ */
+export interface UserMemoryExtractorInput extends Message {
+    /**
+     * Session memory facts from multiple sessions to consolidate
+     */
+    sessionFacts: MemoryFact[];
+    /**
+     * Existing user memory facts (for context and deduplication)
+     */
+    existingUserFacts?: MemoryFact[];
+}
+/**
+ * Output structure from the user memory extractor agent
+ */
+export interface UserMemoryExtractorOutput extends Message {
+    /**
+     * New or updated facts for user memory
+     * Only include facts that need to be added or updated
+     * Do not include unchanged facts that already exist
+     * Each label should be unique - these will replace old facts with same labels
+     */
+    newFacts: MemoryFact[];
+    /**
+     * Fact labels to remove from user memory
+     * Each string should match a label in existingUserFacts
+     */
+    removeFacts?: string[];
+}
+/**
+ * Type alias for a user memory extractor agent
+ */
+export type UserMemoryExtractor = Agent<UserMemoryExtractorInput, UserMemoryExtractorOutput>;
+/**
+ * Configuration for user memory
+ * User memory contains long-term facts consolidated from multiple sessions
+ */
+export interface UserMemoryConfig {
+    /**
+     * User memory mode
+     * - "auto": Enable memory and auto-consolidate at appropriate times
+     * - "disabled": Disable user memory completely
+     * @default DEFAULT_USER_MEMORY_MODE ("auto")
+     */
+    mode?: "auto" | "disabled";
+    /**
+     * Ratio of maxTokens to allocate for user memory (0-1)
+     *
+     * Defines what portion of maxTokens budget should be allocated for
+     * injecting user memory facts into the prompt.
+     *
+     * @default DEFAULT_MEMORY_RATIO (0.04 = 4% of maxTokens)
+     * @example 0.04 means if maxTokens=80000, allocate 3200 tokens for memory
+     */
+    memoryRatio?: number;
+    /**
+     * Maximum number of fact entries to load from storage
+     * @default DEFAULT_MEMORY_QUERY_LIMIT (200)
+     */
+    queryLimit?: number;
+    /**
+     * Whether to perform memory consolidation asynchronously
+     * @default DEFAULT_USER_MEMORY_ASYNC (true)
+     */
+    async?: boolean;
+    /**
+     * Agent that extracts user memory facts from session memory
+     * Input: { sessionFacts: MemoryFact[], existingUserFacts?: MemoryFact[] }
+     * Output: { newFacts: MemoryFact[], removeFacts?: string[] }
+     */
+    extractor?: UserMemoryExtractor;
+}
+/**
+ * Configuration for session memory
+ * Session memory contains facts extracted from the current session's conversation
+ */
+export interface SessionMemoryConfig {
+    /**
+     * Session memory mode
+     * - "auto": Enable memory and auto-update after each conversation turn
+     * - "disabled": Disable memory completely
+     * @default DEFAULT_SESSION_MEMORY_MODE ("auto")
+     */
+    mode?: "auto" | "disabled";
+    /**
+     * Ratio of maxTokens to allocate for session memory (0-1)
+     *
+     * Defines what portion of maxTokens budget should be allocated for
+     * injecting session memory facts into the prompt.
+     *
+     * @default DEFAULT_MEMORY_RATIO (0.04 = 4% of maxTokens)
+     * @example 0.04 means if maxTokens=80000, allocate 3200 tokens for memory
+     */
+    memoryRatio?: number;
+    /**
+     * Maximum number of fact entries to load from storage
+     * @default DEFAULT_MEMORY_QUERY_LIMIT (200)
+     */
+    queryLimit?: number;
+    /**
+     * Whether to perform memory extraction asynchronously
+     * @default DEFAULT_SESSION_MEMORY_ASYNC (true)
+     */
+    async?: boolean;
+    /**
+     * Agent that extracts facts from conversation messages
+     * Input: { existingUserFacts?: MemoryFact[], existingFacts?: MemoryFact[], messages: ChatModelInputMessage[] }
+     * Output: { newFacts: MemoryFact[], removeFacts?: string[] }
+     */
+    extractor?: MemoryExtractor;
+}

package/lib/cjs/prompt/compact/types.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_USER_MEMORY_ASYNC = exports.DEFAULT_USER_MEMORY_MODE = exports.DEFAULT_SESSION_MEMORY_ASYNC = exports.DEFAULT_SESSION_MEMORY_MODE = exports.DEFAULT_MEMORY_QUERY_LIMIT = exports.DEFAULT_MEMORY_RATIO = exports.DEFAULT_COMPACT_ASYNC = exports.DEFAULT_KEEP_RECENT_RATIO = exports.DEFAULT_MAX_TOKENS = exports.DEFAULT_COMPACT_MODE = exports.DEFAULT_SESSION_MODE = void 0;
+/**
+ * Default session mode
+ */
+exports.DEFAULT_SESSION_MODE = "auto";
+/**
+ * Default compaction mode
+ */
+exports.DEFAULT_COMPACT_MODE = "auto";
+/**
+ * Default maximum tokens before triggering compaction
+ */
+exports.DEFAULT_MAX_TOKENS = 80000;
+/**
+ * Default ratio of maxTokens to reserve for keeping recent messages
+ */
+exports.DEFAULT_KEEP_RECENT_RATIO = 0.5;
+/**
+ * Default async mode for compaction
+ */
+exports.DEFAULT_COMPACT_ASYNC = true;
+// ============================================================================
+// User Memory Types
+// ============================================================================
+/**
+ * Default ratio of maxTokens to allocate for user memory
+ */
+exports.DEFAULT_MEMORY_RATIO = 0.04;
+/**
+ * Default query limit for loading memory facts
+ */
+exports.DEFAULT_MEMORY_QUERY_LIMIT = 200;
+/**
+ * Default session memory mode
+ */
+exports.DEFAULT_SESSION_MEMORY_MODE = "auto";
+/**
+ * Default async mode for session memory extraction
+ */
+exports.DEFAULT_SESSION_MEMORY_ASYNC = true;
+// ============================================================================
+// User Memory Types
+// ============================================================================
+/**
+ * Default user memory mode
+ */
+exports.DEFAULT_USER_MEMORY_MODE = "auto";
+/**
+ * Default async mode for user memory consolidation
+ */
+exports.DEFAULT_USER_MEMORY_ASYNC = true;

package/lib/cjs/prompt/compact/user-memory-extractor.d.ts

@@ -0,0 +1,7 @@
+import { AIAgent, type AIAgentOptions } from "../../agents/ai-agent.js";
+import type { UserMemoryExtractorInput, UserMemoryExtractorOutput } from "./types.js";
+export interface CreateUserMemoryExtractorOptions extends AIAgentOptions<UserMemoryExtractorInput, UserMemoryExtractorOutput> {
+}
+export declare class AIUserMemoryExtractor extends AIAgent<UserMemoryExtractorInput, UserMemoryExtractorOutput> {
+    constructor(options?: CreateUserMemoryExtractorOptions);
+}