@framers/agentos 0.1.101 → 0.1.102

package/dist/memory/facade/types.d.ts.map

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

package/dist/memory/facade/types.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Public API types for the Memory facade.
+ *
+ * These types form the stable, public-facing contract for the Memory subsystem.
+ * They are intentionally independent of internal cognitive-science machinery so
+ * consumers only need to import from this file rather than from deep internals.
+ *
+ * @module memory/facade/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/memory/facade/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/memory/facade/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/memory/feedback/RetrievalFeedbackSignal.d.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Retrieval feedback signal — detects which injected memory
+ * traces were actually used vs ignored by the LLM response.
+ *
+ * ## Why this exists
+ * When the memory system injects context traces into a prompt, not all of
+ * them will be relevant to the model's generated response.  Tracking which
+ * memories were actually referenced allows the spaced-repetition engine to:
+ * - Reinforce genuinely helpful memories (via `updateOnRetrieval`).
+ * - Accelerate decay on repeatedly-ignored memories (via `penalizeUnused`).
+ *
+ * ## Detection heuristic
+ * A keyword overlap heuristic is used instead of a full LLM call to keep
+ * the feedback loop non-blocking and low-latency:
+ *   1. Extract unique words > 4 characters from each trace's content.
+ *   2. Check how many of those keywords appear in the LLM's response.
+ *   3. If matchRatio > 0.30 → signal = 'used', otherwise 'ignored'.
+ *
+ * An optional `similarityFn` can be injected for higher-fidelity semantic
+ * detection, but is not required for the default path.
+ *
+ * ## Persistence
+ * Each feedback event is written synchronously to the `retrieval_feedback`
+ * table in the agent's `SqliteBrain`.  The `detect()` method therefore
+ * requires that a corresponding row exists in `memory_traces` for every
+ * trace passed in (i.e. the trace must already be persisted).
+ *
+ * @module agentos/memory/feedback/RetrievalFeedbackSignal
+ */
+import type { MemoryTrace } from '../types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+/**
+ * A single retrieval feedback event for one memory trace.
+ *
+ * `signal`:
+ * - `'used'`    — the LLM's response contained enough keywords from this trace
+ *                 to be considered referenced (matchRatio > 0.30).
+ * - `'ignored'` — the LLM did not appear to use this trace in its response.
+ *
+ * `context` carries the query or situational description that was active at
+ * feedback time.  Stored in the `query` column of `retrieval_feedback`.
+ */
+export interface RetrievalFeedback {
+    /** The ID of the memory trace this feedback relates to. */
+    traceId: string;
+    /** Whether the trace was referenced by the LLM response. */
+    signal: 'used' | 'ignored';
+    /** Optional contextual string (e.g. the original user query). */
+    context?: string;
+    /** Unix ms timestamp when the feedback was recorded. */
+    timestamp: number;
+}
+/**
+ * Detects which injected memory traces were used vs ignored by the LLM, and
+ * persists those signals to the `retrieval_feedback` table.
+ *
+ * **Lifecycle:**
+ * 1. Before generation: retrieve relevant traces and inject them into the prompt.
+ * 2. After response delivery (non-blocking): call `detect(injectedTraces, response)`.
+ * 3. The decay pipeline reads `getStats(traceId)` during consolidation and
+ *    applies `penalizeUnused` / `updateOnRetrieval` accordingly.
+ */
+export declare class RetrievalFeedbackSignal {
+    private readonly brain;
+    private readonly similarityFn?;
+    /**
+     * @param brain        - The agent's SQLite brain; used to persist and query feedback rows.
+     * @param similarityFn - Optional semantic similarity function for higher-fidelity detection.
+     *   Receives two strings and returns a promise of a similarity score in [0, 1].
+     *   When provided, the score supplements the keyword heuristic, but the
+     *   current implementation uses the keyword path only (reserved for future use).
+     */
+    constructor(brain: SqliteBrain, similarityFn?: ((a: string, b: string) => Promise<number>) | undefined);
+    /**
+     * Detect which of the injected traces were referenced in `response`, persist
+     * the signals to `retrieval_feedback`, and return the full feedback array.
+     *
+     * **Keyword heuristic:**
+     * - Extract all words > 4 characters from each trace's `content` field,
+     *   lowercased and stripped of non-alphanumeric characters.
+     * - Compute `matchRatio = (words found in response) / (unique keywords)`.
+     * - Signal = `'used'` if matchRatio > 0.30, else `'ignored'`.
+     *
+     * When a trace has no qualifying keywords (all words ≤ 4 characters), it is
+     * treated as `'ignored'` — there is nothing to match against.
+     *
+     * **Note:** `detect()` is synchronous under the hood (better-sqlite3) but
+     * declared `async` to allow future replacement with an LLM-backed detector.
+     *
+     * @param injectedTraces - Memory traces that were injected into the prompt.
+     * @param response       - The LLM's generated response text.
+     * @returns Array of `RetrievalFeedback` events, one per injected trace.
+     */
+    detect(injectedTraces: MemoryTrace[], response: string): Promise<RetrievalFeedback[]>;
+    /**
+     * Retrieve the feedback history for a single trace, ordered by most-recent
+     * first.
+     *
+     * @param traceId - The memory trace ID to look up.
+     * @param limit   - Maximum number of rows to return.  Defaults to 100.
+     * @returns Array of `RetrievalFeedback` events, most-recent first.
+     */
+    getHistory(traceId: string, limit?: number): RetrievalFeedback[];
+    /**
+     * Return aggregate counts of `'used'` and `'ignored'` signals for a trace.
+     *
+     * Useful for the consolidation pipeline to decide whether to apply
+     * `penalizeUnused` (many ignores) or `updateOnRetrieval` (many used).
+     *
+     * @param traceId - The memory trace ID to aggregate.
+     * @returns `{ used, ignored }` counts.
+     */
+    getStats(traceId: string): {
+        used: number;
+        ignored: number;
+    };
+    /**
+     * Extract unique keywords from a text string.
+     *
+     * A keyword is any word that:
+     * - Has more than 4 characters after stripping non-alphanumeric characters.
+     * - Is lowercased.
+     *
+     * Short stop-words (≤ 4 chars) are excluded because they appear in almost
+     * every response and would inflate `matchRatio` without providing signal.
+     *
+     * @param text - The source text (typically a trace's `content` field).
+     * @returns Deduplicated array of lowercase keywords longer than 4 characters.
+     */
+    private _extractKeywords;
+}
+//# sourceMappingURL=RetrievalFeedbackSignal.d.ts.map

