@kognai/orchestrator-core 0.1.0

package/dist/lib/asmr.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ASMR episodic memory cluster (TICKET-215 Wave D) — extract → retrieve +
+ * Sherlock supervisor-memory context. Namespaced ('asmr.*') to keep generic
+ * names (e.g. RetrievalResult) off the package's flat surface.
+ */
+export * from './asmr-extractor';
+export * from './asmr-retrieval';
+export * from './sherlock-memory';

package/dist/lib/asmr.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * ASMR episodic memory cluster (TICKET-215 Wave D) — extract → retrieve +
+ * Sherlock supervisor-memory context. Namespaced ('asmr.*') to keep generic
+ * names (e.g. RetrievalResult) off the package's flat surface.
+ */
+__exportStar(require("./asmr-extractor"), exports);
+__exportStar(require("./asmr-retrieval"), exports);
+__exportStar(require("./sherlock-memory"), exports);

package/dist/lib/brainx-client.d.ts

@@ -0,0 +1,72 @@
+export type MemoryType = 'fact' | 'procedure' | 'episode' | 'preference' | 'error' | 'success' | 'reflection' | 'skill_rental_gotcha' | 'skill_rental_learning';
+export type MemoryTier = 'HOT' | 'WARM' | 'COLD' | 'ARCHIVE' | 'RENTAL_EXPIRED';
+export interface BrainXMemory {
+    id: string;
+    agent_id: string;
+    sprint?: string;
+    content: string;
+    summary?: string;
+    embedding: number[];
+    memory_type: MemoryType;
+    tier: MemoryTier;
+    importance: number;
+    tags: string[];
+    access_count: number;
+    last_accessed_at?: Date;
+    created_at: Date;
+    rental_id?: string;
+    skill_id?: string;
+    rental_swarm_id?: string;
+    rental_expires_at?: Date;
+    propagated_from?: string;
+    is_rental_expired: boolean;
+    feedback_included: boolean;
+    anonymised_content?: string;
+}
+export interface StoreOptions {
+    sprint?: string;
+    memory_type?: MemoryType;
+    importance?: number;
+    tags?: string[];
+    rental_id?: string;
+    skill_id?: string;
+    rental_swarm_id?: string;
+    rental_expires_at?: Date;
+}
+export interface RetrieveOptions {
+    topK?: number;
+    minImportance?: number;
+    tiers?: MemoryTier[];
+    sprint?: string;
+    excludeExpired?: boolean;
+}
+export declare class BrainXClient {
+    private agentId;
+    private pg;
+    constructor(agentId: string);
+    /**
+     * Lazily initialise pg pool. Requires pg to be installed.
+     * Falls back gracefully if DATABASE_URL / PG* env vars are missing.
+     */
+    private getPool;
+    /**
+     * Store a memory. Generates embedding automatically.
+     * Returns the new memory ID, or null if DB unavailable.
+     */
+    store(content: string, opts?: StoreOptions): Promise<string | null>;
+    /**
+     * Retrieve memories by semantic similarity to a query.
+     * Uses pgvector cosine distance for native GPU-accelerated search.
+     */
+    retrieve(query: string, opts?: RetrieveOptions): Promise<BrainXMemory[]>;
+    /**
+     * Promote a memory's access_count and last_accessed_at on retrieval.
+     */
+    touch(id: string): Promise<void>;
+    /**
+     * Inject HOT-tier memories as context prefix for the agent's next prompt.
+     * Returns formatted text block, empty string if no HOT memories.
+     */
+    injectContext(sprintHint?: string): Promise<string>;
+    close(): Promise<void>;
+}

package/dist/lib/brainx-client.js

