@remind_ai/remind 0.1.0

package/dist/src/core/ingest.js

@@ -0,0 +1,117 @@
+// REMind · L0 ingest (write pipeline) · Owner: Bibhas
+// draft(input): salience gate -> factual/episodic routing -> fact extraction OR (graph triples + denoised summary).
+// Returns a draft MemoryRecord (does NOT persist). Ported from the POC addToMemory.
+import { classify, complete } from '../llm.js';
+import { idFor } from '../ids.js';
+const now = () => new Date().toISOString();
+export async function draft(input) {
+    const { user, assistant } = input.messages;
+    const source = input.source ?? 'conversation';
+    // 1. Salience / long-term gate.
+    const isLongTerm = await classify(`You decide whether a user/assistant exchange contains anything worth storing in LONG-TERM memory.
+` +
+        `Respond with a single word: 'yes' or 'no'.
+` +
+        `Examples:
+` +
+        `- { user: My birthday is on 27th June, assistant: excited for it } -> yes
+` +
+        `- { user: what's 2x3, assistant: 6 } -> no
+` +
+        `- { user: Pav Bhaji is my favorite food } -> yes
+` +
+        `Conversation: { user: ${user}, assistant: ${assistant} }
+Answer only 'yes' or 'no'.`);
+    if (isLongTerm.startsWith('no'))
+        return null;
+    // 2. Factual vs episodic routing.
+    const isFactual = await classify(`Decide whether the exchange should be stored as FACTUAL memory (durable facts) vs EPISODIC (a time-stamped event).
+` +
+        `Respond 'yes' for factual, 'no' for episodic.
+` +
+        `Examples:
+` +
+        `- { user: My favorite color is blue } -> yes
+` +
+        `- { user: I went trekking in Manali last summer } -> no
+` +
+        `- { user: I work at Google as a backend developer } -> yes
+` +
+        `Conversation: { user: ${user}, assistant: ${assistant} }
+Answer only 'yes' or 'no'.`);
+    if (isFactual.startsWith('yes')) {
+        // 3a. Fact extraction — denoise to a concise statement.
+        const fact = await complete(`Extract the durable fact as a short precise statement, no extra words.
+` +
+            `Examples:
+` +
+            `- { user: My favorite color is blue } -> User's favorite color is blue
+` +
+            `- { user: I work at Google as a backend developer } -> User is a backend developer at Google
+` +
+            `Conversation: { user: ${user}, assistant: ${assistant} }
+Return only the fact string.`, { temperature: 0 });
+        return {
+            id: idFor(input.agentId, 'fact', fact),
+            agentId: input.agentId,
+            type: 'factual',
+            content: fact,
+            trust: 1,
+            confidence: 0.8,
+            provenance: { source },
+            tier: 'hot',
+            sourceId: input.sourceId,
+            createdAt: now(),
+        };
+    }
+    // 3b. Episodic — extract graph triples + a denoised vector summary.
+    const triples = await extractTriples(user, assistant);
+    const summary = await complete(`Summarize the episodic event into a single clean sentence for semantic storage, noise removed. Return only the sentence.
+` +
+        `Examples:
+` +
+        `- { user: I went trekking in Manali last summer } -> User traveled to Manali for trekking last summer.
+` +
+        `- { user: I watched Interstellar last weekend } -> User watched the movie Interstellar last weekend.
+` +
+        `Conversation: { user: ${user}, assistant: ${assistant} }`, { temperature: 0 });
+    return {
+        id: idFor(input.agentId, 'episodic', summary),
+        agentId: input.agentId,
+        type: 'episodic',
+        content: summary,
+        triples,
+        trust: 1,
+        confidence: 0.7,
+        provenance: { source },
+        tier: 'hot',
+        sourceId: input.sourceId,
+        createdAt: now(),
+    };
+}
+async function extractTriples(user, assistant) {
+    const raw = await complete(`Extract the episodic event as knowledge-graph triples.
+` +
+        `Return ONLY a JSON array of objects: [{"subject":"...","relation":"...","object":"..."}].
+` +
+        `Use "User" as the subject when the event is about the user. Keep names concise. No prose, no markdown.
+` +
+        `Examples:
+` +
+        `- { user: I went trekking in Manali last summer } -> [{"subject":"User","relation":"traveledTo","object":"Manali"}]
+` +
+        `- { user: I watched Interstellar last weekend } -> [{"subject":"User","relation":"watchedMovie","object":"Interstellar"}]
+` +
+        `Conversation: { user: ${user}, assistant: ${assistant} }`, { temperature: 0 });
+    try {
+        const cleaned = raw.replace(/^```(?:json)?/i, '').replace(/```$/, '').trim();
+        const parsed = JSON.parse(cleaned);
+        if (Array.isArray(parsed)) {
+            return parsed.filter((t) => t && t.subject && t.relation && t.object);
+        }
+    }
+    catch {
+        // ignore malformed JSON — episodic still stored as a vector summary.
+    }
+    return [];
+}

