@everworker/oneringai

A unified AI agent library with multi-provider support for text generation, image/video generation, audio (TTS/STT), and agentic workflows.

What's new in 1.2.0

OneRingAI 1.2.0 expands the GPT-6 Astra work into a current, capability-checked API layer for all four major vendors.

• OpenAI and Astra: Adds GPT-6.1 Sol, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Cyber, and GPT-Rosalind Research alongside Astra. The Responses integration now preserves ordered text, tool, compaction, and reasoning state through managed tool loops and supports the newest hosted tools. Computer-use screenshot continuations accept either data URLs or uploaded file IDs. GPT-6 sampling controls are validated against the effective reasoning effort. New connector-first wrappers cover Decisions, GPT-Live WebSockets, and custom voice creation.
• Anthropic: Adds Claude Opus 5.5 and Sonnet 5.5 with their distinct adaptive-thinking rules, current server-tool versions, deferred tools, programmatic callers, compaction, and native tool search. Provider-owned blocks and distinct signed-thinking blocks are retained in provider order so tool-search continuations can be replayed faithfully.
• Google: Adds Gemini 3.8 Flash and Live variants, Interactions continuation tokens, file search, computer use, background Live status, custom voices, Gemini 3.8 TTS, and Nano Banana 2.1 image generation. Streaming preserves signed thought state and provider usage across continuations.
• xAI: Adds Grok 4.7, native X search and hosted coding tools, reasoning and cost telemetry, plus Grok Voice Transcribe 2.0 through a dedicated provider.

Model and API access can still be organization- or region-gated by each vendor. Read the Astra and current vendor API guide, the 1.2.0 changelog, and the model registry audit.

Built for coding agents

OneRingAI ships a canonical Agent Guide that gives Codex, Claude Code, and custom coding agents the complete mental model they need to work with the library: connector-first authentication, agents and execution modes, tools, context plugins, memory, multimodal APIs, orchestration, MCP, tenancy, persistence, documentation routing, and validation.

In this repository, AGENTS.md is the shared source of truth and CLAUDE.md directs Claude Code to it. When OneRingAI is installed from npm, both files—plus the public API reference and specialist memory/tool guides—are included in the package. If an agent does not discover the guide automatically, give it this one instruction:

Before writing OneRingAI code, read
node_modules/@everworker/oneringai/AGENTS.md in full. Follow its connector-first
patterns, use only public package exports, and consult the specialist document
it routes you to before guessing an API.

That is enough to orient an agent before asking it to build something:

Now create a TypeScript research agent that uses my named OpenAI connector,
Serper for search, ZenRows for scraping, and the tool catalog. Keep credentials
out of code and add a runnable smoke test.

Custom agents can load the same file into their system/developer context. The guide is deliberately concise enough to load as context while linking to the full User Guide, API reference, connector/tool catalog, memory documentation, and runnable examples when deeper work is required.

Agent Runtime: run complete agents through one API

The preview Agent Runtime is the integration layer for pre-built agent systems—not merely another text-model adapter. It lets an application or workflow select a native OneRingAI agent or an OpenAI Codex SDK agent through the same specification/session/run API while each driver keeps its own agent loop, tools, context, and workspace behavior.

| What the runtime normalizes | Current local-preview behavior | |-----------------------------|--------------------------------| | Drivers | Native OneRingAI agents and the optional Codex TypeScript SDK | | Selection | Agent, model, and model-validated reasoning effort at spec or per-run scope | | Observation | Live messages, vendor-exposed reasoning, and tool/command/file activity when exposed by the selected driver, plus usage and terminal results | | Control | Autonomous, observable runs; approvals and steering are capability-gated and not yet implemented locally | | Safety | Explicit policy, bounded output/events, cancellation cleanup, one writer per workspace, and fail-closed workspace quarantine | | Placement | Trusted local execution today; isolated container/microVM execution is the planned server backend |

The example below assumes an OpenAI connector named openai-main; install @openai/codex-sdk when enabling the optional Codex driver.

import {
  AgentRuntime,
  LocalExecutionBackend,
} from '@everworker/oneringai/agent-runtime';
import { CodexSdkDriver }
  from '@everworker/oneringai/agent-runtime/codex';

const runtime = new AgentRuntime({
  backend: new LocalExecutionBackend({ drivers: [new CodexSdkDriver()] }),
});

const codingAgent = runtime.agent({
  id: 'coding-agent',
  driver: 'openai.codex.sdk',
  connector: 'openai-main',
  model: 'gpt-5.3-codex',
  reasoning: { effort: 'high' },
});

Autonomous does not mean opaque: callers can consume run.events() to render the agent’s ongoing work without pausing it for approval. Unsupported features fail in capability preflight instead of silently degrading.

Start with the detailed Agent Runtime guide, run the local OneRingAI/Codex example, and use the design document for architectural decisions, security boundaries, and the server/App Server/Claude/A2A roadmap.

Meet AMOS: a terminal agent built with OneRingAI

Want to see the library running as a real application? AMOS is the terminal-based AI assistant in this repository, built entirely on OneRingAI.

AMOS turns the library's core capabilities into an interactive CLI: configure named connectors, switch vendors and models without restarting, use guarded filesystem and shell tools, search with Serper, scrape with ZenRows, inspect context usage, and save or resume working sessions.

Explore AMOS, its commands, and local setup →

Memory is a first-class subsystem

OneRingAI includes a complete, standalone MemorySystem—not just chat history and not a thin vector-store wrapper. It models knowledge as typed entities and provenance-aware facts, combines graph traversal with vector search, resolves repeated mentions to stable identities, and turns accumulated observations into evolving profiles. It is substantial enough to be its own package, but ships as part of OneRingAI so agents, connectors, embeddings, permissions, and context injection work together without integration glue.

| Capability | What the memory layer provides | |------------|--------------------------------| | Knowledge model | Entities, atomic and relational facts, typed metadata, aliases, multiple identifiers, confidence, importance, provenance, contextIds, supersession, and archival history | | Retrieval | Ranked recall, semantic search over embedded facts and documents, N-hop graph traversal, related tasks/events, and bitemporal asOf queries | | Ingestion | Plain text, email, and calendar signal adapters; deterministic participant seeding; LLM extraction; entity resolution; and custom source/extractor interfaces | | Learning | Incremental user-profile generation, optional organization profiles, background conversation ingestion, and per-user-per-agent behavior rules | | Storage and scale | Zero-dependency in-memory storage plus Mongo adapters, native $graphLookup, Atlas Vector Search, index helpers, and pluggable IMemoryStore backends | | Security | Required ownership, owner/group/world permissions, optional principal ACLs, storage-level read filtering, write authorization, and LLM-safe scoped tools |

Use it in three ways:

1. Directly through MemorySystem in a server, worker, migration, or any non-agent application.
2. Inside an agent with MemoryPluginNextGen (six read tools and profile injection) plus the optional MemoryWritePluginNextGen (six write tools).
3. As an ingestion pipeline with SignalIngestor or SessionIngestorPluginNextGen, including retrieval-only agents that learn in the background without giving the LLM write access.