@@ -0,0 +1,200 @@
+"use strict";
+// BrainX memory client — AMD-02 Addendum (P0-MEM2)
+// Wraps PostgreSQL + pgvector for episodic memory store/retrieve.
+// Requires: npm install pg @types/pg
+// Requires: PostgreSQL + pgvector running locally (see brainx-schema.sql)
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainXClient = void 0;
+const brainx_embed_1 = require("./brainx-embed");
+// ── Client ───────────────────────────────────────────────────────────────────
+class BrainXClient {
+    agentId;
+    pg = null;
+    constructor(agentId) {
+        this.agentId = agentId;
+    }
+    /**
+     * Lazily initialise pg pool. Requires pg to be installed.
+     * Falls back gracefully if DATABASE_URL / PG* env vars are missing.
+     */
+    async getPool() {
+        if (this.pg)
+            return this.pg;
+        if (!process.env.DATABASE_URL && !process.env.PGHOST) {
+            process.stderr.write('[brainx] No DB config — memory ops are no-ops\n');
+            return null;
+        }
+        try {
+            const { Pool } = await Promise.resolve().then(() => __importStar(require('pg')));
+            this.pg = new Pool({
+                connectionString: process.env.DATABASE_URL,
+                max: 5,
+                idleTimeoutMillis: 30000,
+            });
+            return this.pg;
+        }
+        catch {
+            process.stderr.write('[brainx] pg not installed — run: npm install pg\n');
+            return null;
+        }
+    }
+    /**
+     * Store a memory. Generates embedding automatically.
+     * Returns the new memory ID, or null if DB unavailable.
+     */
+    async store(content, opts = {}) {
+        const pool = await this.getPool();
+        if (!pool)
+            return null;
+        const vec = await (0, brainx_embed_1.embed)(content);
+        const sql = `
+      INSERT INTO brainx_memories
+        (agent_id, sprint, content, embedding, memory_type, importance, tags,
+         rental_id, skill_id, rental_swarm_id, rental_expires_at)
+      VALUES ($1,$2,$3,$4::vector,$5,$6,$7,$8,$9,$10,$11)
+      RETURNING id
+    `;
+        const vals = [
+            this.agentId,
+            opts.sprint ?? null,
+            content,
+            `[${vec.join(',')}]`,
+            opts.memory_type ?? 'episode',
+            opts.importance ?? 5,
+            opts.tags ?? [],
+            opts.rental_id ?? null,
+            opts.skill_id ?? null,
+            opts.rental_swarm_id ?? null,
+            opts.rental_expires_at ?? null,
+        ];
+        const res = await pool.query(sql, vals);
+        return res.rows[0].id;
+    }
+    /**
+     * Retrieve memories by semantic similarity to a query.
+     * Uses pgvector cosine distance for native GPU-accelerated search.
+     */
+    async retrieve(query, opts = {}) {
+        const pool = await this.getPool();
+        if (!pool)
+            return [];
+        const topK = opts.topK ?? 5;
+        const minImp = opts.minImportance ?? 1;
+        const tiers = opts.tiers ?? ['HOT', 'WARM', 'COLD'];
+        const excludeExpired = opts.excludeExpired ?? true;
+        const vec = await (0, brainx_embed_1.embed)(query);
+        const sql = `
+      SELECT *, 1 - (embedding <=> $1::vector) AS similarity
+      FROM brainx_memories
+      WHERE agent_id      = $2
+        AND importance   >= $3
+        AND tier          = ANY($4::memory_tier_enum[])
+        AND ($5::boolean = FALSE OR is_rental_expired = FALSE)
+        AND ($6::text IS NULL OR sprint = $6)
+      ORDER BY embedding <=> $1::vector
+      LIMIT $7
+    `;
+        const vals = [
+            `[${vec.join(',')}]`,
+            this.agentId,
+            minImp,
+            tiers,
+            excludeExpired,
+            opts.sprint ?? null,
+            topK,
+        ];
+        const res = await pool.query(sql, vals);
+        return res.rows;
+    }
+    /**
+     * Promote a memory's access_count and last_accessed_at on retrieval.
+     */
+    async touch(id) {
+        const pool = await this.getPool();
+        if (!pool)
+            return;
+        await pool.query(`UPDATE brainx_memories
+       SET access_count = access_count + 1, last_accessed_at = NOW()
+       WHERE id = $1`, [id]);
+    }
+    /**
+     * Inject HOT-tier memories as context prefix for the agent's next prompt.
+     * Returns formatted text block, empty string if no HOT memories.
+     */
+    async injectContext(sprintHint) {
+        const pool = await this.getPool();
+        if (!pool)
+            return '';
+        const sql = `
+      SELECT content FROM brainx_memories
+      WHERE agent_id = $1 AND tier = 'HOT'
+        AND ($2::text IS NULL OR sprint = $2)
+      ORDER BY importance DESC, created_at DESC
+      LIMIT 10
+    `;
+        const res = await pool.query(sql, [this.agentId, sprintHint ?? null]);
+        if (res.rows.length === 0)
+            return '';
+        const lines = res.rows.map(r => `- ${r.content}`).join('\n');
+        return `## Episodic Memory (HOT)\n${lines}\n`;
+    }
+    async close() {
+        if (this.pg) {
+            await this.pg.end();
+            this.pg = null;
+        }
+    }
+}
+exports.BrainXClient = BrainXClient;
+// ── Smoke test ───────────────────────────────────────────────────────────────
+if (require.main === module) {
+    (async () => {
+        const client = new BrainXClient('smoke-test-agent');
+        console.log('\n🧠 BrainX Client Smoke Test');
+        const id = await client.store('Agents must seek knowledge before acting.', {
+            memory_type: 'reflection', importance: 8, tags: ['five-principles'],
+        });
+        if (id) {
+            console.log(`✅ store() → id: ${id}`);
+            const results = await client.retrieve('what should agents do before starting?');
+            console.log(`✅ retrieve() → ${results.length} results`);
+        }
+        else {
+            console.log('⚠️  DB not configured — graceful no-op confirmed');
+        }
+        await client.close();
+    })();
+}

