AgentOS · TypeScript AI Agent Framework

Agents that remember, forge their own tools, and survive long-running sessions. Persistent cognitive memory, optional HEXACO personality, multi-agent orchestration, and one dispatch interface across 13 LLM providers. Apache-2.0.

Benchmarks * Website * Docs * npm * Discord * Blog

AgentOS is an open-source TypeScript framework for AI agents that remember, adapt, and write their own tools.

• Top open-source memory benchmarks: 85.6% on LongMemEval-S at $0.0090/correct (gpt-4o and gpt-5-mini readers, routed per question type), and 70.2% on LongMemEval-M, the only open-source library above 65% on M with reproducible methodology.
• Runtime tool forging. An agent writes a JavaScript function with JSON Schemas for its input and output, the declared test cases run it, an LLM judge reviews the result, and on approval the tool joins the session's tool list. Forged code runs in an in-process node:vm context or, with QuickJSExecutor, in a QuickJS WebAssembly instance of its own for each call.
• Persistent cognitive memory with Ebbinghaus decay and 8 neuroscience-backed mechanisms, among them retrieval-induced forgetting, reconsolidation and source-confidence decay.
• Optional HEXACO personality, 7 orchestration strategies, guardrails, and voice across 13 LLM providers; 100+ extensions and 88 skills ship as separate packages with registries that load them.

Install

npm install @framers/agentos

import { agent } from '@framers/agentos';

const tutor = agent({
  provider: 'anthropic',                          // resolves to claude-sonnet-4-6 (provider default)
  // model: 'claude-opus-4-8',                    // pin a specific model to override the default
  instructions: 'You are a patient CS tutor.',
  personality: { openness: 0.9, conscientiousness: 0.95 },
});

// Provider auto-detected from env when `provider` is omitted.
// Cognitive memory, sentiment tracking and metaprompts: runtime: 'gmi' (see GMIs below).

const session = tutor.session('student-1');
await session.send('Explain recursion with an analogy.');
await session.send('Can you expand on that?'); // remembers context

Full quickstart * Examples cookbook * API reference

Sessions. A session keeps the whole conversation whether memory is on or off: each send() records its tool calls, their results and the model's signed thinking, and every later request replays them. stream() records its turn as the prompt and the final text (with runtime: 'gmi', every step, as send() does). History is capped at about 120K tokens by default. Set history: false for a stateless session, set history: { maxTokens } to change the cap, and call reseed() to replace the history with a shorter set of messages you build yourself. close() ends a session and frees its history: the next session(id) with that id starts empty, and agent.usage(id) still reports what the id spent.

const stateless = agent({ model, memory: false, history: false }).session('job-1');
const bounded = agent({ model, history: { maxTokens: 60_000 } }).session('job-2');
bounded.reseed([{ role: 'user', content: 'compact resume snapshot' }]);

Emergent Design

Three things accumulate across a session and compose into behavior: memory (what was said, decided, retrieved), the tool surface (which grows when an agent forges a tool the judge approves), and an optional HEXACO personality vector that shapes the prompt and scales memory encoding. Each is configurable and observable.

Runtime tool forging. When no tool covers a sub-task, the agent calls forge_tool with a chain of existing tools or a JavaScript function, JSON Schemas for input and output, and test cases. Code mode is off until the host sets emergentConfig.allowSandboxTools. Source that uses eval, require or process is rejected before it runs. Forged code runs in an in-process node:vm context by default, with a 5 s timeout, and node:vm is not a security boundary; with QuickJSExecutor, each call runs in a QuickJS WebAssembly instance of its own with its memory limited. A separate LLM judge reviews the candidate with its test results, and an approved tool joins the session's tool list. A forged tool exports as a SKILL.md skill. Emergent capabilities ->

HEXACO personality (optional). Off by default. agent() writes the trait values into the system prompt as directives, one for each trait above 0.65 or below 0.35. A cognitive memory manager given the same traits scales its encoding and seven of its eight mechanisms by them, and an AgentGraph branches on a trait with addPersonalityEdge(). HEXACO docs ->