Start with the Memory Layer Guide. The specialist docs cover the API, permissions, predicate vocabulary, and signal ingestion.

Context plugins and tools are modular by design

AgentContextNextGen is the runtime composition layer around an agent. Its goal is to let each capability own its instructions, context content, tools, token accounting, compaction behavior, and persisted state while the context manager assembles one coherent model input. Compaction happens once before the LLM call, tool-call/result pairs stay together, and disabled features add no tools or prompt content.

| Context feature | Purpose | |-----------------|---------| | Working memory | External, tiered scratch storage for raw notes, summaries, and findings | | In-context memory | Small high-value state kept directly in the prompt—no retrieval call required | | Self-learning memory | Profiles, graph/vector retrieval, document search, and optional controlled writes through memory_* tools | | Tool catalog | Lets agents discover and load only the tool categories needed for the current task | | Shared workspace | Versioned coordination board for multi-agent teams | | Persistent instructions / user info | Backward-compatible stores; new applications should generally prefer the self-learning memory system |

Tools reach an agent from four explicit sources: application-supplied ToolFunctions, the 39 generated built-ins, feature plugins (store_*, memory_*, catalog tools, and others), and connector-generated tools. ConnectorTools.for(name) always adds a protected authenticated API tool when the connector has a baseURL, then adds a specialized pack where OneRingAI has one—for example Slack, GitHub, Microsoft, Google Workspace, Telegram, Twilio, Zoom, web search/scraping, and AI media connectors. Generated names are connector-prefixed, so multiple accounts and vendors can coexist safely.

See the Connector & Tool Catalog for the complete 50-template matrix, every first-party specialized pack, and discovery APIs. The Context Management guide covers plugin lifecycle, stores, compaction, persistence, and custom plugins.

Table of Contents

• What's new in 1.2.0
• Built for coding agents
• Agent Runtime: run complete agents through one API
• Meet AMOS: a terminal agent built with OneRingAI
• Memory is a first-class subsystem
• Context plugins and tools are modular by design
• Features
• Quick Start — Installation, basic usage, tools, vision, audio, images, video, search, scraping
• Supported Providers
• Key Features
  • 1. Agent with Plugins
  • 2. Dynamic Tool Management
  • 3. Tool Execution Plugins
  • 4. Tool Permissions
  • 5. Session Persistence
  • Storage Registry
  • 6. Working Memory
  • 7. Research with Search Tools
  • 8. Context Management
  • 9. InContextMemory
  • 10. Persistent Instructions
  • 11. User Info
  • Self-Learning Memory — plugin + tools — MemoryPluginNextGen + MemoryWritePluginNextGen with 12 memory_* LLM tools (6 read incl. memory_search_documents + 6 write incl. memory_set_agent_rule)
  • 12. Direct LLM Access
  • Advanced Inference — Prompt caching, async batches, provider-hosted tools, telemetry, and data policy
  • 13. Audio Capabilities
  • Embeddings — Multi-vendor text and multimodal embeddings with MRL dimension control
  • 14. Model Registry
  • 15. Streaming
  • 16. OAuth for External APIs
  • 17. Developer Tools
  • 18. Custom Tool Generation — Agents create, test, and persist their own tools
  • 19. Desktop Automation Tools — Screenshot, mouse, keyboard, window control for computer use agents
  • 20. Document Reader — PDF, DOCX, XLSX, PPTX, CSV, HTML, images
  • 21. Routine Execution — Multi-step workflows with task dependencies, validation, and memory bridging
  • 22. External API Integration — Scoped Registry, Vendor Templates, Tool Discovery
  • 23. Microsoft Graph Connector Tools — Email, calendar, meetings, and Teams transcripts
  • 24. Tool Catalog — Dynamic discovery and loading for large tool sets
  • 25. Async (Non-Blocking) Tools — Background tool execution with auto-continuation
  • 26. Long-Running Sessions (Suspend/Resume) — Suspend agent loops waiting for external input, resume days later
  • 27. Agent Registry — Global tracking, deep inspection, parent/child hierarchy, event fan-in, external control
  • 28. Agent Orchestrator — Multi-agent teams with shared workspace, delegation, and async execution
  • 29. Telegram Connector Tools — Bot API tools for messaging, updates, and webhooks
  • 30. Twilio Connector Tools — SMS and WhatsApp messaging tools
  • 31. Google Workspace Connector Tools — Gmail, Calendar, Meet, and Drive tools
  • 32. Zoom Connector Tools — Meeting management and transcripts
  • 33. Unified Calendar — Cross-provider meeting slot finder (Google + Microsoft)
  • 34. Multi-Account Connectors — Multiple accounts per vendor with automatic routing
  • 35. Integration Testing — Reusable test suites for connector tools
  • 36. Instruction Templates — {{DATE}}, {{AGENT_ID}}, custom {{COMMAND:arg}} with extensible registry
• MCP Integration
• Documentation
• Examples
• Development
• Architecture
• Troubleshooting
• Contributing
• License

Documentation

Start here if you're looking for detailed docs or the full API reference.

| Document | Description | |----------|-------------| | Agent Guide | Canonical context file for Codex, Claude Code, and custom coding agents: architecture, recipes, capability routing, safety invariants, and documentation map | | Agent Runtime Guide | Detailed usage guide for interchangeable OneRingAI/Codex agents, model and reasoning controls, live observation, capabilities, policy, lifecycle, and cleanup | | Agent Runtime Design | Implemented local preview for OneRingAI and Codex SDK agents: generic model/reasoning controls, live observable autonomous runs, capabilities, policy, and the isolated-server roadmap | | User Guide | Comprehensive guide covering every feature with examples — connectors, agents, context, plugins, audio, video, search, MCP, OAuth, and more | | API Reference | Auto-generated reference for all public exports — classes, interfaces, types, and functions with signatures | | Memory Layer Guide | Standalone entity/fact memory system: graph and vector retrieval, ingestion, resolution, profiles, adapters, scaling, and agent integration | | Memory API & Security | Complete MemorySystem API, with dedicated permissions, predicates, and signals guides | | Connector & Tool Catalog | All 50 connector templates, generic authenticated API behavior, specialized tool packs, built-ins, plugin tools, and discovery APIs | | Runnable Examples | Every example program, what it demonstrates, required credentials, side effects, and exact run command | | 1.0.0 Upgrade Guide | Breaking changes, compatibility guarantees, migration checklist, and before/after examples | | Model Registry Audit | Vendor-by-vendor gaps, implemented status, model snapshot, API boundaries, and official sources | | CHANGELOG | Full 1.0.0 release notes, breaking changes, validation, and version history |

Tutorial / Architecture Series

Part 0. One Lib to Rule Them All: Why We Built OneRingAI: introduction and architecture overview

Part 1. Your AI Agent Forgets Everything. Here’s How We Fixed It.: context management plugins

YOUetal

