Introducing minns-sdk: Give Your AI Agents a Memory That Learns
We're excited to announce the release of minns-sdk (v0.4.4), a lightweight TypeScript SDK for minns.ai, the self-evolving agentic database that transforms discrete events into semantic graphs packed with memories, strategies, and claims.
If you're building autonomous agents or LLM-powered applications, you've likely hit the same wall: agents don't remember, and they don't learn. Every session starts from scratch. Past mistakes get repeated. Successful patterns are forgotten. minns-sdk fixes that.
npm install minns-sdk
The Problem
Today's AI agents are stateless by default. They process a request, return a response, and move on. But real intelligence requires continuity: the ability to recall what worked, avoid what didn't, and build generalizable knowledge over time.
Building this from scratch means stitching together grapgh and vector databases, custom retrieval logic, memory management, and strategy extraction pipelines and custom models to learn agent behaviours. It's months of work before your agent can "learn" anything meaningful.
The Solution
minns-sdk gives your agents a complete learning stack in a single dependency all built on top of the minns memory layer a the first databse built for agentic workflows.
it works by when your agents submit events describing what your agent does (actions, observations, reasoning, communication) and minns.ai handles the rest: extracting memories, discovering strategies, identifying facts, and building a contexual graph your agent can query at any time.
Highlights
Fluent, Type-Safe Event Builder
Construct rich events with a clean chainable API. No boilerplate, full IntelliSense support:
import { createClient } from 'minns-sdk';
const client = createClient({
apiKey: "your-api-key",
baseUrl: "https://minns.ai",
});
const response = await client
.event("research-agent", { agentId: 2001, sessionId: 177031103 })
.action("search_database", { query: "quantum computing" })
.outcome({ resultsFound: 10 })
.state({ user_id: "alice@example.com" })
.goal("Research quantum trends", 5)
.send();
Six event types cover the full spectrum of agent behavior: Action, Observation, Context, Cognitive, Communication, and Learning.
Three-Tier Memory Hierarchy
Memories aren't just stored. They're consolidated. The system automatically promotes knowledge through three tiers:
- Episodic: Individual experiences captured automatically from events
- Semantic: Generalized patterns distilled from 3+ similar episodes
- Schema: High-level reusable principles extracted from 3+ semantic memories
const memories = await client.getAgentMemories(2001, 10);
console.log(memories[0].summary); // What happened
console.log(memories[0].takeaway); // The key lesson
console.log(memories[0].causal_note); // Why it succeeded or failed
console.log(memories[0].tier); // "Episodic" | "Semantic" | "Schema"
Your agent starts with raw experiences and gradually builds a library of proven principles, just like a human expert.
Automatic Strategy Extraction
minns.ai watches your agent's behavior and extracts reusable strategies with success/failure tracking, executable playbooks, and even counterfactual analysis:
const strategies = await client.getAgentStrategies(2001, 5);
console.log(strategies[0].playbook); // Step-by-step execution guide
console.log(strategies[0].when_to_use); // Conditions for this strategy
console.log(strategies[0].failure_modes); // Known failure scenarios
console.log(strategies[0].quality_score); // Confidence metric
Need real-time guidance? Ask for action suggestions based on the agent's current context:
const suggestions = await client.getActionSuggestions(contextHash);
Semantic Claims Search
Extract atomic facts from unstructured text using a NER + LLM + Embedding pipeline. Enable it on any event with a single flag:
const response = await client
.event("extractor-agent", { agentId: 3001, sessionId: 177031103 })
.context("OpenAI released GPT-5 on March 15, 2025 with 10T parameters")
.send({ enableSemantic: true });
// Later, search extracted facts
const claims = await client.searchClaims({
query_text: "GPT-5 release date",
top_k: 5,
min_similarity: 0.7
});
Local Intent Parsing (Zero Extra LLM Calls)
The built-in sidecar lets you extract structured intents from LLM responses without making additional API calls. Just inject an instruction block into your system prompt and parse locally:
import { buildSidecarInstruction, extractIntentAndResponse } from 'minns-sdk';
const spec = {
domain: "travel_booking",
fallback_intent: "query",
intents: [
{ name: "book_flight", slots: { origin: {}, destination: {}, date: {} } },
{ name: "cancel_booking", slots: { booking_id: {} } },
{ name: "query" }
]
};
// Add to your LLM system prompt
const instruction = buildSidecarInstruction(spec);
// After LLM responds, parse locally. No network call
const { intent, assistantResponse } = extractIntentAndResponse(
llmOutput, userMessage, spec
);
Built for Performance
- Automatic batching: buffer events and flush on interval or size threshold
- Async queuing with backpressure handling (up to 1,000 events queued)
- Fire-and-forget telemetry that never blocks your agent's critical path
- Security-hardened serialization: circular reference detection, prototype pollution protection, BigInt-to-string conversion for Rust compatibility
const client = createClient({
apiKey: "your-api-key",
autoBatch: true,
batchInterval: 100, // flush every 100ms
batchMaxSize: 20, // or every 20 events
});
// Events are buffered locally and sent in batches
await client.event("agent", ids).action("step_1", {}).enqueue();
await client.event("agent", ids).action("step_2", {}).enqueue();
await client.event("agent", ids).action("step_3", {}).enqueue();
// All three sent in a single batch
Graph Analytics & Visualization
Query the full semantic graph that minns.ai builds from your agent's events. Inspect connectivity, traverse relationships, and extract subgraphs:
const analytics = await client.getAnalytics();
const graph = await client.getGraphByContext(contextHash);
const traversal = await client.traverseGraph(startNodeId, 3); // 3-hop BFS
How It Works
High-Level Flow
Your Agent
↓ (events)
minns-sdk Client
↓ (HTTP / batched)
minns.ai Backend
↓ (automatic processing)
Semantic Graph ← Memories ← Strategies ← Claims
↓
Your Agent queries what it needs
- Your agent acts: searches, reasons, communicates, observes
- You submit events describing those actions via the fluent builder API
- minns.ai processes them into a semantic graph, extracting memories, strategies, and factual claims
- Your agent queries learned knowledge to make better decisions next time
SDK Architecture
Under the hood, minns-sdk is organized into a few focused modules:
minns-sdk
├── MinnsClient Core client, manages HTTP, batching, telemetry
│ ├── EventBuilder Fluent chainable API for constructing events
│ ├── Event Queue Local buffer with backpressure (autoBatch mode)
│ └── Safe Serializer Circular ref detection, BigInt handling, payload validation
│
├── Memory APIs getAgentMemories(), getContextMemories()
├── Strategy APIs getAgentStrategies(), getSimilarStrategies(), getActionSuggestions()
├── Semantic APIs searchClaims()
├── Graph APIs getAnalytics(), getGraph(), traverseGraph(), queryGraphNodes()
│
├── Intent Sidecar Local intent parsing without extra LLM calls
│ ├── buildSidecarInstruction() Generates prompt instruction block
│ └── extractIntentAndResponse() Parses structured intent from raw LLM output
│
└── Intent Registry Goal-based spec routing per (agentType, goalDescription)
EventBuilder is the main interface most developers interact with. It validates required fields (agentId, sessionId, event type), auto-generates UUIDs and nanosecond timestamps, and exposes chainable methods like .action(), .observation(), .state(), .goal(), and .causedBy() that build up a typed event payload. Calling .send() submits it synchronously; calling .enqueue() buffers it locally for batch delivery.
Event processing follows one of three paths depending on your configuration:
EventBuilder.send()
↓
┌─────────────────────────────────┐
│ Config check │
│ ├── defaultAsync: false? │──→ POST /api/event (sync, await response)
│ ├── defaultAsync: true? │──→ POST /api/event?async=true (fire-and-forget)
│ └── autoBatch: true? │──→ Push to local queue
│ ├── queue hits batchMaxSize? ──→ Flush batch via POST /api/events
│ └── batchInterval elapsed? ──→ Flush batch via POST /api/events
└─────────────────────────────────┘
Safe serialization runs on every outbound payload. It walks the object tree to replace circular references with "[Circular]", converts BigInt values to strings (for Rust u128 compatibility), strips __proto__ and constructor keys to prevent prototype pollution, and rejects payloads exceeding the configured size limit (default 1MB).
Telemetry is opt-in and fully non-blocking. When enabled, the SDK fires POST requests to /api/telemetry after each operation with latency, status codes, error messages, and token count estimates. You can also pass a custom onTelemetry callback for your own monitoring pipeline.
The SDK handles serialization, batching, error recovery, and telemetry so you can focus on your agent's logic.
Get Started
Install the SDK and submit your first event in under 5 minutes:
npm install minns-sdk
import { createClient } from 'minns-sdk';
const client = createClient({ apiKey: "your-api-key" });
await client
.event("my-agent", { agentId: 1, sessionId: Date.now() })
.action("hello_world", { message: "First event!" })
.send();
// Your agent is now learning.
Check out the full documentation on GitHub and the API reference to explore everything the SDK offers.
What's Next
We're actively developing minns-sdk with a focus on:
- Streaming event support for real-time agent workflows
- Multi-agent collaboration primitives built on the communication event type
- Pre-built integrations for popular agent frameworks (LangChain,openclaw)
We'd love your feedback. Try it out, open issues, and let us know what your agents need to learn.
