/**
 * Agent memory integration — pre/post turn middleware for knowledge graph injection.
 *
 * Two integration points:
 *
 *   Pre-turn  (buildMemoryContext):
 *     Before invoking the LLM, query the knowledge graph for entities mentioned
 *     in the user message. Return a formatted context block (capped at maxTokens).
 *     Caller injects this into the system prompt or first message.
 *
 *   Post-turn (extractAndStoreMemory):
 *     After the LLM responds, extract new entities/facts from the turn and write
 *     them to the graph. Uses an optional lightweight LLM extract function —
 *     when absent, falls back to heuristic extraction.
 *
 * All DB operations gracefully degrade when the DB is not initialised.
 * The module is dependency-injected for testability — no hard coupling to LLM APIs.
 *
 * @module
 */
import type { AgentMessage } from "@mariozechner/pi-agent-core";
import { KnowledgeGraphSession } from "../../memory/knowledge-graph.js";
import type { ObjectType } from "../../memory/knowledge-graph.js";
export type ExtractedItem = {
    label: string;
    type: ObjectType;
    data?: Record<string, unknown>;
};
/** Lightweight LLM function used for post-turn extraction. */
export type ExtractFn = (userMessage: string, assistantResponse: string) => Promise<ExtractedItem[]>;
export type MemoryContextResult = {
    /** Formatted text block for injection into system prompt or message context. */
    contextBlock: string;
    /** Estimated token count of the context block. */
    tokenCount: number;
    /** Number of memory objects referenced in the block. */
    objectCount: number;
};
export type MemoryIntegrationOptions = {
    /** Maximum token budget for the injected context block. Default: 500. */
    maxTokens?: number;
    /** Maximum number of related objects to traverse per entity. Default: 5. */
    maxRelated?: number;
};
/**
 * Extract potential entity names mentioned in a user message.
 * Uses capitalised word sequences as a proxy for proper nouns.
 */
export declare function detectEntityMentions(message: string): string[];
/**
 * Build a memory context block for injection before an LLM call.
 *
 * Queries the knowledge graph for entities mentioned in the user message.
 * Truncates to maxTokens to stay within context budget.
 * Returns an empty block when the DB is not ready.
 *
 * @example
 * const ctx = buildMemoryContext("Tell me about prod-01", { maxTokens: 500 });
 * if (ctx.contextBlock) {
 *   systemPrompt += "\n\n## Memory Context\n" + ctx.contextBlock;
 * }
 */
export declare function buildMemoryContext(userMessage: string, session: KnowledgeGraphSession, opts?: MemoryIntegrationOptions): MemoryContextResult;
/**
 * Extract new memory objects from a completed turn and write them to the graph.
 *
 * When extractFn is provided (LLM-based extraction), it's called with the turn.
 * Falls back to heuristic extraction when absent.
 *
 * Post-extracted entities are linked to any pre-existing related entities found
 * in the same message via `related_to` edges.
 *
 * @param userMessage     The user's message text
 * @param assistantResponse  The assistant's response text
 * @param extractFn       Optional LLM extraction function
 * @returns Count of objects written to the graph
 */
export declare function extractAndStoreMemory(userMessage: string, assistantResponse: string, session: KnowledgeGraphSession, extractFn?: ExtractFn): Promise<number>;
/**
 * Extract the text content of the last assistant message from a messages array.
 * Returns empty string if no assistant message is found.
 */
export declare function extractLastAssistantText(messages: AgentMessage[]): string;
/**
 * Summarise the current knowledge graph state for diagnostics.
 */
export declare function getMemoryStats(): Record<string, number>;
/**
 * Detect whether an assistant response signals successful task completion.
 *
 * Looks for common completion phrases. Intentionally conservative to avoid
 * false positives — only fires on unambiguous success language.
 */
export declare function detectTaskSuccess(assistantResponse: string): boolean;
/**
 * Record a successful task as a `Skill` memory object in the knowledge graph.
 *
 * Called from the post-turn hook when a success signal is detected.
 * Stores the task description, tool sequence, and outcome as a searchable
 * `skill` memory object. Future tasks of the same type can retrieve this
 * via `searchFacts({ query: taskType, type: "skill" })`.
 *
 * @param taskDescription  Short description of what was accomplished
 * @param toolSequence     Ordered list of tool names used (can be empty)
 * @param session          Active knowledge graph session
 * @returns The id of the created memory object, or undefined on failure
 */
export declare function recordSkillSuccess(params: {
    taskDescription: string;
    toolSequence: string[];
    session: KnowledgeGraphSession;
}): string | undefined;