Showcasing another amazing "built with oneringai": "no saas" agentic business team

Features

• ✨ Unified API - One interface for 12 AI providers (OpenAI, Anthropic, Google, Vertex, Groq, Together, Perplexity, Grok, DeepSeek, Mistral, Ollama, Custom)
• 🧩 Agent Runtime preview - Plug-compatible OneRingAI/Codex agent drivers with model and thinking selection, live reasoning/activity events, and capability-gated future interaction
• 🔑 Connector-First Architecture - Single auth system with support for multiple keys per vendor
• 📊 Model Registry v2 - Lifecycle, aliases, endpoints, official sources, and modality-aware pricing for current text/realtime models plus dedicated image, video, voice, STT, and embedding registries
• 🎤 Audio Capabilities - Text-to-Speech and Speech-to-Text with OpenAI, Google, and xAI, including xAI WebSocket streaming
• ☎️ OpenAI Realtime API - GA voice agents, live transcription, and speech translation over WebSocket/WebRTC, plus SIP call control, tools, VAD, and Twilio bridging
• 🧭 GPT-6 Astra Responses extensions - Async tools, WebSocket steering, persistent reasoning/compaction state, safety alerts, Decisions, GPT-Live, and custom voices
• 📞 xAI Voice Agent API - JSON or binary audio, browser credentials, conversation resumption, reasoning controls, and SIP refer/hangup
• 🖼️ Image Generation - GPT Image 2.5 Sunburst/Flare, Gemini Nano Banana 2.1, Imagen, and Grok Imagine generation/editing
• 🎬 Video Generation - Callable OpenAI Sora 2 (with published retirement metadata), Google Veo/Omni, and Grok Imagine Video 1.5
• 🔢 Embeddings - Text and multimodal embedding generation, including Gemini Embedding 2 for text, image, audio, video, and documents
• 🔍 Web Search - Connector-based search with Serper, Brave, Tavily, and RapidAPI providers
• 🔌 NextGen Context - Clean, plugin-based context management with AgentContextNextGen
• 🎛️ Dynamic Tool Management - Enable/disable tools at runtime, namespaces, priority-based selection
• 🔌 Tool Execution Plugins - Pluggable pipeline for logging, analytics, UI updates, custom behavior
• 💾 Session Persistence - Save and resume conversations with full state restoration
• ⏸️ Long-Running Sessions - Suspend agent loops via SuspendSignal, resume hours/days later with Agent.hydrate()
• 👤 Multi-User Support - Set userId once, flows automatically to all tool executions and session metadata
• 🔒 Auth Identities - Restrict agents to specific connectors (and accounts), composable with access policies
• 🤖 Universal Agent - ⚠️ Deprecated - Use Agent with plugins instead
• 🤖 Task Agents - ⚠️ Deprecated - Use Agent with WorkingMemoryPluginNextGen
• 🔬 Research Agent - ⚠️ Deprecated - Use Agent with search tools
• 🎯 Context Management - Algorithmic compaction with tool-result-to-memory offloading
• 📌 InContextMemory - Live key-value storage directly in LLM context with optional UI display (showInUI)
• 📝 Persistent Instructions - ⚠️ Deprecated in favour of MemoryPluginNextGen (self-learning memory). Still works unchanged.
• 👤 User Info Plugin - ⚠️ Deprecated in favour of MemoryPluginNextGen. Still works unchanged.
• 🧠 Self-Learning Memory - MemoryPluginNextGen + MemoryWritePluginNextGen + 12 memory_* tools — brain-like entity/fact store with three-principal permissions, semantic search, graph queries, LLM-synthesised profiles that evolve from observations, user-driven behavior rules, optional background ingestion via SessionIngestorPluginNextGen
• 🛠️ Agentic Workflows - Built-in tool calling and multi-turn conversations
• 🔧 Developer Tools - Filesystem and shell tools for coding assistants (read, write, edit, grep, glob, bash)
• 🧰 Custom Tool Generation - Let agents create, test, and persist their own reusable tools at runtime — complete meta-tool system with VM sandbox
• 🖥️ Desktop Automation - OS-level computer use — screenshot, mouse, keyboard, and window control for vision-driven agent loops
• 📄 Document Reader - Universal file-to-text converter — PDF, DOCX, XLSX, PPTX, CSV, HTML, images auto-converted to markdown
• 🔌 MCP Integration - Model Context Protocol client for seamless tool discovery from local and remote servers
• 👁️ Vision Support - Analyze images with AI across all providers
• 📋 Clipboard Integration - Paste screenshots directly (like Claude Code!)
• 🔐 Scoped Connector Registry - Pluggable access control for multi-tenant connector isolation
• 💾 StorageRegistry - Centralized storage configuration — swap all backends (sessions, media, custom tools, etc.) with one configure() call
• 🔐 OAuth 2.0 - Full OAuth support for external APIs with encrypted token storage
• 📦 Vendor Templates - Pre-configured auth templates for 50 services (GitHub, Slack, Stripe, etc.)
• 📧 Microsoft Graph Tools - Email, calendar, meetings, and Teams transcripts via Microsoft Graph API
• 🔁 Routine Execution - Multi-step workflows with task dependencies, LLM validation, retry logic, and memory bridging between tasks
• 📊 Execution Recording - Persist full routine execution history with createExecutionRecorder() — replaces manual hook wiring
• ⏰ Scheduling & Triggers - SimpleScheduler for interval/one-time schedules, EventEmitterTrigger for webhook/queue-driven execution
• 📦 Tool Catalog - Dynamic tool loading/unloading — agents discover and load only the categories they need at runtime
• Async Tools - Non-blocking tool execution — long-running tools run in background while the agent continues reasoning, with auto-continuation when results arrive
• 📡 Agent Registry - Global tracking of all active agents — deep inspection, parent/child hierarchy, event fan-in, external control
• 📱 Telegram Tools - 6 Telegram Bot API tools — send messages/photos, get updates, webhooks, chat info
• 📞 Twilio Tools - 4 Twilio tools — SMS, WhatsApp messaging, message listing and details
• 📧 Google Workspace Tools - 11 tools for Gmail, Calendar, Meet transcripts, and Drive (read, search, list files)
• 🎥 Zoom Tools - 3 Zoom tools — create/update meetings, get cloud recording transcripts
• 📅 Unified Calendar - Cross-provider meeting slot finder aggregating Google + Microsoft calendars
• 👥 Multi-Account Connectors - Multiple accounts per vendor (e.g., work + personal) with automatic routing
• 🧪 Integration Testing - Reusable test suite framework for connector tools with 10 built-in suites
• 📝 Instruction Templates - {{DATE}}, {{AGENT_ID}}, {{RANDOM:1:10}} and custom {{COMMAND:arg}} in agent instructions — extensible registry with async support
• 🔄 Streaming - Real-time responses with event streams
• ⚡ Advanced Inference - Provider-aware prompt caching, asynchronous text batches, provider-hosted tools, detailed usage telemetry, and explicit data-handling policy
• 📝 TypeScript - Full type safety and IntelliSense support