package/dist/memory/feedback/RetrievalFeedbackSignal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RetrievalFeedbackSignal.d.ts","sourceRoot":"","sources":["../../../src/memory/feedback/RetrievalFeedbackSignal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAM3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAmBD;;;;;;;;;GASG;AACH,qBAAa,uBAAuB;IAShC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAThC;;;;;;OAMG;gBAEgB,KAAK,EAAE,WAAW,EAClB,YAAY,CAAC,GAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,aAAA;IAO3E;;;;;;;;;;;;;;;;;;;OAmBG;IACG,MAAM,CACV,cAAc,EAAE,WAAW,EAAE,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAkC/B;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,iBAAiB,EAAE;IAmB7D;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAyB5D;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gBAAgB;CAUzB"}

package/dist/memory/feedback/RetrievalFeedbackSignal.js

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Retrieval feedback signal — detects which injected memory
+ * traces were actually used vs ignored by the LLM response.
+ *
+ * ## Why this exists
+ * When the memory system injects context traces into a prompt, not all of
+ * them will be relevant to the model's generated response.  Tracking which
+ * memories were actually referenced allows the spaced-repetition engine to:
+ * - Reinforce genuinely helpful memories (via `updateOnRetrieval`).
+ * - Accelerate decay on repeatedly-ignored memories (via `penalizeUnused`).
+ *
+ * ## Detection heuristic
+ * A keyword overlap heuristic is used instead of a full LLM call to keep
+ * the feedback loop non-blocking and low-latency:
+ *   1. Extract unique words > 4 characters from each trace's content.
+ *   2. Check how many of those keywords appear in the LLM's response.
+ *   3. If matchRatio > 0.30 → signal = 'used', otherwise 'ignored'.
+ *
+ * An optional `similarityFn` can be injected for higher-fidelity semantic
+ * detection, but is not required for the default path.
+ *
+ * ## Persistence
+ * Each feedback event is written synchronously to the `retrieval_feedback`
+ * table in the agent's `SqliteBrain`.  The `detect()` method therefore
+ * requires that a corresponding row exists in `memory_traces` for every
+ * trace passed in (i.e. the trace must already be persisted).
+ *
+ * @module agentos/memory/feedback/RetrievalFeedbackSignal
+ */
+// ---------------------------------------------------------------------------
+// RetrievalFeedbackSignal
+// ---------------------------------------------------------------------------
+/**
+ * Detects which injected memory traces were used vs ignored by the LLM, and
+ * persists those signals to the `retrieval_feedback` table.
+ *
+ * **Lifecycle:**
+ * 1. Before generation: retrieve relevant traces and inject them into the prompt.
+ * 2. After response delivery (non-blocking): call `detect(injectedTraces, response)`.
+ * 3. The decay pipeline reads `getStats(traceId)` during consolidation and
+ *    applies `penalizeUnused` / `updateOnRetrieval` accordingly.
+ */
+export class RetrievalFeedbackSignal {
+    /**
+     * @param brain        - The agent's SQLite brain; used to persist and query feedback rows.
+     * @param similarityFn - Optional semantic similarity function for higher-fidelity detection.
+     *   Receives two strings and returns a promise of a similarity score in [0, 1].
+     *   When provided, the score supplements the keyword heuristic, but the
+     *   current implementation uses the keyword path only (reserved for future use).
+     */
+    constructor(brain, similarityFn) {
+        this.brain = brain;
+        this.similarityFn = similarityFn;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Detect which of the injected traces were referenced in `response`, persist
+     * the signals to `retrieval_feedback`, and return the full feedback array.
+     *
+     * **Keyword heuristic:**
+     * - Extract all words > 4 characters from each trace's `content` field,
+     *   lowercased and stripped of non-alphanumeric characters.
+     * - Compute `matchRatio = (words found in response) / (unique keywords)`.
+     * - Signal = `'used'` if matchRatio > 0.30, else `'ignored'`.
+     *
+     * When a trace has no qualifying keywords (all words ≤ 4 characters), it is
+     * treated as `'ignored'` — there is nothing to match against.
+     *
+     * **Note:** `detect()` is synchronous under the hood (better-sqlite3) but
+     * declared `async` to allow future replacement with an LLM-backed detector.
+     *
+     * @param injectedTraces - Memory traces that were injected into the prompt.
+     * @param response       - The LLM's generated response text.
+     * @returns Array of `RetrievalFeedback` events, one per injected trace.
+     */
+    async detect(injectedTraces, response) {
+        const responseLower = response.toLowerCase();
+        const feedbacks = [];
+        const now = Date.now();
+        const insertStmt = this.brain.db.prepare(`INSERT INTO retrieval_feedback (trace_id, signal, query, created_at)
+       VALUES (?, ?, ?, ?)`);
+        for (const trace of injectedTraces) {
+            const keywords = this._extractKeywords(trace.content);
+            let signal = 'ignored';
+            if (keywords.length > 0) {
+                const matchCount = keywords.filter((kw) => responseLower.includes(kw)).length;
+                const matchRatio = matchCount / keywords.length;
+                if (matchRatio > 0.3) {
+                    signal = 'used';
+                }
+            }
+            insertStmt.run(trace.id, signal, null, now);
+            feedbacks.push({
+                traceId: trace.id,
+                signal,
+                timestamp: now,
+            });
+        }
+        return feedbacks;
+    }
+    /**
+     * Retrieve the feedback history for a single trace, ordered by most-recent
+     * first.
+     *
+     * @param traceId - The memory trace ID to look up.
+     * @param limit   - Maximum number of rows to return.  Defaults to 100.
+     * @returns Array of `RetrievalFeedback` events, most-recent first.
+     */
+    getHistory(traceId, limit = 100) {
+        const rows = this.brain.db
+            .prepare(`SELECT id, trace_id, signal, query, created_at
+         FROM retrieval_feedback
+         WHERE trace_id = ?
+         ORDER BY created_at DESC, id DESC
+         LIMIT ?`)
+            .all(traceId, limit);
+        return rows.map((row) => ({
+            traceId: row.trace_id,
+            signal: row.signal,
+            context: row.query ?? undefined,
+            timestamp: row.created_at,
+        }));
+    }
+    /**
+     * Return aggregate counts of `'used'` and `'ignored'` signals for a trace.
+     *
+     * Useful for the consolidation pipeline to decide whether to apply
+     * `penalizeUnused` (many ignores) or `updateOnRetrieval` (many used).
+     *
+     * @param traceId - The memory trace ID to aggregate.
+     * @returns `{ used, ignored }` counts.
+     */
+    getStats(traceId) {
+        const rows = this.brain.db
+            .prepare(`SELECT signal, COUNT(*) AS count
+         FROM retrieval_feedback
+         WHERE trace_id = ?
+         GROUP BY signal`)
+            .all(traceId);
+        let used = 0;
+        let ignored = 0;
+        for (const row of rows) {
+            if (row.signal === 'used')
+                used = row.count;
+            else if (row.signal === 'ignored')
+                ignored = row.count;
+        }
+        return { used, ignored };
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Extract unique keywords from a text string.
+     *
+     * A keyword is any word that:
+     * - Has more than 4 characters after stripping non-alphanumeric characters.
+     * - Is lowercased.
+     *
+     * Short stop-words (≤ 4 chars) are excluded because they appear in almost
+     * every response and would inflate `matchRatio` without providing signal.
+     *
+     * @param text - The source text (typically a trace's `content` field).
+     * @returns Deduplicated array of lowercase keywords longer than 4 characters.
+     */
+    _extractKeywords(text) {
+        const words = text
+            .toLowerCase()
+            .split(/\s+/)
+            .map((w) => w.replace(/[^a-z0-9]/g, ''))
+            .filter((w) => w.length > 4);
+        // Return deduplicated list using a Set for uniqueness.
+        return [...new Set(words)];
+    }
+}
+//# sourceMappingURL=RetrievalFeedbackSignal.js.map

package/dist/memory/feedback/RetrievalFeedbackSignal.js.map

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

package/dist/memory/feedback/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Barrel export for the retrieval feedback subsystem.
+ *
+ * The feedback module provides:
+ * - `RetrievalFeedbackSignal` — detects used vs ignored memory traces and
+ *   persists those signals to the agent's SQLite brain.
+ * - `RetrievalFeedback` — the typed event shape for a single feedback record.
+ *
+ * @module agentos/memory/feedback
+ */
+export { RetrievalFeedbackSignal } from './RetrievalFeedbackSignal.js';
+export type { RetrievalFeedback } from './RetrievalFeedbackSignal.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/feedback/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/feedback/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/memory/feedback/index.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Barrel export for the retrieval feedback subsystem.
+ *
+ * The feedback module provides:
+ * - `RetrievalFeedbackSignal` — detects used vs ignored memory traces and
+ *   persists those signals to the agent's SQLite brain.
+ * - `RetrievalFeedback` — the typed event shape for a single feedback record.
+ *
+ * @module agentos/memory/feedback
+ */
+export { RetrievalFeedbackSignal } from './RetrievalFeedbackSignal.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/feedback/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/feedback/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/memory/index.d.ts

@@ -56,4 +56,26 @@ export { MarkdownWorkingMemory } from './working/MarkdownWorkingMemory.js';
 export type { WriteResult } from './working/MarkdownWorkingMemory.js';
 export { UpdateWorkingMemoryTool } from './working/UpdateWorkingMemoryTool.js';
 export { ReadWorkingMemoryTool } from './working/ReadWorkingMemoryTool.js';
+export { Memory } from './facade/index.js';
+export type { ScoredTrace } from './facade/index.js';
+export type { MemoryConfig, EmbeddingConfig, ExtendedConsolidationConfig, IngestionConfig, RememberOptions, RecallOptions, IngestOptions, IngestResult, ExportOptions, ImportOptions, ImportResult, ConsolidationResult as MemoryConsolidationResult, MemoryHealth, LoadOptions, LoadedDocument, DocumentMetadata, DocumentChunk, ExtractedImage, ExtractedTable, } from './facade/index.js';
+export type { IDocumentLoader } from './ingestion/IDocumentLoader.js';
+export { TextLoader } from './ingestion/TextLoader.js';
+export { MarkdownLoader } from './ingestion/MarkdownLoader.js';
+export { HtmlLoader } from './ingestion/HtmlLoader.js';
+export { PdfLoader } from './ingestion/PdfLoader.js';
+export { DocxLoader } from './ingestion/DocxLoader.js';
+export { LoaderRegistry } from './ingestion/LoaderRegistry.js';
+export { FolderScanner } from './ingestion/FolderScanner.js';
+export { ChunkingEngine } from './ingestion/ChunkingEngine.js';
+export { MultimodalAggregator } from './ingestion/MultimodalAggregator.js';
+export { UrlLoader } from './ingestion/UrlLoader.js';
+export { RetrievalFeedbackSignal } from './feedback/index.js';
+export type { RetrievalFeedback } from './feedback/index.js';
+export { ConsolidationLoop } from './consolidation/index.js';
+export { JsonExporter, JsonImporter, MarkdownExporter, MarkdownImporter, ObsidianExporter, ObsidianImporter, SqliteExporter, SqliteImporter, ChatGptImporter, } from './io/index.js';
+export { SqliteBrain } from './store/SqliteBrain.js';
+export { SqliteKnowledgeGraph } from './store/SqliteKnowledgeGraph.js';
+export { SqliteMemoryGraph } from './store/SqliteMemoryGraph.js';
+export { MemoryAddTool, MemoryUpdateTool, MemoryDeleteTool, MemoryMergeTool, MemorySearchTool, MemoryReflectTool, } from './tools/index.js';
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/memory/index.js

@@ -47,4 +47,28 @@ export { DEFAULT_INFINITE_CONTEXT_CONFIG } from './context/types.js';
 export { MarkdownWorkingMemory } from './working/MarkdownWorkingMemory.js';
 export { UpdateWorkingMemoryTool } from './working/UpdateWorkingMemoryTool.js';
 export { ReadWorkingMemoryTool } from './working/ReadWorkingMemoryTool.js';
+// --- Memory Facade (Phase 1: Ingestion + Self-Improving Graph) ---
+export { Memory } from './facade/index.js';
+export { TextLoader } from './ingestion/TextLoader.js';
+export { MarkdownLoader } from './ingestion/MarkdownLoader.js';
+export { HtmlLoader } from './ingestion/HtmlLoader.js';
+export { PdfLoader } from './ingestion/PdfLoader.js';
+export { DocxLoader } from './ingestion/DocxLoader.js';
+export { LoaderRegistry } from './ingestion/LoaderRegistry.js';
+export { FolderScanner } from './ingestion/FolderScanner.js';
+export { ChunkingEngine } from './ingestion/ChunkingEngine.js';
+export { MultimodalAggregator } from './ingestion/MultimodalAggregator.js';
+export { UrlLoader } from './ingestion/UrlLoader.js';
+// --- Retrieval Feedback ---
+export { RetrievalFeedbackSignal } from './feedback/index.js';
+// --- Self-Improving Consolidation ---
+export { ConsolidationLoop } from './consolidation/index.js';
+// --- Import/Export ---
+export { JsonExporter, JsonImporter, MarkdownExporter, MarkdownImporter, ObsidianExporter, ObsidianImporter, SqliteExporter, SqliteImporter, ChatGptImporter, } from './io/index.js';
+// --- SQLite Storage ---
+export { SqliteBrain } from './store/SqliteBrain.js';
+export { SqliteKnowledgeGraph } from './store/SqliteKnowledgeGraph.js';
+export { SqliteMemoryGraph } from './store/SqliteMemoryGraph.js';
+// --- Agent Memory Tools ---
+export { MemoryAddTool, MemoryUpdateTool, MemoryDeleteTool, MemoryMergeTool, MemorySearchTool, MemoryReflectTool, } from './tools/index.js';
 //# sourceMappingURL=index.js.map

package/dist/memory/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoCH,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,mBAAmB;AACnB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,sCAAsC,CAAC;AAG9C,gBAAgB;AAChB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,oCAAoC,CAAC;AAG5C,yBAAyB;AACzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAG7E,gBAAgB;AAChB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,0BAA0B;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGrF,4BAA4B;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,kCAAkC;AAClC,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,oBAAoB;AACpB,OAAO,EAAE,+BAA+B,EAAE,MAAM,yCAAyC,CAAC;AAY1F,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,uCAAuC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAGnE,uCAAuC;AACvC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAGrF,2CAA2C;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAGjF,4CAA4C;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAYxE,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AAErE,6CAA6C;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAE3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"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"}

package/dist/memory/ingestion/ChunkingEngine.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview ChunkingEngine — splits raw document text into `DocumentChunk`
+ * slices ready for embedding and vector-store ingestion.
+ *
+ * Four strategies are supported:
+ *
+ * - **fixed**       — split at a fixed character count with word-boundary
+ *                     awareness and configurable overlap.
+ * - **semantic**    — embed individual sentences and split where cosine
+ *                     similarity drops below a threshold (topic boundaries).
+ *                     Falls back to `fixed` when no `embedFn` is supplied.
+ * - **hierarchical**— honour Markdown heading structure; each heading creates
+ *                     a new chunk boundary with the heading stored in metadata.
+ *                     Long sections are sub-split with `fixed`.
+ * - **layout**      — preserve fenced code blocks and pipe-delimited tables as
+ *                     atomic chunks; surrounding prose is split with `fixed`.
+ *
+ * @module memory/ingestion/ChunkingEngine
+ */
+import type { DocumentChunk } from '../facade/types.js';
+/**
+ * The four supported chunking strategies.
+ *
+ * - `'fixed'`       — character-count split with overlap.
+ * - `'semantic'`    — embedding-guided topic-boundary split.
+ * - `'hierarchical'`— Markdown heading-aware split.
+ * - `'layout'`      — code/table-aware split that preserves special blocks.
+ */
+export type ChunkStrategy = 'fixed' | 'semantic' | 'hierarchical' | 'layout';
+/**
+ * Options controlling how the `ChunkingEngine` splits a document.
+ *
+ * All fields except `strategy` are optional and fall back to sensible defaults.
+ */
+export interface ChunkOptions {
+    /**
+     * Algorithm used to split the content.
+     * @see ChunkStrategy
+     */
+    strategy: ChunkStrategy;
+    /**
+     * Target character count for each produced chunk.
+     * @default 512
+     */
+    chunkSize?: number;
+    /**
+     * Number of characters to overlap between consecutive chunks.
+     * Prevents context loss at split boundaries.
+     * @default 64
+     */
+    chunkOverlap?: number;
+    /**
+     * Async function that embeds a batch of strings into dense vectors.
+     * Required for the `'semantic'` strategy; ignored by all others.
+     * When omitted and `strategy` is `'semantic'`, the engine falls back to
+     * the `'fixed'` strategy.
+     *
+     * @param texts - Batch of strings to embed.
+     * @returns Promise resolving to one vector (number[]) per input string.
+     */
+    embedFn?: (texts: string[]) => Promise<number[][]>;
+}
+/**
+ * Splits raw document text into an ordered array of `DocumentChunk` objects
+ * suitable for embedding and storage in a vector index.
+ *
+ * @example
+ * ```typescript
+ * const engine = new ChunkingEngine();
+ * const chunks = await engine.chunk(content, { strategy: 'fixed', chunkSize: 512 });
+ * ```
+ */
+export declare class ChunkingEngine {
+    /**
+     * Chunks the provided `content` string according to the given `options`.
+     *
+     * All strategy implementations are async to accommodate the optional
+     * `embedFn` used by the semantic strategy.
+     *
+     * @param content - Full document text to split.
+     * @param options - Chunking strategy and tuning parameters.
+     * @returns Ordered array of `DocumentChunk` objects with sequential indices.
+     */
+    chunk(content: string, options: ChunkOptions): Promise<DocumentChunk[]>;
+    /**
+     * Splits content at a fixed character count with word-boundary awareness
+     * and configurable overlap between consecutive chunks.
+     *
+     * @param content      - Text to split.
+     * @param chunkSize    - Target character count per chunk.
+     * @param chunkOverlap - Overlap in characters between consecutive chunks.
+     * @returns Ordered `DocumentChunk[]`.
+     */
+    private _chunkFixed;
+    /**
+     * Embeds individual sentences and inserts split points wherever the cosine
+     * similarity between consecutive sentence embeddings drops below
+     * {@link SEMANTIC_SPLIT_THRESHOLD} (topic boundary heuristic).
+     *
+     * When `embedFn` is not supplied the method falls back to `_chunkFixed`.
+     *
+     * Any resulting group that exceeds `2 × chunkSize` characters is further
+     * sub-split with the fixed strategy.
+     *
+     * @param content      - Text to split.
+     * @param chunkSize    - Target character count per chunk.
+     * @param chunkOverlap - Overlap used when sub-splitting oversized groups.
+     * @param embedFn      - Optional batch embedding function.
+     * @returns Ordered `DocumentChunk[]`.
+     */
+    private _chunkSemantic;
+    /**
+     * Recognises Markdown heading lines (`# H1`, `## H2`, …, `###### H6`) and
+     * creates a new chunk boundary at each heading.  The heading text is stored
+     * in `DocumentChunk.heading` and its level in `metadata.headingLevel`.
+     *
+     * Sections whose text exceeds `chunkSize` are sub-split with the fixed
+     * strategy while preserving the heading metadata.
+     *
+     * @param content      - Markdown-formatted text.
+     * @param chunkSize    - Maximum characters per output chunk.
+     * @param chunkOverlap - Overlap used when sub-splitting oversized sections.
+     * @returns Ordered `DocumentChunk[]`.
+     */
+    private _chunkHierarchical;
+    /**
+     * Detects fenced code blocks (``` … ```) and pipe-delimited tables and
+     * emits each as an atomic chunk (never split mid-block).  Surrounding prose
+     * is split with the fixed strategy.
+     *
+     * Chunk metadata:
+     * - Code blocks:  `{ type: 'code' }`
+     * - Tables:       `{ type: 'table' }`
+     * - Prose:        no special metadata.
+     *
+     * @param content      - Text potentially containing code blocks and tables.
+     * @param chunkSize    - Target character count for prose chunks.
+     * @param chunkOverlap - Overlap for prose fixed-splits.
+     * @returns Ordered `DocumentChunk[]`.
+     */
+    private _chunkLayout;
+}
+//# sourceMappingURL=ChunkingEngine.d.ts.map

package/dist/memory/ingestion/ChunkingEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChunkingEngine.d.ts","sourceRoot":"","sources":["../../../src/memory/ingestion/ChunkingEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;CACpD;AAiID;;;;;;;;;GASG;AACH,qBAAa,cAAc;IAKzB;;;;;;;;;OASG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA6B7E;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;IAYnB;;;;;;;;;;;;;;;OAeG;YACW,cAAc;IAkF5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,kBAAkB;IAmJ1B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,YAAY;CA6GrB"}