Maniac

The Maniac class registers agents, wires memory stores, and exposes chat, chatStream, resume, and background task APIs.

Maniac is the long-lived application entrypoint. Construct it once, register one or more agents, and call chat / chatStream with a threadId for durable multi-turn conversations.

Construction

import { Maniac, OpenAICompatibleModel } from "@maniac-ai/agents";
import { InMemoryMemory } from "@maniac-ai/agents/memory";

const app = new Maniac({
  model: new OpenAICompatibleModel({ slug: "gpt-4o-mini" }),
  memory: new InMemoryMemory(),
  budget: { max_iterations: 32, max_tokens: 100_000 },
  observationalMemory: { scope: "thread" },
  workingMemory: { enable_update_tool: true },
  backgroundTasks: { enabled: true },
  persistPartialOnError: true
});

Shared defaults

Field	Purpose
`model`	Default model when an agent registration omits `model`
`memory`	Backing store; auto-builds `ConversationStore`, checkpoint store, etc.
`policy`	Permission policy inherited by agents unless overridden
`budget`	Token/cost/wall-clock limits inherited by agents
`observationalMemory`	Cross-turn observation buffer + reflector
`workingMemory`	Mutable doc the agent updates via `remember`
`backgroundTasks`	Enables `BackgroundTaskDispatcher` and `bg_*` tools
`tracerFactory`	Creates a per-run `Tracer` (default: `() => new Tracer()`)

Auto-built stores

When memory is set, Maniac constructs:

conversationStore — required by chat / chatStream
observationStore + observationBuffer — when observationalMemory is configured
workingMemoryStore + workingMemoryRunner — when workingMemory is configured
checkpointStore — for pause/resume unless explicitly null

Pass pre-built store instances to share state across multiple Maniac apps or customize persistence.

Register agents

app.agent({
  id: "support",
  instructions: "You are a helpful support agent.",
  tools: [lookupOrder]
});

// Dynamic instructions
app.agent({
  id: "personalized",
  instructions: (ctx) =>
    `Help user ${ctx.resource_id ?? "guest"}. Query: ${ctx.query}`,
  model: new OpenAICompatibleModel({ slug: "gpt-4o" })
});

instructions accepts a string or an InstructionsBuilder that receives RequestContext (query, agent_id, resource_id, metadata).

Retrieve specs with app.get("support") or app.has("support").

Background tasks

When backgroundTasks.enabled is true, the app exposes app.dispatcher and control helpers:

await app.runUntilIdle(); // drain the dispatcher
await app.enqueueBackground({ agentId: "support", tool: "...", args: {} });

See Background tasks for bg_list, bg_wait, and orchestrator spawn tools.

Lifecycle

Call app.aclose() on shutdown to drain observation and working-memory background updaters and tear down the dispatcher.

Honcho memory

Swap InMemoryMemory for HonchoMemory to use the hosted reasoning layer — Maniac auto-wires HonchoConversationStore and injects ask_about_user:

import { HonchoMemory, Maniac } from "@maniac-ai/agents";

const memory = new HonchoMemory({
  apiKey: process.env.HONCHO_API_KEY!,
  environment: "production"
});
const app = new Maniac({ model, memory });
app.agent({ id: "support", instructions: "Help the user." });

await app.chat("support", "hi", { threadId: "thread-1", resourceId: "user-42" });