Multi-User Support: Set userId once on an agent and it automatically flows to all tool executions, OAuth token retrieval, session metadata, and connector scoping. Combine with identities and access policies for complete multi-tenant isolation. See Multi-User Support and Auth Identities in the User Guide.

Quick Start

Installation

npm install @everworker/oneringai

Basic Usage

import { Connector, Agent, Vendor } from '@everworker/oneringai';

// 1. Create a connector (authentication)
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// 2. Create an agent
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-5.6-terra',
});

// 3. Run
const response = await agent.run('What is the capital of France?');
console.log(response.output_text);
// Output: "The capital of France is Paris."

With Tools

import { ToolFunction } from '@everworker/oneringai';

const weatherTool: ToolFunction = {
  definition: {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get current weather',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string' },
        },
        required: ['location'],
      },
    },
  },
  execute: async (args) => {
    return { temp: 72, location: args.location };
  },
};

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-5.6-terra',
  tools: [weatherTool],
});

await agent.run('What is the weather in Paris?');

Vision

import { createMessageWithImages } from '@everworker/oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-5.6-terra',
});

const response = await agent.run(
  createMessageWithImages('What is in this image?', ['./photo.jpg'])
);

Audio

import { TextToSpeech, SpeechToText } from '@everworker/oneringai';

// Text-to-Speech — built-in voice
const tts = TextToSpeech.create({
  connector: 'openai',
  model: 'tts-1-hd',
  voice: 'nova', // alloy | ash | ballad | coral | echo | fable | onyx | nova | sage | shimmer | verse | marin | cedar
});

await tts.toFile('Hello, world!', './output.mp3');

// Text-to-Speech — custom voice (OpenAI). Pass the `voice_…` id you got
// when registering the voice in the OpenAI dashboard; the SDK call is
// handled automatically.
const customTts = TextToSpeech.create({
  connector: 'openai',
  model: 'gpt-4o-mini-tts',
  voice: 'voice_1234abcd',
});
await customTts.toFile('Spoken in your bespoke voice.', './brand.mp3');

// Speech-to-Text
const stt = SpeechToText.create({
  connector: 'openai',
  model: 'gpt-transcribe',
});

const result = await stt.transcribeFile('./audio.mp3');
console.log(result.text);

// Headerless raw telephony PCM must identify its wire format.
const phoneResult = await stt.transcribe(pcm16le8kBuffer, {
  encoding: 'pcm',
  sampleRate: 8000,
});

Image Generation

import { ImageGeneration } from '@everworker/oneringai';

// OpenAI GPT Image
const imageGen = ImageGeneration.create({ connector: 'openai' });

const result = await imageGen.generate({
  prompt: 'A futuristic city at sunset',
  model: 'gpt-image-2.5-sunburst',
  size: '1024x1024',
  quality: 'high',
});

// Save to file
const buffer = Buffer.from(result.data[0].b64_json!, 'base64');
await fs.writeFile('./output.png', buffer);

// Google Gemini native image
const googleGen = ImageGeneration.create({ connector: 'google' });

const googleResult = await googleGen.generate({
  prompt: 'A colorful butterfly in a garden',
  model: 'gemini-nano-banana-2.1',
  size: '2048x2048',
  aspectRatio: '16:9',
  n: 2,
});

Video Generation

import { VideoGeneration } from '@everworker/oneringai';

// OpenAI Sora (deprecated; callable until the Videos API shuts down 2026-09-24)
const videoGen = VideoGeneration.create({ connector: 'openai' });

// Start video generation (async - returns a job)
const job = await videoGen.generate({
  prompt: 'A cinematic shot of a sunrise over mountains',
  model: 'sora-2',
  duration: 8,
  resolution: '1280x720',           // 720x1280 / 1280x720 / 1024x1792 / 1792x1024 (1.4× HD)
});

// Wait for completion
const result = await videoGen.waitForCompletion(job.jobId);

// Download the video
const videoBuffer = await videoGen.download(job.jobId);
await fs.writeFile('./output.mp4', videoBuffer);

// Google Veo
const googleVideo = VideoGeneration.create({ connector: 'google' });

const veoJob = await googleVideo.generate({
  prompt: 'A butterfly flying through a garden',
  model: 'veo-3.1-lite-generate-preview',
  duration: 8,
});

Sora 2/2 Pro are still callable but have published deprecation and retirement metadata. Production pickers should show lifecycle and retirementDate, not infer recommendation from isActive alone. Google Veo/Omni and xAI Grok Imagine Video 1.5 are covered in the User Guide.

Sora: extend, remix, edit (OpenAI only)

The Videos API references completed clips by id — pass the jobId returned by generate(), not a buffer or URL.

// Extend — generate an additional segment after the source clip.
const extension = await videoGen.extend({
  video: job.jobId,           // id of a completed video
  prompt: 'The camera pulls back to reveal a snow-covered valley',
  extendDuration: 8,          // length of the *new* segment, snapped to 4/8/12
});

// Remix — same length, prompt-steered re-generation.
const remix = await videoGen.remix({
  videoId: job.jobId,
  prompt: 'Same composition, but at golden hour',
});

// Edit — apply a prompt-described change to a completed clip.
const edited = await videoGen.edit({
  videoId: job.jobId,
  prompt: 'Add light snowfall throughout',
});

Sora: reusable characters (OpenAI only)

Upload a reference video to register a character. Note: the unified generate() does not yet apply the character id — reference the character in your prompt and use getCharacter() to look it up.

const character = await videoGen.createCharacter({
  name: 'Hero',
  video: './reference-shot.mp4', // Buffer | local path | URL
});
// → { id: 'char_…', name: 'Hero' }

const scene = await videoGen.generate({
  prompt: 'Hero walks across a windswept beach at dusk',
});

// Look up later
const same = await videoGen.getCharacter(character.id);

Embeddings

import { Embeddings } from '@everworker/oneringai';

// OpenAI embeddings
const embeddings = Embeddings.create({ connector: 'openai' });

const result = await embeddings.embed(['Hello world', 'How are you?'], {
  model: 'text-embedding-3-small',
  dimensions: 512,  // MRL: reduce dimensions for faster search
});

console.log(result.embeddings.length);     // 2
console.log(result.embeddings[0].length);  // 512

// Ollama (local, free)
const local = Embeddings.create({ connector: 'ollama-local' });
const localResult = await local.embed('search query');
// Uses embeddinggemma by default (compact, multilingual, 768 dims)

Document Reader

Read any document format — agents automatically get markdown text from PDFs, Word docs, spreadsheets, and more:

import { Agent, developerTools } from '@everworker/oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: developerTools,
});

// read_file auto-converts binary documents to markdown
await agent.run('Read /path/to/report.pdf and summarize the key findings');
await agent.run('Read /path/to/data.xlsx and describe the trends');
await agent.run('Read /path/to/presentation.pptx and list all slides');

Programmatic usage:

