/** Persistent memory scope: where the agent's MEMORY.md lives. */
export type MemoryScope = "user" | "project" | "local";
/** Memory file name inside the per-agent memory dir. */
export declare const MEMORY_FILE_NAME = "MEMORY.md";
/** Max lines of MEMORY.md injected into the system prompt (benchmark: 200). */
export declare const MEMORY_MAX_LINES = 200;
/** Header of the injected memory block. */
export declare const MEMORY_BLOCK_HEADER = "[AGENT MEMORY \u2014 PERSISTENT]";
/** Marker appended when the memory file exceeds the line budget. */
export declare const MEMORY_TRUNCATION_MARKER = "[memory truncated";
/**
 * True when the agent name is unsafe to embed in a memory path (empty, too
 * long, or outside the whitelist — blocks `../` traversal, separators,
 * absolute shapes, and hidden-dot names).
 */
export declare function isUnsafeName(name: string): boolean;
/**
 * Validate a frontmatter `memory:` value into a MemoryScope. Anything other
 * than `user` | `project` | `local` (including absent) degrades to undefined
 * (memory disabled) — garbage never crashes discovery.
 */
export declare function parseMemoryScope(value: string | undefined): MemoryScope | undefined;
/**
 * Resolve the per-agent memory dir for a scope (see module header for the
 * three exact locations). `agentDir` overrides the user-scope root (the global
 * agent dir); it defaults to `~/.pi/agent`. Throws on unsafe agent names and
 * unknown scopes — callers de-grade to a warning, never traverse.
 */
export declare function resolveMemoryDir(scope: MemoryScope, agentName: string, cwd: string, agentDir?: string): string;
/**
 * Safely read `<memoryDir>/MEMORY.md`. Returns undefined when the dir or file
 * is absent. THROWS when the memory dir or the memory file is a symlink —
 * symlinked memory is an attack surface (reads through links to arbitrary
 * targets) and is refused outright (lstat, never follow).
 */
export declare function safeMemoryRead(memoryDir: string): string | undefined;
/**
 * Ensure the memory dir exists (mkdir recursive). Refuses symlinked targets:
 * an existing symlink at the memory-dir path is never written through, and a
 * post-mkdir re-check guards the create race. Returns the dir.
 */
export declare function ensureMemoryDir(memoryDir: string): string;
/** Options for `buildMemoryBlock`. */
export interface MemoryBlockOptions {
    /** True when the agent has NO write/edit tools: consult-only memory. */
    readOnly?: boolean;
}
/**
 * Build the memory block appended to the agent SYSTEM PROMPT: header + access
 * mode + MEMORY.md content (truncated to MEMORY_MAX_LINES) + format
 * instructions. `readOnly: true` produces the explicit consult-only block for
 * agents without write/edit tools. Read errors (symlinks, unsafe paths)
 * propagate — the dispatch layer degrades to a warning, never a crash.
 */
export declare function buildMemoryBlock(memoryDir: string, options?: MemoryBlockOptions): string;