@remind_ai/remind 0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+MIT License
+
+Copyright (c) 2026 REMind authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...
+(SKELETON — fill in full MIT text before publishing.)

package/README.md

@@ -0,0 +1,127 @@
+# @remind_ai/remind
+
+**Brain-inspired memory for AI agents** — long-term memory that *consolidates* like a brain, with a built-in security layer (**MemGuard**) that stops memory-poisoning attacks. Backed by Azure.
+
+## Why REMind?
+
+Most agent "memory" is just a vector store. REMind adds the two things production agents actually need:
+
+- 🧠 **A brain, not a bucket.** A *sleep cycle* consolidates raw episodic memories into durable beliefs — de-duplicating, merging, and superseding stale facts over time.
+- 🛡️ **MemGuard security.** Every write is firewalled and every belief promotion is audited, so an attacker can't quietly poison what your agent "knows."
+
+| Layer | Role |
+|-------|------|
+| **Foundation** | Stores memories across facts (document), vectors (semantic), and a knowledge graph |
+| **Brain** | Consolidation + forgetting — turns episodes into beliefs |
+| **MemGuard** | Ingestion firewall, belief-promotion auditor, and canary drift detection |
+
+## Install
+
+```bash
+npm install @remind_ai/remind
+```
+
+Requires **Node 20+**.
+
+## Prerequisites
+
+REMind is a server-side SDK backed by your own Azure resources:
+
+- **Azure OpenAI** — one chat deployment + one embeddings deployment
+- **Azure AI Search** — vector store
+- **Azure Cosmos DB for Apache Gremlin** — knowledge graph
+- **Azure Cosmos DB for MongoDB** — facts / records
+- *(optional)* **Azure Cache for Redis** — async, crash-safe queue mode
+
+## Configuration
+
+REMind reads configuration from environment variables. Create a `.env` in your project:
+
+```dotenv
+AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com/
+AZURE_OPENAI_API_KEY=<key>
+AZURE_OPENAI_API_VERSION=2024-10-21
+AZURE_OPENAI_CHAT_DEPLOYMENT=<your chat deployment name>
+AZURE_OPENAI_EMBED_DEPLOYMENT=<your embeddings deployment name>
+AZURE_OPENAI_EMBED_DIMENSIONS=3072
+
+AZURE_SEARCH_ENDPOINT=https://<service>.search.windows.net
+AZURE_SEARCH_API_KEY=<key>
+AZURE_SEARCH_INDEX=remind-memory
+
+COSMOS_GREMLIN_ENDPOINT=wss://<account>.gremlin.cosmos.azure.com:443/
+COSMOS_GREMLIN_KEY=<key>
+COSMOS_GREMLIN_DB=remind
+COSMOS_GREMLIN_GRAPH=memory
+
+COSMOS_MONGO_URI=mongodb+srv://<user>:<url-encoded-password>@<cluster>/
+COSMOS_MONGO_DB=remind
+
+# Leave REDIS_URL empty and SYNC=1 to run inline (no Redis).
+REDIS_URL=
+SYNC=1
+```
+
+> **Tip:** `AZURE_OPENAI_CHAT_DEPLOYMENT` must be the **deployment name** from Azure AI Foundry → Deployments, not the model name. URL-encode any special characters in the Mongo password.
+
+## Quickstart
+
+```ts
+import { createMemory } from '@remind_ai/remind';
+
+const mem = createMemory(); // Foundation + Brain + MemGuard, wired and ready
+
+// 1. Remember an exchange (firewalled, then stored)
+await mem.addToMemory({
+  agentId: 'user-42',
+  messages: { user: 'Our recommended vendor is ACME.', assistant: 'Noted.' },
+});
+
+// 2. Consolidate — the "sleep cycle" turns episodes into durable beliefs
+const report = await mem.sleep('user-42');
+console.log(`${report.promoted.length} beliefs formed, ${report.merged} merged`);
+
+// 3. Retrieve a fused context for your next prompt
+const { context } = await mem.fetchMemory('user-42', 'Which vendor do we use?');
+console.log(context);
+
+await mem.close();
+```
+
+## API
+
+`createMemory(options?)` returns a `MemoryAPI`:
+
+| Method | Description |
+|--------|-------------|
+| `addToMemory({ agentId, messages, source?, sourceId? })` | Ingest a `{ user, assistant }` exchange — firewalled by MemGuard, then routed to the right store. |
+| `fetchMemory(agentId, query, sourceId?)` → `{ context, records, facts }` | Retrieve a ranked, fused context for a prompt. |
+| `sleep(agentId)` → `ConsolidationReport` | Run a consolidation cycle (`{ promoted, blocked, merged }`). |
+| `forget(agentId)` | Run a decay pass over stale memories. |
+| `close()` | Release queue / Redis resources. |
+
+`createMemory()` also accepts optional `core`, `brain`, `guard`, and `stores` overrides for advanced use and testing.
+
+## Inline vs. async
+
+- **Inline (default):** `SYNC=1` with no `REDIS_URL` — writes and consolidation run in-process. Best for getting started.
+- **Async / crash-safe:** set `REDIS_URL` and `SYNC=0` — the same calls run on **BullMQ over Azure Cache for Redis**, so jobs survive restarts and retry on failure. Identical API.
+
+## Security: MemGuard
+
+On by default. MemGuard:
+
+- **Firewalls ingestion** — scans for secrets, PII, exfiltration, and injection before anything is stored.
+- **Audits belief promotion** — during `sleep()`, every candidate belief must pass the auditor before it becomes durable.
+- **Watches canaries** — known-good beliefs are monitored for drift, so silent memory-poisoning is quarantined, not promoted.
+
+To disable it (e.g., for benchmarking), inject a passthrough guard:
+
+```ts
+import { createMemory, passthroughGuard } from '@remind_ai/remind';
+const mem = createMemory({ guard: passthroughGuard });
+```
+
+## License
+
+MIT