import { DocumentReader, readDocumentAsContent } from '@everworker/oneringai';

// Read any file to markdown pieces
const reader = DocumentReader.create();
const result = await reader.read('/path/to/report.pdf');
console.log(result.pieces); // DocumentPiece[] (text + images)

// One-call conversion to LLM Content[] (for multimodal input)
const content = await readDocumentAsContent('/path/to/slides.pptx', {
  imageFilter: { minWidth: 100, minHeight: 100 },
  imageDetail: 'auto',
});

const response = await agent.run([
  { type: 'input_text', text: 'Analyze this document:' },
  ...content,
]);

Supported Formats:

• Office: DOCX, PPTX, ODT, ODP, ODS, RTF (via officeparser)
• Spreadsheets: XLSX, CSV (via exceljs)
• PDF (via unpdf)
• HTML (via Readability + Turndown)
• Text: TXT, MD, JSON, XML, YAML
• Images: PNG, JPG, GIF, WEBP, SVG (pass-through as base64)

Web Search

Connector-based web search with multiple providers:

import { Connector, SearchProvider, ConnectorTools, Services, Agent, tools } from '@everworker/oneringai';

// Create search connector
Connector.create({
  name: 'serper-main',
  serviceType: Services.Serper,
  auth: { type: 'api_key', apiKey: process.env.SERPER_API_KEY! },
  baseURL: 'https://google.serper.dev',
});

// Option 1: Use SearchProvider directly
const search = SearchProvider.create({ connector: 'serper-main' });
const results = await search.search('latest AI developments 2026', {
  numResults: 10,
  country: 'us',
  language: 'en',
});

// Option 2: Use with Agent via ConnectorTools
const searchTools = ConnectorTools.for('serper-main');

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [...searchTools, tools.webFetch],
});

await agent.run('Search for quantum computing news and summarize');

Supported Search Providers:

• Serper - Google search via Serper.dev (2,500 free queries)
• Brave - Independent search index (privacy-focused)
• Tavily - AI-optimized search with summaries
• RapidAPI - Real-time web search (various pricing)

Web Scraping

Enterprise web scraping with automatic fallback and bot protection bypass:

import { Connector, ScrapeProvider, ConnectorTools, Services, Agent, tools } from '@everworker/oneringai';

// Create ZenRows connector for bot-protected sites
Connector.create({
  name: 'zenrows',
  serviceType: Services.Zenrows,
  auth: { type: 'api_key', apiKey: process.env.ZENROWS_API_KEY! },
  baseURL: 'https://api.zenrows.com/v1',
});

// Option 1: Use ScrapeProvider directly
const scraper = ScrapeProvider.create({ connector: 'zenrows' });
const result = await scraper.scrape('https://protected-site.com', {
  includeMarkdown: true,
  vendorOptions: {
    jsRender: true,        // JavaScript rendering
    premiumProxy: true,    // Residential IPs
  },
});

// Option 2: Use web_scrape tool with Agent via ConnectorTools
const scrapeTools = ConnectorTools.for('zenrows');

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [...scrapeTools, tools.webFetch],
});

// web_scrape auto-falls back: native → API
await agent.run('Scrape https://example.com and summarize');

Supported Scrape Providers:

• ZenRows - Enterprise scraping with JS rendering, residential proxies, anti-bot bypass
• Jina Reader - Clean content extraction with AI-powered readability
• Firecrawl - Web scraping with JavaScript rendering
• ScrapingBee - Headless browser scraping with proxy rotation

Supported Providers

| Provider | Text | Vision | TTS | STT | Image | Video | Tools | Context | |----------|------|--------|-----|-----|-------|-------|-------|---------| | OpenAI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 1.05M | | Anthropic (Claude) | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | 1M | | Google (Gemini) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 1M | | Google Vertex AI | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | 1M | | Grok (xAI) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 1M | | Groq | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | 128K | | Together AI | ✅ | Some | ❌ | ❌ | ❌ | ❌ | ✅ | 128K | | DeepSeek | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | 1M | | Mistral | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | 32K | | Perplexity | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | 128K | | Ollama | ✅ | Varies | ❌ | ❌ | ❌ | ❌ | ✅ | Varies | | Custom | ✅ | Varies | ❌ | ❌ | ❌ | ❌ | ✅ | Varies |

DeepSeek has a dedicated adapter rather than the generic OpenAI path. It supports Chat Completions, Responses, streaming, reasoning replay across tool turns, JSON/JSON Schema where the selected transport supports it, model listing, connector-backed FIM/balance access, and first-party native web search. The connector can target the official API or a known hosted endpoint:

import { Agent, Connector, Vendor } from '@everworker/oneringai';

Connector.create({
  name: 'deepseek-openrouter',
  vendor: Vendor.DeepSeek,
  auth: { type: 'api_key', apiKey: process.env.OPENROUTER_API_KEY! },
  options: { deepseekHost: 'openrouter' },
});

const agent = Agent.create({
  connector: 'deepseek-openrouter',
  model: 'deepseek-v4-pro', // mapped to the host's model ID
});

Built-in hosts are official, openrouter, together, fireworks, deepinfra, nvidia-nim, and azure-foundry. Use custom plus an explicit baseURL for another OpenAI-compatible deployment. Host-specific model IDs and limits are resolved separately from the canonical DeepSeek model registry.

Key Features

1. Agent with Plugins

The Agent class is the primary agent type, supporting all features through composable plugins:

import { Agent, createFileContextStorage } from '@everworker/oneringai';

// Create storage for session persistence
const storage = createFileContextStorage('my-assistant');

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  userId: 'user-123',            // Flows to all tool executions automatically
  identities: [                   // Only these connectors visible to tools
    { connector: 'github' },
    { connector: 'slack' },
  ],
  tools: [weatherTool, emailTool],
  context: {
    features: {
      workingMemory: true,      // Store/retrieve data across turns
      inContextMemory: true,    // Key-value pairs directly in context
      persistentInstructions: true,  // Agent instructions that persist to disk
    },
    agentId: 'my-assistant',
    storage,
  },
});

// Run the agent
const response = await agent.run('Check weather and email me the report');
console.log(response.output_text);

// Save session for later
await agent.context.save('session-001');

Features:

• 🔧 Plugin Architecture - Enable/disable features via context.features
• 💾 Session Persistence - Save/load full state with ctx.save() and ctx.load()
• 📝 Working Memory - Store findings with automatic eviction
• 📌 InContextMemory - Key-value pairs visible directly to LLM
• 🔄 Persistent Instructions - Agent instructions that persist across sessions

2. Dynamic Tool Management

Control tools at runtime. AgentContextNextGen is the single source of truth - agent.tools and agent.context.tools are the same ToolManager instance:

import { Agent } from '@everworker/oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [weatherTool, emailTool, databaseTool],
});

// Disable tool temporarily
agent.tools.disable('database_tool');

// Enable later
agent.tools.enable('database_tool');

// UNIFIED ACCESS: Both paths access the same ToolManager
console.log(agent.tools === agent.context.tools);  // true

// Changes via either path are immediately reflected
agent.context.tools.disable('email_tool');
console.log(agent.tools.listEnabled().includes('email_tool'));  // false

// Context-aware selection
const selected = agent.tools.selectForContext({
  mode: 'interactive',
  currentTask: 'send-invoice',
});

// Backward compatible
agent.addTool(newTool);        // Still works!
agent.removeTool('old_tool');  // Still works!

3. Tool Execution Plugins

Extend tool execution with custom behavior through a pluggable pipeline architecture. Add logging, analytics, UI updates, permission prompts, or any custom logic:

import { Agent, LoggingPlugin, type IToolExecutionPlugin } from '@everworker/oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [weatherTool],
});

// Add built-in logging plugin
agent.tools.executionPipeline.use(new LoggingPlugin());

// Create a custom plugin
const analyticsPlugin: IToolExecutionPlugin = {
  name: 'analytics',
  priority: 100,

  async beforeExecute(ctx) {
    console.log(`Starting ${ctx.toolName}`);
  },

  async afterExecute(ctx, result) {
    const duration = Date.now() - ctx.startTime;
    trackToolUsage(ctx.toolName, duration);
    return result; // Must return result (can transform it)
  },

  async onError(ctx, error) {
    reportError(ctx.toolName, error);
    return undefined; // Let error propagate (or return value to recover)
  },
};

agent.tools.executionPipeline.use(analyticsPlugin);

Plugin Lifecycle:

1. beforeExecute - Modify args, abort execution, or pass through
2. Tool execution
3. afterExecute - Transform results (runs in reverse priority order)
4. onError - Handle/recover from errors

Plugin Context (PluginExecutionContext):

interface PluginExecutionContext {
  toolName: string;           // Name of the tool being executed
  args: unknown;              // Original arguments (read-only)
  mutableArgs: unknown;       // Modifiable arguments
  metadata: Map<string, unknown>; // Share data between plugins
  startTime: number;          // Execution start timestamp
  tool: ToolFunction;         // The tool being executed
  executionId: string;        // Unique ID for this execution
}

Built-in Plugins:

• LoggingPlugin - Logs tool execution with timing and result summaries

Pipeline Management:

// Add plugin
agent.tools.executionPipeline.use(myPlugin);

// Remove plugin
agent.tools.executionPipeline.remove('plugin-name');

// Check if registered
agent.tools.executionPipeline.has('plugin-name');

// Get plugin
const plugin = agent.tools.executionPipeline.get('plugin-name');

// List all plugins
const plugins = agent.tools.executionPipeline.list();

4. Tool Permissions

Policy-based permission system with per-user rules, argument inspection, and pluggable storage. Permissions are enforced at the ToolManager pipeline level -- all tool execution paths are gated.

Zero-Config (Backward Compatible)

Existing code works unchanged. Tools that declare scope: 'always' (including the built-in read-only filesystem tools) execute immediately. Tools declaring 'session' or 'once' use the approval flow; without an onApprovalRequired callback they are denied rather than silently allowed:

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [readFile, bash],
  permissions: {
    onApprovalRequired: async (ctx) => showApprovalDialog(ctx),
  },
});

// read_file executes immediately (in DEFAULT_ALLOWLIST)
// bash triggers approval flow (write/shell tools require approval by default)

Per-User Permission Rules

User rules have the highest priority -- they override all built-in policies. Rules support argument inspection with conditions:

import { PermissionPolicyManager } from '@everworker/oneringai';

const manager = new PermissionPolicyManager();

// Allow bash, but only in the project directory
await manager.userRules.addRule({
  id: '1', toolName: 'bash', action: 'allow', enabled: true,
  createdBy: 'user', createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
  conditions: [{ argName: 'command', operator: 'not_contains', value: 'rm -rf' }],
});

// Block all web tools unconditionally
await manager.userRules.addRule({
  id: '2', toolName: 'web_fetch', action: 'deny', enabled: true, unconditional: true,
  createdBy: 'admin', createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
});

Condition operators: starts_with, not_starts_with, contains, not_contains, equals, not_equals, matches (regex), not_matches.

Policy Model

OneRingAI evaluates composable policies in priority order (deny short-circuits). The package root exports IPermissionPolicy, PermissionPolicyManager, user-rule storage, and the legacy-compatible allowlist/blocklist configuration. The source tree also contains the following internal policy implementations:

| Policy | Description | |--------|-------------| | AllowlistPolicy | Auto-allow tools in the allowlist (read-only, memory, catalog) | | BlocklistPolicy | Hard-block tools in the blocklist (no approval possible) | | SessionApprovalPolicy | Cache approvals per-session with optional argument-scoped keys | | PathRestrictionPolicy | Restrict file tools to allowed directory roots | | BashFilterPolicy | Block/flag dangerous shell commands by pattern | | UrlAllowlistPolicy | Restrict web tools to allowed URL domains | | RolePolicy | Role-based access control (map user roles to tool permissions) | | RateLimitPolicy | Limit tool invocations per time window |

The concrete classes in that table are not package-root exports in 1.0.0. Use the public allowlist/blocklist options, or implement IPermissionPolicy:

import type { IPermissionPolicy } from '@everworker/oneringai';

const noPrivilegedShell: IPermissionPolicy = {
  name: 'app:no-privileged-shell',
  priority: 50,
  evaluate(ctx) {
    const command = String(ctx.args.command ?? '');
    return ctx.toolName === 'bash' && /\b(?:sudo|rm\s+-rf)\b/.test(command)
      ? {
          verdict: 'deny',
          reason: 'Privileged and recursive-delete commands are blocked',
          policyName: 'app:no-privileged-shell',
        }
      : {
          verdict: 'abstain',
          reason: 'Not applicable',
          policyName: 'app:no-privileged-shell',
        };
  },
};

const agent = Agent.create({
  connector: 'openai', model: 'gpt-4.1',
  permissions: {
    policies: [noPrivilegedShell],
  },
});

Approval Dialog Integration

When a tool needs approval, the onApprovalRequired callback fires. Return a createRule to persist the decision:

const agent = Agent.create({
  connector: 'openai', model: 'gpt-4.1',
  permissions: {
    onApprovalRequired: async (ctx) => {
      const userChoice = await showApprovalDialog(ctx.toolName, ctx.args);

      return {
        approved: userChoice.allow,
        // Persist as a user rule so it won't ask again
        createRule: userChoice.remember ? {
          description: `Auto-allow ${ctx.toolName}`,
          conditions: [{ argName: 'path', operator: 'starts_with', value: '/workspace' }],
        } : undefined,
      };
    },
  },
});

Tool Self-Declaration

Tool authors declare permission defaults on the tool definition. App developers can override at registration:

const myTool: ToolFunction = {
  definition: { type: 'function', function: { name: 'deploy', description: '...', parameters: {} } },
  execute: async (args) => { /* ... */ },
  // Author-declared defaults
  permission: {
    scope: 'once',
    riskLevel: 'high',
    approvalMessage: 'This will deploy to production',
    sensitiveArgs: ['environment', 'version'],
  },
};

