@remind_ai/remind 0.1.0

package/dist/src/memguard/provenance.js

@@ -0,0 +1,36 @@
+// REMind · L2 provenance · Owner: Prayash
+// tag(record, source) + lineage(id): every belief traceable to its source memory. Powers the audit log.
+/** id -> the sources/parents that produced it, for the audit log. */
+const lineageMap = new Map();
+/** Stamp a freshly drafted record with its origin source. */
+export function tag(record, source, sourceId) {
+    const provenance = {
+        source: source || record.provenance?.source || 'unknown',
+        derivedFrom: record.provenance?.derivedFrom,
+    };
+    const tagged = {
+        ...record,
+        provenance,
+        sourceId: sourceId ?? record.sourceId,
+    };
+    lineageMap.set(tagged.id, [provenance.source, ...(provenance.derivedFrom ?? [])]);
+    return tagged;
+}
+/**
+ * Stamp a consolidated belief with the source records it was derived from so the
+ * auditor's decision is always traceable back to concrete memories.
+ */
+export function tagDerived(record, sources) {
+    const derivedFrom = sources.map((s) => s.id);
+    const provenance = {
+        source: record.provenance?.source || 'consolidation',
+        derivedFrom,
+    };
+    const tagged = { ...record, provenance };
+    lineageMap.set(tagged.id, derivedFrom);
+    return tagged;
+}
+/** Look up the recorded lineage for a record id (sources / parent ids). */
+export function lineage(id) {
+    return lineageMap.get(id) ?? [];
+}

package/dist/src/memguard/trust.d.ts

@@ -0,0 +1,27 @@
+import type { MemoryRecord } from '../types.js';
+/** Below this, a record is quarantined at ingest. */
+export declare const QUARANTINE_THRESHOLD = 0.4;
+/** A consolidation source at/under this trust taints any belief derived from it. */
+export declare const LOW_TRUST_SOURCE = 0.5;
+/** Minimum trust for a record to reach the agent via onOutput. */
+export declare const OUTPUT_MIN_TRUST = 0.4;
+export interface TrustSignals {
+    source?: string;
+    isInstruction?: boolean;
+    hasSecrets?: boolean;
+    hasPII?: boolean;
+    hasExfiltration?: boolean;
+}
+/**
+ * Score a record's trustworthiness in 0..1 from its source and detector signals.
+ * Conservative by design: any attempt to command the agent or smuggle data out
+ * collapses trust well below the quarantine line.
+ */
+export declare function scoreTrust(_record: MemoryRecord, signals: TrustSignals): number;
+/**
+ * Mark a record quarantined: it is retained for audit/lineage but is never
+ * surfaced to the agent and can never be promoted into a belief.
+ */
+export declare function quarantine(record: MemoryRecord): MemoryRecord;
+/** Whether a record is safe to use as trusted material (not quarantined, above floor). */
+export declare function isTrusted(record: MemoryRecord, floor?: number): boolean;

package/dist/src/memguard/trust.js

@@ -0,0 +1,53 @@
+// REMind · L2 trust + quarantine · Owner: Prayash
+// score(record, signals) -> 0..1 trust; quarantine(record) -> kept for audit, never surfaced or promoted.
+/** Below this, a record is quarantined at ingest. */
+export const QUARANTINE_THRESHOLD = 0.4;
+/** A consolidation source at/under this trust taints any belief derived from it. */
+export const LOW_TRUST_SOURCE = 0.5;
+/** Minimum trust for a record to reach the agent via onOutput. */
+export const OUTPUT_MIN_TRUST = 0.4;
+/** Baseline trust by declared source. Unknown/web sources start skeptical. */
+const SOURCE_BASE = {
+    system: 0.95,
+    user: 0.8,
+    tool: 0.6,
+    agent: 0.6,
+    import: 0.5,
+    web: 0.45,
+    unknown: 0.5,
+};
+function clamp(n) {
+    return Math.max(0, Math.min(1, n));
+}
+/**
+ * Score a record's trustworthiness in 0..1 from its source and detector signals.
+ * Conservative by design: any attempt to command the agent or smuggle data out
+ * collapses trust well below the quarantine line.
+ */
+export function scoreTrust(_record, signals) {
+    let trust = SOURCE_BASE[(signals.source ?? 'unknown').toLowerCase()] ?? 0.5;
+    if (signals.isInstruction)
+        trust -= 0.6;
+    if (signals.hasExfiltration)
+        trust -= 0.5;
+    if (signals.hasSecrets)
+        trust -= 0.4;
+    if (signals.hasPII)
+        trust -= 0.15;
+    return clamp(trust);
+}
+/**
+ * Mark a record quarantined: it is retained for audit/lineage but is never
+ * surfaced to the agent and can never be promoted into a belief.
+ */
+export function quarantine(record) {
+    return {
+        ...record,
+        quarantined: true,
+        trust: Math.min(record.trust ?? 0, QUARANTINE_THRESHOLD - 0.01),
+    };
+}
+/** Whether a record is safe to use as trusted material (not quarantined, above floor). */
+export function isTrusted(record, floor = LOW_TRUST_SOURCE) {
+    return !record.quarantined && (record.trust ?? 0) >= floor;
+}