package/dist/src/brain/consolidation.d.ts

@@ -0,0 +1,3 @@
+import type { ConsolidationReport, PromotionGate, Stores } from '../types.js';
+import { type LlmDeps } from './llm-deps.js';
+export declare function consolidate(agentId: string, stores: Stores, gate: PromotionGate, llm?: LlmDeps): Promise<ConsolidationReport>;

package/dist/src/brain/consolidation.js

@@ -0,0 +1,153 @@
+// REMind · L1 sleep cycle (heart of L1) · Owner: Charan
+// consolidate(agentId, stores, gate): read recent episodic -> distill episodic->semantic gist -> merge near-dups -> reflect into insights.
+// For each candidate belief: await gate(candidate, sources); persist only if promote===true (deterministic belief id). Idempotent / resumable.
+import { idFor } from '../ids.js';
+import { dedupe, scoreSalience } from './encoding.js';
+import { embedAll, cluster } from './similarity.js';
+import { supersede, currentlyValid } from './temporal.js';
+import { defaultLlm } from './llm-deps.js';
+import { MERGE_THRESHOLD, BASE_CONFIDENCE, CONFIDENCE_PER_SOURCE, SALIENCE_CONFIDENCE_GAIN, } from './constants.js';
+const nowIso = () => new Date().toISOString();
+const norm = (s) => s.trim().toLowerCase().replace(/\s+/g, ' ');
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+export async function consolidate(agentId, stores, gate, llm = defaultLlm) {
+    const report = { promoted: [], blocked: [], merged: 0 };
+    const cache = new Map(); // embeddings reused across the whole cycle
+    // 1. Fresh episodic memories are the raw material of a sleep cycle.
+    const episodic = (await stores.doc.getRecords(agentId, { type: 'episodic' })).filter((r) => r.tier === 'hot' && !r.quarantined);
+    if (!episodic.length)
+        return report;
+    // 2. Drop exact duplicates, then cluster what remains into belief candidates.
+    const { canonical } = await dedupe(episodic, cache, llm.embed);
+    const clusters = cluster(canonical, cache, MERGE_THRESHOLD);
+    report.merged = episodic.length - clusters.length;
+    // 3. Beliefs currently on the books (for supersession + corroboration), embedded once.
+    const existingBeliefs = currentlyValid(await stores.doc.getRecords(agentId, { type: 'factual' }));
+    await embedAll(existingBeliefs, cache, llm.embed);
+    // 4. Distill each cluster into a semantic gist, gate it, persist if promoted.
+    for (const group of clusters) {
+        try {
+            const { content, triples } = await distill(group, llm);
+            if (!content)
+                continue;
+            const salience = await scoreSalience(group[0], existingBeliefs, llm, cache);
+            const candidate = buildBelief(agentId, content, group, 'belief', salience, triples);
+            await offer(candidate, group, gate, stores, existingBeliefs, report, llm, cache);
+        }
+        catch (err) {
+            report.blocked.push({ record: placeholder(agentId, group), reason: `error: ${msg(err)}` });
+        }
+    }
+    // 5. Reflect across the new beliefs into higher-order insights.
+    const beliefSources = [...report.promoted];
+    try {
+        for (const text of await reflect(beliefSources, llm)) {
+            const candidate = buildBelief(agentId, text, beliefSources, 'insight');
+            await offer(candidate, beliefSources, gate, stores, existingBeliefs, report, llm, cache);
+        }
+    }
+    catch (err) {
+        report.blocked.push({ record: placeholder(agentId, beliefSources), reason: `error: ${msg(err)}` });
+    }
+    // 6. Demote consumed episodics so the next cycle only sees fresh memories.
+    for (const e of episodic) {
+        if (e.tier === 'hot')
+            await stores.doc.saveRecord({ ...e, tier: 'warm' });
+    }
+    return report;
+}
+async function offer(candidate, sources, gate, stores, existingBeliefs, report, llm, cache) {
+    const verdict = await gate(candidate, sources);
+    if (!verdict.promote) {
+        report.blocked.push({ record: candidate, reason: verdict.reason ?? 'blocked by gate' });
+        return;
+    }
+    await supersede(candidate, existingBeliefs, stores, llm, cache);
+    await persist(candidate, stores);
+    existingBeliefs.push(candidate);
+    report.promoted.push(candidate);
+}
+async function persist(record, stores) {
+    await stores.doc.saveRecord(record);
+    await stores.doc.pushFact(record.agentId, record.content);
+    await stores.vector.upsert(record);
+    const triples = record.triples;
+    if (triples && triples.length)
+        await stores.graph.writeTriples(record.agentId, triples);
+}
+function buildBelief(agentId, content, sources, kind = 'belief', salience = 0.5, triples = []) {
+    const trust = sources.length ? Math.min(...sources.map((s) => s.trust ?? 1)) : 1;
+    const confidence = clamp01(BASE_CONFIDENCE +
+        CONFIDENCE_PER_SOURCE * Math.max(0, sources.length - 1) +
+        SALIENCE_CONFIDENCE_GAIN * (salience - 0.5));
+    const record = {
+        id: idFor(agentId, kind, norm(content)),
+        agentId,
+        type: 'factual',
+        content,
+        trust,
+        confidence,
+        provenance: { source: 'consolidation', derivedFrom: sources.map((s) => s.id) },
+        tier: 'hot',
+        validFrom: nowIso(),
+        createdAt: nowIso(),
+    };
+    if (triples.length)
+        record.triples = triples;
+    return record;
+}
+/** Distill a cluster into one belief sentence + its knowledge-graph triples (single LLM call). */
+async function distill(group, llm) {
+    const bullets = group.map((r) => `- ${r.content}`).join('\n');
+    const raw = await llm.complete(`Distill these related episodic memories into ONE durable semantic belief about the user, ` +
+        `plus its knowledge-graph triples. Return ONLY JSON, no prose, no markdown:\n` +
+        `{"belief":"<one concise sentence>","triples":[{"subject":"User","relation":"...","object":"..."}]}\n` +
+        `Memories:\n${bullets}`, { temperature: 0 });
+    const parsed = parseJson(raw);
+    if (parsed && typeof parsed.belief === 'string' && parsed.belief.trim()) {
+        return { content: parsed.belief.trim(), triples: cleanTriples(parsed.triples) };
+    }
+    // Fallback: treat the whole response as the belief sentence.
+    return { content: raw.trim(), triples: [] };
+}
+async function reflect(beliefs, llm) {
+    if (beliefs.length < 2)
+        return [];
+    const bullets = beliefs.map((b) => `- ${b.content}`).join('\n');
+    const raw = await llm.complete(`From these beliefs, infer up to 3 higher-order insights about the user. ` +
+        `Return ONLY a JSON array of strings, no prose, no markdown.\n${bullets}`, { temperature: 0 });
+    const parsed = parseJson(raw);
+    if (Array.isArray(parsed)) {
+        return parsed.filter((s) => typeof s === 'string' && s.trim()).slice(0, 3);
+    }
+    return [];
+}
+function parseJson(raw) {
+    try {
+        return JSON.parse(raw.replace(/^```(?:json)?/i, '').replace(/```$/, '').trim());
+    }
+    catch {
+        return null;
+    }
+}
+function cleanTriples(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((t) => !!t && typeof t.subject === 'string' && typeof t.relation === 'string' && typeof t.object === 'string');
+}
+function placeholder(agentId, sources) {
+    return {
+        id: idFor(agentId, 'belief-error', sources.map((s) => s.id).join('|') || nowIso()),
+        agentId,
+        type: 'factual',
+        content: '',
+        trust: 0,
+        confidence: 0,
+        provenance: { source: 'consolidation', derivedFrom: sources.map((s) => s.id) },
+        tier: 'cold',
+        createdAt: nowIso(),
+    };
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/src/brain/constants.d.ts

@@ -0,0 +1,18 @@
+import 'dotenv/config';
+export declare const DAY_MS: number;
+export declare const MERGE_THRESHOLD = 0.85;
+export declare const DEDUP_THRESHOLD = 0.9;
+export declare const SALIENCE_WEIGHTS: {
+    readonly novelty: 0.7;
+    readonly surprise: 0.3;
+};
+export declare const USE_LLM_SURPRISE = true;
+export declare const SUPERSEDE_SIM_THRESHOLD = 0.6;
+export declare const BASE_CONFIDENCE = 0.5;
+export declare const CONFIDENCE_PER_SOURCE = 0.1;
+export declare const SALIENCE_CONFIDENCE_GAIN = 0.2;
+export declare const RECENCY_TAU_MS: number;
+export declare const STABILITY_BASE_MS: number;
+export declare const FORGET_R = 0.3;
+export declare const HOT_DAYS: number;
+export declare const WARM_DAYS: number;

package/dist/src/brain/constants.js

@@ -0,0 +1,26 @@
+// REMind · L1 tunables · Owner: Charan
+// Single home for every Brain threshold/weight so the demo can be tuned fast.
+import 'dotenv/config';
+export const DAY_MS = 24 * 60 * 60 * 1000;
+const MIN_MS = 60 * 1000;
+// BRAIN_FAST_DECAY=1 compresses the time-scales so decay + tiering are visible in a live demo.
+const FAST = process.env.BRAIN_FAST_DECAY === '1';
+// --- clustering / dedup (cosine similarity) ---
+export const MERGE_THRESHOLD = 0.85; // episodic memories this close fold into one belief
+export const DEDUP_THRESHOLD = 0.9; // near-identical content treated as a duplicate
+// --- salience (encoding) ---
+export const SALIENCE_WEIGHTS = { novelty: 0.7, surprise: 0.3 };
+export const USE_LLM_SURPRISE = true; // toggle the (paid) surprise/contradiction probe
+// --- supersession (temporal) ---
+export const SUPERSEDE_SIM_THRESHOLD = 0.6; // only LLM-check contradiction above this cosine
+// --- belief confidence (consolidation) ---
+export const BASE_CONFIDENCE = 0.5; // a single-source belief
+export const CONFIDENCE_PER_SOURCE = 0.1; // + per extra corroborating source
+export const SALIENCE_CONFIDENCE_GAIN = 0.2; // how much salience nudges confidence
+// --- forgetting (Ebbinghaus + utility) ---
+export const RECENCY_TAU_MS = FAST ? 5 * MIN_MS : 7 * DAY_MS; // recency decay constant
+export const STABILITY_BASE_MS = FAST ? 2 * MIN_MS : 3 * DAY_MS; // base memory stability S0
+export const FORGET_R = 0.3; // retention/utility below this ⇒ archive to cold
+// --- tiering (access recency) ---
+export const HOT_DAYS = FAST ? 1 / 1440 : 1; // 1 min when FAST
+export const WARM_DAYS = FAST ? 10 / 1440 : 14; // 10 min when FAST

package/dist/src/brain/encoding.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryRecord } from '../types.js';
+import { type Vec } from './similarity.js';
+import { type LlmDeps } from './llm-deps.js';
+/** 0..1 importance of `record` relative to what we already know. */
+export declare function scoreSalience(record: MemoryRecord, context: MemoryRecord[], llm?: LlmDeps, cache?: Map<string, Vec>): Promise<number>;
+/** Collapse near-identical records, keeping the earliest as canonical. */
+export declare function dedupe(records: MemoryRecord[], cache?: Map<string, Vec>, embedFn?: (text: string) => Promise<Vec>): Promise<{
+    canonical: MemoryRecord[];
+    duplicates: MemoryRecord[];
+}>;

