@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

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:

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

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:

import { createMemory, passthroughGuard } from '@remind_ai/remind';
const mem = createMemory({ guard: passthroughGuard });

License

MIT