package/dist/src/queue/connection.d.ts

@@ -0,0 +1,6 @@
+import { Redis } from 'ioredis';
+/** Use real BullMQ/Redis only when a Redis URL is configured AND we are not forcing inline (SYNC) mode. */
+export declare function useRedis(): boolean;
+/** Lazily open one shared ioredis connection (BullMQ requires maxRetriesPerRequest: null). */
+export declare function getConnection(): Redis;
+export declare function closeConnection(): Promise<void>;

package/dist/src/queue/connection.js

@@ -0,0 +1,23 @@
+// REMind · Queue connection · Owner: Yasho
+// One shared Redis connection (Azure Cache for Redis) for BullMQ when REDIS_URL is set;
+// otherwise the queues fall back to an inline in-process shim with the same .add() API.
+import { Redis } from 'ioredis';
+import { config } from '../config.js';
+/** Use real BullMQ/Redis only when a Redis URL is configured AND we are not forcing inline (SYNC) mode. */
+export function useRedis() {
+    return Boolean(config.redis.url) && !config.sync;
+}
+let connection = null;
+/** Lazily open one shared ioredis connection (BullMQ requires maxRetriesPerRequest: null). */
+export function getConnection() {
+    if (!connection) {
+        connection = new Redis(config.redis.url, { maxRetriesPerRequest: null });
+    }
+    return connection;
+}
+export async function closeConnection() {
+    if (connection) {
+        await connection.quit();
+        connection = null;
+    }
+}

package/dist/src/queue/queues.d.ts

@@ -0,0 +1,29 @@
+import type { IngestInput, MemoryRecord } from '../types.js';
+export type Processor<T> = (data: T) => Promise<void>;
+export interface JobQueue<T> {
+    readonly name: string;
+    add(data: T): Promise<void>;
+    process(handler: Processor<T>): void;
+    close(): Promise<void>;
+}
+export interface IngestJob {
+    input: IngestInput;
+}
+export interface ConsolidateJob {
+    agentId: string;
+}
+export interface ForgetJob {
+    agentId: string;
+}
+export interface QuarantineJob {
+    record: MemoryRecord;
+    reason: string;
+}
+export interface Queues {
+    ingest: JobQueue<IngestJob>;
+    consolidate: JobQueue<ConsolidateJob>;
+    forget: JobQueue<ForgetJob>;
+    quarantine: JobQueue<QuarantineJob>;
+}
+/** Build the four queues with the active backend. Call once and share the instances. */
+export declare function createQueues(): Queues;

package/dist/src/queue/queues.js

@@ -0,0 +1,64 @@
+// REMind · Queue definitions · Owner: Yasho
+// A tiny JobQueue abstraction with two backends: BullMQ over Azure Cache for Redis
+// (durable, retried, crash-safe) and an inline in-process shim (SYNC / no-Redis) that runs
+// the processor immediately. ingest / consolidate / forget / quarantine share the API.
+import { Queue, Worker } from 'bullmq';
+import { getConnection, useRedis } from './connection.js';
+/** Inline backend: add() runs the registered processor right away (deterministic, no Redis). */
+class InlineQueue {
+    name;
+    handler;
+    constructor(name) {
+        this.name = name;
+    }
+    process(handler) {
+        this.handler = handler;
+    }
+    async add(data) {
+        if (!this.handler)
+            throw new Error(`inline queue "${this.name}" has no processor`);
+        await this.handler(data);
+    }
+    async close() {
+        /* nothing to release */
+    }
+}
+/** BullMQ backend over Azure Cache for Redis: durable, retried, crash-safe. */
+class RedisQueue {
+    name;
+    queue;
+    worker;
+    constructor(name) {
+        this.name = name;
+        this.queue = new Queue(name, { connection: getConnection() });
+    }
+    process(handler) {
+        this.worker = new Worker(this.name, (job) => handler(job.data), {
+            connection: getConnection(),
+        });
+    }
+    async add(data) {
+        await this.queue.add(this.name, data, {
+            removeOnComplete: true,
+            removeOnFail: 100,
+            attempts: 3,
+            backoff: { type: 'exponential', delay: 1000 },
+        });
+    }
+    async close() {
+        await this.worker?.close();
+        await this.queue.close();
+    }
+}
+function makeQueue(name) {
+    return useRedis() ? new RedisQueue(name) : new InlineQueue(name);
+}
+/** Build the four queues with the active backend. Call once and share the instances. */
+export function createQueues() {
+    return {
+        ingest: makeQueue('remind-ingest'),
+        consolidate: makeQueue('remind-consolidate'),
+        forget: makeQueue('remind-forget'),
+        quarantine: makeQueue('remind-quarantine'),
+    };
+}

