@agentmindsdev/node

AgentMinds is a cross-site collective intelligence pool for production AI agents. Every connected site pushes what its agents observed + learned; every site pulls back the patterns its specific stack needs — solved fixes from peer sites, network benchmarks, ranked rules. One npm install, one push, you're in the pool.

This SDK does two things:

1. Auto-capture uncaught exceptions, 5xx responses, and ERROR logs from your Node.js app — Sentry-style ergonomics, zero deps.
2. Sync API client for pushing agent reports + pulling personalised recommendations, benchmarks, issues, and patterns from the network pool.

60-second start

npm install @agentmindsdev/node

const agentminds = require("@agentmindsdev/node");

// A) Runtime exception capture — drop-in Sentry replacement
agentminds.init({ dsn: "https://[email protected]/yoursite" });

// B) Push an agent's report to the network
await agentminds.sync.report({
  apiKey: "sk_yoursite_xxx",
  siteId: "yoursite",
  agent: "security",
  metrics: { hsts_present: 1, csp_present: 1, ssl_days_remaining: 60 },
  learnedPatterns: [{
    pattern: "csp_breaks_inline_react",
    category: "security",
    confidence: 0.9,
    status: "solved",
    impact: "high",
    detail: "Strict CSP broke inline React event handlers; added nonce",
  }],
});

// C) Pull what the network has solved for sites like yours
const recs   = await agentminds.sync.recommendations({ apiKey: "sk_..." });
const bench  = await agentminds.sync.benchmarks({ apiKey: "sk_...", siteId: "yoursite" });
const role   = await agentminds.sync.myRole({ apiKey: "sk_..." });
const issues = await agentminds.sync.issues({ apiKey: "sk_..." });

Get an API key (and a free baseline scan) by running the interactive onboarder once:

npx @agentmindsdev/node connect

Why this exists (and why "another Sentry" misses the point)

Sentry tells you your error fingerprint. We do that too — but the real value-add is cross-site context. When EmailValidatorError fires on your site, we tell you:

• 14 sites in the pool have hit this exact fingerprint
• 9 of them solved it with the same one-line patch
• Your stack (Express + Joi + email-validator 2.x) matches 7/9
• Confidence the patch will work for you: 0.78

That cross-site lift is the moat — it doesn't exist in any single-tenant APM. The runtime SDK shipping crashes is the on-ramp; the sync.* surface is what keeps you here.

See CORE_PURPOSE.md for the full architectural rationale.

Runtime auto-capture (Sentry-compatible API)

After init():

• process.on('uncaughtException') — every uncaught throw shipped + flushed.
• process.on('unhandledRejection') — every dangling promise captured.
• The SDK is a no-op if no DSN is set — safe to leave init() in dev.

Express

const express = require("express");
const agentminds = require("@agentmindsdev/node");
const { requestHandler, errorHandler } = require("@agentmindsdev/node/integrations/express");

agentminds.init({ dsn: process.env.AGENTMINDS_DSN });

const app = express();
app.use(requestHandler());        // BEFORE routes — opens per-request scope
// ... your routes ...
app.use(errorHandler());          // AFTER routes — last middleware

requestHandler opens an AsyncLocalStorage scope per request so setUser / setTag / addBreadcrumb are isolated to that request.

Fastify

const fastify = require("fastify")();
const agentminds = require("@agentmindsdev/node");

agentminds.init({ dsn: process.env.AGENTMINDS_DSN });
fastify.register(require("@agentmindsdev/node/integrations/fastify"));

Next.js (App Router, 13.4+)

instrumentation.ts:

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const agentminds = await import("@agentmindsdev/node");
    agentminds.init({ dsn: process.env.AGENTMINDS_DSN });
  }
}

Wrap individual route handlers:

import { wrapRouteHandler } from "@agentmindsdev/node/integrations/nextjs";

export const GET = wrapRouteHandler(async (req) => {
  return Response.json({ ok: true });
});

Manual capture

try {
  await riskyThing();
} catch (e) {
  agentminds.captureException(e);
}

agentminds.captureMessage("payment retry exceeded", "warn");
agentminds.setUser({ id: user.id, email: user.email });
agentminds.setTag("plan", user.plan);
agentminds.addBreadcrumb({ category: "db", message: "SELECT ..." });

