@framers/agentos 0.1.101 → 0.1.102

package/README.md

@@ -186,6 +186,22 @@ provider.  All five strategies are available out of the box:
 | `debate` | Agents argue and refine a shared answer over multiple rounds |
 | `review-loop` | One agent drafts, another reviews and requests revisions |
 | `hierarchical` | A coordinator dispatches sub-tasks to specialist agents at runtime |
+| `graph` | Explicit dependency DAG via `dependsOn`; tiers run concurrently |
+
+**Graph strategy** — declare dependencies between agents and let the orchestrator
+handle topological ordering and concurrent execution:
+
+```typescript
+const team = agency({
+  agents: {
+    researcher:  { instructions: 'Research the topic.' },
+    writer:      { instructions: 'Write an article.',       dependsOn: ['researcher'] },
+    illustrator: { instructions: 'Describe illustrations.', dependsOn: ['researcher'] },
+    reviewer:    { instructions: 'Review everything.',      dependsOn: ['writer', 'illustrator'] },
+  },
+  strategy: 'graph', // auto-detected when any agent has dependsOn
+});
+```
 
 Add guardrails, HITL, resource controls, observability, `listen()` for voice
 transport, `connect()` for channel adapters, RAG context injection, and real

package/dist/memory/config.d.ts

@@ -79,6 +79,45 @@ export interface ConsolidationConfig {
     mergeSimilarityThreshold: number;
     /** Minimum cluster size for schema integration. @default 5 */
     minClusterSize: number;
+    /**
+     * What event or schedule triggers a consolidation run.
+     * - `'turns'`    – fire after every N conversation turns (`every` = turn count).
+     * - `'interval'` – fire on a wall-clock timer (`every` = milliseconds).
+     * - `'manual'`   – only fire when explicitly requested.
+     * @default 'interval'
+     */
+    trigger?: 'turns' | 'interval' | 'manual';
+    /**
+     * Numeric complement to `trigger`.
+     * When `trigger='turns'` this is the turn count; when `trigger='interval'`
+     * this is the millisecond period.
+     * @default 3_600_000
+     */
+    every?: number;
+    /**
+     * Minimum Ebbinghaus strength below which a trace is pruned.
+     * Must be between 0 and 1.
+     * @default 0.05
+     */
+    pruneThreshold?: number;
+    /**
+     * Cosine similarity above which two traces are candidates for merging.
+     * Must be between 0 and 1.
+     * @default 0.92
+     */
+    mergeThreshold?: number;
+    /**
+     * Whether the consolidation engine should derive new insight traces from
+     * clusters of related memories during each cycle.
+     * @default true
+     */
+    deriveInsights?: boolean;
+    /**
+     * Maximum number of new insight traces the engine may derive per cycle.
+     * Guards against unbounded graph growth.
+     * @default 10
+     */
+    maxDerivedPerCycle?: number;
 }
 export interface CognitiveMemoryPersonaConfig {
     /** Feature detection strategy. @default 'keyword' */

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

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

package/dist/memory/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/memory/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA6KH,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,YAAY,EAAE,GAAG;IACjB,kBAAkB,EAAE,GAAG;IACvB,2BAA2B,EAAE,GAAG;IAChC,4BAA4B,EAAE,GAAG;IACjC,eAAe,EAAE,OAAS;CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,gBAAgB,EAAE,IAAI;IACtB,iBAAiB,EAAE,QAAU;IAC7B,qBAAqB,EAAE,GAAG;CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAA2B;IAC/D,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,IAAI;IACpB,iBAAiB,EAAE,IAAI;IACvB,iBAAiB,EAAE,IAAI;IACvB,gBAAgB,EAAE,IAAI;IACtB,gBAAgB,EAAE,IAAI;CACvB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/memory/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4NH,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,CAAC,MAAM,uBAAuB,GAAmB;IACrD,YAAY,EAAE,GAAG;IACjB,kBAAkB,EAAE,GAAG;IACvB,2BAA2B,EAAE,GAAG;IAChC,4BAA4B,EAAE,GAAG;IACjC,eAAe,EAAE,OAAS;CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAgB;IAC/C,gBAAgB,EAAE,IAAI;IACtB,iBAAiB,EAAE,QAAU;IAC7B,qBAAqB,EAAE,GAAG;CAC3B,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAA2B;IAC/D,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,IAAI;IACpB,iBAAiB,EAAE,IAAI;IACvB,iBAAiB,EAAE,IAAI;IACvB,gBAAgB,EAAE,IAAI;IACtB,gBAAgB,EAAE,IAAI;CACvB,CAAC"}

package/dist/memory/consolidation/ConsolidationLoop.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview ConsolidationLoop — self-improving background memory maintenance.
+ *
+ * Runs 6 ordered consolidation steps that mirror the brain's offline
+ * slow-wave-sleep consolidation process:
+ *
+ * 1. **Prune** — soft-delete traces whose Ebbinghaus strength has decayed
+ *    below the configurable `pruneThreshold`.
+ * 2. **Merge** — deduplicate near-identical traces. Uses embedding cosine
+ *    similarity when available, falls back to exact content-hash comparison.
+ * 3. **Strengthen** — read retrieval-feedback co-usage signals and record
+ *    Hebbian co-activation edges in the memory graph.
+ * 4. **Derive** — (requires LLM) detect clusters of related memories and
+ *    synthesise higher-level insight traces from them.
+ * 5. **Compact** — promote old, high-retrieval episodic traces to semantic
+ *    type (lightweight episodic-to-semantic migration).
+ * 6. **Re-index** — rebuild the FTS5 index and log the consolidation run
+ *    to the `consolidation_log` table.
+ *
+ * A simple boolean mutex prevents concurrent runs. If `run()` is called
+ * while a cycle is already in progress, it returns immediately with zero
+ * counts.
+ *
+ * @module agentos/memory/consolidation/ConsolidationLoop
+ */
+import type { ConsolidationResult, ExtendedConsolidationConfig } from '../facade/types.js';
+import type { SqliteBrain } from '../store/SqliteBrain.js';
+import type { IMemoryGraph } from '../graph/IMemoryGraph.js';
+/**
+ * Self-improving background consolidation loop with 6 ordered steps:
+ * prune, merge, strengthen, derive, compact, re-index.
+ *
+ * All database operations use the synchronous `better-sqlite3` API through
+ * the shared {@link SqliteBrain} connection. The `run()` method is async
+ * to accommodate the LLM-backed derive step.
+ */
+export declare class ConsolidationLoop {
+    private readonly brain;
+    private readonly memoryGraph;
+    private readonly options?;
+    /**
+     * Simple mutex flag. When `true`, a consolidation cycle is in progress
+     * and any concurrent `run()` call returns immediately with zero counts.
+     */
+    private _running;
+    /**
+     * @param brain       - The agent's SQLite brain database connection.
+     * @param memoryGraph - The memory association graph for co-activation and clustering.
+     * @param options     - Optional LLM invoker and embedding function for
+     *   derive and merge steps respectively.
+     */
+    constructor(brain: SqliteBrain, memoryGraph: IMemoryGraph, options?: {
+        /** LLM function for deriving insights from memory clusters. */
+        llmInvoker?: (prompt: string) => Promise<string>;
+        /** Embedding function for computing trace similarity. */
+        embedFn?: (texts: string[]) => Promise<number[][]>;
+    } | undefined);
+    /**
+     * Run one full consolidation cycle.
+     *
+     * The mutex prevents concurrent runs — if `_running` is already true,
+     * returns immediately with a zero-count result.
+     *
+     * @param config - Optional overrides for consolidation thresholds.
+     * @returns Consolidation statistics (pruned, merged, derived, compacted, durationMs).
+     */
+    run(config?: Partial<ExtendedConsolidationConfig>): Promise<ConsolidationResult>;
+    /**
+     * Whether consolidation is currently running.
+     * Useful for callers to check before scheduling a new run.
+     */
+    get isRunning(): boolean;
+    /**
+     * Query all non-deleted traces and soft-delete those whose current
+     * Ebbinghaus strength has decayed below `threshold`.
+     *
+     * @param threshold - Minimum strength to survive pruning.
+     * @returns Number of traces pruned.
+     */
+    private _prune;
+    /**
+     * Find and merge trace pairs with very similar content.
+     *
+     * When an embedding function is available, cosine similarity is used.
+     * Otherwise falls back to exact content hash comparison (SHA-256).
+     *
+     * Merge semantics:
+     * - The trace with more retrievals survives; the other is soft-deleted.
+     * - Tags are unioned (JSON arrays merged, deduplicated).
+     * - Emotional vectors are averaged.
+     * - The survivor takes the maximum strength of the pair.
+     *
+     * @param threshold - Cosine similarity above which two traces are merged.
+     * @returns Number of traces merged (deleted).
+     */
+    private _merge;
+    /**
+     * Merge two traces: keep the one with more retrievals, soft-delete the other.
+     * Union tags, average emotions, take max strength.
+     *
+     * @param a          - First trace row.
+     * @param b          - Second trace row.
+     * @param deletedIds - Set tracking which IDs have been soft-deleted this cycle.
+     */
+    private _mergeTracePair;
+    /**
+     * Query the `retrieval_feedback` table for traces that were co-used
+     * (same query string, both with signal = 'used') and record Hebbian
+     * co-activation edges in the memory graph.
+     *
+     * @returns Number of co-activation pairs strengthened.
+     */
+    private _strengthen;
+    /**
+     * Detect memory clusters and use the LLM to derive higher-level insights.
+     *
+     * Skips entirely if no `llmInvoker` was provided. For each of the top-N
+     * clusters (by size), collects member trace contents and sends them to the
+     * LLM with a concise instruction prompt.
+     *
+     * @param minClusterSize - Minimum cluster size for `detectClusters()`.
+     * @param maxDerived     - Maximum number of insights to create this cycle.
+     * @returns Number of insight traces created.
+     */
+    private _derive;
+    /**
+     * Find episodic traces older than 7 days with high retrieval count and
+     * promote them to semantic type.
+     *
+     * This is a lightweight version of compaction — full LLM-based summarization
+     * via the CompactionEngine is deferred. For now, the trace type is simply
+     * changed to 'semantic' and the timestamp is logged.
+     *
+     * @returns Number of traces compacted.
+     */
+    private _compact;
+    /**
+     * Rebuild the FTS5 index to reflect any content changes from the cycle,
+     * and write a summary row to the `consolidation_log` table.
+     *
+     * @param pruned    - Number of traces pruned.
+     * @param merged    - Number of traces merged.
+     * @param derived   - Number of insights derived (includes strengthened edges).
+     * @param compacted - Number of traces compacted.
+     * @param durationMs - Total cycle duration in milliseconds.
+     */
+    private _reindex;
+    /**
+     * Convert a raw `TraceRow` into a minimal `MemoryTrace`-compatible shape
+     * that `computeCurrentStrength()` can consume.
+     *
+     * Only the fields required by the Ebbinghaus formula are populated:
+     * `encodingStrength`, `stability` (derived from strength as a proxy),
+     * and `lastAccessedAt`.
+     *
+     * @param row - Raw SQLite row from `memory_traces`.
+     * @returns A minimal MemoryTrace object.
+     */
+    private _rowToMinimalTrace;
+    /**
+     * Compute cosine similarity between two embedding vectors.
+     *
+     * @param a - First vector.
+     * @param b - Second vector.
+     * @returns Cosine similarity in [-1, 1].
+     */
+    private _cosineSimilarity;
+    /**
+     * Average two emotion objects by computing the mean of all shared numeric keys.
+     *
+     * @param a - First emotion record.
+     * @param b - Second emotion record.
+     * @returns Averaged emotion record.
+     */
+    private _averageEmotions;
+}
+//# sourceMappingURL=ConsolidationLoop.d.ts.map

package/dist/memory/consolidation/ConsolidationLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsolidationLoop.d.ts","sourceRoot":"","sources":["../../../src/memory/consolidation/ConsolidationLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAC3F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAyD7D;;;;;;;GAOG;AACH,qBAAa,iBAAiB;IAc1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAf3B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;OAKG;gBAEgB,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,YAAY,EACzB,OAAO,CAAC,EAAE;QACzB,+DAA+D;QAC/D,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;QACjD,yDAAyD;QACzD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;KACpD,YAAA;IAOH;;;;;;;;OAQG;IACG,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAwCtF;;;OAGG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;IAMD;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAgCd;;;;;;;;;;;;;;OAcG;YACW,MAAM;IAmDpB;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAgDvB;;;;;;OAMG;YACW,WAAW;IA+CzB;;;;;;;;;;OAUG;YACW,OAAO;IAuErB;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ;IA+BhB;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ;IA4BhB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,kBAAkB;IAsC1B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;CAezB"}