@lleverage-ai/agent-sdk 0.0.1

package/dist/memory/loader.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Memory loading functions for agent memory system.
+ *
+ * Implements the two-tier memory architecture:
+ * - **User-Level Memory**: `~/.deepagents/{agentId}/agent.md`
+ * - **Project-Level Memory**: `[git-root]/.deepagents/agent.md`
+ *
+ * Also supports loading additional memory files from the user's agent directory.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   loadAgentMemory,
+ *   loadAdditionalMemoryFiles,
+ *   buildMemorySection,
+ * } from "@lleverage-ai/agent-sdk";
+ *
+ * // Load user-level memory
+ * const userMemory = await loadAgentMemory("~/.deepagents/my-agent/agent.md");
+ *
+ * // Load all additional files from user directory
+ * const additional = await loadAdditionalMemoryFiles("~/.deepagents/my-agent");
+ *
+ * // Build a formatted memory section for the prompt
+ * const section = buildMemorySection(userMemory, projectMemory, additional);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { MemoryPermissionStore } from "./permissions.js";
+import type { MemoryDocument, MemoryMetadata, MemoryStore } from "./store.js";
+/**
+ * Options for loading agent memory.
+ *
+ * @category Memory
+ */
+export interface LoadAgentMemoryOptions {
+    /**
+     * Custom memory store to use.
+     * Defaults to FilesystemMemoryStore.
+     */
+    store?: MemoryStore;
+    /**
+     * Override home directory for ~ expansion.
+     */
+    homeDir?: string;
+}
+/**
+ * Options for loading additional memory files.
+ *
+ * @category Memory
+ */
+export interface LoadAdditionalMemoryOptions {
+    /**
+     * Custom memory store to use.
+     * Defaults to FilesystemMemoryStore.
+     */
+    store?: MemoryStore;
+    /**
+     * File to exclude (usually agent.md).
+     * @defaultValue ["agent.md"]
+     */
+    exclude?: string[];
+    /**
+     * Override home directory for ~ expansion.
+     */
+    homeDir?: string;
+}
+/**
+ * Result from loading additional memory files.
+ *
+ * @category Memory
+ */
+export interface AdditionalMemoryFile {
+    /**
+     * Filename without path.
+     */
+    filename: string;
+    /**
+     * Full content of the file.
+     */
+    content: string;
+    /**
+     * Parsed metadata from frontmatter.
+     */
+    metadata: MemoryMetadata;
+}
+/**
+ * Load a single agent memory file.
+ *
+ * Reads the file, parses YAML frontmatter, and returns the document.
+ *
+ * @param filePath - Path to the memory file
+ * @param options - Loading options
+ * @returns The memory content, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const memory = await loadAgentMemory("~/.deepagents/my-agent/agent.md");
+ * if (memory) {
+ *   console.log(memory.content);
+ * }
+ * ```
+ *
+ * @category Memory
+ */
+export declare function loadAgentMemory(filePath: string, options?: LoadAgentMemoryOptions): Promise<MemoryDocument | undefined>;
+/**
+ * Load all additional memory files from a directory.
+ *
+ * Scans the directory for .md files (excluding agent.md by default)
+ * and returns their content.
+ *
+ * @param dirPath - Path to the agent memory directory
+ * @param options - Loading options
+ * @returns Array of additional memory file content
+ *
+ * @example
+ * ```typescript
+ * const files = await loadAdditionalMemoryFiles("~/.deepagents/my-agent");
+ * for (const file of files) {
+ *   console.log(`${file.filename}: ${file.content.slice(0, 100)}...`);
+ * }
+ * ```
+ *
+ * @category Memory
+ */
+export declare function loadAdditionalMemoryFiles(dirPath: string, options?: LoadAdditionalMemoryOptions): Promise<AdditionalMemoryFile[]>;
+/**
+ * Find the git root directory from a given path.
+ *
+ * @param fromPath - Starting path to search from
+ * @returns The git root path, or undefined if not in a git repo
+ *
+ * @example
+ * ```typescript
+ * const gitRoot = await findGitRoot("/path/to/project/src/file.ts");
+ * // Returns "/path/to/project" if that's the git root
+ * ```
+ *
+ * @category Memory
+ */
+export declare function findGitRoot(fromPath: string): Promise<string | undefined>;
+/**
+ * Get the project memory path based on git root.
+ *
+ * @param workingDirectory - Current working directory
+ * @returns Path to project memory file, or undefined if not in git repo
+ *
+ * @example
+ * ```typescript
+ * const projectMemoryPath = await getProjectMemoryPath("/path/to/project");
+ * // Returns "/path/to/project/.deepagents/agent.md"
+ * ```
+ *
+ * @category Memory
+ */
+export declare function getProjectMemoryPath(workingDirectory: string): Promise<string | undefined>;
+/**
+ * Get the user memory path for an agent.
+ *
+ * @param agentId - The agent identifier
+ * @param homeDir - Optional home directory override
+ * @returns Path to user memory file
+ *
+ * @example
+ * ```typescript
+ * const userMemoryPath = getUserMemoryPath("my-agent");
+ * // Returns "/home/user/.deepagents/my-agent/agent.md"
+ * ```
+ *
+ * @category Memory
+ */
+export declare function getUserMemoryPath(agentId: string, homeDir?: string): string;
+/**
+ * Get the user agent directory for an agent.
+ *
+ * @param agentId - The agent identifier
+ * @param homeDir - Optional home directory override
+ * @returns Path to user agent directory
+ *
+ * @category Memory
+ */
+export declare function getUserAgentDir(agentId: string, homeDir?: string): string;
+/**
+ * Options for building the memory section.
+ *
+ * @category Memory
+ */
+export interface BuildMemorySectionOptions {
+    /**
+     * Header for the user memory section.
+     * @defaultValue "# User Memory"
+     */
+    userHeader?: string;
+    /**
+     * Header for the project memory section.
+     * @defaultValue "# Project Memory"
+     */
+    projectHeader?: string;
+    /**
+     * Header for additional files section.
+     * @defaultValue "# Additional Context"
+     */
+    additionalHeader?: string;
+    /**
+     * Include file names as subheaders for additional files.
+     * @defaultValue true
+     */
+    includeFilenames?: boolean;
+}
+/**
+ * Build a formatted memory section for injection into prompts.
+ *
+ * Combines user memory, project memory, and additional files into
+ * a single formatted string suitable for system prompt injection.
+ *
+ * @param userMemory - User-level memory document
+ * @param projectMemory - Project-level memory document
+ * @param additionalFiles - Additional memory files
+ * @param options - Formatting options
+ * @returns Formatted memory section string
+ *
+ * @example
+ * ```typescript
+ * const userMemory = await loadAgentMemory("~/.deepagents/agent/agent.md");
+ * const projectMemory = await loadAgentMemory("/project/.deepagents/agent.md");
+ * const additional = await loadAdditionalMemoryFiles("~/.deepagents/agent");
+ *
+ * const section = buildMemorySection(userMemory, projectMemory, additional);
+ * const systemPrompt = `You are a helpful assistant.\n\n${section}`;
+ * ```
+ *
+ * @category Memory
+ */
+export declare function buildMemorySection(userMemory: MemoryDocument | undefined, projectMemory: MemoryDocument | undefined, additionalFiles: AdditionalMemoryFile[], options?: BuildMemorySectionOptions): string;
+/**
+ * Audit event emitted when memory is loaded.
+ *
+ * @category Memory
+ */
+export interface MemoryAuditEvent {
+    /**
+     * Event type.
+     */
+    type: "memory_loaded" | "memory_approval_requested" | "memory_approval_denied" | "memory_content_changed";
+    /**
+     * Path to the memory file.
+     */
+    path: string;
+    /**
+     * Content hash of the memory file.
+     */
+    contentHash: string;
+    /**
+     * Whether the load was approved.
+     */
+    approved: boolean;
+    /**
+     * Timestamp (Unix ms).
+     */
+    timestamp: number;
+    /**
+     * Agent ID that loaded the memory.
+     */
+    agentId: string;
+    /**
+     * Previous content hash (for change detection).
+     */
+    previousHash?: string;
+}
+/**
+ * Options for loading all agent memory.
+ *
+ * @category Memory
+ */
+export interface LoadAllMemoryOptions {
+    /**
+     * Unique identifier for the agent.
+     */
+    agentId: string;
+    /**
+     * Working directory for project memory detection.
+     * @defaultValue process.cwd()
+     */
+    workingDirectory?: string;
+    /**
+     * Custom home directory override.
+     */
+    homeDir?: string;
+    /**
+     * Custom memory store.
+     */
+    store?: MemoryStore;
+    /**
+     * Memory permission store for approval persistence.
+     *
+     * When provided, approval decisions are persisted and checked on each load.
+     * If the file content has changed since approval, re-approval is required.
+     */
+    permissionStore?: MemoryPermissionStore;
+    /**
+     * Callback to request project memory approval.
+     *
+     * Project-level memory may contain sensitive instructions.
+     * Use this callback to implement approval workflows.
+     *
+     * When permissionStore is provided:
+     * - This callback is only invoked if the file is not approved or has changed
+     * - Approval is automatically persisted when granted
+     */
+    requestProjectApproval?: (projectPath: string, contentHash: string, previousHash?: string) => Promise<boolean>;
+    /**
+     * Callback for audit events.
+     *
+     * Called when memory is loaded, approval is requested, or content changes are detected.
+     * Use this to integrate with audit logging systems or hooks.
+     */
+    onAuditEvent?: (event: MemoryAuditEvent) => void | Promise<void>;
+}
+/**
+ * Result from loading all agent memory.
+ *
+ * @category Memory
+ */
+export interface LoadAllMemoryResult {
+    /**
+     * User-level memory document.
+     */
+    userMemory: MemoryDocument | undefined;
+    /**
+     * Project-level memory document.
+     */
+    projectMemory: MemoryDocument | undefined;
+    /**
+     * Additional memory files.
+     */
+    additionalFiles: AdditionalMemoryFile[];
+    /**
+     * Whether project memory was approved.
+     */
+    projectApproved: boolean;
+    /**
+     * Built memory section for prompt injection.
+     */
+    memorySection: string;
+}
+/**
+ * Load all agent memory (user, project, and additional files).
+ *
+ * This is the main entry point for loading agent memory.
+ * It handles the two-tier architecture, approval workflow, and change detection.
+ *
+ * @param options - Loading options
+ * @returns Complete memory loading result
+ *
+ * @example Basic usage
+ * ```typescript
+ * const memory = await loadAllMemory({
+ *   agentId: "my-agent",
+ *   workingDirectory: "/path/to/project",
+ *   requestProjectApproval: async (path, hash, previousHash) => {
+ *     if (previousHash) {
+ *       console.log(`Memory file ${path} has changed!`);
+ *     }
+ *     return confirm(`Load project memory from ${path}?`);
+ *   },
+ * });
+ *
+ * // Use in system prompt
+ * const systemPrompt = `You are a helpful assistant.\n\n${memory.memorySection}`;
+ * ```
+ *
+ * @example With permission persistence and audit logging
+ * ```typescript
+ * import { createMemoryPermissionStore } from "@lleverage-ai/agent-sdk";
+ *
+ * const permStore = createMemoryPermissionStore();
+ *
+ * const memory = await loadAllMemory({
+ *   agentId: "my-agent",
+ *   permissionStore: permStore,
+ *   requestProjectApproval: async (path, hash, previousHash) => {
+ *     // Only called if not approved or content changed
+ *     return confirm(`Approve ${path}?`);
+ *   },
+ *   onAuditEvent: (event) => {
+ *     console.log("Memory audit:", event);
+ *   },
+ * });
+ * ```
+ *
+ * @category Memory
+ */
+export declare function loadAllMemory(options: LoadAllMemoryOptions): Promise<LoadAllMemoryResult>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/memory/loader.d.ts.map

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