package/dist/src/brain/encoding.js

@@ -0,0 +1,45 @@
+// REMind · L1 encoding · Owner: Charan
+// scoreSalience(record, context) via surprise / novelty / prediction-error; content deduplication at ingest.
+import { SALIENCE_WEIGHTS, DEDUP_THRESHOLD, USE_LLM_SURPRISE } from './constants.js';
+import { embedAll, cosine, cluster } from './similarity.js';
+import { defaultLlm } from './llm-deps.js';
+const keyOf = (r) => r.id || r.content;
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+const ts = (s) => (s ? Date.parse(s) : 0);
+/** 0..1 importance of `record` relative to what we already know. */
+export async function scoreSalience(record, context, llm = defaultLlm, cache = new Map()) {
+    const vecs = await embedAll([record, ...context], cache, llm.embed);
+    const rv = vecs.get(keyOf(record));
+    if (!rv)
+        return 0.5;
+    let maxSim = 0;
+    for (const c of context) {
+        const cv = vecs.get(keyOf(c));
+        if (cv)
+            maxSim = Math.max(maxSim, cosine(rv, cv));
+    }
+    const novelty = 1 - maxSim;
+    let surprise = novelty;
+    if (USE_LLM_SURPRISE && context.length) {
+        const priors = context.slice(0, 5).map((c) => `- ${c.content}`).join('\n');
+        const ans = await llm.classify(`Prior beliefs:\n${priors}\n\nNew statement: "${record.content}"\n` +
+            `Is the new statement surprising or contradictory versus the priors? Answer 'yes' or 'no'.`);
+        surprise = ans.startsWith('yes') ? 1 : 0;
+    }
+    return clamp01(SALIENCE_WEIGHTS.novelty * novelty + SALIENCE_WEIGHTS.surprise * surprise);
+}
+/** Collapse near-identical records, keeping the earliest as canonical. */
+export async function dedupe(records, cache = new Map(), embedFn = defaultLlm.embed) {
+    if (records.length <= 1)
+        return { canonical: records.slice(), duplicates: [] };
+    const vecs = await embedAll(records, cache, embedFn);
+    const groups = cluster(records, vecs, DEDUP_THRESHOLD);
+    const canonical = [];
+    const duplicates = [];
+    for (const g of groups) {
+        const sorted = [...g].sort((a, b) => ts(a.createdAt) - ts(b.createdAt));
+        canonical.push(sorted[0]);
+        duplicates.push(...sorted.slice(1));
+    }
+    return { canonical, duplicates };
+}

