auggy

library0.4.4jsnpmunverified

Auggy (Augment-1) is a modular agent runtime written in TypeScript for Bun (≥1.2.0), designed for long-running organizational interface agents with persistent memory. Current stable version is 0.3.1 (npm) with a heading toward 0.4.x. It features pluggable engines (Anthropic, OpenAI, OpenRouter), swappable augments (memory, context, transport, tools), SQLite-first memory with fact extraction, operator escalation, shell execution, budget controls, and YAML-based configuration. Key differentiators: Bun-native, no build step, built-in agent lifecycle management, Railway deploy support, and a 2PC turn-gate capability. Release cadence is irregular; pre-1.0, breaking changes expected.

ai-ml

npm install auggy

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AUGGY

auggy

ai-mljavascriptv0.4.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Auggy

✓ import { Auggy } from 'auggy'

✗ const Auggy = require('auggy')

ESM-only package; CJS require not supported. Bun handles TypeScript directly.

KernelOptions

✓ import type { KernelOptions } from 'auggy/kernel'

✗ import { KernelOptions } from 'auggy'

Use type import from subpath for better tree-shaking and to avoid runtime inclusion.

AgentConfig

✓ import { AgentConfig } from 'auggy/config'

✗ import { AgentConfig } from 'auggy'

AgentConfig is exported from the 'config' subpath, not the main entry.

Creates a minimal Auggy agent with file memory and web transport, then starts it. Shows config structure and instantiation.

import { Auggy } from 'auggy'; import { AgentConfig } from 'auggy/config'; const config: AgentConfig = { id: crypto.randomUUID(), name: 'my-agent', engine: { provider: 'openai', model: 'gpt-4' }, augments: [ { name: 'memory', type: 'fileMemory', options: { source: './memory.txt', mutable: true, priority: 'required', placement: 'system', eviction: 'never' } }, { name: 'web', type: 'webTransport', options: { port: 8080, auth: { type: 'bearer', token: process.env.AUGGY_WEB_TOKEN ?? '' } } } ] }; const agent = new Auggy(config); await agent.start(); console.log('Agent running on port 8080');

Debug

Known issues

breakingauggy requires Bun >=1.2.0 and will not run on Node.js or Deno.

fix

Install Bun (https://bun.sh/install) and use it as the runtime.

affects: >=0.1

breakingPre-1.0 breaking changes occur frequently. Pin exact version or use lockfile.

fix

Pin to exact version (e.g., auggy@0.3.1) in package.json

affects: <1.0

deprecatedThe 'augment' field in YAML was renamed to 'augments' in v0.3.0. Old configs using 'augment' will fail silently.

fix

Rename 'augment' to 'augments' in your agent YAML files.

affects: <0.3.0

gotchaThe auggy CLI global install requires Bun, but 'auggy create' scaffolds TypeScript files referencing 'auggy' as a local dependency. Running 'npm i -g auggy' does not make 'auggy' available in the project's node_modules.

fix

Always run 'bun add auggy@latest' inside the agent directory after scaffolding.

affects: >=0.1

gotchaMemory augments with 'eviction: never' may cause unbounded growth if fact extraction is enabled. Default memory is SQLite, but no automatic retention limit.

fix

Configure eviction policy (e.g., 'lru' or 'ttl') or implement a cleanup cron.

affects: >=0.1

breakingIn v0.3.0, the agent ID format changed from UUID to v7 UUID. Existing databases with old UUIDs must be migrated.

fix

Run migrator script from the GitHub releases page before upgrading.

affects: <0.3.0

Errors

Common errors & fixes

error: Cannot find module 'auggy'

auggy is not installed locally or dependencies are missing (e.g., after cloning without bun install).

fix

Run 'bun install' in the project root or add auggy via 'bun add auggy'.

TypeError: auggy_1.Auggy is not a constructor

CommonJS require was used instead of ESM import. Auggy is an ESM-only package.

fix

Change 'const { Auggy } = require("auggy")' to 'import { Auggy } from "auggy"' and ensure your package.json has '"type": "module"'.

Error: Cannot find module './kernel' imported from auggy/kernel

Using wrong import path; auggy/kernel is not a valid subpath.

fix

Use correct subpath: 'auggy/src/kernel' or import from main entry: 'auggy'.

Error: Unsupported engine - bun must be >=1.2.0

The system has an older version of Bun installed (below 1.2.0).

fix

Update Bun: run 'bun upgrade' or download a newer version from https://bun.sh.

Upgrade

Version history

0.4.4latest on npm

Audit

Dependencies

typescriptoptionalPeer dependency required for type-checking and development

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/looselyorganized/augment-1 ↗

packageauggy ↗

homepagehttps://github.com/looselyorganized/augment-1#readme ↗