// App developer can override at registration
agent.tools.register(myTool, {
  permission: { scope: 'session' },  // Relax to session-level approval
});

For complete documentation, see the User Guide.

5. Session Persistence

Save and resume full context state including conversation history and plugin states:

import { AgentContextNextGen, createFileContextStorage } from '@everworker/oneringai';

// Create storage for the agent
const storage = createFileContextStorage('my-assistant');

// Create context with storage
const ctx = AgentContextNextGen.create({
  model: 'gpt-4.1',
  features: { workingMemory: true },
  storage,
});

// Build up state
ctx.addUserMessage('Remember: my favorite color is blue');
await ctx.memory?.store('user_color', 'User favorite color', 'blue');

// Save session with metadata
await ctx.save('session-001', { title: 'User Preferences' });

// Later... load session
const ctx2 = AgentContextNextGen.create({ model: 'gpt-4.1', storage });
const loaded = await ctx2.load('session-001');

if (loaded) {
  // Full state restored: conversation, plugin states, etc.
  const color = await ctx2.memory?.retrieve('user_color');
  console.log(color); // 'blue'
}

What's Persisted:

• Complete conversation history
• All plugin states (WorkingMemory entries, InContextMemory, etc.)
• System prompt

Storage Location: ~/.oneringai/agents/<agentId>/sessions/<sessionId>.json

Storage Registry

Swap all storage backends (sessions, media, custom tools, OAuth tokens, etc.) with a single configure() call at init time. No breaking changes — all existing APIs continue to work.

import { StorageRegistry } from '@everworker/oneringai';

StorageRegistry.configure({
  media: new S3MediaStorage(),
  oauthTokens: new EncryptedFileTokenStorage(),
  // Context-aware factories — optional StorageContext for multi-tenant partitioning
  customTools: (ctx) => new MongoCustomToolStorage(ctx?.userId),
  sessions: (agentId, ctx) => new RedisContextStorage(agentId, ctx?.tenantId),
  persistentInstructions: (agentId, ctx) => new DBInstructionsStorage(agentId, ctx?.userId),
  workingMemory: (ctx) => new RedisMemoryStorage(ctx?.tenantId),
  routineDefinitions: (ctx) => new MongoRoutineStorage(ctx?.userId),
});

// All agents and tools automatically use these backends
const agent = Agent.create({ connector: 'openai', model: 'gpt-4.1' });

Resolution order: explicit constructor param > StorageRegistry > file-based default.

Multi-tenant: Factories receive an optional StorageContext (opaque, like ConnectorAccessContext). Set via StorageRegistry.setContext({ userId, tenantId }) — auto-forwarded to all factory calls for per-user/per-tenant storage partitioning.

See the User Guide for full documentation.

6. Working Memory

Use the WorkingMemoryPluginNextGen for agents that need to store and retrieve data:

import { Agent } from '@everworker/oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [weatherTool, emailTool],
  context: {
    features: { workingMemory: true },
  },
});

// Agent now has unified store_get, store_set, store_delete, store_list, store_action tools
await agent.run('Check weather for SF and remember the result');

Features:

• 📝 Working Memory - Store and retrieve data with priority-based eviction
• 🏗️ Hierarchical Memory - Raw → Summary → Findings tiers for research tasks
• 🧠 Context Management - Automatic handling of context limits
• 💾 Session Persistence - Save/load via ctx.save() and ctx.load()

7. Research with Search Tools

Use Agent with search tools and WorkingMemoryPluginNextGen for research workflows:

import { Agent, ConnectorTools, Connector, Services, tools } from '@everworker/oneringai';

// Setup search connector
Connector.create({
  name: 'serper-main',
  serviceType: Services.Serper,
  auth: { type: 'api_key', apiKey: process.env.SERPER_API_KEY! },
  baseURL: 'https://google.serper.dev',
});

// Create agent with search and memory
const searchTools = ConnectorTools.for('serper-main');

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [...searchTools, tools.webFetch],
  context: {
    features: { workingMemory: true },
  },
});

// Agent can search and store findings in memory
await agent.run('Research AI developments in 2026 and store key findings');

Features:

• 🔍 Web Search - SearchProvider with Serper, Brave, Tavily, RapidAPI
• 📝 Working Memory - Store findings with priority-based eviction
• 🏗️ Tiered Memory - Raw → Summary → Findings pattern

8. Context Management

AgentContextNextGen is the modern, plugin-based context manager. It provides clean separation of concerns with composable plugins:

import { Agent, AgentContextNextGen } from '@everworker/oneringai';

// Option 1: Use AgentContextNextGen directly (standalone)
const ctx = AgentContextNextGen.create({
  model: 'gpt-4.1',
  systemPrompt: 'You are a helpful assistant.',
  features: { workingMemory: true, inContextMemory: true },
});

ctx.addUserMessage('What is the weather in Paris?');
const { input, budget } = await ctx.prepare(); // Ready for LLM call

// Option 2: Via Agent.create
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: {
    features: { workingMemory: true },
  },
});

// Agent uses AgentContextNextGen internally
await agent.run('Check the weather');

Feature Configuration

Enable/disable features independently. Disabled features = no associated tools registered:

// Minimal stateless agent (no memory)
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: {
    features: { workingMemory: false }
  }
});

// Full-featured agent with all plugins
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: {
    features: {
      workingMemory: true,
      inContextMemory: true,
      persistentInstructions: true
    },
    agentId: 'my-assistant',  // Required for persistentInstructions
  }
});

Available Features: | Feature | Default | Plugin | Associated Tools | |---------|---------|--------|------------------| | workingMemory | true | WorkingMemoryPluginNextGen | Unified store_* tools (store="notes"). Actions: cleanup_raw, query | | inContextMemory | true | InContextMemoryPluginNextGen | Unified store_* tools (store="whiteboard") | | persistentInstructions | false | PersistentInstructionsPluginNextGen | Unified store_* tools (store="instructions"). Actions: clear | | userInfo | false | UserInfoPluginNextGen | Unified store_* tools (store="user_info") + todo_add/update/remove | | toolCatalog | false | ToolCatalogPluginNextGen | tool_catalog_search/load/unload | | sharedWorkspace | false | SharedWorkspacePluginNextGen | Unified store_* tools (store="workspace"). Actions: log, history, archive, clear | | memory | false | MemoryPluginNextGen | 6 read tools: memory_recall, memory_graph, memory_search, memory_search_documents, memory_find_entity, memory_list_facts. Requires plugins.memory.memory: MemorySystem. | | memoryWrite | false | MemoryWritePluginNextGen | 6 write tools: memory_remember, memory_link, memory_upsert_entity, memory_forget, memory_restore, memory_set_agent_rule. Requires memory: true. |

AgentContextNextGen architecture:

