cognitive-core 0.2.4 → 0.3.1

package/dist/memory/filesystem-cascade.js

@@ -0,0 +1,221 @@
+/**
+ * Filesystem cascade (§6.2): reindex-on-edit for markdown-canonical stores.
+ *
+ * The EverOS invariant is "files are canonical; the derived index follows them."
+ * Startup reindex already replays the whole tree (crash recovery); this closes
+ * the live gap — while the process is running, an external edit to a canonical
+ * file (a hand-edited `SKILL.md`, a `git pull`) is picked up without a reboot.
+ *
+ * Shape (EverOS's durable-queue model, sized to ccore):
+ *   chokidar watch → debounce → enqueue to a durable SQLite queue → worker drains,
+ *   content-hash gated, so only genuinely-changed files re-index.
+ *
+ * The queue + hash index live in SQLite (the rebuildable cache), NOT in a
+ * per-file sidecar: the content hash tracks "what the derived rows were built
+ * from," so it belongs with the derived rows. `rm cognitive-core.db` drops both
+ * and a cold boot full-reindexes from files — the invariant holds.
+ *
+ * The watcher is optional (off in short-lived eval/CLI runs, on for long-lived
+ * servers). Derived rows always come from files either way — this only changes
+ * *when* the reindex happens, never the source of truth.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { basename, relative, sep } from 'node:path';
+const DEFAULT_DEBOUNCE_MS = 150;
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_POLL_INTERVAL_MS = 100;
+export class FilesystemCascade {
+    persistence;
+    targets;
+    targetByKind = new Map();
+    debounceMs;
+    maxAttempts;
+    onError;
+    usePolling;
+    pollIntervalMs;
+    watchers = [];
+    drainTimer;
+    draining = false;
+    drainQueued = false;
+    started = false;
+    constructor(persistence, targets, options = {}) {
+        this.persistence = persistence;
+        this.targets = targets;
+        for (const target of targets)
+            this.targetByKind.set(target.kind, target);
+        this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+        this.maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        this.onError = options.onError;
+        this.usePolling = options.usePolling ?? false;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    /**
+     * Attach watchers and drain any backlog left by a prior session. Idempotent.
+     * chokidar is imported lazily so short-lived runs that never watch don't pay
+     * for it (and a missing optional dep can't break a non-watching boot).
+     */
+    async start() {
+        if (this.started)
+            return;
+        const { watch } = await import('chokidar');
+        const ready = [];
+        for (const target of this.targets) {
+            await mkdir(target.root, { recursive: true });
+            const watcher = watch(target.root, {
+                ignoreInitial: true, // startup reindex already covers what's on disk
+                persistent: true,
+                usePolling: this.usePolling,
+                interval: this.pollIntervalMs,
+                ignored: (candidate) => this.isIgnored(target.root, candidate),
+            });
+            watcher.on('add', (path) => this.onFileEvent(target, path, 'upsert'));
+            watcher.on('change', (path) => this.onFileEvent(target, path, 'upsert'));
+            watcher.on('unlink', (path) => this.onFileEvent(target, path, 'delete'));
+            watcher.on('error', (error) => this.onError?.('<watcher>', error));
+            // Resolve once the initial scan is done: only then does `ignoreInitial`
+            // stop swallowing events, so a write right after start() is reliably seen.
+            ready.push(new Promise((resolve) => watcher.once('ready', () => resolve())));
+            this.watchers.push(watcher);
+        }
+        await Promise.all(ready);
+        this.started = true;
+        await this.drain();
+    }
+    /** Close watchers, flush pending timers, and drain what's left in-session. */
+    async stop() {
+        if (this.drainTimer) {
+            clearTimeout(this.drainTimer);
+            this.drainTimer = undefined;
+        }
+        const watchers = this.watchers.splice(0);
+        await Promise.all(watchers.map((watcher) => watcher.close()));
+        this.started = false;
+        // Flush any enqueued-but-undrained changes so nothing is lost this session
+        // (next-boot reindex is the backstop, but draining here keeps SQLite current).
+        await this.drain();
+    }
+    /**
+     * Drain the pending queue now. Serialized against itself: a call that arrives
+     * mid-drain sets a re-run flag instead of interleaving, so watcher bursts and
+     * an explicit drain() never process the same row twice.
+     */
+    async drain() {
+        if (this.draining) {
+            this.drainQueued = true;
+            return { indexed: 0, removed: 0, skipped: 0, errored: 0 };
+        }
+        this.draining = true;
+        const total = { indexed: 0, removed: 0, skipped: 0, errored: 0 };
+        try {
+            do {
+                this.drainQueued = false;
+                const pass = await this.drainOnce();
+                total.indexed += pass.indexed;
+                total.removed += pass.removed;
+                total.skipped += pass.skipped;
+                total.errored += pass.errored;
+            } while (this.drainQueued);
+        }
+        finally {
+            this.draining = false;
+        }
+        return total;
+    }
+    async drainOnce() {
+        const result = { indexed: 0, removed: 0, skipped: 0, errored: 0 };
+        const rows = this.persistence.peekPendingMdChanges();
+        for (const row of rows) {
+            const target = this.targetByKind.get(row.kind);
+            if (!target) {
+                // Orphan kind (store removed) — retire the row rather than loop on it.
+                this.persistence.completeMdChange(row.id);
+                continue;
+            }
+            try {
+                if (row.op === 'delete' || !existsSync(row.path)) {
+                    await this.applyRemoval(target, row.path);
+                    this.persistence.completeMdChange(row.id);
+                    result.removed++;
+                    continue;
+                }
+                const content = await readFile(row.path, 'utf-8');
+                const hash = sha256(content);
+                if (this.persistence.getMdFileIndex(row.path)?.content_hash === hash) {
+                    // Unchanged since last index — skip the re-embed/re-index entirely.
+                    this.persistence.completeMdChange(row.id);
+                    result.skipped++;
+                    continue;
+                }
+                const entityId = await target.reindexFile(row.path);
+                this.persistence.setMdFileIndex({ path: row.path, contentHash: hash, entityId });
+                this.persistence.completeMdChange(row.id);
+                result.indexed++;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.persistence.failMdChange(row.id, message, this.maxAttempts);
+                this.onError?.(row.path, error);
+                result.errored++;
+            }
+        }
+        return result;
+    }
+    async applyRemoval(target, path) {
+        const indexed = this.persistence.getMdFileIndex(path);
+        if (indexed?.entity_id) {
+            await target.removeEntity(indexed.entity_id);
+        }
+        this.persistence.deleteMdFileIndex(path);
+    }
+    onFileEvent(target, path, op) {
+        if (!target.isCanonical(path))
+            return;
+        this.persistence.enqueueMdChange({ path, kind: target.kind, op });
+        this.scheduleDrain();
+    }
+    scheduleDrain() {
+        if (this.drainTimer)
+            clearTimeout(this.drainTimer);
+        this.drainTimer = setTimeout(() => {
+            this.drainTimer = undefined;
+            void this.drain().catch((error) => this.onError?.('<drain>', error));
+        }, this.debounceMs);
+        // Don't let a pending debounce timer keep the process alive on its own.
+        this.drainTimer.unref?.();
+    }
+    /**
+     * Ignore derived/temp noise *below* the watched root — `.ccore/` sidecars,
+     * `.candidates/`, and `.SKILL.md.<ts>.tmp` atomic-write temp files — without
+     * ignoring the root itself (which lives under `.atlas`, a dot-dir). Tested per
+     * relative segment so our own writes never trigger a reindex feedback loop.
+     */
+    isIgnored(root, candidate) {
+        const rel = relative(root, candidate);
+        if (!rel || rel.startsWith('..'))
+            return false;
+        return rel.split(sep).some((segment) => segment.startsWith('.'));
+    }
+}
+function sha256(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+/**
+ * Build the procedural-playbook cascade target: watch `.atlas/playbooks`, treat
+ * `SKILL.md` files as canonical, reindex via the file-granular helper, and drop
+ * derived rows through the structural-write-free `removeCanonical`.
+ */
+export function createPlaybookCascadeTarget(deps) {
+    return {
+        kind: 'playbook',
+        root: deps.root,
+        isCanonical: (path) => basename(path) === 'SKILL.md',
+        reindexFile: deps.reindexFile,
+        removeEntity: deps.removeEntity,
+    };
+}
+export function createFilesystemCascade(persistence, targets, options) {
+    return new FilesystemCascade(persistence, targets, options);
+}
+//# sourceMappingURL=filesystem-cascade.js.map

package/dist/memory/filesystem-cascade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-cascade.js","sourceRoot":"","sources":["../../src/memory/filesystem-cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAgDpD,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAC/B,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,MAAM,OAAO,iBAAiB;IAgBT;IAfF,OAAO,CAAkB;IACzB,YAAY,GAAG,IAAI,GAAG,EAAyB,CAAC;IAChD,UAAU,CAAS;IACnB,WAAW,CAAS;IACpB,OAAO,CAA0C;IACjD,UAAU,CAAU;IACpB,cAAc,CAAS;IAEvB,QAAQ,GAAgB,EAAE,CAAC;IACpC,UAAU,CAA4C;IACtD,QAAQ,GAAG,KAAK,CAAC;IACjB,WAAW,GAAG,KAAK,CAAC;IACpB,OAAO,GAAG,KAAK,CAAC;IAExB,YACmB,WAA8B,EAC/C,OAAwB,EACxB,UAAoC,EAAE;QAFrB,gBAAW,GAAX,WAAW,CAAmB;QAI/C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,KAAK,MAAM,MAAM,IAAI,OAAO;YAAE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACzE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAC5D,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,oBAAoB,CAAC;QAC/D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC;QAC9C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;IAC3E,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO;QACzB,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAoB,EAAE,CAAC;QAClC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE;gBACjC,aAAa,EAAE,IAAI,EAAE,gDAAgD;gBACrE,UAAU,EAAE,IAAI;gBAChB,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,QAAQ,EAAE,IAAI,CAAC,cAAc;gBAC7B,OAAO,EAAE,CAAC,SAAiB,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC;aACvE,CAAC,CAAC;YACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;YAC9E,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;YACjF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;YACjF,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;YAC5E,wEAAwE;YACxE,2EAA2E;YAC3E,KAAK,CAAC,IAAI,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;YACnF,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC9B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC9B,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzC,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,2EAA2E;QAC3E,+EAA+E;QAC/E,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;YACxB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC5D,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,MAAM,KAAK,GAAuB,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACrF,IAAI,CAAC;YACH,GAAG,CAAC;gBACF,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;gBACzB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;gBACpC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;gBAC9B,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;gBAC9B,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;gBAC9B,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC;YAChC,CAAC,QAAQ,IAAI,CAAC,WAAW,EAAE;QAC7B,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,KAAK,CAAC,SAAS;QACrB,MAAM,MAAM,GAAuB,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QACtF,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,oBAAoB,EAAE,CAAC;QACrD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,uEAAuE;gBACvE,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC1C,SAAS;YACX,CAAC;YACD,IAAI,CAAC;gBACH,IAAI,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;oBACjD,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;oBAC1C,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBAC1C,MAAM,CAAC,OAAO,EAAE,CAAC;oBACjB,SAAS;gBACX,CAAC;gBAED,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAClD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC7B,IAAI,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI,EAAE,CAAC;oBACrE,oEAAoE;oBACpE,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;oBAC1C,MAAM,CAAC,OAAO,EAAE,CAAC;oBACjB,SAAS;gBACX,CAAC;gBAED,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACpD,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;gBACjF,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC1C,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;gBACjE,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBAChC,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,MAAqB,EAAE,IAAY;QAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACvB,MAAM,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC3C,CAAC;IAEO,WAAW,CAAC,MAAqB,EAAE,IAAY,EAAE,EAAuB;QAC9E,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;YAAE,OAAO;QACtC,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAClE,IAAI,CAAC,aAAa,EAAE,CAAC;IACvB,CAAC;IAEO,aAAa;QACnB,IAAI,IAAI,CAAC,UAAU;YAAE,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACnD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;YAC5B,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC;QACvE,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QACpB,wEAAwE;QACxE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;OAKG;IACK,SAAS,CAAC,IAAY,EAAE,SAAiB;QAC/C,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAC/C,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACnE,CAAC;CACF;AAED,SAAS,MAAM,CAAC,OAAe;IAC7B,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAI3C;IACC,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,UAAU;QAC5D,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;KAChC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,WAA8B,EAC9B,OAAwB,EACxB,OAAkC;IAElC,OAAO,IAAI,iBAAiB,CAAC,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC"}

package/dist/memory/index.d.ts

@@ -1,22 +1,26 @@
 export { ExperienceMemory, type PruneResult } from './experience.js';
 export { MemorySystem, createMemorySystem, type MemoryQueryResult, type MemoryQueryResultV2, } from './system.js';
-export { PlaybookLibrary, createPlaybookLibrary, type PlaybookMatch, } from './playbook.js';
-export { MetaMemory, createMetaMemory, } from './meta.js';
-export { TeamExperienceMemory, createTeamExperienceMemory, type TeamExperience, type TeamAnalysisResult, type AgentCredit, type InteractionCredit, type CoordinationAssessment, type RoleLessonEntry, type TeamLessonEntry, type CompositionLessonCategory, type CoordinationLessonCategory, type TeamMetaObservationEntry, } from './team-experience.js';
-export { ReflexionMemory, createReflexionMemory, type ReflexionQueryOptions, } from './reflexion.js';
+export { PlaybookLibrary, createPlaybookLibrary, type PlaybookMatch, type FrontierMember, type StructuralPlaybookWriter, type ObjectivePreference, } from './playbook.js';
+export { MetaMemory, createMetaMemory } from './meta.js';
+export { MetaPlaybookBank, type MetaPlaybookFindOptions } from './meta-playbook-bank.js';
+export { META_PLAYBOOK_SEEDS, type MetaPlaybookSeed } from './seeds/meta-playbook-seeds.js';
+export { META_STRATEGY_SEEDS } from './seeds/meta-strategy-seeds.js';
+export { seedMetaPlaybookBank, seedMetaStrategies, type SeedMetaPlaybookOptions, type SeedMetaStrategiesOptions, } from './seeds/seed-loader.js';
+export { ReflexionMemory, createReflexionMemory, type ReflexionQueryOptions } from './reflexion.js';
 export { CoherenceChecker, createCoherenceChecker, type CoherenceResult, type CoherenceCheckerConfig, } from './coherence.js';
-export { ReasoningBank, createReasoningBank, type ExperienceCluster, type ClusterStats, type ReasoningBankConfig, } from './reasoning-bank.js';
-export { CausalStore, createCausalStore, type CausalEdge, } from './causal-store.js';
 export { TemporalCompressor, createTemporalCompressor, type TemporalCompressorConfig, type CompressionResult, } from './temporal-compressor.js';
 export { KnowledgeBank } from './knowledge-bank.js';
-export { KnowledgeGraphManager } from './knowledge-graph.js';
 export { KnowledgeDefragmenter } from './knowledge-defrag.js';
+export { extractConversationFacts, buildExtractionPrompt, parseFacts, type ConversationTurn, type ConversationExtractionInput, type ExtractionCompletionFn, } from './extraction/conversation-extractor.js';
+export { createLlmMemoryEvolver, parseEvolutionPlan, type EvolverCompletionFn, type LlmEvolverOptions, } from './evolution/llm-evolver.js';
+export type { MemoryEvolver, MemoryEvolutionInput, MemoryEvolutionPlan, EvolutionAction, EvolutionResult, } from '../types/knowledge.js';
 export type { SearchProvider, SearchProviderResult } from './search-provider.js';
-export { TextSimilaritySearchProvider, MinimemSearchProvider, type MinimemSearchClient, } from './search-providers/index.js';
-export { BaseGraphLayer, SemanticGraphLayer, TemporalGraphLayer, CausalGraphLayer, EntityGraphLayer, } from './graph-layers/index.js';
+export { TextSimilaritySearchProvider, MinimemSearchProvider, type MinimemSearchClient, KeywordExpandingSearchProvider, type CompletionFn, } from './search-providers/index.js';
 export { SqlitePersistence, createSqlitePersistence } from '../persistence/index.js';
 export type { SqlitePersistenceConfig } from '../persistence/index.js';
-export { loadCuratedPlaybooks, BUNDLED_SEED_PACK_DIR, type CuratedPlaybookFile, type CuratedLoadResult, type CuratedLoadOptions, } from './curated-loader.js';
+export { loadCuratedPlaybooks, BUNDLED_SEED_PACK_DIR, BUNDLED_SEED_PACKS, type CuratedPlaybookFile, type CuratedLoadResult, type CuratedLoadOptions, } from './curated-loader.js';
 export { resolvePlaybookSource, isGitSource, parseGitSource, discoverPlaybookDir, sourceStateKey, type ParsedGitSource, type PlaybookManifest, type SourceState, type ResolveResult, type ResolveOptions, } from './source-resolver.js';
 export { compilePlaybookToSkill, exportPlaybooksAsSkills, exportPlaybookAsSkill, type SkillExportFilter, type SkillExportOptions, type SkillExportResult, type ExportedSkill, } from './skill-exporter.js';
+export { playbookToSkillMarkdown, skillMarkdownToPlaybook, parsePlaybookSkillMarkdown, exportPlaybookAsCanonicalSkill, exportPlaybooksAsCanonicalSkills, validateCanonicalPlaybookFiles, reindexCanonicalPlaybookFiles, reindexCanonicalPlaybookFile, canonicalPlaybookDirName, ProceduralMemoryFileStore, pruneSqliteOnlyPlaybooks, readAtlasMemoryManifest, writeAtlasMemoryManifest, type ParsedProceduralSkill, type PlaybookSkillMarkdownOptions, type AtlasMemoryManifest, type ProceduralPruneResult, type CanonicalPlaybookExportResult, type CanonicalPlaybookValidationIssue, type CanonicalPlaybookValidationResult, type CanonicalPlaybookReindexIssue, type CanonicalPlaybookReindexResult, } from './procedural-skill.js';
+export { FilesystemCascade, createFilesystemCascade, createPlaybookCascadeTarget, type CascadeTarget, type FilesystemCascadeOptions, type CascadeDrainResult, } from './filesystem-cascade.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":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,UAAU,EACV,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,KAAK,qBAAqB,GAC3B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,iBAAiB,GACvB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,mBAAmB,GACzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACrF,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGvE,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"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"}

package/dist/memory/index.js

@@ -3,31 +3,34 @@ export { MemorySystem, createMemorySystem, } from './system.js';
 // Playbook-based memory
 export { PlaybookLibrary, createPlaybookLibrary, } from './playbook.js';
 // Meta-learning memory
-export { MetaMemory, createMetaMemory, } from './meta.js';
-// Team experience memory
-export { TeamExperienceMemory, createTeamExperienceMemory, } from './team-experience.js';
+export { MetaMemory, createMetaMemory } from './meta.js';
+export { MetaPlaybookBank } from './meta-playbook-bank.js';
+export { META_PLAYBOOK_SEEDS } from './seeds/meta-playbook-seeds.js';
+export { META_STRATEGY_SEEDS } from './seeds/meta-strategy-seeds.js';
+export { seedMetaPlaybookBank, seedMetaStrategies, } from './seeds/seed-loader.js';
 // Reflexion episodes
-export { ReflexionMemory, createReflexionMemory, } from './reflexion.js';
+export { ReflexionMemory, createReflexionMemory } from './reflexion.js';
 // Coherence checking
 export { CoherenceChecker, createCoherenceChecker, } from './coherence.js';
-// Reasoning bank (clustered experience retrieval)
-export { ReasoningBank, createReasoningBank, } from './reasoning-bank.js';
-// Causal edge store
-export { CausalStore, createCausalStore, } from './causal-store.js';
 // Temporal compression
 export { TemporalCompressor, createTemporalCompressor, } from './temporal-compressor.js';
 // Knowledge bank (semantic memory)
 export { KnowledgeBank } from './knowledge-bank.js';
-export { KnowledgeGraphManager } from './knowledge-graph.js';
 export { KnowledgeDefragmenter } from './knowledge-defrag.js';
-export { TextSimilaritySearchProvider, MinimemSearchProvider, } from './search-providers/index.js';
-export { BaseGraphLayer, SemanticGraphLayer, TemporalGraphLayer, CausalGraphLayer, EntityGraphLayer, } from './graph-layers/index.js';
+// Conversational ADD-only fact extraction (WS3)
+export { extractConversationFacts, buildExtractionPrompt, parseFacts, } from './extraction/conversation-extractor.js';
+// Agentic memory evolution (merge / link / supersede)
+export { createLlmMemoryEvolver, parseEvolutionPlan, } from './evolution/llm-evolver.js';
+export { TextSimilaritySearchProvider, MinimemSearchProvider, KeywordExpandingSearchProvider, } from './search-providers/index.js';
 // Re-export persistence module
 export { SqlitePersistence, createSqlitePersistence } from '../persistence/index.js';
 // Curated playbook loading
-export { loadCuratedPlaybooks, BUNDLED_SEED_PACK_DIR, } from './curated-loader.js';
+export { loadCuratedPlaybooks, BUNDLED_SEED_PACK_DIR, BUNDLED_SEED_PACKS, } from './curated-loader.js';
 // Source resolver (git + local path resolution for curated sources)
 export { resolvePlaybookSource, isGitSource, parseGitSource, discoverPlaybookDir, sourceStateKey, } from './source-resolver.js';
 // Skill export (compile playbooks → Open Agent Skills format)
 export { compilePlaybookToSkill, exportPlaybooksAsSkills, exportPlaybookAsSkill, } from './skill-exporter.js';
+// Canonical procedural-memory SKILL.md files
+export { playbookToSkillMarkdown, skillMarkdownToPlaybook, parsePlaybookSkillMarkdown, exportPlaybookAsCanonicalSkill, exportPlaybooksAsCanonicalSkills, validateCanonicalPlaybookFiles, reindexCanonicalPlaybookFiles, reindexCanonicalPlaybookFile, canonicalPlaybookDirName, ProceduralMemoryFileStore, pruneSqliteOnlyPlaybooks, readAtlasMemoryManifest, writeAtlasMemoryManifest, } from './procedural-skill.js';
+export { FilesystemCascade, createFilesystemCascade, createPlaybookCascadeTarget, } from './filesystem-cascade.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,OAAO,EAAE,gBAAgB,EAAoB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,kBAAkB,GAGnB,MAAM,aAAa,CAAC;AAErB,wBAAwB;AACxB,OAAO,EACL,eAAe,EACf,qBAAqB,GAEtB,MAAM,eAAe,CAAC;AAEvB,uBAAuB;AACvB,OAAO,EACL,UAAU,EACV,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAEnB,yBAAyB;AACzB,OAAO,EACL,oBAAoB,EACpB,0BAA0B,GAW3B,MAAM,sBAAsB,CAAC;AAE9B,qBAAqB;AACrB,OAAO,EACL,eAAe,EACf,qBAAqB,GAEtB,MAAM,gBAAgB,CAAC;AAExB,qBAAqB;AACrB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,GAGvB,MAAM,gBAAgB,CAAC;AAExB,kDAAkD;AAClD,OAAO,EACL,aAAa,EACb,mBAAmB,GAIpB,MAAM,qBAAqB,CAAC;AAE7B,oBAAoB;AACpB,OAAO,EACL,WAAW,EACX,iBAAiB,GAElB,MAAM,mBAAmB,CAAC;AAE3B,uBAAuB;AACvB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,GAGzB,MAAM,0BAA0B,CAAC;AAElC,mCAAmC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,GAEtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,+BAA+B;AAC/B,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGrF,2BAA2B;AAC3B,OAAO,EACL,oBAAoB,EACpB,qBAAqB,GAItB,MAAM,qBAAqB,CAAC;AAE7B,oEAAoE;AACpE,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,cAAc,GAMf,MAAM,sBAAsB,CAAC;AAE9B,8DAA8D;AAC9D,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,GAKtB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAoB,MAAM,iBAAiB,CAAC;AACrE,OAAO,EACL,YAAY,EACZ,kBAAkB,GAGnB,MAAM,aAAa,CAAC;AAErB,wBAAwB;AACxB,OAAO,EACL,eAAe,EACf,qBAAqB,GAKtB,MAAM,eAAe,CAAC;AAEvB,uBAAuB;AACvB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAgC,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAyB,MAAM,gCAAgC,CAAC;AAC5F,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EACL,oBAAoB,EACpB,kBAAkB,GAGnB,MAAM,wBAAwB,CAAC;AAEhC,qBAAqB;AACrB,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAA8B,MAAM,gBAAgB,CAAC;AAEpG,qBAAqB;AACrB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,GAGvB,MAAM,gBAAgB,CAAC;AAExB,uBAAuB;AACvB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,GAGzB,MAAM,0BAA0B,CAAC;AAElC,mCAAmC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,gDAAgD;AAChD,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,UAAU,GAIX,MAAM,wCAAwC,CAAC;AAEhD,sDAAsD;AACtD,OAAO,EACL,sBAAsB,EACtB,kBAAkB,GAGnB,MAAM,4BAA4B,CAAC;AASpC,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,EAErB,8BAA8B,GAE/B,MAAM,6BAA6B,CAAC;AAErC,+BAA+B;AAC/B,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGrF,2BAA2B;AAC3B,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GAInB,MAAM,qBAAqB,CAAC;AAE7B,oEAAoE;AACpE,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,cAAc,GAMf,MAAM,sBAAsB,CAAC;AAE9B,8DAA8D;AAC9D,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,qBAAqB,GAKtB,MAAM,qBAAqB,CAAC;AAE7B,6CAA6C;AAC7C,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,0BAA0B,EAC1B,8BAA8B,EAC9B,gCAAgC,EAChC,8BAA8B,EAC9B,6BAA6B,EAC7B,4BAA4B,EAC5B,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,GAUzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,2BAA2B,GAI5B,MAAM,yBAAyB,CAAC"}

package/dist/memory/knowledge-bank.d.ts

@@ -1,17 +1,32 @@
-import type { KnowledgeNote, KnowledgeMatch, KnowledgeStats, EntityUpdate, Contradiction, ExtractedKnowledge, InboxResult, DefragResult, DecayResult, GraphLayerName, PlaybookLink } from '../types/knowledge.js';
+import type { KnowledgeNote, KnowledgeMatch, KnowledgeStats, EntityUpdate, Contradiction, ExtractedKnowledge, InboxResult, DefragResult, DecayResult, ConventionScope, MemoryEvolver, MemoryEvolutionPlan, EvolutionResult, LinkRelation } from '../types/knowledge.js';
 import type { Trajectory } from '../types/index.js';
 import type { TrajectorySource } from '../types/trajectory-source.js';
 import type { KnowledgeBankConfig } from '../types/config.js';
-import type { AgenticTaskRunner } from '../workspace/runner.js';
 import type { TrajectoryAnalyzer, AnalysisResult } from '../learning/analyzer.js';
-import { KnowledgeGraphManager } from './knowledge-graph.js';
 import { CoherenceChecker } from './coherence.js';
 import type { SearchProvider } from './search-provider.js';
+import { type HybridSearchProviderOptions } from './search-providers/hybrid.js';
+import type { EmbeddingProvider } from '../embeddings/provider.js';
+import type { ConversationExtractionInput, ExtractionCompletionFn } from './extraction/conversation-extractor.js';
+/** Context handed to an agentic knowledge extractor. */
+export interface AgenticKnowledgeExtractionInput {
+    trajectory: Trajectory;
+    analysis: AnalysisResult;
+    /** Known entity names from the knowledge bank */
+    existingEntities: string[];
+    /** Related notes for agent context */
+    relatedNotes: KnowledgeNote[];
+}
+/**
+ * Agentic extraction callback. The workspace layer provides one via
+ * `createAgenticKnowledgeExtractor(taskRunner)` — injected as a function so
+ * the memory layer never imports workspace modules (no import cycle).
+ */
+export type AgenticKnowledgeExtractor = (input: AgenticKnowledgeExtractionInput) => Promise<ExtractedKnowledge>;
 /**
  * KnowledgeBank — Semantic memory store for facts, concepts, and relationships.
  *
  * Uses the filesystem as the universal primary index (minimem-compatible).
- * Maintains a multi-layer graph overlay as a derived index for relationship queries.
  *
  * Directory structure:
  *   {memoryDir}/
@@ -20,18 +35,22 @@ import type { SearchProvider } from './search-provider.js';
  *       entities/       — living entity docs ({entity}.md)
  *       domains/        — domain summaries ({domain}.md)
  *     inbox/            — unorganized agent-authored notes
- *     .knowledge/       — derived index files (graph, manifest)
+ *     .knowledge/       — derived index files (manifest)
  */
 export declare class KnowledgeBank {
-    readonly graph: KnowledgeGraphManager;
     private memoryDir;
     private readonly bankConfig;
     private initialized;
     private searchProvider;
     private coherenceChecker;
+    /** Neural embedding provider for note retrieval (null ⇒ lexical floor). */
+    private embedder;
+    /** True once an embedder is configured — takes precedence over minimem auto-detect. */
+    private embeddingConfigured;
     private observationsDir;
     private entitiesDir;
     private domainsDir;
+    private conventionsDir;
     private inboxDir;
     private indexDir;
     constructor(memoryDir: string, config: KnowledgeBankConfig);
@@ -41,7 +60,6 @@ export declare class KnowledgeBank {
      * Create a new knowledge note and write it to disk.
      * Runs coherence checking against existing notes — contradictions are flagged
      * via metadata but the note is still stored.
-     * Updates the graph overlay in memory.
      */
     addObservation(note: KnowledgeNote): Promise<string>;
     /**
@@ -78,17 +96,41 @@ export declare class KnowledgeBank {
      */
     getAllNotes(): Promise<KnowledgeNote[]>;
     /**
-     * Get related notes via multi-layer graph traversal.
+     * Store a convention note.
+     * Uses addObservation as the underlying write path (coherence skip is safe
+     * here since conventions are user-authored, not extracted).
      */
-    getRelated(noteId: string, options?: {
-        depth?: number;
-        layers?: GraphLayerName[];
-        minWeight?: number;
-    }): Promise<KnowledgeMatch[]>;
+    storeConvention(note: KnowledgeNote): Promise<string>;
     /**
-     * Get cross-system links to playbooks.
+     * Upsert a convention by ID: if one with the same ID already exists,
+     * merge the evidence count and re-evaluate the binding threshold.
+     *
+     * Binding rules (PR-D3):
+     *   - 'instruction' type correction → binding immediately (evidenceCount=1 suffices)
+     *   - other types → binding when evidenceCount >= 2
+     *
+     * Returns the (possibly updated) note.
      */
-    getPlaybookLinks(noteId: string): Promise<PlaybookLink[]>;
+    upsertConvention(note: KnowledgeNote): Promise<KnowledgeNote>;
+    /**
+     * Retrieve conventions filtered by scope and optionally by domain.
+     *
+     * Scope semantics:
+     *   - 'global' conventions are always returned regardless of requested scope.
+     *   - Other scopes are returned only when their scope matches the requested scope.
+     *
+     * Pass `repoOrDomain` to additionally filter 'repo' or 'domain' scoped conventions
+     * by a specific identifier stored in the note's domain array.
+     */
+    getConventions(options?: {
+        scope?: ConventionScope;
+        repoOrDomain?: string;
+        bindingOnly?: boolean;
+    }): Promise<KnowledgeNote[]>;
+    /**
+     * Get a convention note by ID.
+     */
+    getConventionById(id: string): Promise<KnowledgeNote | null>;
     getStats(): Promise<KnowledgeStats>;
     /**
      * Search knowledge notes by text similarity.
@@ -99,10 +141,17 @@ export declare class KnowledgeBank {
         maxResults?: number;
     }): Promise<KnowledgeMatch[]>;
     /**
-     * Get relevant knowledge for a task using 3-tier retrieval:
-     * 1. Domain summary match
-     * 2. Entity name match in task description
-     * 3. Semantic text similarity search
+     * Get relevant knowledge for a task.
+     *
+     * Retrieval is a single fused ranking rather than fixed tiers:
+     * - Domain summaries (when a domain is given) are pinned on top as high-level
+     *   context.
+     * - A wide pool of atomic fact/observation notes is retrieved semantically.
+     * - Entity records that match the query (index mode) do NOT inject content;
+     *   instead they add a score BOOST to their linked atomic facts, lifting
+     *   entity-relevant facts within the pool (see DESIGN WS2a/WS2b).
+     * - Legacy content-mode entity notes are still surfaced as `entity` matches.
+     * All non-domain candidates then compete on a single fused score.
      */
     getRelevantKnowledge(task: {
         description: string;
@@ -110,10 +159,16 @@ export declare class KnowledgeBank {
     }, options?: {
         maxNotes?: number;
         maxTokens?: number;
-        layers?: GraphLayerName[];
     }): Promise<KnowledgeMatch[]>;
     /**
-     * Process inbox files: classify, move to correct directory, add to graph.
+     * Gather the linked neighbors of the top-ranked matches (1 hop), following
+     * only explicit non-index edges. Each neighbor is scored as a discount of the
+     * seed that reached it, so it competes for a slot without outranking direct
+     * matches. Returns notes not already present in `seen`.
+     */
+    private expandLinkedNeighbors;
+    /**
+     * Process inbox files: classify, move to correct directory.
      * Files with valid frontmatter are classified by type field.
      * Files without valid frontmatter get heuristic classification as observations.
      */
@@ -122,7 +177,39 @@ export declare class KnowledgeBank {
      * Run the full 7-step defragmentation cycle via KnowledgeDefragmenter.
      */
     defragment(): Promise<DefragResult>;
+    /**
+     * Agentic memory evolution. Given an `evolver` (an agent- or LLM-backed
+     * function; see `createAgenticMemoryEvolver` / `createLlmMemoryEvolver`), take
+     * a snapshot of the bank, let the evolver propose a plan, then apply it via
+     * existing primitives:
+     * - `supersede` → recordContradiction (down-weight stale, point new note)
+     * - `merge`     → write a consolidated entity note linking the source facts
+     * - `link`      → add an explicit edge (esp. entity↔entity) for multi-hop
+     *
+     * The bank never learns HOW the plan was produced — the evolver is a plain
+     * function, keeping the memory layer free of the agent/workspace runtime.
+     */
+    evolve(evolver: MemoryEvolver): Promise<EvolutionResult>;
+    /** Apply a {@link MemoryEvolutionPlan}. Referenced-but-missing note ids are skipped. */
+    applyEvolutionPlan(plan: MemoryEvolutionPlan): Promise<EvolutionResult>;
+    /**
+     * Add an explicit graph edge from one note to another (idempotent). Returns
+     * false if the source note does not exist. Entity↔entity edges added here are
+     * what let a single retrieval surface a pre-linked structure for multi-hop
+     * questions instead of forcing the answerer to re-derive the join.
+     */
+    addLink(fromId: string, toId: string, relation: LinkRelation): Promise<boolean>;
     applyExtraction(extraction: ExtractedKnowledge): Promise<void>;
+    /**
+     * First-class ADD-only conversational extraction (see DESIGN WS3).
+     *
+     * Extracts atomic, coreference-resolved, dated, entity-tagged facts from
+     * dialogue turns and writes them as observations. The LLM is injected as a
+     * `complete` callback so the memory layer carries no model dependency; without
+     * one a deterministic heuristic is used. Returns the extracted knowledge that
+     * was applied.
+     */
+    extractFromConversation(input: ConversationExtractionInput, complete?: ExtractionCompletionFn): Promise<ExtractedKnowledge>;
     /**
      * Reinforce a knowledge note with new evidence from a trajectory.
      * Uses EMA to increase confidence: newConf = (1 - alpha) * oldConf + alpha * 1.0
@@ -139,15 +226,16 @@ export declare class KnowledgeBank {
      * Iterates all trajectories, runs extraction (agent or heuristic), and applies results.
      */
     extractFrom(source: TrajectorySource, options?: {
-        taskRunner?: AgenticTaskRunner;
+        agenticExtractor?: AgenticKnowledgeExtractor;
         analyzer?: TrajectoryAnalyzer;
     }): Promise<ExtractedKnowledge[]>;
     /**
      * Extract knowledge from a single trajectory.
-     * Uses the workspace template if a taskRunner is provided, otherwise falls back to heuristic.
-     * Applies the extraction to the knowledge bank.
+     * Uses the agentic extractor if provided (wire one up with the workspace
+     * layer's `createAgenticKnowledgeExtractor`), otherwise falls back to the
+     * heuristic extractor. Applies the extraction to the knowledge bank.
      */
-    extractFromTrajectory(trajectory: Trajectory, analysis?: AnalysisResult, taskRunner?: AgenticTaskRunner): Promise<ExtractedKnowledge>;
+    extractFromTrajectory(trajectory: Trajectory, analysis?: AnalysisResult, agenticExtractor?: AgenticKnowledgeExtractor): Promise<ExtractedKnowledge>;
     /**
      * Format knowledge notes as a markdown section for agent prompt injection.
      * Groups by type: domain summaries → entities → observations.
@@ -165,6 +253,34 @@ export declare class KnowledgeBank {
      * Replace the active search provider (strategy pattern).
      */
     setSearchProvider(provider: SearchProvider): void;
+    /**
+     * Attach a neural embedding provider. When set, knowledge-note retrieval
+     * defaults to a **hybrid** scorer ({@link HybridSearchProvider}: lexical
+     * TextSimilarity + embedding cosine, fused by balanced linear w=0.5 — the
+     * cross-benchmark best); pass `null` to revert to the lexical TextSimilarity
+     * floor.
+     *
+     * Why hybrid by default: on real memory-QA retrieval (LoCoMo) the hybrid beats
+     * BOTH pure embedding and pure lexical overall (+9pp over the best single
+     * channel) — embedding alone actually *lost* to lexical there because most
+     * questions share surface tokens with their evidence. See
+     * docs/DESIGN-memory-qa-benchmarks.md §4a. Set `mode: 'embedding'` for the
+     * pure-cosine path (e.g. paraphrase-heavy corpora; see amem §6.6).
+     *
+     * Precedence: an explicitly configured embedder wins over minimem
+     * auto-detection (see {@link detectMinimem}).
+     */
+    setEmbeddingProvider(provider: EmbeddingProvider | null, options?: {
+        minScore?: number;
+        mode?: 'hybrid' | 'embedding';
+        /**
+         * Hybrid fusion tuning. Defaults remain encoder-aware linear fusion, but
+         * benchmark runners can opt into RRF or explicit weights.
+         */
+        hybrid?: HybridSearchProviderOptions;
+    }): void;
+    /** The attached embedding provider, if any. */
+    getEmbeddingProvider(): EmbeddingProvider | null;
     /**
      * Detect whether minimem is available and set up the MinimemSearchProvider.
      *
@@ -202,6 +318,10 @@ export declare class KnowledgeBank {
      * When minimemAware, paths are nested under memory/knowledge/ instead of knowledge/.
      */
     private resolveNotePath;
+    /**
+     * Resolve the relative path for a convention note filename.
+     */
+    private resolveConventionPath;
     /**
      * Move an inbox note to the correct directory based on its type.
      * Updates the note's filePath accordingly.
@@ -212,9 +332,6 @@ export declare class KnowledgeBank {
      * Applies heuristic: observation type, agent-authored origin, agentAuthoredInitial confidence.
      */
     private processRawInboxFile;
-    /**
-     * Convert a KnowledgeNote to a GraphNode.
-     */
     /**
      * Enforce a token budget on a list of matches.
      * Always includes at least one match.
@@ -229,6 +346,5 @@ export declare class KnowledgeBank {
      * Used for coherence checking before insertion.
      */
     private getRelatedNotes;
-    private noteToGraphNode;
 }
 //# sourceMappingURL=knowledge-bank.d.ts.map