package/dist/src/core/memory-types.d.ts

@@ -0,0 +1,45 @@
+import type { MemoryRecord, MemoryType, Tier } from '../types.js';
+/** Behavioural defaults for one kind of memory. */
+export interface MemoryTypeSpec {
+    /** Tier a brand-new record of this type lands in before consolidation. */
+    tier: Tier;
+    /** Default model confidence (0..1) when a writer does not supply one. */
+    confidence: number;
+    /** Durable kinds survive decay; ephemeral kinds are trimmed/expired fast. */
+    durable: boolean;
+    /** Soft retention budget in ms (Infinity = never auto-expire). decay() hint. */
+    ttlMs: number;
+    /** One-line human description for audits and debugging. */
+    description: string;
+}
+/** The taxonomy: every MemoryType in the frozen contract has exactly one spec. */
+export declare const MEMORY_TYPES: Record<MemoryType, MemoryTypeSpec>;
+/** Tier a fresh record of `type` should default to. */
+export declare const defaultTier: (type: MemoryType) => Tier;
+/** Default confidence for `type` when the writer has none. */
+export declare const defaultConfidence: (type: MemoryType) => number;
+/** Durable types survive decay; ephemeral ones (short/working) do not. */
+export declare const isDurable: (type: MemoryType) => boolean;
+/** Soft retention budget (ms) for `type`; Infinity means never auto-expire. */
+export declare const retentionFor: (type: MemoryType) => number;
+/** True once an ephemeral record has outlived its ttl (measured from last use). */
+export declare function isExpired(record: MemoryRecord, at?: string): boolean;
+/** Input for the lightweight (non-LLM) memory kinds. */
+export interface ScratchInput {
+    agentId: string;
+    content: string;
+    source?: string;
+    sourceId?: string;
+}
+/** Recent-conversation memory (sliding window). Draft only — does not persist. */
+export declare const draftShortTerm: (input: ScratchInput) => MemoryRecord;
+/** Per-task scratchpad memory. Draft only — does not persist. */
+export declare const draftWorking: (input: ScratchInput) => MemoryRecord;
+/** Learned skill / routine memory. Draft only — does not persist. */
+export declare const draftProcedural: (input: ScratchInput) => MemoryRecord;
+/**
+ * Sliding short-term window: keep only the `limit` most recent short-term
+ * records, newest first. Older ones fall out of context (Brain.decay expires
+ * them once they pass their ttl).
+ */
+export declare function windowShortTerm(records: MemoryRecord[], limit?: number): MemoryRecord[];

package/dist/src/core/memory-types.js

@@ -0,0 +1,104 @@
+// REMind · L0 memory taxonomy · Owner: Bibhas (breadth)
+// short-term window, working scratchpad, procedural skills + tier defaults.
+//
+// The frozen contract names five MemoryTypes; ingest.ts produces the two that
+// need LLM extraction (factual, episodic). This module owns the other three
+// lightweight kinds plus the per-type defaults the whole foundation reads from:
+// it is the single source of truth for how a freshly drafted record of any type
+// is tiered, trusted, and retained. The Brain layer's consolidate()/decay()
+// consume these specs to promote durable memories and expire ephemeral ones.
+import { idFor } from '../ids.js';
+const now = () => new Date().toISOString();
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+/** The taxonomy: every MemoryType in the frozen contract has exactly one spec. */
+export const MEMORY_TYPES = {
+    factual: {
+        tier: 'hot',
+        confidence: 0.8,
+        durable: true,
+        ttlMs: Infinity,
+        description: 'Durable semantic fact about the user or the world.',
+    },
+    procedural: {
+        tier: 'warm',
+        confidence: 0.75,
+        durable: true,
+        ttlMs: Infinity,
+        description: 'A learned skill, routine, or how-to the agent can reuse.',
+    },
+    episodic: {
+        tier: 'hot',
+        confidence: 0.7,
+        durable: true,
+        ttlMs: 30 * DAY,
+        description: 'A time-stamped event; consolidates into facts/graph over time.',
+    },
+    short: {
+        tier: 'hot',
+        confidence: 0.5,
+        durable: false,
+        ttlMs: HOUR,
+        description: 'Recent conversation window; ephemeral context that decays fast.',
+    },
+    working: {
+        tier: 'hot',
+        confidence: 0.4,
+        durable: false,
+        ttlMs: 15 * MINUTE,
+        description: 'Active task scratchpad; discarded once the task completes.',
+    },
+};
+/** Tier a fresh record of `type` should default to. */
+export const defaultTier = (type) => MEMORY_TYPES[type].tier;
+/** Default confidence for `type` when the writer has none. */
+export const defaultConfidence = (type) => MEMORY_TYPES[type].confidence;
+/** Durable types survive decay; ephemeral ones (short/working) do not. */
+export const isDurable = (type) => MEMORY_TYPES[type].durable;
+/** Soft retention budget (ms) for `type`; Infinity means never auto-expire. */
+export const retentionFor = (type) => MEMORY_TYPES[type].ttlMs;
+/** True once an ephemeral record has outlived its ttl (measured from last use). */
+export function isExpired(record, at = now()) {
+    const ttl = MEMORY_TYPES[record.type].ttlMs;
+    if (!Number.isFinite(ttl))
+        return false;
+    const since = Date.parse(record.lastUsedAt ?? record.createdAt);
+    const checkedAt = Date.parse(at);
+    if (Number.isNaN(since) || Number.isNaN(checkedAt))
+        return true;
+    return checkedAt - since > ttl;
+}
+/** Build a draft record of a lightweight kind. Deterministic id => idempotent persist. */
+function build(type, input) {
+    const spec = MEMORY_TYPES[type];
+    return {
+        id: idFor(input.agentId, type, input.content),
+        agentId: input.agentId,
+        type,
+        content: input.content,
+        trust: 1,
+        confidence: spec.confidence,
+        provenance: { source: input.source ?? type },
+        tier: spec.tier,
+        sourceId: input.sourceId,
+        createdAt: now(),
+    };
+}
+/** Recent-conversation memory (sliding window). Draft only — does not persist. */
+export const draftShortTerm = (input) => build('short', input);
+/** Per-task scratchpad memory. Draft only — does not persist. */
+export const draftWorking = (input) => build('working', input);
+/** Learned skill / routine memory. Draft only — does not persist. */
+export const draftProcedural = (input) => build('procedural', input);
+/**
+ * Sliding short-term window: keep only the `limit` most recent short-term
+ * records, newest first. Older ones fall out of context (Brain.decay expires
+ * them once they pass their ttl).
+ */
+export function windowShortTerm(records, limit = 10) {
+    return records
+        .filter((r) => r.type === 'short')
+        .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt))
+        .slice(0, limit);
+}

package/dist/src/core/retrieval.d.ts

@@ -0,0 +1,2 @@
+import type { RetrievalResult, Stores } from '../types.js';
+export declare function fetchMemory(stores: Stores, agentId: string, query: string, sourceId?: string): Promise<RetrievalResult>;

package/dist/src/core/retrieval.js

@@ -0,0 +1,55 @@
+// REMind · L0 retrieval (read pipeline) · Owner: Bibhas
+// query rewrite -> vector search -> better-chunks re-query -> frequency fusion -> graph filter -> context assembly.
+// Ported from the POC fetchMemory + the retrieval half of createMessage.
+import { complete } from '../llm.js';
+export async function fetchMemory(stores, agentId, query, sourceId) {
+    // 1. Query rewriting — fix typos + enrich.
+    const refined = await complete(`Fix typos and add helpful context to this query so it retrieves better. Return only the rewritten query string.
+Query: ${query}`);
+    // 2. First retrieval.
+    const first = await stores.vector.search(agentId, refined, 3, sourceId);
+    // 3. Better-chunks re-query.
+    const refined2 = await complete(`Given the user's query and the chunks retrieved, produce an improved retrieval query (same intent). Return only the query string.
+` +
+        `Original query: ${query}
+Rewritten query: ${refined}
+Chunks: ${JSON.stringify(first.map((r) => r.content))}`);
+    const second = await stores.vector.search(agentId, refined2, 3, sourceId);
+    // 4. Frequency fusion — chunks seen in both passes rank higher.
+    const priority = fuse([...first, ...second]).slice(0, 3);
+    // 5. Knowledge-graph relations, filtered to what's relevant.
+    const graphMap = await stores.graph.fetchGraph(agentId);
+    let relations = '';
+    if (graphMap.trim()) {
+        relations = await complete(`From the knowledge-graph relations below, keep only those relevant to the retrieved chunks. Do not add anything. Return plain text.
+` +
+            `Relations:
+${graphMap}
+Relevant chunks: ${JSON.stringify(priority.map((r) => r.content))}`);
+    }
+    // 6. Durable facts + context assembly.
+    const facts = await stores.doc.getFacts(agentId);
+    const context = assemble(facts, relations, priority);
+    return { context, records: priority, facts };
+}
+function fuse(records) {
+    const freq = new Map();
+    records.forEach((r, i) => {
+        const key = r.id || r.content;
+        const e = freq.get(key);
+        if (e)
+            e.count++;
+        else
+            freq.set(key, { count: 1, first: i, rec: r });
+    });
+    return [...freq.values()]
+        .sort((a, b) => b.count - a.count || a.first - b.first)
+        .map((e) => e.rec);
+}
+function assemble(facts, relations, chunks) {
+    const factsText = facts.length ? facts.map((f) => `- ${f}`).join('\n') : 'None';
+    const chunkText = chunks.length ? chunks.map((c) => `- ${c.content}`).join('\n') : 'None';
+    return (`Factual context about the user:\n${factsText}\n\n` +
+        `Episodic relations:\n${relations.trim() || 'None'}\n\n` +
+        `Relevant memory chunks:\n${chunkText}`);
+}

package/dist/src/core/stores/doc.store.d.ts

@@ -0,0 +1,2 @@
+import type { DocStore } from '../../types.js';
+export declare const docStore: DocStore;

package/dist/src/core/stores/doc.store.js

@@ -0,0 +1,74 @@
+// REMind · L0 document store · Owner: Bibhas
+// Azure Cosmos DB for MongoDB (Mongoose drop-in). Holds facts + MemoryRecord metadata.
+import mongoose, { Schema } from 'mongoose';
+import { config } from '../../config.js';
+let conn = null;
+function connect() {
+    // `dbName` is the only option we set. mongoose's ConnectOptions extends the mongodb
+    // driver's TLS-derived options (Pick<tls.ConnectionOptions, ...>), which some TypeScript
+    // versions mis-evaluate as having required members; cast through unknown so the editor
+    // and the workspace compiler agree.
+    const options = { dbName: config.mongo.db };
+    if (!conn)
+        conn = mongoose.connect(config.mongo.uri, options);
+    return conn;
+}
+const RecordSchema = new Schema({
+    id: { type: String, unique: true, index: true },
+    agentId: { type: String, index: true },
+    type: String,
+    content: String,
+    trust: Number,
+    confidence: Number,
+    provenance: Schema.Types.Mixed,
+    validFrom: String,
+    validTo: String,
+    tier: String,
+    quarantined: Boolean,
+    sourceId: String,
+    createdAt: String,
+    lastUsedAt: String,
+    triples: Schema.Types.Mixed,
+}, { versionKey: false });
+const AgentSchema = new Schema({ agentId: { type: String, unique: true, index: true }, facts: [String] }, { versionKey: false });
+const RecordModel = mongoose.models.MemoryRecord ?? mongoose.model('MemoryRecord', RecordSchema);
+const AgentModel = mongoose.models.Agent ?? mongoose.model('Agent', AgentSchema);
+function toRecord(d) {
+    return {
+        id: d.id,
+        agentId: d.agentId,
+        type: d.type,
+        content: d.content,
+        trust: d.trust ?? 1,
+        confidence: d.confidence ?? 0.5,
+        provenance: d.provenance ?? { source: 'doc' },
+        tier: d.tier ?? 'warm',
+        validFrom: d.validFrom,
+        validTo: d.validTo,
+        quarantined: d.quarantined,
+        sourceId: d.sourceId,
+        createdAt: d.createdAt ?? new Date().toISOString(),
+        lastUsedAt: d.lastUsedAt,
+        triples: d.triples,
+    };
+}
+export const docStore = {
+    async pushFact(agentId, fact) {
+        await connect();
+        await AgentModel.updateOne({ agentId }, { $addToSet: { facts: fact } }, { upsert: true });
+    },
+    async getFacts(agentId) {
+        await connect();
+        const a = await AgentModel.findOne({ agentId }).lean();
+        return a?.facts ?? [];
+    },
+    async saveRecord(record) {
+        await connect();
+        await RecordModel.updateOne({ id: record.id }, { $set: record }, { upsert: true });
+    },
+    async getRecords(agentId, filter = {}) {
+        await connect();
+        const docs = await RecordModel.find({ agentId, ...filter }).lean();
+        return docs.map(toRecord);
+    },
+};