Soul files. An agent's identity, writing style, hard limits and HEXACO scores can live in a SOUL.md workspace. Every way of building an agent applies the identity and the hard limits: the hard limits close the system prompt, and the soul's agentId is the agent's one id. With systemBlocks, the soul's prose and style are left out and its hard limits still close the prompt. Its memory/ directory holds the operator's markdown wiki (an index.md catalog plus entities/, concepts/, log/ pages with [[wikilinks]]), shared by everyone the agent talks with. A souled agent's conversation memory is kept per user (the session's userId, else the session) in a store beside it, and compiled into that user's own pages; souledAgent() wires it end to end. souledAgent() keeps each person's memory under their own scope, deletes it for good with agent.forgetUser(userId) and keeps it deleted through restores; what stays your duty. Soul Files ->

import { souledAgent } from '@framers/agentos';

const aria = await souledAgent({ provider: 'anthropic', soul: '~/.agentos/agents/aria' });

Generalized Mind Instances (GMIs)

On the full runtime, every session is served by a GMI: a persistent agent with its own persona, mood, conversation history and reasoning trace; with agent({ runtime: 'gmi' }) an agent's sessions are GMIs too. agent() without runtime: 'gmi' is the lightweight helper; it calls the model with a prompt and keeps session history. A GMI of the full runtime runs a turn loop around the same model, tools, guardrails and cognitive memory:

• Sentiment → metaprompts. When a persona enables sentiment tracking, every user turn is scored; sustained frustration or confusion fires recovery metaprompts, and a self-reflection metaprompt re-reads the GMI's mood and task context from evidence.
• Mood-weighted memory. With cognitive memory attached, each exchange is encoded with the GMI's current mood and recalled with emotional congruence in the score.
• Self-modification tools. With selfImprovement.enabled, the runtime registers adapt_personality, manage_skills, create_workflow and self_evaluate; adapt_personality changes the running GMI's traits within bounds, and a mutation store records the changes when a storage adapter and persistWithDecay are configured.
• A reasoning trace of the last 500 decisions by default (reasoningTraceConfig on the persona or the runtime's default), and persona overlays per session.

import { AgentOS, AgentOSResponseChunkType, BUILT_IN_PERSONAS } from '@framers/agentos';

// AgentOS.create() reads persona files from ./personas by default. Personas can
// also be given inline, as parsed JSON or code-built objects; here, the five the
// package ships. A custom loader covers any other source.
const agentos = await AgentOS.create({ personas: BUILT_IN_PERSONAS });
for await (const chunk of agentos.processRequest({
  userId: 'user-42', sessionId: 'research-q1', selectedPersonaId: 'v_researcher',
  textInput: 'Summarize the open incidents from this week.',
})) {
  if (chunk.type === AgentOSResponseChunkType.TEXT_DELTA) process.stdout.write(chunk.textDelta);
}

agent({ runtime: 'gmi' }), also exported as gmi(), builds its GMIs in process from the agent's options, with no AgentOS runtime. Of the parts above, these GMIs run the reasoning trace, the mood-weighted memory when memory is on, and sentiment tracking with the five preset event metaprompts (frustration recovery, confusion clarification, satisfaction reinforcement, error recovery and engagement boost) when their profile turns them on. The 'full' profile turns on cognitive memory, sentiment tracking and those five metaprompts; 'light', the default, keeps the reasoning trace and adds memory only when memory is set. The self-reflection metaprompt, the self-modification tools, persona overlays and the runtime's guardrails, retrieval and channels do not run on this path. This tutor's GMIs run every part this path has:

import { agent } from '@framers/agentos';

const tutor = agent({
  runtime: 'gmi',
  cognition: 'full',
  provider: 'openai',
  instructions: 'You are a patient CS tutor.',
  memory: { embedding: { provider: 'openai' } }, // cognitive memory embeds with text-embedding-3-small
});
const session = tutor.session('student-1', { userId: 'student-7f3a' }); // memory is scoped to the user id
await session.send('Explain recursion with an analogy.');

What a GMI adds over a plain agent →

Memory Benchmarks

Both headline results use a per-category reader router (gpt-4o answers temporal-reasoning and single-session-user questions, gpt-5-mini the other four types), with the gpt-4o-2024-08-06 judge, full N=500, single-CLI reproduction with bootstrap 95% CIs and per-benchmark judge-FPR probes.

• LongMemEval-S: 85.6% at $0.0090/correct, 3,558 ms p50. With gpt-4o reading every question, the same retrieval scores 84.2%, level with Mastra OM with a gpt-4o actor (84.23%; Mastra uses gemini-2.5-flash as its observer and reflector); Mastra OM reports 94.87% with a gpt-5-mini actor. Full table and methodology: LEADERBOARD.md.
• LongMemEval-M: 70.2% (1.5M-token haystacks, 500 sessions): the only open-source library above 65% on M with reproducible methodology.

Full leaderboard -> * Transparency audit -> * LongMemEval paper (Wu et al., ICLR 2025)

Why AgentOS

Full framework comparison ->

Key Features

Multi-Agent in 6 Lines

import { agency } from '@framers/agentos';

const team = agency({
  strategy: 'graph',
  agents: {
    researcher: { provider: 'anthropic', instructions: 'Find relevant facts.' },                            // -> claude-sonnet-4-6
    writer:     { provider: 'openai',    instructions: 'Summarize clearly.', dependsOn: ['researcher'] },   // -> gpt-4o
    reviewer:   { provider: 'gemini',    instructions: 'Check accuracy.',    dependsOn: ['writer'] },       // -> gemini-2.5-flash
  },
});

const result = await team.generate('Compare TCP vs UDP for game networking.');

Strategies: sequential, parallel, debate, review-loop, hierarchical, graph, panel. With hierarchical + emergent: { enabled: true }, the manager forges new sub-agents at runtime. Every roster agent can set its own provider, model, apiKey and effort; a parallel or panel agency can require a provider quorum (quorum: { minProviders: 2 }) before it synthesizes. A modelPool fills every seat that names neither provider nor model from named models on each call, with strict per-seat credentials and every key redacted from the records. Multi-agent docs ->

Ecosystem

Extensions load from the manifest a host passes to AgentOS.create({ extensionManifest }); createCuratedManifest() from @framers/agentos-extensions-registry builds one from the curated extensions that are installed, and a runtime without a manifest loads none. Extensions architecture ->

Configure API Keys

Three layers, highest priority first: inline apiKey on the call, a module-level setDefaultProvider() at boot, or environment-variable auto-detection (OPENAI_API_KEY, ANTHROPIC_API_KEY, and the rest, resolved in priority order and reorderable with setProviderPriority([...])). A comma-separated list of keys gives a provider a key pool: round-robin by default, or AGENTOS_KEY_POOL_STRATEGY_<PROVIDER>=ordered (AGENTOS_KEY_POOL_STRATEGY_ANTHROPIC=ordered for Anthropic's keys alone; AGENTOS_KEY_POOL_STRATEGY=ordered for every provider's) to use the keys in order and fail over to the next when one is revoked, unpaid or throttled (Key rotation). probeProviderKey({ provider, apiKey }) says whether one key is live, out of credit, rejected or throttled, by the same billing probe the pool sends.

Full credential resolution + default models per provider ->

API Surfaces

• agent(): lightweight stateful agent. Prompts, sessions, personality, hooks, tools, memory through memoryProvider hooks. With runtime: 'gmi' (or gmi()), every session is a GMI built from the same options, with cognitive memory, sentiment tracking and metaprompts per its cognition profile.
• agency(): multi-agent teams built from agent() members, with HITL approval gates, run limits, structured output, provenance and, on the hierarchical strategy, specialists spawned at runtime. Its guardrails and rag options are reported or logged and not applied, and voice.enabled serves the agency as JSON text over a local WebSocket. It wires no channels; channel adapters run on the full runtime or with ChannelRouter.
• generateText() / streamText() / generateObject() / generateImage() / removeBackground() / generateVideo() / generateMusic() / performOCR() / embedText(): low-level multi-modal helpers. generateText() and streamText() take tools; the other helpers take none.
• workflow() / AgentGraph / mission(): three orchestration authoring APIs over one graph runtime.

Provider fallback is on by default for generateText(), streamText(), agent() and agency(): when a call fails with a retryable error, it is retried on the other providers whose keys are in the environment. Pass fallbackProviders: [] to turn it off, or a list to set the chain yourself. The GMIs of the full runtime (processRequest()) call their provider without a fallback chain. The GMIs of agent({ runtime: 'gmi' }) call it through a completion gateway built from the agent's fallbackProviders, which moves to the next provider when a call fails with a retryable error before its first output, and not after it.

Full API reference -> * High-Level API guide ->

Documentation & Community

• Benchmarks: benchmark tables, 95% confidence intervals, methodology audit
• Architecture: system design, layer breakdown
• Cognitive Memory: 8 mechanisms with 30+ APA citations
• RAG Configuration: vector stores, embeddings, sources
• Document Ingestion: PDF, Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, HTML and Markdown read to text, with bounds on what a Word or office archive inflates to
• Library Index: sources over any vector store, and a browser entry for a page's own search and records, transcript files from other notetakers (SubRip, WebVTT, Otter, Fireflies, Word) read to turns with the speakers kept apart, and the plan of an archive's entries
• Text Processing & Search: tokenizers and stemming, BM25, fuzzy and hybrid search, text statistics, chunking, reranking
• Reranking: one RerankerService over a local Transformers.js cross-encoder (scoring stays in the process), Cohere's rerank API, an LLM judge on any model your function calls, or a provider of your own
• Guardrails: two-phase dispatcher, four verdicts, a hold on a BLOCK that keeps content back for a person's review, fail-open and fail-closed guards
• Voice Pipeline: TTS, STT, telephony
• Blog: engineering posts, benchmark publications, transparency audits
• Discord * GitHub Issues * Wilds.ai (AI game worlds powered by AgentOS)

Contributing

git clone https://github.com/framerslab/agentos.git && cd agentos
pnpm install && pnpm build && pnpm test

pnpm run test:coverage runs the suite with coverage, as CI does: the run fails below the thresholds in vitest.config.ts, and CI sends master's figures to Codecov, which the coverage badge reads.

We use Conventional Commits. Project guides:

Startups & Partnerships

AgentOS is Apache-2.0 and free. We integrate any quality provider on technical merit, and partners and sponsors are featured in the README and docs, labeled as such. Companies engage through partner startup programs, sponsorship, or a provider integration. See SPONSORS.md.

Programs & partners

Partner	Type	Provides	Since
	Startup Program	Speech-to-text + text-to-speech credits, go-to-market	2026

Ways to engage

Interested? Email [email protected].

License

Apache 2.0

   

Built by Frame * Wilds.ai