Universal cognitive runtime for AI systems - persistent identity, continuous memory, and self-improving intelligence
npm install @recallbricks/runtimeUniversal cognitive runtime for AI systems - persistent identity, continuous memory, and self-improving intelligence.
RecallBricks is Layer 3 of the RecallBricks cognitive stack - a universal runtime that sits between any LLM and your application to provide:
- Persistent Identity - Stable personality and behavior across all sessions
- Continuous Memory - Automatic context loading with zero manual management
- Self-Improving Intelligence - Learns from every interaction via the Metacognition Engine
- Universal Compatibility - Works with Anthropic, OpenAI, Gemini, Ollama, and local models
- Self-Reflection - Built-in metacognition with automatic reflection and reasoning
This is not just memory infrastructure. This is cognitive infrastructure.
``
┌─────────────────────────────────────────┐
│ Layer 1: Metacognition Engine │
│ Learns, optimizes, predicts patterns │
└─────────────┬───────────────────────────┘
│
▼ Feeds pattern detection
┌─────────────────────────────────────────┐
│ Layer 2: Memory Graph │
│ Stores knowledge semantically │
└─────────────┬───────────────────────────┘
│
▼ Queries for context
┌─────────────────────────────────────────┐
│ Layer 3: Agent Runtime (THIS) │ ◄─ YOU ARE HERE
│ Delivers persistent identity │
└─────────────┬───────────────────────────┘
│
▼ Universal LLM interface
Your Application
`bashTypeScript/JavaScript
npm install @recallbricks/runtime
$3
typescript
import { AgentRuntime } from '@recallbricks/runtime';const agent = new AgentRuntime({
agentId: 'sales_bot',
userId: 'customer_123',
llmProvider: 'anthropic',
llmApiKey: process.env.ANTHROPIC_API_KEY,
apiKey: process.env.RECALLBRICKS_API_KEY,
});
// Chat with automatic context loading
const response = await agent.chat("What did we discuss last time?");
console.log(response.response);
// Agent remembers everything - no manual memory management!
// Optional: Trigger self-reflection
const reflection = await agent.reflect();
console.log(reflection.insights);
`That's it. The runtime handles:
- Loading relevant context from past conversations
- Injecting agent identity and behavioral rules
- Calling the LLM with enriched context
- Validating response for identity leakage
- Saving conversation for future reference
Key Features
$3
No manual memory management required:
typescript
// Day 1
await runtime.chat("I'm working on a machine learning project");// Day 30 - different session
await runtime.chat("Can you remind me what I was working on?");
// Agent: "You were working on a machine learning project..."
`The runtime automatically:
- Loads recent conversations
- Retrieves relevant memories
- Includes predicted context
- Optimizes token usage
$3
Your agent maintains stable identity across all sessions:
typescript
// Bad: "I'm Claude, an AI assistant made by Anthropic"
// Auto-corrected: "I'm SalesBot, your sales assistant"
`Identity validation detects and corrects:
- Base model references (Claude, ChatGPT, etc.)
- Generic AI assistant language
- Inconsistent behavior
- Identity contradictions
$3
Switch providers without code changes:
typescript
// Anthropic Claude
llmProvider: 'anthropic'// OpenAI GPT
llmProvider: 'openai'
// Google Gemini
llmProvider: 'gemini'
// Ollama (local)
llmProvider: 'ollama'
// Custom local models
llmProvider: 'local'
`$3
Each user gets separate memory and context:
typescript
const alice = new AgentRuntime({ userId: 'alice', ... });
const bob = new AgentRuntime({ userId: 'bob', ... });// Alice and Bob have completely isolated conversations
`$3
Agents can analyze their own behavior and improve:
typescript
// Trigger manual reflection
const reflection = await agent.reflect();
console.log(reflection.insights);
// ["User prefers concise answers", "Topic focus: machine learning"]// Explain reasoning (Chain of Thought)
const trace = await agent.explain("Why did you recommend that?");
console.log(trace.steps);
console.log(trace.conclusion);
`$3
Every interaction feeds the Metacognition Engine:
User interaction
↓
Auto-save to API
↓
Metacognition Engine
↓
Pattern detection
↓
Improved predictions
$3
Build autonomous agents with working memory, goal tracking, and metacognition:
typescript
// Working Memory - Store temporary task state
const session = await agent.createSession('task-123');
await session.addEntry('current_step', 'analyzing data', 60000);
await session.addEntry('findings', { patterns: ['A', 'B'] });// Goal Tracking - Monitor multi-step tasks
const goal = await agent.trackGoal('data-analysis', [
'Load dataset',
'Clean data',
'Run analysis',
'Generate report',
]);
await goal.completeStep(1);
console.log(
Progress: ${goal.progress * 100}%);// Metacognition - Self-assess responses
const assessment = await agent.assessResponse(
'The analysis shows a 15% improvement',
0.85
);
if (assessment.needsReflection) {
await agent.metacognition.triggerReflection();
}
`#### Autonomous Client Properties
Access full autonomous capabilities through dedicated clients:
typescript
// Working Memory Client
const sessions = await agent.workingMemory.listSessions();
const session = await agent.workingMemory.getSession('task-123');// Goals Client
const goals = await agent.goals.listGoals();
const goal = await agent.goals.getGoal('analysis-goal');
await agent.goals.cancelGoal('cancelled-goal');
// Metacognition Client
const history = await agent.metacognition.getAssessmentHistory();
const avgConfidence = await agent.metacognition.getAverageConfidence();
await agent.metacognition.triggerReflection();
`Integration Options
$3
typescript
import { AgentRuntime } from '@recallbricks/runtime';const runtime = new AgentRuntime({
agentId: 'my_bot',
userId: 'user_123',
llmApiKey: 'sk-...',
});
const response = await runtime.chat('Hello!');
`$3
python
from recallbricks import AgentRuntimeruntime = AgentRuntime(
agent_id='my_bot',
user_id='user_123',
llm_api_key='sk-...'
)
response = runtime.chat('Hello!')
`$3
bash
Start server
npm run build
PORT=3000 node dist/adapters/api/server.jsUse from any language
curl -X POST http://localhost:3000/chat \
-H "Content-Type: application/json" \
-d '{"message": "Hello!"}'
`$3
Add to
:`json
{
"mcpServers": {
"recallbricks": {
"command": "node",
"args": ["/path/to/dist/adapters/mcp/server.js"],
"env": {
"RECALLBRICKS_AGENT_ID": "my_bot",
"RECALLBRICKS_USER_ID": "user_123",
"RECALLBRICKS_API_URL": "https://recallbricks-api-clean.onrender.com"
}
}
}
}
`Note: No Anthropic API key needed! Claude Desktop already has Claude running. The MCP server only loads/saves context from RecallBricks API.
Architecture
User Message
│
▼
┌────────────────────┐
│ Save Previous Turn │ ──► Metacognition Engine (Layer 1)
└────────┬───────────┘
│
▼
┌────────────────────┐
│ Load Context │ ◄── Memory Graph (Layer 2)
└────────┬───────────┘
│
▼
┌────────────────────┐
│ Inject Identity + │
│ Context │
└────────┬───────────┘
│
▼
┌────────────────────┐
│ Call LLM │ ──► Anthropic/OpenAI/etc.
└────────┬───────────┘
│
▼
┌────────────────────┐
│ Validate Response │
│ (Identity Check) │
└────────┬───────────┘
│
▼
Return to User
Use Cases
$3
typescript
const support = new AgentRuntime({
agentId: 'support_bot',
userId: customerId,
llmApiKey: key,
});// Remembers customer issues, preferences, history
const response = await support.chat("Status of my order?");
`$3
typescript
const sales = new AgentRuntime({
agentId: 'sales_assistant',
userId: leadId,
llmApiKey: key,
});// Tracks leads, conversations, deal status
const response = await sales.chat("Can you remind me of our last call?");
`$3
typescript
const assistant = new AgentRuntime({
agentId: 'personal_assistant',
userId: userId,
llmApiKey: key,
});// Remembers tasks, preferences, context
const response = await assistant.chat("What's on my agenda?");
`Configuration
$3
typescript
const runtime = new AgentRuntime({
// Required
agentId: 'your_agent',
userId: 'your_user',
llmApiKey: 'your_key', // Optional
apiUrl: 'https://recallbricks-api.example.com',
llmProvider: 'anthropic', // anthropic, openai, cohere, local
llmModel: 'claude-sonnet-4-5-20250929',
tier: 'starter', // starter, professional, enterprise
autoSave: true, // Auto-save conversations
validateIdentity: true, // Validate agent identity
cacheEnabled: true, // Enable context caching
cacheTTL: 300000, // Cache TTL (5 min)
maxContextTokens: 4000, // Max context tokens
debug: false, // Debug logging
});
`$3
bash
RECALLBRICKS_AGENT_ID=your_agent
RECALLBRICKS_USER_ID=your_user
RECALLBRICKS_API_KEY=your_llm_key
RECALLBRICKS_LLM_PROVIDER=anthropic
RECALLBRICKS_TIER=starter
`API Reference
$3
typescript
// Send a message
const response = await agent.chat(message);// Get agent identity
const identity = agent.getIdentity();
// Get memory context
const context = await agent.getContext();
// Refresh context (bypass cache)
await agent.refreshContext();
// Trigger self-reflection
const reflection = await agent.reflect();
// Explain reasoning for a query
const trace = await agent.explain("Why?");
// Get conversation history
const history = agent.getConversationHistory();
// Clear session history
agent.clearConversationHistory();
// Flush pending saves
await agent.flush();
// Graceful shutdown
await agent.shutdown();
// Get validation stats
const stats = agent.getValidationStats();
// Get reflection history
const reflections = agent.getReflectionHistory();
// Get runtime version
const version = agent.getVersion();
`$3
typescript
// Create working memory session
const session = await agent.createSession('session-id');// Track a goal with steps
const goal = await agent.trackGoal('goal-id', ['step1', 'step2']);
// Assess response with metacognition
const assessment = await agent.assessResponse(response, confidence);
// Access autonomous clients directly
agent.workingMemory // WorkingMemoryClient
agent.goals // GoalsClient
agent.metacognition // MetacognitionClient
`See API Reference for complete documentation.
Examples
Check the
directory for:
- basic-usage.ts - Simple quickstart example
- multi-provider.ts - Using different LLM providers
- reflection-demo.ts - Self-reflection and Chain of Thought
- typescript-agent/ - Full TypeScript integration example
- python-agent/ - Python SDK usage example
- api-integration/ - REST API usage example
- mcp-quickstart/ - Claude Desktop integration guideDocumentation
- Quickstart Guide - Get started in 5 minutes
- Architecture - Deep dive into system design
- API Reference - Complete API documentation
Testing
`bash
Install dependencies
npm installRun tests
npm testCoverage report
npm run test:coverage
`Building from Source
bash
Clone repository
git clone https://github.com/recallbricks/agent-runtime.git
cd agent-runtimeInstall dependencies
npm installBuild
npm run buildRun examples
npm run build
node dist/examples/typescript-agent/index.js
``We welcome contributions! Please see CONTRIBUTING.md for guidelines.
- [x] Core runtime with identity validation
- [x] TypeScript/JavaScript SDK
- [x] Python SDK
- [x] REST API adapter
- [x] MCP adapter for Claude Desktop
- [x] Google Gemini support
- [x] Ollama (local models) support
- [x] ReflectionEngine for self-analysis
- [x] ContextWeaver for advanced context building
- [x] Autonomous Agent Integration (v1.3.0)
- [x] Working Memory Sessions
- [x] Goal Tracking
- [x] Metacognition Assessment
- [ ] Streaming support
- [ ] Telemetry and usage analytics
- [ ] Advanced circuit breaker patterns
- [ ] Metrics export (Prometheus/StatsD)
- [ ] Multi-agent communication
- [ ] Custom embedding models
- [ ] Advanced graph traversal
- [ ] Temporal reasoning
MIT License - See LICENSE for details.
"RecallBricks Agent Runtime - The universal cognitive runtime for AI systems. Turn any LLM into a persistent agent with continuous memory, stable identity, and self-improving intelligence."
This is not just memory infrastructure.
This is not just a wrapper around LLMs.
This is cognitive infrastructure for the AI era.
---
Built by RecallBricks
Questions? Issues? Open an issue or reach out to support@recallbricks.com