Frequently Asked Questions

AgentOS is an open-source TypeScript runtime for building production AI agents, developed by Frame.dev. It provides multi-agent orchestration, cognitive memory, multimodal RAG, opt-in safety guardrails (PII redaction, content moderation, grounding checks), voice pipelines, 37 channel adapters, and 13 LLM provider integrations. AgentOS also powers the AI systems behind Wilds.ai, an AI-native gaming platform. Self-hostable and free.

Yes. The runtime, the curated extensions, the guardrail packs and the curated skills are all licensed under Apache 2.0. You can use AgentOS commercially, modify it and redistribute it under that license.

AgentOS supports 13 LLM providers: OpenAI, Anthropic, Google Gemini, Groq, Together AI, Mistral, xAI (Grok), OpenRouter, Requesty, LiteLLM, Ollama, Claude Code CLI and Gemini CLI. Provider fallback chains allow automatic failover.

AgentOS is written entirely in TypeScript and runs on Node.js. The npm package is @framers/agentos. It works with any TypeScript or JavaScript project.

AgentOS is TypeScript-native (not Python), includes cognitive memory with Ebbinghaus decay curves and HEXACO personality modeling, offers opt-in guardrail packs for PII redaction, content moderation and grounding checks, provides 37 channel adapters (Discord, Telegram, Slack, email, and more), and supports 6 orchestration strategies including graph-based agent DAGs. It also ships with 88 curated skills and a capability discovery engine that puts only the relevant tools and skills in context, within a token budget per tier.

