@cuylabs/agent-memory-filesystem 5.0.0

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+import { AgentMemoryRecord, AgentMemoryScope, AgentMemoryRememberInput, AgentMemoryRecallInput, AgentMemoryCompactionCommitInput, AgentMemoryTurnEndInput, AgentMemoryProvider, AgentMemoryRecallResult } from '@cuylabs/agent-core/memory';
+import { AgentConfig, Profile, Tool } from '@cuylabs/agent-core';
+
+interface MemoryTokenizer {
+    normalize(value: string): string;
+    tokenize(value: string): string[];
+}
+interface DefaultMemoryTokenizerOptions {
+    minTermLength?: number;
+    preservePathTerms?: boolean;
+    /** Optional caller-owned terms to ignore. No stop words are applied by default. */
+    stopWords?: Iterable<string>;
+}
+declare function createDefaultMemoryTokenizer(options?: DefaultMemoryTokenizerOptions): MemoryTokenizer;
+
+interface MemoryRecordSearchInput {
+    sessionId?: string;
+    turnId?: string;
+    query?: string;
+    limit: number;
+    scope?: AgentMemoryScope;
+    tags?: string[];
+    minScore?: number;
+}
+interface MemorySearchEngine {
+    search(records: readonly AgentMemoryRecord[], input: MemoryRecordSearchInput): AgentMemoryRecord[];
+}
+
+interface AgenticMemoryRecallOptions {
+    /**
+     * Model used by the private recall worker. Required unless `profile.model`
+     * is provided.
+     */
+    model?: AgentConfig["model"];
+    /**
+     * Optional profile using the same shape as agent-core subagent profiles.
+     * The profile is applied inside the provider and is never exposed as a
+     * foreground tool.
+     */
+    profile?: Profile;
+    /** Optional extra tools for the private recall worker, usually read-only helpers. */
+    tools?: Tool.AnyInfo[];
+    /** Optional middleware/policy stack for the private recall worker's tool calls. */
+    middleware?: AgentConfig["middleware"];
+    /** Optional approval policy for private recall worker tools. */
+    approval?: AgentConfig["approval"];
+    /** Tool execution mode for the private recall worker. */
+    toolExecutionMode?: AgentConfig["toolExecutionMode"];
+    /** Recall worker system prompt. `{basePrompt}` works when overridden by a profile. */
+    systemPrompt?: string;
+    /** Override the user prompt sent to the private recall worker. */
+    prompt?: (input: AgentMemoryRecallInput) => string;
+    name?: string;
+    cwd?: string;
+    maxSteps?: number;
+    maxOutputTokens?: number;
+    temperature?: number;
+    contextWindow?: number;
+    timeoutMs?: number;
+    maxMessages?: number;
+    maxMessageChars?: number;
+    maxPromptChars?: number;
+    maxSummaryChars?: number;
+}
+interface MemoryProviderRecallOptions extends DefaultMemoryTokenizerOptions {
+    /**
+     * Private recall worker configuration. Automatic recall is agentic-only:
+     * when this is omitted, the provider still exposes search/list/get tools but
+     * does not install an automatic recall hook.
+     */
+    agent?: AgenticMemoryRecallOptions;
+    engine?: MemorySearchEngine;
+    tokenizer?: MemoryTokenizer;
+    minScore?: number;
+    snippetContextLines?: number;
+    maxSnippetLines?: number;
+}
+interface MemoryDraft {
+    content: string;
+    title?: string;
+    kind?: string;
+    scope?: AgentMemoryScope;
+    source?: string;
+    tags?: string[];
+    memoryKey?: string;
+    onExisting?: AgentMemoryRememberInput["onExisting"];
+    metadata?: Record<string, unknown>;
+}
+type MemoryCaptureResult = MemoryDraft | MemoryDraft[] | undefined | void;
+type MemoryTurnCapture = (input: AgentMemoryTurnEndInput) => Promise<MemoryCaptureResult> | MemoryCaptureResult;
+type MemoryCompactionCapture = (input: AgentMemoryCompactionCommitInput) => Promise<MemoryCaptureResult> | MemoryCaptureResult;
+interface MemoryProviderRememberOptions {
+    captureTurn?: MemoryTurnCapture;
+    captureBeforeCompactionCommit?: MemoryCompactionCapture;
+}
+interface MemoryProviderOptions {
+    id?: string;
+    /**
+     * Memory root. Relative paths are resolved from each call's `cwd`.
+     *
+     * Default: `.agent-memory`
+     */
+    root?: string;
+    recordsDir?: string;
+    /**
+     * Scope applied when a memory draft/tool call omits `scope`.
+     *
+     * Default: `project`
+     */
+    defaultScope?: AgentMemoryScope;
+    recall?: MemoryProviderRecallOptions;
+    remember?: MemoryProviderRememberOptions;
+}
+
+declare function createFilesystemMemoryProvider(options?: MemoryProviderOptions): AgentMemoryProvider;
+declare const createMemoryProvider: typeof createFilesystemMemoryProvider;
+
+declare const AGENTIC_MEMORY_CAPTURE_BINDER: unique symbol;
+type AgenticMemoryCaptureInput = {
+    kind: "turn";
+    input: AgentMemoryTurnEndInput;
+} | {
+    kind: "compaction";
+    input: AgentMemoryCompactionCommitInput;
+};
+type AgenticMemoryCaptureWriter = (draft: MemoryDraft, input: AgenticMemoryCaptureInput) => Promise<void> | void;
+interface AgenticMemoryCaptureReadInput {
+    sessionId?: string;
+    turnId?: string;
+    cwd: string;
+    query?: string;
+    limit: number;
+    scope?: AgentMemoryScope;
+    tags?: string[];
+}
+interface AgenticMemoryCaptureRuntime {
+    write: AgenticMemoryCaptureWriter;
+    search?: (input: AgenticMemoryCaptureReadInput) => Promise<AgentMemoryRecord[]> | AgentMemoryRecord[];
+    list?: (input: AgenticMemoryCaptureReadInput) => Promise<AgentMemoryRecord[]> | AgentMemoryRecord[];
+}
+type AgenticMemoryCaptureFunction = MemoryTurnCapture & MemoryCompactionCapture & {
+    [AGENTIC_MEMORY_CAPTURE_BINDER]?: (runtime: AgenticMemoryCaptureRuntime) => MemoryTurnCapture & MemoryCompactionCapture;
+};
+interface AgenticMemoryCaptureOptions {
+    /**
+     * Model used by the private memory writer. Required unless `profile.model`
+     * is set.
+     */
+    model?: AgentConfig["model"];
+    /**
+     * Optional profile using the same shape as agent-core subagent profiles.
+     * The profile is applied inside the provider; it is not exposed as a
+     * foreground subagent tool.
+     */
+    profile?: Profile;
+    /** Optional extra tools for the private worker, usually read-only helpers. */
+    tools?: Tool.AnyInfo[];
+    /** Optional middleware/policy stack for the private worker's tool calls. */
+    middleware?: AgentConfig["middleware"];
+    /** Optional approval policy for private worker tools. */
+    approval?: AgentConfig["approval"];
+    /** Tool execution mode for the private worker. */
+    toolExecutionMode?: AgentConfig["toolExecutionMode"];
+    /** Capture worker system prompt. `{basePrompt}` works when overridden by a profile. */
+    systemPrompt?: string;
+    /** Override the user prompt sent to the private worker. */
+    prompt?: (input: AgenticMemoryCaptureInput) => string;
+    /** Override parsing of the worker response into provider memory drafts. */
+    parse?: (output: string, input: AgenticMemoryCaptureInput) => MemoryCaptureResult;
+    name?: string;
+    cwd?: string;
+    maxSteps?: number;
+    maxOutputTokens?: number;
+    temperature?: number;
+    contextWindow?: number;
+    timeoutMs?: number;
+    maxMessages?: number;
+    maxMessageChars?: number;
+    maxPromptChars?: number;
+}
+declare function createAgenticMemoryCapture(options: AgenticMemoryCaptureOptions): AgenticMemoryCaptureFunction;
+
+interface AgenticMemoryRecallRuntime {
+    search(input: {
+        cwd: string;
+        query: string;
+        limit: number;
+        scope?: AgentMemoryScope;
+        tags?: string[];
+    }): Promise<AgentMemoryRecord[]> | AgentMemoryRecord[];
+    list?(input: {
+        cwd: string;
+        limit: number;
+        scope?: AgentMemoryScope;
+        tags?: string[];
+    }): Promise<AgentMemoryRecord[]> | AgentMemoryRecord[];
+    get(input: {
+        cwd: string;
+        id: string;
+        scope?: AgentMemoryScope;
+    }): Promise<AgentMemoryRecord | undefined> | AgentMemoryRecord | undefined;
+}
+declare function runAgenticMemoryRecall(options: {
+    input: AgentMemoryRecallInput;
+    runtime: AgenticMemoryRecallRuntime;
+    recall: AgenticMemoryRecallOptions;
+}): Promise<AgentMemoryRecallResult>;
+
+interface FilesystemMemorySearchEngineOptions extends DefaultMemoryTokenizerOptions {
+    tokenizer?: MemoryTokenizer;
+    snippetContextLines?: number;
+    maxSnippetLines?: number;
+}
+declare function createFilesystemMemorySearchEngine(options?: FilesystemMemorySearchEngineOptions): MemorySearchEngine;
+
+export { type AgenticMemoryCaptureInput, type AgenticMemoryCaptureOptions, type AgenticMemoryRecallOptions, type AgenticMemoryRecallRuntime, type DefaultMemoryTokenizerOptions, type FilesystemMemorySearchEngineOptions, type MemoryCaptureResult, type MemoryCompactionCapture, type MemoryDraft, type MemoryProviderOptions, type MemoryProviderRecallOptions, type MemoryProviderRememberOptions, type MemorySearchEngine, type MemoryTokenizer, type MemoryTurnCapture, createAgenticMemoryCapture, createDefaultMemoryTokenizer, createFilesystemMemoryProvider, createFilesystemMemorySearchEngine, createMemoryProvider, runAgenticMemoryRecall };