framerslab/agentos

**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 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**, 6 orchestration strategies, guardrails, and voice across **13 LLM providers**; 100+ extensions and 88 skills ship as separate packages with registries that load them.
---
Install
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.
---
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.** 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 ->
---
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: