一环AI智能框架

Installation

npm install @everworker/oneringai

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

Quick Start

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-4.1',
});

// 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."

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

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

3. Tool Execution Plugins (NEW)

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();

10b. Self-Learning Memory — plugin + tools

A brain-like, queryable knowledge store built on the memory layer. Two cooperating context plugins + 11 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 } from '@everworker/oneringai';

const memory = createMemorySystemWithConnectors({
  store: new InMemoryAdapter(),                 // or MongoMemoryAdapter for production
  connectors: {
    embedding: { connector: 'openai', model: 'text-embedding-3-small', dimensions: 1536 },
    profile:   { connector: 'anthropic', model: 'claude-sonnet-4-6' },
  },
});

const agent = Agent.create({
  connector: 'anthropic',
  model: 'claude-sonnet-4-6',
  userId: 'alice',                              // REQUIRED — memory's owner invariant
  context: {
    agentId: 'my-assistant',
    features: {
      memory: true,                             // reads: profile injection + 5 retrieval tools
      memoryWrite: true,                        // writes: 6 mutation tools (omit for retrieval-only)
    },
    plugins: {
      memory: {
        memory,
        // groupId: 'team-A',                   // trusted, from your auth layer
        // userProfileInjection: { topFacts: 20, relatedTasks: true },
        // groupBootstrap: { displayName: 'Acme', identifiers: [{ kind: 'domain', value: 'acme.com' }] },
      },
    },
  },
});

await agent.run('Remember I prefer concise answers');
// Agent calls memory_remember({subject:"me", predicate:"prefers", value:"concise answers"})
// Fact stored → profile regen fires in background → next turn sees it in the user profile

Key Features: - 🧠 Self-learning — profiles synthesised from facts via incremental regeneration (prior profile + new facts + invalidated IDs → evolved profile) - 🔐 Three-principal permissions — owner / group / world, enforced at the adapter - 📊 Ranked recall — profile + top facts by confidence × recency × predicateWeight × importance - 🕸️ Graph queries — Mongo native $graphLookup when available, iterative BFS fallback - 🔍 Semantic search — over embedded facts (with Atlas Vector Search at scale) - 🧬 Multi-ID entities — lookup by email / slack_id / github_login / domain / any identifier; upsert auto-merges - 📜 Supersession history — corrections archive predecessors; audit chain preserved via archivedOnly: true - 🪧 User-driven behavior rules — memory_set_agent_rule records "be terse" / "reply in Russian" / "your name is Jason" directives, rendered back into the system message every turn (per-user-per-agent scoped) - 🏢 Optional org bootstrap — when groupBootstrap is set, an organization entity is upserted and rendered as a separate "Your Organization Profile" block alongside the user profile - 🛡️ LLM-safe — groupId fixed by host app (never from tool args); ghost-write protection; contextIds auto-downgrade; numeric limits clamped

12 LLM tools (memory_*), split into two opt-in bundles:

Read (via MemoryPluginNextGen, feature flag memory): - memory_recall(subject, include?) — profile + top facts + optional tiers (documents / semantic / neighbors) - memory_graph(start, direction, maxDepth, predicates?) — N-hop traversal - memory_search(query, topK?, filter?) — semantic text search across facts - memory_search_documents(query, mode?, attachedTo?, role?, limit?) — search long-form documents (type='document') by content. Semantic mode matches contentEmbedding; keyword mode is case-insensitive substring over body + title. - memory_find_entity(by, action? ∈ {find, list}) — lookup or list (read-only) - memory_list_facts(subject, predicate?, archivedOnly?) — structured enumeration

Write (via MemoryWritePluginNextGen, feature flag memoryWrite, requires memory: true): - memory_remember(subject, predicate, value?/objectId?/details?, visibility?) — write a fact (atomic or document) - memory_link(from, predicate, to) — write a relational fact - memory_upsert_entity(type, displayName, identifiers, ...) — create or merge an entity by identifier - memory_forget(factId, replaceWith?) — archive or supersede (rate-limited 10/60s/user) - memory_restore(factId) — un-archive (undo for memory_forget) - memory_set_agent_rule(rule, replaces?) — record a user-specific behavior rule for THIS agent

Enable memory: true alone for retrieval-only agents (and pair with SessionIngestorPluginNextGen for passive background learning); enable both flags for agents that write memory deliberately.

Flexible SubjectRef — every tool accepts any of: entity id, "me", "this_agent", {id}, {identifier: {kind, value}}, {surface: "..."}.

Storage backends: InMemoryAdapter (zero deps, dev/tests), MongoMemoryAdapter + RawMongoCollection (production servers — supports native $graphLookup + Atlas Vector Search via ensureVectorSearchIndexes()), MongoMemoryAdapter + MeteorMongoCollection (Meteor apps — reactive publications). Custom adapters implement IMemoryStore.

See the USER_GUIDE Self-Learning Memory section for the user-guide-level walkthrough, docs/MEMORY_GUIDE.md for the full conceptual model + adapter setup + signal ingestion, docs/MEMORY_API.md for the MemorySystem API reference, and docs/MEMORY_PERMISSIONS.md for the permission model.