package/dist/src/types.d.ts

@@ -0,0 +1,97 @@
+export type MemoryType = 'episodic' | 'factual' | 'short' | 'working' | 'procedural';
+export type Tier = 'hot' | 'warm' | 'cold';
+export interface Provenance {
+    source: string;
+    derivedFrom?: string[];
+}
+/** A knowledge-graph edge extracted from an episodic memory. */
+export interface Triple {
+    subject: string;
+    relation: string;
+    object: string;
+}
+export interface MemoryRecord {
+    id: string;
+    agentId: string;
+    type: MemoryType;
+    content: string;
+    embedding?: number[];
+    triples?: Triple[];
+    trust: number;
+    confidence: number;
+    provenance: Provenance;
+    validFrom?: string;
+    validTo?: string;
+    tier: Tier;
+    quarantined?: boolean;
+    sourceId?: string;
+    createdAt: string;
+    lastUsedAt?: string;
+}
+export interface IngestInput {
+    agentId: string;
+    messages: {
+        user: string;
+        assistant: string;
+    };
+    source?: string;
+    sourceId?: string;
+}
+export interface RetrievalResult {
+    context: string;
+    records: MemoryRecord[];
+    facts: string[];
+}
+export interface ConsolidationReport {
+    promoted: MemoryRecord[];
+    blocked: {
+        record: MemoryRecord;
+        reason: string;
+    }[];
+    merged: number;
+}
+export interface VectorStore {
+    upsert(record: MemoryRecord): Promise<void>;
+    search(agentId: string, query: string, k?: number, sourceId?: string): Promise<MemoryRecord[]>;
+}
+export interface GraphStore {
+    writeTriples(agentId: string, triples: Triple[]): Promise<void>;
+    fetchGraph(agentId: string): Promise<string>;
+}
+export interface DocStore {
+    pushFact(agentId: string, fact: string): Promise<void>;
+    getFacts(agentId: string): Promise<string[]>;
+    saveRecord(record: MemoryRecord): Promise<void>;
+    getRecords(agentId: string, filter?: Record<string, unknown>): Promise<MemoryRecord[]>;
+}
+export interface Stores {
+    vector: VectorStore;
+    graph: GraphStore;
+    doc: DocStore;
+}
+export interface MemoryEngineCore {
+    draft(input: IngestInput): Promise<MemoryRecord | null>;
+    persist(record: MemoryRecord): Promise<MemoryRecord>;
+    fetchMemory(agentId: string, query: string, sourceId?: string): Promise<RetrievalResult>;
+}
+export type PromotionGate = (candidate: MemoryRecord, from: MemoryRecord[]) => Promise<{
+    promote: boolean;
+    reason?: string;
+}>;
+export interface Brain {
+    consolidate(agentId: string, stores: Stores, gate: PromotionGate): Promise<ConsolidationReport>;
+    decay(agentId: string, stores: Stores): Promise<void>;
+}
+export interface MemGuardHooks {
+    onIngest(input: IngestInput, draft: MemoryRecord): Promise<{
+        allow: boolean;
+        record: MemoryRecord;
+        reason?: string;
+    }>;
+    onConsolidate: PromotionGate;
+    onOutput(records: MemoryRecord[]): Promise<MemoryRecord[]>;
+    checkCanaries(): Promise<{
+        drift: boolean;
+        details: string;
+    }>;
+}

package/dist/src/types.js

@@ -0,0 +1,3 @@
+// REMind · Frozen Contract · Owner: Yasho
+// Shared types + the three seam interfaces. The only file all four layers import.
+export {};

package/dist/src/workers/consolidate.worker.d.ts

@@ -0,0 +1,5 @@
+import type { ConsolidationReport } from '../types.js';
+import type { Layers } from '../engine.js';
+import type { Queues } from '../queue/queues.js';
+export declare function runConsolidate(layers: Layers, agentId: string): Promise<ConsolidationReport>;
+export declare function registerConsolidateWorker(queues: Queues, layers: Layers): void;

package/dist/src/workers/consolidate.worker.js

@@ -0,0 +1,15 @@
+// REMind · Consolidate worker (consumer) · Owner: Yasho
+// The sleep cycle in sequence: guard.checkCanaries (before) -> brain.consolidate (each
+// candidate gated by guard.onConsolidate) -> guard.checkCanaries (after). Returns the report so
+// SYNC-mode callers can inspect it; in async mode BullMQ retries the whole job on crash.
+export async function runConsolidate(layers, agentId) {
+    await layers.guard.checkCanaries();
+    const report = await layers.brain.consolidate(agentId, layers.stores, layers.guard.onConsolidate);
+    await layers.guard.checkCanaries();
+    return report;
+}
+export function registerConsolidateWorker(queues, layers) {
+    queues.consolidate.process(async ({ agentId }) => {
+        await runConsolidate(layers, agentId);
+    });
+}