package/dist/lib/brainx-embed.d.ts

@@ -0,0 +1,14 @@
+export declare function embed(text: string): Promise<number[]>;
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export interface EmbeddedItem {
+    id: string;
+    embedding: number[];
+}
+export interface RankedItem extends EmbeddedItem {
+    similarity: number;
+}
+/**
+ * Given a query string, rank a list of pre-embedded items by cosine similarity.
+ * Returns items sorted descending, optionally limited to topK.
+ */
+export declare function rankBySimilarity(query: string, items: EmbeddedItem[], topK?: number): Promise<RankedItem[]>;

package/dist/lib/brainx-embed.js

@@ -0,0 +1,139 @@
+"use strict";
+// BrainX local embedding adapter — AMD-02 Addendum (P0-MEM1)
+// Replaces OpenAI text-embedding-3-small (1536 dims) with nomic-embed-text via Ollama (768 dims)
+// All embeddings are generated locally on Mac Mini M4 — zero cost, no data leaves the vault.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.embed = embed;
+exports.cosineSimilarity = cosineSimilarity;
+exports.rankBySimilarity = rankBySimilarity;
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const OLLAMA_BASE = process.env.OLLAMA_BASE || 'http://127.0.0.1:11434'; // SEC1: loopback-only default
+const EMBED_MODEL = 'nomic-embed-text';
+const EMBED_DIMS = 768;
+// ── Core embedding ──────────────────────────────────────────────────────────
+async function embed(text) {
+    const body = JSON.stringify({ model: EMBED_MODEL, input: text });
+    return new Promise((resolve, reject) => {
+        const url = new URL(`${OLLAMA_BASE}/api/embed`);
+        const mod = url.protocol === 'https:' ? https : http;
+        const req = mod.request({
+            hostname: url.hostname,
+            port: url.port || (url.protocol === 'https:' ? 443 : 80),
+            path: url.pathname,
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+            timeout: 10000,
+        }, (res) => {
+            let data = '';
+            res.on('data', (chunk) => (data += chunk));
+            res.on('end', () => {
+                try {
+                    const json = JSON.parse(data);
+                    const vec = json.embeddings?.[0];
+                    if (!vec || vec.length !== EMBED_DIMS) {
+                        reject(new Error(`embed: expected ${EMBED_DIMS}-dim vector, got ${vec?.length ?? 'none'}`));
+                    }
+                    else {
+                        resolve(vec);
+                    }
+                }
+                catch (e) {
+                    reject(new Error(`embed: JSON parse error — ${e.message}`));
+                }
+            });
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('embed: Ollama timeout')); });
+        req.write(body);
+        req.end();
+    });
+}
+// ── Math helpers ────────────────────────────────────────────────────────────
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        throw new Error('cosineSimilarity: dimension mismatch');
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+/**
+ * Given a query string, rank a list of pre-embedded items by cosine similarity.
+ * Returns items sorted descending, optionally limited to topK.
+ */
+async function rankBySimilarity(query, items, topK = 5) {
+    const queryVec = await embed(query);
+    return items
+        .map(item => ({ ...item, similarity: cosineSimilarity(queryVec, item.embedding) }))
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, topK);
+}
+// ── Smoke test ──────────────────────────────────────────────────────────────
+if (require.main === module) {
+    (async () => {
+        console.log(`\n🧠 BrainX Embed Smoke Test`);
+        console.log(`   Model: ${EMBED_MODEL} (${EMBED_DIMS} dims)`);
+        console.log(`   Ollama: ${OLLAMA_BASE}\n`);
+        try {
+            const t0 = Date.now();
+            const vec = await embed('The five principles bind every agent in the Kognai swarm.');
+            console.log(`✅ embed() — ${vec.length} dims in ${Date.now() - t0}ms`);
+            console.log(`   First 5 values: [${vec.slice(0, 5).map(v => v.toFixed(4)).join(', ')}...]\n`);
+            const items = [
+                { id: 'a', embedding: await embed('Seek knowledge before acting') },
+                { id: 'b', embedding: await embed('Protect user data and dignity') },
+                { id: 'c', embedding: await embed('Benefit others through your output') },
+            ];
+            const ranked = await rankBySimilarity('what does it mean to act ethically?', items, 3);
+            console.log('✅ rankBySimilarity() results:');
+            for (const r of ranked) {
+                console.log(`   [${r.id}] similarity=${r.similarity.toFixed(4)}`);
+            }
+            console.log('\n✅ PASS — nomic-embed-text local adapter working\n');
+        }
+        catch (err) {
+            console.error('❌ FAIL:', err.message);
+            console.error('   Is Ollama running? Is nomic-embed-text pulled?');
+            console.error('   Run: ollama pull nomic-embed-text');
+            process.exit(1);
+        }
+    })();
+}