package/dist/src/core/stores/graph.store.d.ts

@@ -0,0 +1,2 @@
+import type { GraphStore } from '../../types.js';
+export declare const graphStore: GraphStore;

package/dist/src/core/stores/graph.store.js

@@ -0,0 +1,61 @@
+// REMind · L0 knowledge graph · Owner: Bibhas
+// Azure Cosmos DB for Apache Gremlin (replaces Neo4j). Deterministic, idempotent triple upserts.
+import gremlin from 'gremlin';
+import { config } from '../../config.js';
+// gremlin ships partial types; treat the driver namespace loosely.
+const G = gremlin;
+let client;
+function getClient() {
+    if (client)
+        return client;
+    const authenticator = new G.driver.auth.PlainTextSaslAuthenticator(`/dbs/${config.gremlin.database}/colls/${config.gremlin.graph}`, config.gremlin.key);
+    client = new G.driver.Client(config.gremlin.endpoint, {
+        authenticator,
+        traversalsource: 'g',
+        rejectUnauthorized: true,
+        mimeType: 'application/vnd.gremlin-v2.0+json',
+    });
+    return client;
+}
+/** Gremlin string-literal escaping. */
+const esc = (s) => s.replace(/'/g, "\\'");
+async function ensureVertex(name, agentId) {
+    const n = esc(name);
+    const a = esc(agentId);
+    // partitionKey = agentId so every vertex is tenant-scoped (Cosmos requirement).
+    await getClient().submit(`g.V().has('Entity','name','${n}').has('agentId','${a}').fold()` +
+        `.coalesce(unfold(),addV('Entity').property('name','${n}').property('agentId','${a}').property('partitionKey','${a}'))`);
+}
+export const graphStore = {
+    async writeTriples(agentId, triples) {
+        for (const t of triples) {
+            if (!t.subject || !t.relation || !t.object)
+                continue;
+            await ensureVertex(t.subject, agentId);
+            await ensureVertex(t.object, agentId);
+            const s = esc(t.subject);
+            const o = esc(t.object);
+            const rel = esc(t.relation);
+            const a = esc(agentId);
+            await getClient().submit(`g.V().has('Entity','name','${s}').has('agentId','${a}').as('s')` +
+                `.V().has('Entity','name','${o}').has('agentId','${a}')` +
+                `.coalesce(__.inE('${rel}').where(outV().as('s')), addE('${rel}').from('s'))`);
+        }
+    },
+    async fetchGraph(agentId) {
+        const a = esc(agentId);
+        // outE/inV (not bothE/otherV) so each directed edge is emitted exactly once,
+        // oriented subject -> object — matching the `-[e]->` rendering below.
+        const res = await getClient().submit(`g.V().has('agentId','${a}').as('v').outE().as('e').inV().as('o').select('v','e','o')`);
+        const rows = res?._items ?? (typeof res?.toArray === 'function' ? res.toArray() : res) ?? [];
+        let map = '';
+        for (const row of rows) {
+            const v = row?.v?.properties?.name?.[0]?.value ?? row?.v?.label;
+            const e = row?.e?.label;
+            const o = row?.o?.properties?.name?.[0]?.value ?? row?.o?.label;
+            if (v && e && o)
+                map += `(${v}) -[${e}]-> (${o})\n`;
+        }
+        return map;
+    },
+};

package/dist/src/core/stores/vector.store.d.ts

@@ -0,0 +1,2 @@
+import type { VectorStore } from '../../types.js';
+export declare const vectorStore: VectorStore;

package/dist/src/core/stores/vector.store.js

@@ -0,0 +1,87 @@
+// REMind · L0 vector store · Owner: Bibhas
+// Azure AI Search (native vector search, replaces Qdrant). Per-agent filtering + idempotent upsert.
+import { AzureKeyCredential, SearchClient, SearchIndexClient, } from '@azure/search-documents';
+import { config } from '../../config.js';
+import { embed } from '../../llm.js';
+const credential = new AzureKeyCredential(config.search.apiKey);
+const searchClient = new SearchClient(config.search.endpoint, config.search.index, credential);
+const indexClient = new SearchIndexClient(config.search.endpoint, credential);
+/** OData string-literal escaping. */
+const esc = (s) => s.replace(/'/g, "''");
+let ensured = false;
+async function ensureIndex() {
+    if (ensured)
+        return;
+    const index = {
+        name: config.search.index,
+        fields: [
+            { name: 'id', type: 'Edm.String', key: true, filterable: true },
+            { name: 'agentId', type: 'Edm.String', filterable: true },
+            { name: 'type', type: 'Edm.String', filterable: true },
+            { name: 'sourceId', type: 'Edm.String', filterable: true },
+            { name: 'content', type: 'Edm.String', searchable: true },
+            { name: 'createdAt', type: 'Edm.String', filterable: true, sortable: true },
+            {
+                name: 'embedding',
+                type: 'Collection(Edm.Single)',
+                searchable: true,
+                vectorSearchDimensions: config.azureOpenAI.embedDimensions,
+                vectorSearchProfileName: 'remind-hnsw-profile',
+            },
+        ],
+        vectorSearch: {
+            algorithms: [{ name: 'remind-hnsw', kind: 'hnsw' }],
+            profiles: [{ name: 'remind-hnsw-profile', algorithmConfigurationName: 'remind-hnsw' }],
+        },
+    };
+    await indexClient.createOrUpdateIndex(index);
+    ensured = true;
+}
+export const vectorStore = {
+    async upsert(record) {
+        await ensureIndex();
+        const embedding = record.embedding ?? (await embed(record.content));
+        await searchClient.mergeOrUploadDocuments([
+            {
+                id: record.id,
+                agentId: record.agentId,
+                type: record.type,
+                content: record.content,
+                sourceId: record.sourceId,
+                createdAt: record.createdAt,
+                embedding,
+            },
+        ]);
+    },
+    async search(agentId, query, k = 3, sourceId) {
+        await ensureIndex();
+        const vector = await embed(query);
+        const filters = [`agentId eq '${esc(agentId)}'`];
+        if (sourceId)
+            filters.push(`sourceId eq '${esc(sourceId)}'`);
+        const results = await searchClient.search('*', {
+            vectorSearchOptions: {
+                queries: [{ kind: 'vector', vector, kNearestNeighborsCount: k, fields: ['embedding'] }],
+            },
+            filter: filters.join(' and '),
+            top: k,
+        });
+        const out = [];
+        for await (const r of results.results) {
+            const d = r.document;
+            out.push({
+                id: d.id,
+                agentId: d.agentId,
+                type: d.type,
+                content: d.content,
+                sourceId: d.sourceId,
+                createdAt: d.createdAt,
+                trust: 1,
+                confidence: 0.7,
+                provenance: { source: 'vector' },
+                tier: 'warm',
+            });
+        }
+        return out;
+    },
+};

package/dist/src/engine.d.ts

@@ -0,0 +1,33 @@
+import type { Brain, ConsolidationReport, IngestInput, MemGuardHooks, MemoryEngineCore, RetrievalResult, Stores } from './types.js';
+import { type Queues } from './queue/queues.js';
+/** The three injected layers plus their shared stores — the composition root's payload. */
+export interface Layers {
+    core: MemoryEngineCore;
+    brain: Brain;
+    guard: MemGuardHooks;
+    stores: Stores;
+}
+export interface MemoryAPI {
+    addToMemory(input: IngestInput): Promise<void>;
+    fetchMemory(agentId: string, query: string, sourceId?: string): Promise<RetrievalResult>;
+    sleep(agentId: string): Promise<ConsolidationReport>;
+    forget(agentId: string): Promise<void>;
+    close(): Promise<void>;
+}
+/** A no-op MemGuard: allow everything, never quarantine, never report drift ("MemGuard OFF"). */
+export declare const passthroughGuard: MemGuardHooks;
+export declare class MemoryEngine implements MemoryAPI {
+    private readonly layers;
+    private readonly queues;
+    constructor(layers: Layers, queues?: Queues);
+    /** Write path: enqueue ingest (inline in SYNC mode, async + retried via Redis otherwise). */
+    addToMemory(input: IngestInput): Promise<void>;
+    /** Read path (direct): retrieve, then run the output firewall (guard.onOutput). */
+    fetchMemory(agentId: string, query: string, sourceId?: string): Promise<RetrievalResult>;
+    /** Sleep cycle: run inline and return the report in SYNC mode, else enqueue. */
+    sleep(agentId: string): Promise<ConsolidationReport>;
+    /** Decay pass: inline in SYNC mode, else enqueue. */
+    forget(agentId: string): Promise<void>;
+    /** Release queue / worker / Redis resources. */
+    close(): Promise<void>;
+}

package/dist/src/engine.js

@@ -0,0 +1,63 @@
+// REMind · Orchestrator (producer) · Owner: Yasho
+// MemoryEngine composes Foundation + Brain + MemGuard via dependency injection and owns the
+// queues. Writes enqueue (crash-safe + async via Redis; inline in SYNC mode); reads are direct
+// (core.fetchMemory + guard.onOutput); sleep() runs or enqueues a consolidation cycle.
+import { config } from './config.js';
+import { createQueues } from './queue/queues.js';
+import { closeConnection } from './queue/connection.js';
+import { registerIngestWorker } from './workers/ingest.worker.js';
+import { registerConsolidateWorker, runConsolidate } from './workers/consolidate.worker.js';
+import { registerForgetWorker, runForget } from './workers/forget.worker.js';
+/** A no-op MemGuard: allow everything, never quarantine, never report drift ("MemGuard OFF"). */
+export const passthroughGuard = {
+    onIngest: async (_input, record) => ({ allow: true, record }),
+    onConsolidate: async () => ({ promote: true }),
+    onOutput: async (records) => records,
+    checkCanaries: async () => ({ drift: false, details: 'MemGuard disabled' }),
+};
+export class MemoryEngine {
+    layers;
+    queues;
+    constructor(layers, queues) {
+        this.layers = layers;
+        this.queues = queues ?? createQueues();
+        registerIngestWorker(this.queues, this.layers);
+        registerConsolidateWorker(this.queues, this.layers);
+        registerForgetWorker(this.queues, this.layers);
+    }
+    /** Write path: enqueue ingest (inline in SYNC mode, async + retried via Redis otherwise). */
+    async addToMemory(input) {
+        await this.queues.ingest.add({ input });
+    }
+    /** Read path (direct): retrieve, then run the output firewall (guard.onOutput). */
+    async fetchMemory(agentId, query, sourceId) {
+        const result = await this.layers.core.fetchMemory(agentId, query, sourceId);
+        const records = await this.layers.guard.onOutput(result.records);
+        return { ...result, records };
+    }
+    /** Sleep cycle: run inline and return the report in SYNC mode, else enqueue. */
+    async sleep(agentId) {
+        if (config.sync)
+            return runConsolidate(this.layers, agentId);
+        await this.queues.consolidate.add({ agentId });
+        return { promoted: [], blocked: [], merged: 0 };
+    }
+    /** Decay pass: inline in SYNC mode, else enqueue. */
+    async forget(agentId) {
+        if (config.sync) {
+            await runForget(this.layers, agentId);
+            return;
+        }
+        await this.queues.forget.add({ agentId });
+    }
+    /** Release queue / worker / Redis resources. */
+    async close() {
+        await Promise.all([
+            this.queues.ingest.close(),
+            this.queues.consolidate.close(),
+            this.queues.forget.close(),
+            this.queues.quarantine.close(),
+        ]);
+        await closeConnection(); // no-op in inline/SYNC mode (no connection was opened)
+    }
+}

package/dist/src/ids.d.ts

@@ -0,0 +1 @@
+export declare function idFor(agentId: string, kind: string, content: string): string;