AgentOS: A TypeScript Agent Framework Built Around Session Memory and Runtime Tool Forging
TypeScript AI agent framework: cognitive memory, runtime tool forging, multi-agent orchestration, 11 LLM providers.
At a glance
- What is it?
- AgentOS bundles cognitive memory, a sandboxed tool-forging loop, and multi-agent orchestration behind one dispatch interface across 11 LLM providers. It is a credible fit for long-running TypeScript agents, but the 0.10 session model changes how history and memory interact, and the documentation is the only evidence available here.
- Who is it for?
- Adopt AgentOS if you are building long-running TypeScript agents that need conversation history, memory types such as episodic and semantic, and the option to let an agent write and sandbox a new tool mid-session. Do not adopt it if you want a minimal prompt wrapper, if you cannot run untrusted code inside node:vm, or if you need a memory backend other than the built-in cognitive subsystem.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem AgentOS Targets: State That Outlives One Prompt
Most TypeScript agent code starts as a function that takes a message, calls a provider, and returns text. The trouble begins when the same agent has to run for hours, remember what a user said three turns ago, and handle a task its static tool list does not cover. AgentOS is aimed at that second stage. The README describes agents that "remember, adapt, and write their own tools," and the package ships memory, personality, orchestration and provider dispatch as one unit rather than as separate libraries you wire together. The intended user is a TypeScript engineer building an assistant or autonomous worker that persists across a long session. It is not a thin client for a chat completion endpoint, and the install example reflects that: a single agent() call takes provider, instructions, personality weights and a memory configuration with types and a working-memory flag. If your agent is a one-shot classification call, this framework is more machinery than the job needs.
Cognitive Memory and the Eight Mechanisms Behind It
The memory subsystem is the part AgentOS leans on hardest. The README lists eight mechanisms it calls neuroscience-backed, naming Ebbinghaus decay, retrieval-induced forgetting, reconsolidation and source-confidence decay among them. Those names describe behaviour rather than implementation, and the supplied material does not give the decay curve, the reconsolidation trigger, or the storage layout. What can be confirmed is the configuration surface: memory: { types: ['episodic', 'semantic'], working: { enabled: true } } in the quickstart, which implies memory is typed and that working memory is a separate switch. The project also publishes benchmark results on LongMemEval-S and LongMemEval-M, with a linked public bench repository and a leaderboard. Those numbers come from the project's own harness, so treat them as a claim with a methodology attached, not as an independent measurement. The cost figure quoted alongside the S result, $0.0090 per correct answer with gpt-4o, is the more interesting number for anyone budgeting a long-running agent, because memory retrieval that calls a model on every turn is where spend accumulates.
Runtime Tool Forging and the node:vm Sandbox
The distinctive mechanism is tool forging. According to the README, an agent writes a TypeScript function with a Zod schema, an LLM judge approves it, and the function runs in a hardened node:vm sandbox before joining the catalog for the rest of the session. That is a four-step pipeline: generation, schema definition, judge approval, sandboxed execution, then catalog persistence scoped to the session. The judge is itself an LLM, which means the safety boundary is a model decision plus a process boundary, not a static allowlist. The README calls the sandbox hardened but does not enumerate the hardening in the material available here. The demo referenced in the README, examples/emergent-hierarchical-spawning.mjs, shows three agents with distinct HEXACO personalities collaborating on a code review and forging a tool when their static toolkit falls short. Note the scope limit: the forged tool joins the catalog for the rest of the session, so persistence across sessions is not claimed. If you need a tool to survive a restart, you are writing that yourself.
Sessions in 0.10: History Is Now Separate From Memory
The 0.10 release notes describe the change most likely to break existing assumptions. Sessions now carry a lossless conversation transcript covering assistant tool calls, tool results and thinking blocks, independent of the memory subsystem, bounded by default with whole-block eviction past a roughly 120K-token estimate. The README is explicit that memory: false no longer makes a session stateless, and that history: false is the flag for that. Two knobs therefore control two different things: memory governs the cognitive subsystem, history governs the raw transcript. For long tool-driving loops the release adds session.reseed(snapshot) for atomic history replacement with in-flight epoch guarding, session.messages() as checkpoint material, and per-send overrides including toolChoice, requestTimeout, cache, cacheDiagnostics and blockLabel. The reseed example in the README passes a single user message containing a compact resume snapshot. The cache note is worth reading twice: history byte-stability holds for the stored transcript between eviction events, but the wire request can legitimately differ when dynamic memory context or message-mutating hooks inject per-call content. If you rely on provider prompt caching for cost control, that caveat undercuts the assumption that a stable stored history produces a stable cached prefix.
Getting It Running: Install, Configure, Send
The install is one command: npm install @framers/agentos. The quickstart imports agent from the package and constructs one with a provider name, instructions, personality weights and memory settings. The provider field resolves to a default model per provider, and the README notes that a model field can pin a specific one to override that default. When provider is omitted, the framework auto-detects from environment variables, which is convenient in a hosted environment and less so when you want the failure to be loud rather than a silent fallback. Sessions are created by calling tutor.session('student-1') and then awaiting session.send(...). The 0.10 examples add the configuration that matters for long jobs: agent({ model, memory: false, history: false }).session('job-1') for a genuinely stateless session, and agent({ model, history: { maxTokens: 60_000 } }).session('job-2') to lower the transcript bound. The README also mentions that 100+ extensions and 88 skills auto-load at startup, which is a startup cost and a surface area you should measure before assuming a fast cold start.
Where AgentOS Is the Wrong Choice
Two limits stand out. First, the sandbox is node:vm. That module is a JavaScript execution context, not a security boundary against a determined attacker, and the README's description of it as hardened is not backed in the supplied material by a threat model or a list of restrictions. If your threat model includes a hostile model output writing code that reaches the filesystem or the network, node:vm alone should not be the thing standing in the way. Second, the memory system is opinionated. The cognitive mechanisms are built in, and the supplied material does not describe a pluggable interface for swapping in an external vector store or your own retrieval pipeline, even though vector-search is listed among the repository topics. If you already run a retrieval stack and want the framework to use it, that integration path is not documented here. A third, softer limit: the framework is broad. Memory, personality, orchestration, guardrails, voice and provider dispatch all ship together, and the 0.10 session semantics show that these parts interact in ways that changed between minor versions. Pinning a version and reading the migration notes is part of the cost of adoption.
How AgentOS Differs From a Minimal Provider Wrapper
The obvious alternative is a thin provider SDK plus your own state handling. Take the Vercel AI SDK or a raw provider client: you get a streaming call, tool definitions you write by hand, and a message array you manage. The difference is where state lives. In a minimal wrapper, history is your array and memory is whatever you put in the prompt; nothing decays, nothing is forgotten on retrieval, and no tool is ever generated at runtime. AgentOS moves all of that inside the framework: the session owns the transcript, the memory subsystem owns what persists and how it fades, and the tool catalog can grow during a session. That is a real trade. You give up direct control of the prompt and inherit the framework's eviction and cache behaviour, including the byte-stability caveat. You gain a single dispatch interface across 11 providers, which means switching providers is a config change rather than a rewrite. For a short-lived agent, the minimal wrapper wins on clarity. For an agent that runs for hours and hits gaps in its toolkit, AgentOS is solving problems you would otherwise build yourself.
Maintenance, Versioning and the Apache-2.0 Licence
The release cadence visible in the supplied material is fast: three patch releases on 2026-08-07 alone, with v0.10.14 arriving about a minute after the last push timestamp. A pre-1.0 project moving that quickly means the session semantics you build against can shift, and the 0.10 notes already describe behaviour that changed from earlier versions, including the meaning of memory: false. Budget time for reading release notes on upgrade rather than assuming patch versions are inert. The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; it also requires that you preserve notices and state changes. That is a summary of the licence identifier, not legal advice, and if you are embedding the framework in a distributed product you should read the full text. The material does not describe a commercial support offering, an LTS branch, or a deprecation policy, so plan on tracking master or the npm tag yourself. The public bench repository and leaderboard give you a way to reproduce the memory claims on your own hardware, which is the right first step before trusting the published numbers.
Editorial conclusion
Adopt AgentOS if you are building long-running TypeScript agents that need conversation history, memory types such as episodic and semantic, and the option to let an agent write and sandbox a new tool mid-session. Do not adopt it if you want a minimal prompt wrapper, if you cannot run untrusted code inside node:vm, or if you need a memory backend other than the built-in cognitive subsystem. Before committing, verify the 0.10 session semantics yourself: check that memory: false with history: false is genuinely stateless, confirm the default ~120K-token eviction threshold and the history.maxTokens override behave as documented, and read the cache note about byte-stability, since the stored transcript and the wire request can diverge when dynamic memory context or message-mutating hooks inject per-call content.
Community notes