@agntk/core 0.1.0

package/dist/guardrails/runner.js

@@ -0,0 +1,148 @@
+/**
+ * @fileoverview Guardrail runner with parallel execution and fast-fail.
+ */
+import { createLogger } from '@agntk/logger';
+import { GuardrailBlockedError } from './types.js';
+const log = createLogger('@agntk/core:guardrails');
+// ============================================================================
+// Parallel Runner
+// ============================================================================
+/**
+ * Run guardrails sequentially so each filter operates on the previous filter's output.
+ *
+ * This prevents a bug where parallel execution causes each guardrail to produce
+ * `.filtered` from the original text independently — if guardrail A redacts PII
+ * and guardrail B truncates, the truncated version could leak PII because B never
+ * saw A's redaction.
+ *
+ * Sequential execution ensures filter composition: A redacts → B truncates the
+ * already-redacted text.
+ */
+export async function runGuardrails(guardrails, text, context) {
+    if (guardrails.length === 0)
+        return { results: [], filteredText: text };
+    const results = [];
+    let currentText = text;
+    for (const guard of guardrails) {
+        try {
+            const result = await guard.check(currentText, context);
+            results.push(result);
+            // Chain: each filter operates on the previous filter's output
+            if (!result.passed && result.filtered) {
+                currentText = result.filtered;
+            }
+        }
+        catch (error) {
+            log.error('Guardrail threw', { name: guard.name, error: String(error) });
+            results.push({
+                passed: false,
+                name: guard.name,
+                message: `Guardrail error: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    return { results, filteredText: currentText };
+}
+/**
+ * Check guardrail results and handle the onBlock action.
+ *
+ * @param filteredText - The text after all guardrail filters have been applied sequentially.
+ * @returns The (possibly filtered) text, or throws if blocked.
+ */
+export function handleGuardrailResults(results, text, filteredText, phase, onBlock) {
+    const allPassed = results.every((r) => r.passed);
+    if (allPassed) {
+        return { blocked: false, text, results };
+    }
+    log.info('Guardrail blocked', {
+        phase,
+        onBlock,
+        failed: results.filter((r) => !r.passed).map((r) => r.name),
+    });
+    switch (onBlock) {
+        case 'throw':
+            throw new GuardrailBlockedError(phase, results);
+        case 'filter':
+            // filteredText already has all guardrail filters applied in sequence
+            return { blocked: true, text: filteredText, results };
+        case 'retry':
+            // Signal that a retry is needed — caller handles the retry loop
+            return { blocked: true, text, results };
+        default:
+            throw new GuardrailBlockedError(phase, results);
+    }
+}
+// ============================================================================
+// Agent Wrapper
+// ============================================================================
+/**
+ * Build a guardrail feedback message for retry attempts.
+ * This is appended to the prompt when retrying after an output guardrail failure.
+ */
+export function buildRetryFeedback(results) {
+    const failed = results.filter((r) => !r.passed);
+    const lines = failed.map((r) => `- [${r.name}]: ${r.message ?? 'blocked'}`);
+    return ('\n\n[GUARDRAIL FEEDBACK] Your previous response was blocked. Please regenerate, addressing:\n' +
+        lines.join('\n'));
+}
+/**
+ * Wrap an agent's generate function with guardrail checks.
+ *
+ * Input guardrails run before the agent; output guardrails run after.
+ * Both phases run their guardrails in parallel.
+ */
+export function wrapWithGuardrails(generateFn, config) {
+    const { input: inputGuards = [], output: outputGuards = [], onBlock = 'throw', maxRetries = 2 } = config;
+    return async (input) => {
+        // ─── Input Guardrails ───────────────────────────────────────────────
+        if (inputGuards.length > 0) {
+            const { results: inputResults, filteredText: inputFiltered } = await runGuardrails(inputGuards, input.prompt, {
+                prompt: input.prompt,
+                phase: 'input',
+            });
+            const inputCheck = handleGuardrailResults(inputResults, input.prompt, inputFiltered, 'input', onBlock);
+            if (inputCheck.blocked && onBlock === 'filter') {
+                input = { prompt: inputCheck.text };
+            }
+            // If onBlock is 'retry' for input, we just throw (can't retry user input)
+            if (inputCheck.blocked && onBlock === 'retry') {
+                throw new GuardrailBlockedError('input', inputResults);
+            }
+        }
+        // ─── Agent Execution + Output Guardrails ────────────────────────────
+        let lastResult;
+        let attempts = 0;
+        let currentPrompt = input.prompt;
+        while (attempts <= maxRetries) {
+            lastResult = await generateFn({ prompt: currentPrompt });
+            if (outputGuards.length === 0) {
+                return lastResult;
+            }
+            const { results: outputResults, filteredText: outputFiltered } = await runGuardrails(outputGuards, lastResult.text, {
+                prompt: input.prompt,
+                phase: 'output',
+            });
+            const outputCheck = handleGuardrailResults(outputResults, lastResult.text, outputFiltered, 'output', onBlock);
+            if (!outputCheck.blocked) {
+                return lastResult;
+            }
+            if (onBlock === 'filter') {
+                return { ...lastResult, text: outputCheck.text };
+            }
+            if (onBlock === 'retry') {
+                attempts++;
+                if (attempts > maxRetries) {
+                    throw new GuardrailBlockedError('output', outputResults);
+                }
+                // Append guardrail feedback for the retry
+                currentPrompt = input.prompt + buildRetryFeedback(outputResults);
+                log.info('Retrying with guardrail feedback', { attempt: attempts, maxRetries });
+                continue;
+            }
+            // onBlock === 'throw' is handled inside handleGuardrailResults
+            break;
+        }
+        return lastResult;
+    };
+}
+//# sourceMappingURL=runner.js.map

package/dist/guardrails/runner.js.map

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

package/dist/guardrails/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Type definitions for the guardrails system.
+ */
+/**
+ * Result of a guardrail check.
+ */
+export interface GuardrailResult {
+    /** Whether the content passed the guardrail. */
+    passed: boolean;
+    /** Name of the guardrail that produced this result. */
+    name: string;
+    /** Human-readable message (populated on failure). */
+    message?: string;
+    /** Filtered/cleaned output (if the guardrail supports filtering). */
+    filtered?: string;
+}
+/**
+ * A guardrail function that validates content.
+ * Receives the text to validate and returns a result.
+ * Can be async for guardrails that call external services.
+ */
+export interface Guardrail {
+    /** Unique name for this guardrail. */
+    name: string;
+    /** Check function. Returns result or throws on unexpected errors. */
+    check: (text: string, context?: GuardrailContext) => GuardrailResult | Promise<GuardrailResult>;
+}
+/**
+ * Context passed to guardrails for richer decision-making.
+ */
+export interface GuardrailContext {
+    /** The original user prompt. */
+    prompt?: string;
+    /** Whether this is an input or output guardrail. */
+    phase: 'input' | 'output';
+}
+/**
+ * Action to take when a guardrail blocks.
+ */
+export type OnBlockAction = 'throw' | 'retry' | 'filter';
+/**
+ * Configuration for guardrails on an agent.
+ */
+export interface GuardrailsConfig {
+    /** Guardrails to run on user input (before the agent). */
+    input?: Guardrail[];
+    /** Guardrails to run on agent output (after the agent). */
+    output?: Guardrail[];
+    /** Action when a guardrail blocks. Default: 'throw'. */
+    onBlock?: OnBlockAction;
+    /** Maximum retries when onBlock is 'retry'. Default: 2. */
+    maxRetries?: number;
+}
+/**
+ * Error thrown when a guardrail blocks and onBlock is 'throw'.
+ */
+export declare class GuardrailBlockedError extends Error {
+    readonly guardrailName: string;
+    readonly phase: 'input' | 'output';
+    readonly results: GuardrailResult[];
+    constructor(phase: 'input' | 'output', results: GuardrailResult[]);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/guardrails/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/guardrails/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,MAAM,EAAE,OAAO,CAAC;IAChB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,KAAK,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACjG;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,wDAAwD;IACxD,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,aAAa,EAAE,MAAM,CAAC;IACtC,SAAgB,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1C,SAAgB,OAAO,EAAE,eAAe,EAAE,CAAC;gBAE/B,KAAK,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,eAAe,EAAE;CAUlE"}

package/dist/guardrails/types.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Type definitions for the guardrails system.
+ */
+/**
+ * Error thrown when a guardrail blocks and onBlock is 'throw'.
+ */
+export class GuardrailBlockedError extends Error {
+    guardrailName;
+    phase;
+    results;
+    constructor(phase, results) {
+        const failed = results.filter((r) => !r.passed);
+        const names = failed.map((r) => r.name).join(', ');
+        const messages = failed.map((r) => r.message).filter(Boolean).join('; ');
+        super(`Guardrail blocked (${phase}): [${names}] ${messages}`);
+        this.name = 'GuardrailBlockedError';
+        this.guardrailName = names;
+        this.phase = phase;
+        this.results = results;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/guardrails/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/guardrails/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAyDH;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9B,aAAa,CAAS;IACtB,KAAK,CAAqB;IAC1B,OAAO,CAAoB;IAE3C,YAAY,KAAyB,EAAE,OAA0B;QAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzE,KAAK,CAAC,sBAAsB,KAAK,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @agntk/core — Slim main entry point.
+ *
+ * The 80/20 exports: everything most users need.
+ * Advanced features live in sub-path imports:
+ *   - @agntk/core/workflow   — durability, hooks, teams, scheduling
+ *   - @agntk/core/tools      — tool builders, browser, spawn-agent
+ *   - @agntk/core/evals      — eval suite and assertions
+ *   - @agntk/core/advanced   — guardrail runners, best-of-n, observability, streaming internals
+ */
+export { createAgent } from './agent.js';
+export type { Agent } from './agent.js';
+export type { AgentOptions, AgentRole, ToolPreset, ModelProvider, SubAgentConfig, WorkflowOptions, MemoryOptions, StopFunction, StopContext, AskUserHandler, StepFinishCallback, StreamEventCallback, StreamEvent, } from './types/agent.js';
+export { resolveModel, models } from './models.js';
+export { loadConfig, getConfig, configure, defineConfig, getModelForTier, DEFAULT_MODELS, DEFAULT_PROVIDER, } from './config/index.js';
+export type { AgentConfig, PartialAgentConfig, ModelsConfig, ModelTier, Provider } from './config/index.js';
+export { toolPresets, createToolPreset } from './presets/tools.js';
+export type { ToolPresetLevel, ToolPresetOptions } from './presets/tools.js';
+export { roleConfigs } from './presets/roles.js';
+export type { SkillsConfig, SkillMeta, SkillContent } from './skills/index.js';
+export { loadSkills, discoverSkills } from './skills/index.js';
+export { UsageLimitExceeded, usageLimitStop } from './usage-limits.js';
+export type { UsageLimits, UsageLimitType } from './usage-limits.js';
+export type { ApprovalConfig } from './tools/approval.js';
+export type { GuardrailsConfig, Guardrail, GuardrailResult } from './guardrails/types.js';
+export type { ReflectionStrategy, ReflectionConfig } from './reflection.js';
+export type { MemoryStore, MemoryConfig } from './memory/types.js';
+export { MarkdownMemoryStore } from './memory/store.js';
+export type { MarkdownMemoryStoreOptions } from './memory/store.js';
+export { loadMemoryContext } from './memory/loader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,YAAY,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EACV,YAAY,EACZ,SAAS,EACT,UAAU,EACV,aAAa,EACb,cAAc,EACd,eAAe,EACf,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,GACZ,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAMhD,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAMnG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAChE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAM9C,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAMtD,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAMlE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAMvF,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAYzE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,35 @@
+/**
+ * @agntk/core — Slim main entry point.
+ *
+ * The 80/20 exports: everything most users need.
+ * Advanced features live in sub-path imports:
+ *   - @agntk/core/workflow   — durability, hooks, teams, scheduling
+ *   - @agntk/core/tools      — tool builders, browser, spawn-agent
+ *   - @agntk/core/evals      — eval suite and assertions
+ *   - @agntk/core/advanced   — guardrail runners, best-of-n, observability, streaming internals
+ */
+// ═══════════════════════════════════════════════════════════════════════════════
+// Core — the essentials
+// ═══════════════════════════════════════════════════════════════════════════════
+export { createAgent } from './agent.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// Models
+// ═══════════════════════════════════════════════════════════════════════════════
+export { resolveModel, models } from './models.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// Configuration
+// ═══════════════════════════════════════════════════════════════════════════════
+export { loadConfig, getConfig, configure, defineConfig, getModelForTier, DEFAULT_MODELS, DEFAULT_PROVIDER, } from './config/index.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// Presets
+// ═══════════════════════════════════════════════════════════════════════════════
+export { toolPresets, createToolPreset } from './presets/tools.js';
+export { roleConfigs } from './presets/roles.js';
+export { loadSkills, discoverSkills } from './skills/index.js';
+// ═══════════════════════════════════════════════════════════════════════════════
+// Usage Limits
+// ═══════════════════════════════════════════════════════════════════════════════
+export { UsageLimitExceeded, usageLimitStop } from './usage-limits.js';
+export { MarkdownMemoryStore } from './memory/store.js';
+export { loadMemoryContext } from './memory/loader.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kFAAkF;AAClF,wBAAwB;AACxB,kFAAkF;AAElF,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAkBtC,kFAAkF;AAClF,SAAS;AACT,kFAAkF;AAElF,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEhD,kFAAkF;AAClF,gBAAgB;AAChB,kFAAkF;AAElF,OAAO,EACL,UAAU,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,eAAe,EACf,cAAc,EACd,gBAAgB,GACjB,MAAM,UAAU,CAAC;AAGlB,kFAAkF;AAClF,UAAU;AACV,kFAAkF;AAElF,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAO9C,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAEtD,kFAAkF;AAClF,eAAe;AACf,kFAAkF;AAElF,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AA2BpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/memory/engine.d.ts

@@ -0,0 +1,130 @@
+/**
+ * @agntk/core - Unified Memory Engine
+ *
+ * Single write path: remember() → LLM extraction → parallel writes to Vectra + Graph.
+ * Implements Mem0 ADD/UPDATE/DELETE/NOOP pattern with Hindsight 4-network taxonomy.
+ *
+ * Architecture:
+ * - VectorStore: Semantic similarity search (Vectra)
+ * - GraphStore: Structural relationships (Graphology via QueryPort)
+ * - ExtractionModel: LLM-powered fact extraction
+ * - ContradictionDetector: Write-time conflict detection
+ */
+import type { LanguageModel } from 'ai';
+import type { MemoryStore, MemorySearchResult } from './vectra-store.js';
+import { type ExtractedFact, type MemoryOperation } from './extraction.js';
+/** Graph store interface — matches QueryPort episode/entity methods */
+export interface MemoryGraphStore {
+    upsertEpisode(episode: {
+        id: string;
+        timestamp: string;
+        type: 'conversation' | 'observation' | 'action' | 'decision' | 'learning';
+        summary: string;
+        content: string;
+        entities: string[];
+        relationships: string[];
+    }): Promise<void>;
+    linkEpisodeEntity(episodeId: string, entityName: string): Promise<void>;
+    getEpisodesByQuery(query: string, limit: number): Promise<Array<{
+        id?: string;
+        summary?: string;
+        content?: string;
+        timestamp?: string;
+        type?: string;
+        properties?: Record<string, unknown>;
+    }>>;
+    upsertContradiction(contradiction: {
+        id: string;
+        detectedAt: string;
+        resolution_winner: string | null;
+        resolution_reasoning: string | null;
+        factA_id: string;
+        factA_statement: string;
+        factA_source: string;
+        factA_timestamp: string;
+        factB_id: string;
+        factB_statement: string;
+        factB_source: string;
+        factB_timestamp: string;
+    }): Promise<void>;
+}
+/** Contradiction detector interface — matches brain's ContradictionDetector */
+export interface ContradictionDetectorPort {
+    detect(statementA: string, statementB: string, metadataA?: {
+        id: string;
+        source: string;
+        timestamp: string;
+    }, metadataB?: {
+        id: string;
+        source: string;
+        timestamp: string;
+    }): {
+        id: string;
+        factA: Record<string, string>;
+        factB: Record<string, string>;
+        detectedAt: string;
+    } | null;
+}
+/** Result of a unified remember() operation */
+export interface MemoryWriteResult {
+    id: string;
+    operation: MemoryOperation;
+    facts: ExtractedFact[];
+    vectorStoreId?: string;
+    graphStoreId?: string;
+    contradiction?: {
+        id: string;
+        existingFact: string;
+        newFact: string;
+    };
+}
+/** Configuration for the unified memory engine */
+export interface MemoryEngineConfig {
+    /** Vector store for semantic search (Vectra) */
+    vectorStore: MemoryStore;
+    /** Graph store for structural queries (Graphology via QueryPort) — optional */
+    graphStore?: MemoryGraphStore;
+    /** LLM for extraction pipeline — optional, extraction disabled without it */
+    extractionModel?: LanguageModel;
+    /** Contradiction detector — optional */
+    contradictionDetector?: ContradictionDetectorPort;
+    /** Default top-K for recall */
+    defaultTopK?: number;
+    /** Default similarity threshold */
+    defaultThreshold?: number;
+}
+/** The unified memory engine interface */
+export interface MemoryEngine {
+    /** Store text with LLM extraction → parallel writes to vector + graph */
+    remember(text: string, metadata?: Record<string, unknown>): Promise<MemoryWriteResult>;
+    /** Semantic search via vector store */
+    recall(query: string, options?: {
+        topK?: number;
+        threshold?: number;
+    }): Promise<MemorySearchResult[]>;
+    /** Graph-based knowledge query — returns episodes/entities matching query */
+    queryKnowledge(query: string, limit?: number): Promise<Array<Record<string, unknown>>>;
+    /** Remove a memory by ID from both stores */
+    forget(id: string): Promise<boolean>;
+    /** Get stats */
+    count(): Promise<number>;
+    /** Cleanup */
+    close(): Promise<void>;
+}
+/**
+ * Create a unified memory engine.
+ *
+ * @example
+ * ```typescript
+ * const engine = createMemoryEngine({
+ *   vectorStore: await createMemoryStore({ path: './.memory' }),
+ *   graphStore: new GraphologyAdapter(),
+ *   extractionModel: openai('gpt-4o-mini'),
+ * });
+ *
+ * // Single remember() does extraction + parallel writes
+ * const result = await engine.remember('TypeScript 5.3 supports import attributes');
+ * ```
+ */
+export declare function createMemoryEngine(config: MemoryEngineConfig): MemoryEngine;
+//# sourceMappingURL=engine.d.ts.map

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

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