agentx-sdk 0.1.0

package/dist/memory/file-memory-system.js

@@ -0,0 +1,310 @@
+/**
+ * File-based memory system — main orchestrator.
+ *
+ * Manages Markdown memory files with YAML frontmatter and a MEMORY.md index.
+ * Supports thread-isolated memory: each threadId gets its own subdirectory.
+ * Global memories (no threadId) live in the root memoryDir.
+ *
+ * Layout:
+ *   memoryDir/
+ *     MEMORY.md           ← global index
+ *     project-info.md     ← global memory
+ *     threads/
+ *       telegram-123/
+ *         MEMORY.md       ← thread index
+ *         user-name.md    ← thread-scoped memory
+ *       teams-456/
+ *         MEMORY.md
+ *         ...
+ */
+import { readFile, writeFile, unlink, stat, readdir, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ENTRYPOINT_NAME, MAX_ENTRYPOINT_LINES, MAX_ENTRYPOINT_BYTES, parseMemoryType, } from './memory-types.js';
+import { resolveMemoryDir, ensureMemoryDir, sanitizeFilename } from './memory-paths.js';
+import { scanMemoryFiles, formatMemoryManifest, parseFrontmatter } from './memory-scanner.js';
+import { selectRelevantMemories } from './memory-relevance.js';
+import { memoryFreshnessNote } from './memory-age.js';
+import { buildMemoryInstructions } from './memory-prompts.js';
+const THREADS_DIR = 'threads';
+export class FileMemorySystem {
+    memoryDir;
+    client;
+    logger;
+    relevanceModel;
+    writeLock = false;
+    constructor(config, client, logger) {
+        this.memoryDir = resolveMemoryDir(config.memoryDir);
+        this.client = client;
+        this.logger = logger;
+        this.relevanceModel = config.relevanceModel;
+    }
+    /** Ensure the memory directory exists (idempotent). */
+    async ensureDir() {
+        await ensureMemoryDir(this.memoryDir);
+    }
+    /** Get the resolved memory directory path. */
+    getMemoryDir() {
+        return this.memoryDir;
+    }
+    /**
+     * Resolve the effective directory for a threadId.
+     * No threadId → root memoryDir (global).
+     * With threadId → memoryDir/threads/{threadId}/
+     */
+    resolveDir(threadId) {
+        if (!threadId)
+            return this.memoryDir;
+        return join(this.memoryDir, THREADS_DIR, threadId);
+    }
+    /** Ensure a thread directory exists. */
+    async ensureThreadDir(threadId) {
+        const dir = this.resolveDir(threadId);
+        await mkdir(dir, { recursive: true });
+    }
+    /**
+     * Save a new memory file and update the MEMORY.md index.
+     * When threadId is provided, saves to the thread subdirectory.
+     */
+    async saveMemory(input, threadId) {
+        await this.ensureThreadDir(threadId);
+        const dir = this.resolveDir(threadId);
+        const filename = sanitizeFilename(input.name);
+        const filePath = join(dir, filename);
+        const fileContent = [
+            '---',
+            `name: ${input.name}`,
+            `description: ${input.description}`,
+            `type: ${input.type}`,
+            '---',
+            '',
+            input.content,
+            '',
+        ].join('\n');
+        await writeFile(filePath, fileContent, 'utf-8');
+        await this.addToIndex(filename, input.description, threadId);
+        this.logger.debug('Memory saved', { filename, type: input.type, threadId: threadId ?? 'global' });
+        return filename;
+    }
+    /**
+     * Read and parse a memory file.
+     * When threadId is provided, reads from thread subdirectory.
+     */
+    async readMemory(filename, threadId) {
+        try {
+            const dir = this.resolveDir(threadId);
+            const filePath = join(dir, filename);
+            const content = await readFile(filePath, 'utf-8');
+            const fileStat = await stat(filePath);
+            const frontmatter = parseFrontmatter(content);
+            const bodyMatch = content.match(/^---\s*\n[\s\S]*?\n---\s*\n?([\s\S]*)/);
+            const body = bodyMatch?.[1]?.trim() ?? content;
+            return {
+                filename,
+                filePath,
+                mtimeMs: fileStat.mtimeMs,
+                name: frontmatter.name ?? null,
+                description: frontmatter.description ?? null,
+                type: parseMemoryType(frontmatter.type),
+                content: body,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Delete a memory file and remove its entry from the index.
+     */
+    async deleteMemory(filename, threadId) {
+        try {
+            const dir = this.resolveDir(threadId);
+            const filePath = join(dir, filename);
+            await unlink(filePath);
+            await this.removeFromIndex(filename, threadId);
+            this.logger.debug('Memory deleted', { filename, threadId: threadId ?? 'global' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Scan memory files. When threadId is provided, scans thread dir + global dir (merged).
+     */
+    async scanMemories(signal, threadId) {
+        const globalMemories = await scanMemoryFiles(this.memoryDir, signal);
+        if (!threadId)
+            return globalMemories;
+        const threadDir = this.resolveDir(threadId);
+        const threadMemories = await scanMemoryFiles(threadDir, signal);
+        // Merge: thread memories first (higher priority), then global
+        // Dedupe by filename (thread wins)
+        const seen = new Set(threadMemories.map(m => m.filename));
+        const merged = [...threadMemories, ...globalMemories.filter(m => !seen.has(m.filename))];
+        return merged;
+    }
+    /**
+     * Find relevant memories for a query using LLM selection.
+     * Scans thread + global memories when threadId is provided.
+     */
+    async findRelevant(query, signal, excludeFilenames, threadId) {
+        const memories = await this.scanMemories(signal, threadId);
+        if (memories.length === 0)
+            return [];
+        const filtered = excludeFilenames?.size
+            ? memories.filter(m => !excludeFilenames.has(m.filename))
+            : memories;
+        if (filtered.length === 0)
+            return [];
+        const manifest = formatMemoryManifest(filtered);
+        const validFilenames = new Set(filtered.map(m => m.filename));
+        const selectedFilenames = await selectRelevantMemories(query, manifest, validFilenames, this.client, { model: this.relevanceModel, signal });
+        const results = [];
+        for (const filename of selectedFilenames) {
+            // Try thread dir first, then global
+            const memory = threadId
+                ? (await this.readMemory(filename, threadId) ?? await this.readMemory(filename))
+                : await this.readMemory(filename);
+            if (memory)
+                results.push(memory);
+        }
+        return results;
+    }
+    /**
+     * Build the context prompt from MEMORY.md.
+     * When threadId is provided, merges global + thread MEMORY.md.
+     */
+    async buildContextPrompt(threadId) {
+        const parts = [];
+        // Global MEMORY.md
+        try {
+            const globalContent = await readFile(join(this.memoryDir, ENTRYPOINT_NAME), 'utf-8');
+            if (globalContent.trim())
+                parts.push(globalContent.trim());
+        }
+        catch { /* no global index */ }
+        // Thread MEMORY.md
+        if (threadId) {
+            try {
+                const threadContent = await readFile(join(this.resolveDir(threadId), ENTRYPOINT_NAME), 'utf-8');
+                if (threadContent.trim())
+                    parts.push(threadContent.trim());
+            }
+            catch { /* no thread index */ }
+        }
+        if (parts.length === 0)
+            return '';
+        return truncateEntrypointContent(parts.join('\n'));
+    }
+    /**
+     * Build the behavioral instructions prompt for the memory system.
+     */
+    getMemoryInstructions() {
+        return buildMemoryInstructions(this.memoryDir);
+    }
+    /**
+     * Build the full memory context for injection (MEMORY.md + relevant memories).
+     */
+    async buildFullContext(query, signal, threadId) {
+        const parts = [];
+        const indexContent = await this.buildContextPrompt(threadId);
+        if (indexContent) {
+            parts.push('# Memory Index\n' + indexContent);
+        }
+        const relevant = await this.findRelevant(query, signal, undefined, threadId);
+        if (relevant.length > 0) {
+            parts.push('# Relevant Memories');
+            for (const mem of relevant) {
+                const freshness = memoryFreshnessNote(mem.mtimeMs);
+                const header = mem.name ? `## ${mem.name}` : `## ${mem.filename}`;
+                parts.push(`${header}\n${freshness}${mem.content}`);
+            }
+        }
+        return parts.join('\n\n');
+    }
+    /**
+     * Check if any memory files were created or modified since the given timestamp.
+     * When threadId is provided, checks only the thread directory.
+     */
+    async hasWritesSince(sinceMs, threadId) {
+        const dir = this.resolveDir(threadId);
+        try {
+            const entries = await readdir(dir);
+            for (const entry of entries) {
+                if (!entry.endsWith('.md') || entry === ENTRYPOINT_NAME)
+                    continue;
+                const fileStat = await stat(join(dir, entry));
+                if (fileStat.mtimeMs > sinceMs)
+                    return true;
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    // --- Private helpers ---
+    async addToIndex(filename, description, threadId) {
+        await this.withWriteLock(async () => {
+            const dir = this.resolveDir(threadId);
+            const entrypoint = join(dir, ENTRYPOINT_NAME);
+            let existing = '';
+            try {
+                existing = await readFile(entrypoint, 'utf-8');
+            }
+            catch { /* File doesn't exist yet */ }
+            if (existing.includes(`(${filename})`))
+                return;
+            const newEntry = `- [${description}](${filename}) — ${description}`;
+            const updated = existing ? `${existing.trimEnd()}\n${newEntry}\n` : `${newEntry}\n`;
+            await writeFile(entrypoint, updated, 'utf-8');
+        });
+    }
+    async removeFromIndex(filename, threadId) {
+        await this.withWriteLock(async () => {
+            const dir = this.resolveDir(threadId);
+            const entrypoint = join(dir, ENTRYPOINT_NAME);
+            try {
+                const content = await readFile(entrypoint, 'utf-8');
+                const lines = content.split('\n').filter(line => !line.includes(`(${filename})`));
+                await writeFile(entrypoint, lines.join('\n'), 'utf-8');
+            }
+            catch { /* Index doesn't exist */ }
+        });
+    }
+    async withWriteLock(fn) {
+        while (this.writeLock) {
+            await new Promise(r => setTimeout(r, 10));
+        }
+        this.writeLock = true;
+        try {
+            return await fn();
+        }
+        finally {
+            this.writeLock = false;
+        }
+    }
+}
+/**
+ * Truncate MEMORY.md content to limits: 200 lines, 25KB.
+ */
+export function truncateEntrypointContent(content) {
+    const lines = content.split('\n');
+    if (lines.length > MAX_ENTRYPOINT_LINES) {
+        const truncated = lines.slice(0, MAX_ENTRYPOINT_LINES).join('\n');
+        return truncated + `\n\n[... truncated: ${lines.length - MAX_ENTRYPOINT_LINES} more lines]`;
+    }
+    const bytes = new TextEncoder().encode(content).length;
+    if (bytes > MAX_ENTRYPOINT_BYTES) {
+        let cutoff = content.length;
+        while (new TextEncoder().encode(content.slice(0, cutoff)).length > MAX_ENTRYPOINT_BYTES) {
+            const lastNewline = content.lastIndexOf('\n', cutoff - 1);
+            if (lastNewline <= 0)
+                break;
+            cutoff = lastNewline;
+        }
+        return content.slice(0, cutoff) + '\n\n[... truncated: exceeded 25KB limit]';
+    }
+    return content;
+}
+//# sourceMappingURL=file-memory-system.js.map

package/dist/memory/file-memory-system.js.map

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

package/dist/memory/memory-age.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Memory staleness tracking.
+ *
+ * Models are poor at date arithmetic — a raw ISO timestamp doesn't trigger
+ * staleness reasoning the way "47 days ago" does.
+ */
+/**
+ * Days elapsed since mtime. Floor-rounded — 0 for today, 1 for yesterday.
+ * Negative inputs (future mtime, clock skew) clamp to 0.
+ */
+export declare function memoryAgeDays(mtimeMs: number): number;
+/** Human-readable age string. */
+export declare function memoryAge(mtimeMs: number): string;
+/**
+ * Staleness caveat for memories >1 day old. Returns '' for fresh memories.
+ */
+export declare function memoryFreshnessText(mtimeMs: number): string;
+/**
+ * Per-memory staleness note. Returns '' for memories ≤ 1 day old.
+ */
+export declare function memoryFreshnessNote(mtimeMs: number): string;
+//# sourceMappingURL=memory-age.d.ts.map

package/dist/memory/memory-age.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-age.d.ts","sourceRoot":"","sources":["../../src/memory/memory-age.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,iCAAiC;AACjC,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAS3D;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI3D"}

package/dist/memory/memory-age.js

@@ -0,0 +1,44 @@
+/**
+ * Memory staleness tracking.
+ *
+ * Models are poor at date arithmetic — a raw ISO timestamp doesn't trigger
+ * staleness reasoning the way "47 days ago" does.
+ */
+/**
+ * Days elapsed since mtime. Floor-rounded — 0 for today, 1 for yesterday.
+ * Negative inputs (future mtime, clock skew) clamp to 0.
+ */
+export function memoryAgeDays(mtimeMs) {
+    return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86_400_000));
+}
+/** Human-readable age string. */
+export function memoryAge(mtimeMs) {
+    const d = memoryAgeDays(mtimeMs);
+    if (d === 0)
+        return 'today';
+    if (d === 1)
+        return 'yesterday';
+    return `${d} days ago`;
+}
+/**
+ * Staleness caveat for memories >1 day old. Returns '' for fresh memories.
+ */
+export function memoryFreshnessText(mtimeMs) {
+    const d = memoryAgeDays(mtimeMs);
+    if (d <= 1)
+        return '';
+    return (`This memory is ${d} days old. ` +
+        `Memories are point-in-time observations, not live state — ` +
+        `claims about code behavior or file citations may be outdated. ` +
+        `Verify against current code before asserting as fact.`);
+}
+/**
+ * Per-memory staleness note. Returns '' for memories ≤ 1 day old.
+ */
+export function memoryFreshnessNote(mtimeMs) {
+    const text = memoryFreshnessText(mtimeMs);
+    if (!text)
+        return '';
+    return `[staleness warning] ${text}\n`;
+}
+//# sourceMappingURL=memory-age.js.map

package/dist/memory/memory-age.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-age.js","sourceRoot":"","sources":["../../src/memory/memory-age.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,MAAM,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,OAAO,CAAC;IAC5B,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,WAAW,CAAC;IAChC,OAAO,GAAG,CAAC,WAAW,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,MAAM,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACtB,OAAO,CACL,kBAAkB,CAAC,aAAa;QAChC,4DAA4D;QAC5D,gEAAgE;QAChE,uDAAuD,CACxD,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC1C,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,OAAO,uBAAuB,IAAI,IAAI,CAAC;AACzC,CAAC"}

package/dist/memory/memory-extractor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Background memory extraction service.
+ *
+ * Analyzes recent conversation to extract memories worth saving.
+ * Fire-and-forget — called after each completed turn.
+ *
+ * Uses the forked agent pattern (like old_src/services/extractMemories/):
+ * - Pre-injects manifest of existing memories to avoid duplicates
+ * - Gives the forked agent memory tools (read, write, edit, delete)
+ * - Agent reads existing files before deciding to update or create
+ * - Limited to 5 iterations to prevent rabbit holes
+ */
+import type { FileMemorySystem } from './file-memory-system.js';
+/**
+ * Check if a message contains explicit memory save triggers.
+ */
+export declare function hasExplicitTrigger(message: string): boolean;
+/**
+ * Determine if extraction should run based on triggers.
+ * - Explicit keyword → always extract
+ * - Turn interval → extract every N turns
+ * - Random sampling → probabilistic extraction
+ */
+export declare function shouldExtract(lastMessage: string, turnsSinceExtraction: number, config: {
+    samplingRate?: number;
+    extractionInterval?: number;
+}): boolean;
+/**
+ * Interface for the fork function — avoids circular import with Agent.
+ * Matches the signature of Agent.fork().
+ */
+export interface ForkFn {
+    (prompt: string, options?: {
+        systemPrompt?: string;
+        model?: string;
+        tools?: import('../contracts/entities/agent-tool.js').AgentTool[];
+        background?: boolean;
+    }): Promise<string>;
+}
+/**
+ * Extract memories from conversation using a forked agent with memory tools.
+ *
+ * The forked agent can:
+ * - List existing memories (manifest)
+ * - Read existing memory content
+ * - Edit existing memories (update, not duplicate)
+ * - Write new memories
+ * - Delete outdated memories
+ *
+ * Fire-and-forget — errors are swallowed.
+ */
+export declare function extractMemories(conversationText: string, memorySystem: FileMemorySystem, fork: ForkFn, options?: {
+    model?: string;
+    threadId?: string;
+}): Promise<void>;
+//# sourceMappingURL=memory-extractor.d.ts.map

package/dist/memory/memory-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-extractor.d.ts","sourceRoot":"","sources":["../../src/memory/memory-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAiBhE;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,oBAAoB,EAAE,MAAM,EAC5B,MAAM,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D,OAAO,CAKT;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QACzB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,qCAAqC,EAAE,SAAS,EAAE,CAAC;QAClE,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,gBAAgB,EAAE,MAAM,EACxB,YAAY,EAAE,gBAAgB,EAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/memory/memory-extractor.js

@@ -0,0 +1,91 @@
+/**
+ * Background memory extraction service.
+ *
+ * Analyzes recent conversation to extract memories worth saving.
+ * Fire-and-forget — called after each completed turn.
+ *
+ * Uses the forked agent pattern (like old_src/services/extractMemories/):
+ * - Pre-injects manifest of existing memories to avoid duplicates
+ * - Gives the forked agent memory tools (read, write, edit, delete)
+ * - Agent reads existing files before deciding to update or create
+ * - Limited to 5 iterations to prevent rabbit holes
+ */
+import { formatMemoryManifest } from './memory-scanner.js';
+import { buildForkedExtractionPrompt } from './memory-prompts.js';
+import { createMemoryTools } from './memory-tools.js';
+/** Extraction trigger keywords (multilingual) */
+const EXPLICIT_TRIGGERS = [
+    'remember that',
+    'memorize',
+    'lembra que',
+    'lembre',
+    'não esqueça',
+    'keep in mind',
+    'note that',
+    'for future reference',
+];
+/**
+ * Check if a message contains explicit memory save triggers.
+ */
+export function hasExplicitTrigger(message) {
+    const lower = message.toLowerCase();
+    return EXPLICIT_TRIGGERS.some(t => lower.includes(t));
+}
+/**
+ * Determine if extraction should run based on triggers.
+ * - Explicit keyword → always extract
+ * - Turn interval → extract every N turns
+ * - Random sampling → probabilistic extraction
+ */
+export function shouldExtract(lastMessage, turnsSinceExtraction, config) {
+    if (hasExplicitTrigger(lastMessage))
+        return true;
+    if (turnsSinceExtraction >= (config.extractionInterval ?? 10))
+        return true;
+    if (Math.random() < (config.samplingRate ?? 0.3))
+        return true;
+    return false;
+}
+/**
+ * Extract memories from conversation using a forked agent with memory tools.
+ *
+ * The forked agent can:
+ * - List existing memories (manifest)
+ * - Read existing memory content
+ * - Edit existing memories (update, not duplicate)
+ * - Write new memories
+ * - Delete outdated memories
+ *
+ * Fire-and-forget — errors are swallowed.
+ */
+export async function extractMemories(conversationText, memorySystem, fork, options) {
+    if (!conversationText.trim())
+        return;
+    try {
+        // Pre-scan existing memories (thread + global) for the manifest
+        const existingMemories = await memorySystem.scanMemories(undefined, options?.threadId);
+        const existingManifest = formatMemoryManifest(existingMemories);
+        // Count approximate messages for the prompt
+        const messageCount = conversationText.split('\n').filter(l => l.match(/^(user|assistant|tool):/)).length;
+        const prompt = [
+            buildForkedExtractionPrompt(Math.max(messageCount, 2), existingManifest),
+            '',
+            '## Recent conversation',
+            '',
+            conversationText,
+        ].join('\n');
+        // Create memory tools scoped to the right directory
+        const tools = createMemoryTools(memorySystem.getMemoryDir(), options?.threadId);
+        // Fork a subagent with memory tools — background, fire-and-forget
+        await fork(prompt, {
+            systemPrompt: 'You are a memory extraction subagent. Use your memory tools to save, update, or delete memories based on the conversation provided. Be efficient — minimize tool calls.',
+            model: options?.model,
+            tools,
+            background: true,
+        });
+    }
+    catch {
+        // Extraction is best-effort — never propagate errors
+    }
+}
+//# sourceMappingURL=memory-extractor.js.map

package/dist/memory/memory-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-extractor.js","sourceRoot":"","sources":["../../src/memory/memory-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,iDAAiD;AACjD,MAAM,iBAAiB,GAAG;IACxB,eAAe;IACf,UAAU;IACV,YAAY;IACZ,QAAQ;IACR,aAAa;IACb,cAAc;IACd,WAAW;IACX,sBAAsB;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACpC,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,WAAmB,EACnB,oBAA4B,EAC5B,MAA8D;IAE9D,IAAI,kBAAkB,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,oBAAoB,IAAI,CAAC,MAAM,CAAC,kBAAkB,IAAI,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3E,IAAI,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9D,OAAO,KAAK,CAAC;AACf,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,gBAAwB,EACxB,YAA8B,EAC9B,IAAY,EACZ,OAA+C;IAE/C,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE;QAAE,OAAO;IAErC,IAAI,CAAC;QACH,gEAAgE;QAChE,MAAM,gBAAgB,GAAG,MAAM,YAAY,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QACvF,MAAM,gBAAgB,GAAG,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;QAEhE,4CAA4C;QAC5C,MAAM,YAAY,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAC,MAAM,CAAC;QAEzG,MAAM,MAAM,GAAG;YACb,2BAA2B,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,gBAAgB,CAAC;YACxE,EAAE;YACF,wBAAwB;YACxB,EAAE;YACF,gBAAgB;SACjB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,oDAAoD;QACpD,MAAM,KAAK,GAAG,iBAAiB,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAEhF,kEAAkE;QAClE,MAAM,IAAI,CAAC,MAAM,EAAE;YACjB,YAAY,EAAE,yKAAyK;YACvL,KAAK,EAAE,OAAO,EAAE,KAAK;YACrB,KAAK;YACL,UAAU,EAAE,IAAI;SACjB,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,qDAAqD;IACvD,CAAC;AACH,CAAC"}

package/dist/memory/memory-paths.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Memory directory path resolution and security validation.
+ *
+ * Security model ported from old_src/memdir/paths.ts:
+ * - Rejects relative paths, root/near-root, Windows drive roots, UNC paths, null bytes
+ * - Tilde expansion only from config (~/), not from bare ~ or ~/. or ~/..
+ * - All paths normalized to NFC to prevent Unicode normalization attacks
+ */
+/**
+ * Resolve the memory directory from config, env var, or default.
+ * Priority: config.memoryDir → AGENT_MEMORY_DIR env → ~/.agent/memory/
+ *
+ * Config paths support ~/ expansion (user-friendly).
+ * Env var paths must be absolute (set programmatically).
+ */
+export declare function resolveMemoryDir(memoryDir?: string): string;
+/**
+ * Validate that a path is safely within the memory directory.
+ *
+ * SECURITY: Rejects paths that would be dangerous:
+ * - Empty or contains null bytes (truncation in syscalls)
+ * - Relative paths (!isAbsolute)
+ * - Root/near-root (length < 3)
+ * - Windows drive-root (C:)
+ * - UNC paths (\\server\share or //server/share)
+ * - URL-encoded traversal (%2e%2e)
+ * - Outside memory directory after normalization
+ *
+ * Returns the normalized path if valid, undefined if rejected.
+ */
+export declare function validateMemoryPath(path: string, memoryDir: string): string | undefined;
+/**
+ * Sanitize a name into a safe kebab-case filename with .md extension.
+ */
+export declare function sanitizeFilename(name: string): string;
+/**
+ * Idempotent memory directory creation.
+ */
+export declare function ensureMemoryDir(memoryDir: string): Promise<void>;
+/**
+ * Check if an absolute path is within the memory directory.
+ * Uses NFC normalization to prevent Unicode-based path traversal.
+ */
+export declare function isMemoryPath(absolutePath: string, memoryDir: string): boolean;
+//# sourceMappingURL=memory-paths.d.ts.map

package/dist/memory/memory-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-paths.d.ts","sourceRoot":"","sources":["../../src/memory/memory-paths.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAY3D;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,SAAS,CAqBpB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYrD;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAI7E"}