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 11 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 70.2% on LongMemEval-M, the only open-source library above 65% on M with reproducible methodology.
• Runtime tool forging. An agent writes a TypeScript function with a Zod schema, an LLM judge approves it, and it runs in a hardened node:vm sandbox before joining the catalog for the rest of the session.
• Persistent cognitive memory with 8 neuroscience-backed mechanisms: Ebbinghaus decay, retrieval-induced forgetting, reconsolidation, source-confidence decay.
• Optional HEXACO personality, 6 orchestration strategies, guardrails, and voice across 11 LLM providers; 100+ extensions and 88 skills auto-load at startup.

_{Runtime tool forging + multi-agent collaboration. Reproduce with node examples/emergent-hierarchical-spawning.mjs.}

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 },
  memory: { types: ['episodic', 'semantic'], working: { enabled: true } },
});

// Provider auto-detected from env when `provider` is omitted.

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 in 0.10. Sessions carry a lossless conversation transcript — assistant tool calls, tool results, thinking blocks — independent of the memory subsystem, bounded by default (whole-block eviction past a ~120K-token estimate). memory: false no longer makes a session stateless; pass history: false for that. Long tool-driving loops get session.reseed(snapshot) (atomic history replacement with in-flight epoch guarding), session.messages() as checkpoint material, and per-send generation overrides (toolChoice, requestTimeout, cache, cacheDiagnostics, blockLabel):

// Before 0.10 — stateless unless memory was on:
const s = agent({ model, memory: false }).session('job-1'); // kept no history

// 0.10 — sessions remember by default; opt out explicitly:
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' }]);

Cache note: history byte-stability holds for the stored transcript between eviction events; the wire request can still legitimately differ when dynamic memory context or message-mutating hooks inject per-call content.

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 biases retrieval, routing, and decisions. Each is configurable and observable.

Runtime tool forging. When no tool covers a sub-task, the agent writes a TypeScript function with a Zod schema; a separate LLM judge approves it; it runs in a hardened node:vm sandbox (5s wall clock, no eval/require/process), then joins a discoverable index for the rest of the session. First forge costs full tokens; reuse costs tens. Promoted tools export as SKILL.md skills. Emergent capabilities ->

HEXACO personality (optional). Off by default; the runtime behaves identically without it. When supplied, the kernel weights retrieval, specialist routing, and tool selection by trait values, so the same prompt and tools yield measurably different decision sequences. It lives in the kernel, not the prompt, so it persists under context pressure. HEXACO docs ->

Soul files. Identity, voice, hard limits, and HEXACO scores can live in a SOUL.md workspace. Its memory/ directory is a markdown wiki (an index.md catalog plus entities/, concepts/, log/ pages with [[wikilinks]]) that is the agent's long-term memory: markdown is the source of truth, the vector/graph index is rebuilt from it, and souledAgent() wires it end to end. Soul Files ->

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

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

Memory Benchmarks

gpt-4o reader, 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: +1.4 points over Mastra OM gpt-4o (84.23%), 0.4 behind Emergence.ai's closed-source 86%. The highest publicly reproducible open-source number at gpt-4o.
• 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. With hierarchical + emergent: { enabled: true }, the manager forges new sub-agents at runtime. Multi-agent docs ->

Ecosystem

Extensions and skills auto-load at startup. 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([...])). Comma-separated keys auto-rotate on quota.

Full credential resolution + default models per provider ->

API Surfaces

• agent(): lightweight stateful agent. Prompts, sessions, personality, hooks, tools, memory.
• agency(): multi-agent teams + full runtime. Emergent tooling, guardrails, RAG, voice, channels, HITL.
• generateText() / streamText() / generateObject() / generateImage() / generateVideo() / generateMusic() / performOCR() / embedText(): low-level multi-modal helpers with native tool calling.
• workflow() / AgentGraph / mission(): three orchestration authoring APIs over one graph runtime.

Provider fallback is an explicit opt-in via agent({ fallbackProviders: [...] }); the runtime never silently retries against a different provider unless you configure a chain.

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
• Guardrails: 5 tiers, 6 packs
• 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

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 team@frame.dev.

License

Apache 2.0

Built by Frame * Wilds.ai