tinyagent

A minimal, pluggable autonomous agent library for TypeScript/JavaScript. Ships with a built-in virtual filesystem, dual memory system, AST mutation engine, lifecycle hooks, and a reflection-driven agent loop. Every component is replaceable.

Install

npm install tinyagent

Quick Start

import { TinyAgent, type LLMProvider } from 'tinyagent';

// 1. Implement the LLMProvider interface for your model
const provider: LLMProvider = {
  async generate(history, systemPrompt) {
    const res = await fetch('https://api.example.com/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ messages: history, system: systemPrompt }),
    });
    return res.json(); // must return { reflection, reasoning, commands }
  },
};

// 2. Create an agent
const agent = new TinyAgent({ provider });

// 3. Run it
const history = await agent.run('Create a file called hello.txt with "Hello World" inside it.');
console.log(history);

Execution Modes

// Run to completion
const history = await agent.run('do something');

// Step through one turn at a time
const turn1 = await agent.step('my task');
const turn2 = await agent.step(); // continues same task

// Stream turns as an async iterator
for await (const turn of agent.stream('my task')) {
  console.log(`Turn ${turn.turn}: ${turn.agent.reasoning}`);
  if (turn.finished) break;
}

Key Concepts

• LLMProvider — Bring your own model. Implement one method: generate(history, systemPrompt) → { reflection, reasoning, commands }.
• Commands — CLI-style tools the agent can invoke (ls, read, write, rm, mv, append, mutate, etc.). Register your own or replace the built-ins entirely. eval/spawn are opt-in via createUnsafeCommands().
• VFS — An in-memory virtual filesystem with configurable root path.
• Dual Memory — Voluntary (agent-controlled) and involuntary (automatic context capture) memory stores with optional semantic search, configurable capacity, and similarity threshold.
• Hooks — Lifecycle hooks (beforeLLMCall, afterLLMCall, beforeCommand, afterCommand, onError, onTurnStart, onTurnEnd) for intercepting and modifying agent behavior.
• Symbolic Continuity — On task completion, the agent emits context-sensitive symbols encoding its internal state. A configurable-depth stack of these states is injected into the next run's prompt, giving the agent a warm cognitive start.
• Prompts — Default persona and system prompt are exported and fully customizable.
• Error Classes — Typed errors (AgentRunningError, MaxTurnsExceededError, ProviderError, CommandError) for structured error handling.

Documentation

• Configuration — All config options and runtime API
• Commands — Built-in commands and writing custom ones
• LLM Providers — Implementing providers for different models
• Memory — Memory system and semantic embeddings
• VFS — Virtual filesystem usage
• AST Pipeline — Code mutation engine
• Symbolic Continuity — Persistent internal state across runs
• Hooks — Lifecycle hooks and middleware

Architecture

TinyAgent
├── LLMProvider (pluggable)    — Any LLM backend
├── VirtualFileSystem          — In-memory file operations (ls, read, write, rm, mv, append)
├── AssociativeMemory x2       — Voluntary + Involuntary stores (lexical + semantic)
├── Command Registry           — Built-in + custom commands, runtime register/unregister
├── PipelineEngine             — AST-based code mutations with rollback
├── Hooks                      — Lifecycle interception points
├── Continuity Stack           — Symbolic state persistence across runs
└── Prompt Builder (pluggable) — System prompt generation

Testing

npm test          # run tests once
npm run test:watch  # watch mode

93 tests covering VFS, memory, pipeline, commands, and the full agent lifecycle.

License

MIT