package/dist/src/workers/forget.worker.d.ts

@@ -0,0 +1,4 @@
+import type { Layers } from '../engine.js';
+import type { Queues } from '../queue/queues.js';
+export declare function runForget(layers: Layers, agentId: string): Promise<void>;
+export declare function registerForgetWorker(queues: Queues, layers: Layers): void;

package/dist/src/workers/forget.worker.js

@@ -0,0 +1,8 @@
+// REMind · Forget worker (repeatable) · Owner: Yasho
+// Scheduled/idle decay pass -> brain.decay(agentId, stores). Idempotent: safe to repeat.
+export async function runForget(layers, agentId) {
+    await layers.brain.decay(agentId, layers.stores);
+}
+export function registerForgetWorker(queues, layers) {
+    queues.forget.process(({ agentId }) => runForget(layers, agentId));
+}

package/dist/src/workers/ingest.worker.d.ts

@@ -0,0 +1,6 @@
+import type { IngestInput } from '../types.js';
+import type { Layers } from '../engine.js';
+import type { Queues } from '../queue/queues.js';
+export declare function runIngest(layers: Layers, queues: Queues, input: IngestInput): Promise<void>;
+/** Attach the ingest + quarantine (dead-letter) processors to their queues. */
+export declare function registerIngestWorker(queues: Queues, layers: Layers): void;

package/dist/src/workers/ingest.worker.js

@@ -0,0 +1,36 @@
+// REMind · Ingest worker (consumer) · Owner: Yasho
+// The one place the write pipeline runs in sequence: core.draft -> guard.onIngest ->
+// (allow) core.persist | (block) quarantine. Then bump a per-agent write-count and enqueue
+// a consolidate cycle at the threshold. Pure orchestration; layers make it retry-safe.
+const CONSOLIDATE_THRESHOLD = 5;
+const writeCounts = new Map();
+export async function runIngest(layers, queues, input) {
+    const draft = await layers.core.draft(input);
+    if (!draft)
+        return; // not salient — nothing to store
+    const verdict = await layers.guard.onIngest(input, draft);
+    if (!verdict.allow) {
+        await queues.quarantine.add({
+            record: { ...verdict.record, quarantined: true },
+            reason: verdict.reason ?? 'blocked by ingest firewall',
+        });
+        return;
+    }
+    await layers.core.persist(verdict.record);
+    const next = (writeCounts.get(input.agentId) ?? 0) + 1;
+    if (next >= CONSOLIDATE_THRESHOLD) {
+        writeCounts.set(input.agentId, 0);
+        await queues.consolidate.add({ agentId: input.agentId });
+    }
+    else {
+        writeCounts.set(input.agentId, next);
+    }
+}
+/** Attach the ingest + quarantine (dead-letter) processors to their queues. */
+export function registerIngestWorker(queues, layers) {
+    queues.ingest.process(({ input }) => runIngest(layers, queues, input));
+    queues.quarantine.process(async ({ record }) => {
+        // Persist quarantined records (never promoted) so the audit trail keeps the evidence.
+        await layers.stores.doc.saveRecord({ ...record, quarantined: true });
+    });
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@remind_ai/remind",
+  "version": "0.1.0",
+  "description": "Brain-inspired AI-agent memory SDK with the MemGuard security layer.",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": ["dist/src"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "doctor": "tsx examples/doctor.ts",
+    "demo": "tsx examples/poison-demo.ts",
+    "demo:core": "tsx examples/core-demo.ts",
+    "demo:brain": "tsx examples/brain-demo.ts",
+    "bench:attack": "tsx benchmark/attack.ts",
+    "bench:retrieval": "tsx benchmark/retrieval.ts",
+    "start": "node dist/server/http.js"
+  },
+  "keywords": ["ai", "agent", "memory", "llm", "security", "memguard", "azure", "rag", "vector", "knowledge-graph"],
+  "license": "MIT",
+  "author": "remind_ai",
+  "homepage": "https://github.com/t-yassingh_microsoft/REMind-AI#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/t-yassingh_microsoft/REMind-AI.git" },
+  "bugs": { "url": "https://github.com/t-yassingh_microsoft/REMind-AI/issues" },
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "@azure/search-documents": "^12.1.0",
+    "bullmq": "^5.13.0",
+    "dotenv": "^16.4.5",
+    "gremlin": "^3.7.2",
+    "ioredis": "^5.4.1",
+    "mongoose": "^8.6.0",
+    "openai": "^4.67.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "overrides": {
+    "uuid": "^11.1.1"
+  }
+}