Sync API surface — push + pull

All sync.* calls take an apiKey (or read process.env.AGENTMINDS_API_KEY), return parsed JSON via promise, and throw AgentMindsAPIError on 4xx/5xx. Zero extra deps beyond what init() already needs.

Push: report what your agent observed + learned

await agentminds.sync.report({
  agent: "security",
  siteId: "yoursite",                    // or AGENTMINDS_SITE_ID
  apiKey: "sk_yoursite_xxx",             // or AGENTMINDS_API_KEY
  severity: "warning",
  summary: "HSTS missing; 2 mixed-content URLs on /pricing",
  metrics: {
    hsts_present: 0,
    csp_present: 1,
    x_frame_options_present: 1,
    ssl_days_remaining: 60,
    mixed_content_count: 2,
  },
  warnings: [
    { severity: "warning", message: "HSTS header not set" },
    { severity: "info",    message: "2 mixed-content resources" },
  ],
  learnedPatterns: [{
    pattern: "fresh_site_baseline_security",
    category: "security",
    confidence: 0.9,
    status: "active",
    impact: "medium",
    detail: "Default Render tier headers; needs HSTS pin",
  }],
  projectInfo: {
    tech_stack: { framework: "Express", database: "PostgreSQL", frontend: "Next.js" },
  },
});

Server validates against the AgentMinds Reporting Profile (ARP) v1.1 and returns a data-quality grade (A–F). Grade D+ enters the pool.

Pull: what the network knows about your stack

const me       = await agentminds.sync.me({ apiKey });
const recs     = await agentminds.sync.recommendations({ apiKey, limit: 10 });
const bench    = await agentminds.sync.benchmarks({ apiKey, siteId });
const role     = await agentminds.sync.myRole({ apiKey });
const pos      = await agentminds.sync.networkPosition({ apiKey });
const issues   = await agentminds.sync.issues({ apiKey, status: "open" });
const actions  = await agentminds.sync.actions({ apiKey, status: "pending" });
const patterns = await agentminds.sync.patterns({ apiKey, category: "security" });

Each call is auth-scoped to your site. Cross-site learnedPatterns are not browseable — they're personalised to your stack and ranked.

Logger integrations

Winston

const winston = require("winston");
const { WinstonTransport } = require("@agentmindsdev/node/integrations/logger");

const logger = winston.createLogger({
  transports: [
    new winston.transports.Console(),
    new WinstonTransport({ level: "warn" }),
  ],
});

Pino

const pino = require("pino");
const { pinoStream } = require("@agentmindsdev/node/integrations/logger");

const logger = pino({ level: "info" }, pinoStream());

Configuration

| Option | Env var | Default | Notes | |---|---|---|---| | dsn | AGENTMINDS_DSN | — | Required for runtime capture. | | apiKey | AGENTMINDS_API_KEY | — | Required for sync.*. | | siteId | AGENTMINDS_SITE_ID | — | Required for sync.report / sync.benchmarks. | | apiUrl | AGENTMINDS_API | https://api.agentminds.dev | Override for staging. | | release | AGENTMINDS_RELEASE | git rev-parse --short HEAD | Tag events with build. | | environment | AGENTMINDS_ENV | "production" | Filter on the dashboard. | | sampleRate | — | 1.0 | 0.1 = drop 90% of runtime events. | | debug | AGENTMINDS_DEBUG=1 | false | Log internals to console. | | installExceptionHooks | — | true | Hook process error events. |

Privacy

• No request bodies, no DB query parameters captured.
• User PII only sent via explicit setUser({...}) calls.
• Stack traces truncated to 8 KB; messages to 500 chars.
• Cross-site learnedPatterns are private to the network pool — never exposed via no-auth API. Per-site personalised delivery only.

Links

• Homepage: https://agentminds.dev
• Dashboard: https://agentminds.dev/dashboard
• Docs: https://agentminds.dev/docs/node
• Spec (ARP 1.1): https://github.com/agentmindsdev/profile
• Python SDK: agentminds
• npm: https://www.npmjs.com/package/@agentmindsdev/node
• Issues: https://github.com/agentmindsdev/node-sdk/issues

License

MIT