Paracosm (https://paracosm.agentos.sh) is a structured world-model simulation engine built on AgentOS. It compiles a JSON ScenarioPackage plus a HEXACO leader profile into a turn loop on a seeded, deterministic kernel, where AgentOS agents propose events, forge new JavaScript tools at runtime that AgentOS runs in node:vm with a 10-second time limit, and produce a counterfactual artifact you can fork and replay. Three modes share one schema: turn-loop civilization sims (Mars Genesis is the canonical example), batch-trajectory digital twins, and batch-point Monte-Carlo forecasts. Open-source under Apache 2.0, npm install paracosm. Live demo: https://paracosm.agentos.sh/sim. Source: https://github.com/framerslab/paracosm. Long-form launch post (why we built it, the wilds.ai vault story, the engine reference): https://agentos.sh/blog/paracosm-launch.

Wilds.ai (https://wilds.ai) is an AI-native gaming platform built on AgentOS and Paracosm. AI characters with persistent cognitive memory and HEXACO personality traits inhabit shared world models and diverge from each other based on grounded LLM-as-judge events. Players can drop into existing worlds, fork them, or compile new ones in the browser. Wilds.ai is the canonical production deployment of the AgentOS + Paracosm stack and the official community / support channel (https://wilds.ai/discord) for both projects.

Wunderland (https://wunderland.sh) is a sister project under active development that packages a batteries-included CLI plus daemon on top of the AgentOS extension and skill registries. It ships a 60-command CLI (setup, chat, rag, agency, workflows, evaluate, provenance, knowledge, marketplace, and more), a 5-tier security model (dangerous / permissive / balanced / strict / paranoid), 9 agent presets, step-up HITL authorization, and the same cognitive memory plus graph-based RAG architecture documented in the AgentOS docs. Use @framers/agentos when you want a typescript SDK to embed in your application; use Wunderland when you want a global CLI you can install with pnpm add -g wunderland and configure with a wizard. Source at github.com/jddunn/wunderland (Apache 2.0 from 0.71.0). Preview release; APIs and CLI surface may still change. Getting-started guide: https://docs.agentos.sh/wunderland.

GMI stands for Generalized Mind Instance. It is the agent the AgentOS runtime creates for each session: it holds that session's persona (HEXACO traits), conversation history, mood and reasoning trace, runs each turn through retrieval, prompt assembly, the model call and tool calls, and can be given cognitive memory that persists across sessions. The lightweight agent() helper calls the model directly and creates no GMI unless you pass runtime: 'gmi'; gmi() and the full runtime (AgentOS.processRequest) create GMIs.

HEXACO is a 6-factor personality model from psychology research (Ashton & Lee, 2007). The six dimensions are Honesty-Humility, Emotionality, Extraversion, Agreeableness, Conscientiousness, and Openness to Experience. In AgentOS, HEXACO traits shape how agents communicate and remember. agent() writes traits above 0.65 or below 0.35 into the system prompt as behavior directives. In cognitive memory, high Emotionality increases how much a memory is rewritten when it is recalled (reconsolidation), while high Conscientiousness strengthens retrieval-induced forgetting of competing memories.

AgentOS cognitive memory implements 8 mechanisms from cognitive science research: reconsolidation, retrieval-induced forgetting, involuntary recall, feeling-of-knowing, temporal gist extraction, schema encoding, source confidence decay, and emotion regulation. Memories decay over time following Ebbinghaus forgetting curves (Ebbinghaus, 1885), and each successful retrieval makes a memory more stable, as in spaced repetition. Working memory follows Baddeley's multi-component model (Baddeley, 2000) with 7 slots by default: high Openness adds one, high Conscientiousness removes one, and the count stays between 5 and 9. A new memory is stored as an episodic memory by default and takes a working-memory slot. When the slots are full, the least active slot gives way and its memory stays in storage. Consolidation later turns old, often-retrieved episodic memories into semantic ones.

AgentOS has six opt-in guardrail packs: PII redaction (names, emails, phone numbers, SSNs and more), ML classifiers for toxicity, threats and NSFW content, static analysis of generated code for dangerous patterns, grounding checks against source documents, topicality enforcement to keep agents on-task, and a content-policy rewriter that rewrites or blocks output that breaks your policy. Each pack is an extension you enable on the AgentOS runtime. The classifiers pack scores prompt injection only when its local model cannot load, so for known injection phrases use the built-in phrase-list guardrail.

The capability discovery engine finds tools and skills by semantic search and puts them in the prompt in three tiers, each with a hard token budget. Tier 0 keeps category summaries in context (200 tokens by default). Tier 1 adds the top 5 semantic matches for the turn (800 tokens). Tier 2 adds full schemas or SKILL.md text for the top 2 matches (2,000 tokens). A meta-tool called discover_capabilities lets agents look up available tools at runtime.

The QueryRouter classifies each query into one of 4 tiers and retrieves to match: T0 answers from the conversation with no retrieval, T1 runs a single vector search (a keyword search when no embedding provider is configured), T2 retrieves 15 chunks, adds related chunks through graph expansion and reranks the merged set to the top 5, and T3 splits the query at sentence breaks into up to 5 sub-queries, retrieves 10 chunks for each, adds related chunks through graph expansion, reranks the merged set to the top 10 and then, when deep research is enabled (by default when SERPER_API_KEY is set), runs a deep-research pass whose findings it merges in. It then answers from what it retrieved and returns the answer with its source citations.

Adaptive intelligence is how AgentOS agents adjust their behavior without retraining. Five mechanisms work together: (1) Per-turn prompt assembly: a GMI's PromptEngine builds the system prompt each turn from the persona, mood, conversation history, retrieved memories and available tools. (2) Self-evaluation: with self-improvement enabled, the self_evaluate tool scores the agent's own answer and can change the session's temperature or verbosity, or adjust a trait through adapt_personality. (3) Personality-modulated memory: HEXACO traits tune the memory mechanisms; high Openness makes involuntary recall more likely, and high Conscientiousness strengthens retrieval-induced forgetting of competing memories. (4) Memory consolidation: consolidation passes prune decayed memories, merge duplicates, turn old, often-retrieved episodic memories into semantic ones and, with an LLM configured, derive insight memories from clusters. (5) QueryRouter tiers: retrieval depth follows the query, from no retrieval when the conversation already holds the answer to deep research across the corpus for the hardest ones.

Emergent behaviors are capabilities that agents develop at runtime rather than being explicitly programmed. AgentOS supports five forms: (1) Runtime tool forging: with emergent: true on the AgentOS runtime, agents write new tools in JavaScript through forge_tool. The EmergentCapabilityEngine runs each one in node:vm under a time limit, and an LLM judge reviews the code and its test runs before the tool is registered. (2) Self-adjusting personality: adapt_personality moves a HEXACO trait within set bounds for the running agent. With persistWithDecay and a mutation store, each change is recorded, and the stored records lose strength at most once a day, when the agent adapts. (3) Dynamic skill management: agents enable or disable skills at runtime via manage_skills, adapting their behavioral repertoire to the task at hand. (4) Composable workflow creation: agents compose registered tools into multi-step pipelines via create_workflow, building new capabilities from existing building blocks. (5) Tiered tool promotion: a forged tool starts at the session tier. After at least 5 uses with a success rate of 0.8 or higher, and approval from two LLM reviewers, it moves to the agent tier. A host can promote a tool to the shared tier with EmergentToolRegistry.promote().

Yes. AgentOS provides two complementary LLM-as-judge mechanisms. At the agency level, hitl.llmJudge() creates an approval handler that delegates decisions to an LLM. It evaluates each ApprovalRequest against configurable criteria and returns a structured decision with a confidence score. When confidence falls below the threshold, the decision escalates to a fallback handler (another hitl handler or a human). At the graph level, the humanNode() builder accepts a judge option that delegates the interrupt decision to an LLM. If the judge is confident, the graph continues without suspension. If confidence is low, execution falls through to a normal human interrupt. Both approaches support configurable model, provider, criteria, and confidence threshold. Example: hitl.llmJudge({ model: 'gpt-4o-mini', criteria: 'Is this response factually accurate?', confidenceThreshold: 0.8, fallback: hitl.cli() }).

Yes. When hitl.guardrailOverride is enabled, guardrails run after an approval decision and can still block destructive or sensitive actions. This adds a second safety layer after auto-approve, human approval, or hitl.llmJudge(). The default post-approval guardrails include code-safety and pii-redaction, and you can configure the list with hitl.postApprovalGuardrails. Disable the override only if you explicitly want the approval handler to have the final say.

Install via npm: npm install @framers/agentos. AgentOS requires Node.js 22 or higher. For the CLI tools, install the companion package: npm install -g wunderland.

Import the agent function and configure it with a provider, instructions, and optional personality traits:

import { agent } from '@framers/agentos'

const myAgent = agent({
  provider: 'openai',
  instructions: 'You are a helpful assistant.',
  personality: {
    openness: 0.8,
    conscientiousness: 0.9,
  },
})

const reply = await myAgent.generate('Hello!')
console.log(reply.text)

AgentOS runs voice through VoicePipelineOrchestrator. You give it a streaming STT session, a streaming TTS session, an endpoint detector and a barge-in handler, and it connects them to an agent session over a transport such as a WebSocket. The speech catalog lists 13 STT providers and 13 TTS providers. Of these, 11 STT providers, including Whisper (OpenAI), Deepgram and AssemblyAI, and 10 TTS providers, including ElevenLabs, OpenAI TTS and Google Cloud TTS, are available. The other five entries (Whisper.cpp, NVIDIA NeMo, Coqui XTTS, Bark and StyleTTS2) are marked unavailable, and the provider resolver skips them. Twilio, Telnyx and Plivo providers place and end phone calls.

AgentOS is self-hostable and runs anywhere Node.js 22 or later runs. Deploy on your own infrastructure with Docker, on cloud providers like AWS, GCP, or Azure, or use platforms like Vercel, Railway, or Fly.io. SQLite needs no setup, and the MigrationEngine moves stored data to Postgres, Qdrant, or Pinecone when you need more scale.

Yes. AgentOS works fully offline when paired with Ollama for local LLM inference. Ollama provides access to open-weight models like Llama, Mistral, and Phi locally. The SQLite storage backend and in-memory vector store require no external services. The Wunderland CLI's ollama-setup command detects or installs Ollama and configures the agent to use it.

Yes. AgentOS ships opt-in guardrail packs that redact personal data, moderate content and check answers against sources, approval gates for sensitive tool calls, spend budgets that refuse a call past the cap, and circuit breakers that take a failing provider out of rotation.

AgentOS ships a PII redaction guardrail that strips personal data before it reaches LLM providers, and self-hosted deployment so data stays on your infrastructure. Memory exports to JSON, Markdown, Obsidian or SQLite for an access request. Forgetting a memory hides it from recall and keeps its row in the database, so an erasure request needs a delete in your own storage. GDPR and SOC 2 compliance are organizational responsibilities of the deploying team, not properties of the library itself.

Yes. For production deployments, enterprise licensing, dedicated support, and custom integrations, contact the team at [email protected]. Enterprise support includes priority issue resolution, architecture consulting, and deployment assistance.

[email protected]

Absolutely. AgentOS is designed to be self-hosted from the ground up. For self-hosted deployments, your data stays on your infrastructure with SQLite, Postgres, pgvector, Qdrant, or Neo4j. If you want a managed vendor-hosted vector database instead, Pinecone is also supported. A setup helper can start a local Qdrant container with Docker.