• Plugin-first design - All features are composable plugins
• ToolManager - Tool registration, execution, circuit breakers
• Single system message - All context components combined
• Smart compaction - Happens once, right before LLM call

Compaction strategy:

• algorithmic (default) - Moves large tool results to Working Memory, limits tool pairs, and applies a rolling window after the configured critical threshold is crossed.

Context preparation:

const { input, budget, compacted, compactionLog } = await ctx.prepare();

console.log(budget.totalUsed);           // Total tokens used
console.log(budget.available);           // Remaining tokens
console.log(budget.utilizationPercent);  // Usage percentage

Forced provider-session rollover: automatic compaction is token-triggered; rolloverContext() is an explicit semantic checkpoint for a provider lifetime boundary such as OpenAI Realtime's 60-minute limit:

const result = await agent.rolloverContext({
  preserveRecentTurns: 8, // exact messages, including complete tool pairs
  reason: 'provider-session-expiring',
});

The Agent summarizes the older prefix with a tool-free direct call, replaces it atomically with a continuity brief, leaves plugin state and the append-only history journal untouched, and checkpoints automatically when session storage is configured. It cannot race run(), stream(), async continuation, or an active Realtime execution. A host may provide summarize to use a separate trusted summarizer or proxy. Standalone contexts expose the lower-level ctx.rollover({ summarize, preserveRecentTurns }) API.

9. InContextMemory

Store key-value pairs directly in context for instant LLM access without retrieval calls:

import { AgentContextNextGen } from '@everworker/oneringai';

const ctx = AgentContextNextGen.create({
  model: 'gpt-4.1',
  features: { inContextMemory: true },
  plugins: {
    inContextMemory: { maxEntries: 20 },
  },
});

// Access the plugin
const plugin = ctx.getPlugin('in_context_memory');

// Store data - immediately visible to LLM
plugin.set('current_state', 'Task processing state', { step: 2, status: 'active' });
plugin.set('user_prefs', 'User preferences', { verbose: true }, 'high');

// Store host-owned UI metadata through the direct API
plugin.set('dashboard', 'Progress dashboard', '## Progress\n- [x] Step 1\n- [ ] Step 2', 'normal', true);

// LLM uses unified store tools: store_set("whiteboard", ...), store_get("whiteboard", ...), etc.
// Or access directly via plugin API
const state = plugin.get('current_state');  // { step: 2, status: 'active' }

Key Difference from WorkingMemory:

• WorkingMemory: External storage + index → requires store_get("notes", key) for values
• InContextMemory: Full values in context → instant access, no retrieval needed

UI metadata (showInUI): OneRingAI stores, serializes, and reports this flag, but does not render a sidebar or implement pinning. The built-in store_set schema intentionally does not advertise the field to the LLM; host code can set it through the direct API or expose it deliberately in a custom UI integration. See the User Guide.

Use cases: Session state, user preferences, counters, flags, small accumulated results, live dashboards.

10. Persistent Instructions

Store agent-level custom instructions that persist across sessions on disk:

import { Agent } from '@everworker/oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  context: {
    agentId: 'my-assistant',  // Required for storage path
    features: {
      persistentInstructions: true,
    },
  },
});

// LLM uses unified store tools: store_set("instructions", ...), store_delete("instructions", ...), etc.
// Instructions persist to ~/.oneringai/agents/my-assistant/custom_instructions.json

Key Features:

• 📁 Disk Persistence - Instructions survive process restarts and sessions
• 🔧 LLM-Modifiable - Agent can update its own instructions during execution
• 🔄 Auto-Load - Instructions loaded automatically on agent start
• 🛡️ Never Compacted - Critical instructions always preserved in context

Store Tools (via unified store_* interface):

• store_set("instructions", key, { content }) - Add or update a single instruction by key
• store_delete("instructions", key) - Remove a single instruction by key
• store_list("instructions") - List all instructions with keys and content
• store_action("instructions", "clear", { confirm: true }) - Remove all instructions

Use cases: Agent personality/behavior, user preferences, learned rules, tool usage patterns.

11. User Info

Store user-specific preferences and context that are automatically injected into the LLM system message:

import { Agent } from '@everworker/oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  userId: 'alice',  // Optional — defaults to 'default' user
  context: {
    features: {
      userInfo: true,
    },
  },
});

// LLM uses unified store tools: store_set("user_info", ...), store_get("user_info", ...), etc.
// Data persists to ~/.oneringai/users/alice/user_info.json
// All entries are automatically shown in context — no need to call store_get each turn

Key Features:

• 📁 Disk Persistence - User info survives process restarts and sessions
• 🔄 Auto-Inject - Entries rendered as markdown and included in the system message automatically
• 👥 User-Scoped - Data is per-user, not per-agent — different agents share the same user data
• 🔧 LLM-Modifiable - Agent can update user info during execution

Store Tools (via unified store_* interface):

• store_set("user_info", key, { value, description? }) - Store/update user information
• store_get("user_info", key?) - Retrieve one entry or all entries
• store_delete("user_info", key) - Remove a specific entry
• store_action("user_info", "clear", { confirm: true }) - Clear all entries

TODO Tools (built into the same plugin):

• todo_add - Create a TODO (title, description?, people?, dueDate?, tags?)
• todo_update - Update a TODO (id, plus any fields to change including status: 'done')
• todo_remove - Delete a TODO by id

TODOs are stored alongside user info and rendered in a separate "Current TODOs" checklist in context. The agent proactively suggests creating TODOs when conversation implies action items, reminds about due/overdue items once per day, and auto-cleans completed TODOs after 48 hours.

Use cases: User preferences (theme, language, timezone), user context (role, location), accumulated knowledge about the user, task/TODO tracking with deadlines and people.

⚠️ Deprecated in favour of the Self-Learning Memory plugin below. UserInfoPluginNextGen + PersistentInstructionsPluginNextGen keep working unchanged for existing integrations — no breaking change — but new code should prefer MemoryPluginNextGen.

Self-Learning Memory — plugin + tools

A brain-like, queryable knowledge store built on the memory layer. Two cooperating context plugins + 12 LLM-callable tools turn the agent into a learning system: it bootstraps a person entity for the user (and optionally an organization entity for their group), injects the evolving user profile + any user-given behavior rules into the system message every turn, and exposes memory_* tools so the LLM can read or write the knowledge graph mid-conversation. Observations flow in via memory_remember (LLM-driven) or SessionIngestorPluginNextGen (passive); incremental profile regeneration synthesises them; the next turn sees the updated profile. No manual prompt engineering for user/agent preferences.

import {
  Agent,
  createMemorySystemWithConnectors,
  InMemoryAdapter,
  PredicateRegistry,
} from '@everworker/oneringai';

const predicates = PredicateRegistry.standard().register({
  name: 'prefers',
  description: 'A durable user preference.',
  category: 'preference',
  payloadKind: 'attribute',
  subjectTypes: ['person'],
  lifecycle: 'stable',
});

const memory = createMemorySystemWithConnectors({
  store: new InMemoryAdapter(),