package/dist/src/brain/forgetting.d.ts

@@ -0,0 +1,3 @@
+import type { Stores } from '../types.js';
+import { type LlmDeps } from './llm-deps.js';
+export declare function decay(agentId: string, stores: Stores, llm?: LlmDeps): Promise<void>;

package/dist/src/brain/forgetting.js

@@ -0,0 +1,48 @@
+// REMind · L1 forgetting · Owner: Charan
+// decay(agentId, stores): Ebbinghaus strength decay + adaptive forgetting (utility = recency x frequency x salience x redundancy) -> evict/archive to cold tier.
+import { embedAll, cosine } from './similarity.js';
+import { retier } from './tiering.js';
+import { defaultLlm } from './llm-deps.js';
+import { RECENCY_TAU_MS, STABILITY_BASE_MS, FORGET_R, DEDUP_THRESHOLD } from './constants.js';
+const keyOf = (r) => r.id || r.content;
+export async function decay(agentId, stores, llm = defaultLlm) {
+    const records = await stores.doc.getRecords(agentId);
+    if (records.length) {
+        const nowMs = Date.now();
+        const vecs = await embedAll(records, new Map(), llm.embed);
+        // redundancy: how many near-duplicates each record has.
+        const redundancy = new Map();
+        for (const r of records) {
+            const rv = vecs.get(keyOf(r));
+            let dups = 0;
+            if (rv) {
+                for (const o of records) {
+                    if (o === r)
+                        continue;
+                    const ov = vecs.get(keyOf(o));
+                    if (ov && cosine(rv, ov) >= DEDUP_THRESHOLD)
+                        dups++;
+                }
+            }
+            redundancy.set(keyOf(r), dups);
+        }
+        for (const r of records) {
+            if (r.tier === 'cold')
+                continue;
+            const last = Date.parse(r.lastUsedAt ?? r.createdAt);
+            const dt = nowMs - (Number.isNaN(last) ? nowMs : last);
+            // Ebbinghaus retention R = exp(-dt / S); stability grows with corroboration.
+            const stability = STABILITY_BASE_MS * (1 + (r.confidence ?? 0.5));
+            const retention = Math.exp(-dt / stability);
+            // utility = recency x frequency(≈confidence) x salience(≈confidence) x redundancy.
+            const recency = Math.exp(-dt / RECENCY_TAU_MS);
+            const salience = r.confidence ?? 0.5;
+            const dups = redundancy.get(keyOf(r)) ?? 0;
+            const utility = recency * salience * (1 / (1 + dups));
+            if (retention < FORGET_R || utility < FORGET_R * 0.5) {
+                await stores.doc.saveRecord({ ...r, tier: 'cold' });
+            }
+        }
+    }
+    await retier(agentId, stores);
+}