package/dist/lib/brainx-swarm-bridge.d.ts

@@ -0,0 +1,93 @@
+/**
+ * BrainX Swarm Bridge — Memory Integration for Agent Orchestrator
+ *
+ * Wires BrainX episodic memory into the swarm orchestrator:
+ *
+ *   1. Pre-task: inject relevant HOT memories into agent context
+ *   2. Post-task: store task outcomes as episodic memories
+ *   3. Rental governance: propagate memories within active swarm during rental,
+ *      expire copies on rental end (originator retains WARM)
+ *   4. Distillation: use qwen3:4b to compress verbose memories
+ *
+ * AMD-02 Addendum — Rental Memory Governance Rule:
+ *   - During rental period: propagate skill memories to active swarm agents
+ *   - On rental expiry: originating agent retains memory as WARM tier
+ *   - Copies held by other agents → RENTAL_EXPIRED tier (queryable but deprioritized)
+ *   - Anonymised content generated for expired rentals
+ *
+ * Sprint 652
+ */
+import { type MemoryType } from './brainx-client';
+export interface SwarmContext {
+    swarm_id: string;
+    sprint_id: string;
+    agent_ids: string[];
+    rental_id?: string;
+    rental_expires_at?: Date;
+}
+export interface TaskMemoryInput {
+    agent_id: string;
+    task_id: string;
+    task_title: string;
+    outcome: 'success' | 'failure' | 'partial';
+    summary: string;
+    files_modified: string[];
+    score?: number;
+    error_message?: string;
+}
+export interface MemoryInjection {
+    agent_id: string;
+    context_text: string;
+    memory_count: number;
+}
+export interface GovernanceResult {
+    expired_count: number;
+    retained_count: number;
+    errors: string[];
+}
+export declare class BrainXSwarmBridge {
+    private clients;
+    private swarmCtx;
+    constructor(ctx: SwarmContext);
+    /** Get or create a BrainX client for an agent */
+    private getClient;
+    /**
+     * Inject relevant memories into an agent's context before task execution.
+     * Returns formatted text to prepend to the agent's prompt.
+     */
+    injectMemories(agentId: string): Promise<MemoryInjection>;
+    /**
+     * Inject memories for all agents in the swarm.
+     */
+    injectAll(): Promise<MemoryInjection[]>;
+    /**
+     * Store a task outcome as an episodic memory.
+     * Includes distillation for verbose summaries.
+     */
+    storeTaskMemory(input: TaskMemoryInput): Promise<string | null>;
+    /**
+     * Propagate a memory to all agents in the active swarm during rental period.
+     * Each agent gets a copy with propagated_from set to the originator.
+     */
+    propagateToSwarm(originatorId: string, content: string, memoryType?: MemoryType, importance?: number): Promise<string[]>;
+    /**
+     * Execute Rental Memory Governance Rule on rental expiry:
+     *   - Originating agent: retain as WARM tier
+     *   - Other agents: move to RENTAL_EXPIRED tier
+     *   - Generate anonymised content for expired memories
+     *
+     * Should be called when a rental period ends.
+     */
+    expireRentalMemories(rentalId: string, originatorId: string): Promise<GovernanceResult>;
+    /**
+     * Distill verbose memory content using qwen3:4b.
+     * Returns compressed version, or null if distillation fails.
+     */
+    distill(content: string): Promise<string | null>;
+    close(): Promise<void>;
+}
+/**
+ * Create a BrainX swarm bridge for a sprint execution.
+ * Call this at the start of each swarm run.
+ */
+export declare function createSwarmBridge(swarmId: string, sprintId: string, agentIds: string[], rentalId?: string, rentalExpiresAt?: Date): BrainXSwarmBridge;