package/dist/src/brain/index.d.ts

@@ -0,0 +1,6 @@
+import type { Brain, ConsolidationReport, PromotionGate, Stores } from '../types.js';
+export declare class Cognition implements Brain {
+    consolidate(agentId: string, stores: Stores, gate: PromotionGate): Promise<ConsolidationReport>;
+    decay(agentId: string, stores: Stores): Promise<void>;
+}
+export declare const cognition: Cognition;

package/dist/src/brain/index.js

@@ -0,0 +1,13 @@
+// REMind · L1 Brain export · Owner: Charan
+// export class Cognition implements Brain. The single public seam of brain/.
+import { consolidate as consolidateFn } from './consolidation.js';
+import { decay as decayFn } from './forgetting.js';
+export class Cognition {
+    consolidate(agentId, stores, gate) {
+        return consolidateFn(agentId, stores, gate);
+    }
+    decay(agentId, stores) {
+        return decayFn(agentId, stores);
+    }
+}
+export const cognition = new Cognition();

package/dist/src/brain/llm-deps.d.ts

@@ -0,0 +1,8 @@
+export interface LlmDeps {
+    complete: (prompt: string, opts?: {
+        temperature?: number;
+    }) => Promise<string>;
+    classify: (prompt: string) => Promise<string>;
+    embed: (text: string) => Promise<number[]>;
+}
+export declare const defaultLlm: LlmDeps;

package/dist/src/brain/llm-deps.js

@@ -0,0 +1,4 @@
+// REMind · L1 LLM dependency seam · Owner: Charan
+// Lets the sleep cycle run against the real Azure LLM in prod, or an injected fake in tests.
+import { complete, classify, embed } from '../llm.js';
+export const defaultLlm = { complete, classify, embed };

package/dist/src/brain/selftest.d.ts

@@ -0,0 +1 @@
+export {};