{"id":44333,"library":"auggy","title":"auggy — modular agent runtime","description":"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.","status":"active","version":"0.4.4","language":"javascript","source_language":"en","source_url":"https://github.com/looselyorganized/augment-1","tags":["javascript","agent","agents","ai","anthropic","claude","openai","openrouter","llm"],"install":[{"cmd":"npm install auggy","lang":"bash","label":"npm"},{"cmd":"yarn add auggy","lang":"bash","label":"yarn"},{"cmd":"pnpm add auggy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for type-checking and development","package":"typescript","optional":true}],"imports":[{"note":"ESM-only package; CJS require not supported. Bun handles TypeScript directly.","wrong":"const Auggy = require('auggy')","symbol":"Auggy","correct":"import { Auggy } from 'auggy'"},{"note":"Use type import from subpath for better tree-shaking and to avoid runtime inclusion.","wrong":"import { KernelOptions } from 'auggy'","symbol":"KernelOptions","correct":"import type { KernelOptions } from 'auggy/kernel'"},{"note":"AgentConfig is exported from the 'config' subpath, not the main entry.","wrong":"import { AgentConfig } from 'auggy'","symbol":"AgentConfig","correct":"import { AgentConfig } from 'auggy/config'"}],"quickstart":{"code":"import { Auggy } from 'auggy';\nimport { AgentConfig } from 'auggy/config';\n\nconst config: AgentConfig = {\n  id: crypto.randomUUID(),\n  name: 'my-agent',\n  engine: { provider: 'openai', model: 'gpt-4' },\n  augments: [\n    { name: 'memory', type: 'fileMemory', options: { source: './memory.txt', mutable: true, priority: 'required', placement: 'system', eviction: 'never' } },\n    { name: 'web', type: 'webTransport', options: { port: 8080, auth: { type: 'bearer', token: process.env.AUGGY_WEB_TOKEN ?? '' } } }\n  ]\n};\n\nconst agent = new Auggy(config);\nawait agent.start();\nconsole.log('Agent running on port 8080');","lang":"typescript","description":"Creates a minimal Auggy agent with file memory and web transport, then starts it. Shows config structure and instantiation."},"warnings":[{"fix":"Install Bun (https://bun.sh/install) and use it as the runtime.","message":"auggy requires Bun >=1.2.0 and will not run on Node.js or Deno.","severity":"breaking","affected_versions":">=0.1"},{"fix":"Pin to exact version (e.g., auggy@0.3.1) in package.json","message":"Pre-1.0 breaking changes occur frequently. Pin exact version or use lockfile.","severity":"breaking","affected_versions":"<1.0"},{"fix":"Rename 'augment' to 'augments' in your agent YAML files.","message":"The 'augment' field in YAML was renamed to 'augments' in v0.3.0. Old configs using 'augment' will fail silently.","severity":"deprecated","affected_versions":"<0.3.0"},{"fix":"Always run 'bun add auggy@latest' inside the agent directory after scaffolding.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1"},{"fix":"Configure eviction policy (e.g., 'lru' or 'ttl') or implement a cleanup cron.","message":"Memory augments with 'eviction: never' may cause unbounded growth if fact extraction is enabled. Default memory is SQLite, but no automatic retention limit.","severity":"gotcha","affected_versions":">=0.1"},{"fix":"Run migrator script from the GitHub releases page before upgrading.","message":"In v0.3.0, the agent ID format changed from UUID to v7 UUID. Existing databases with old UUIDs must be migrated.","severity":"breaking","affected_versions":"<0.3.0"}],"env_vars":null,"search_vec":"'-1':7 '-1.0':102 '0.3.1':34 '0.4':40 '1.2.0':18 '2pc':92 'agent':3,11,26,84,107,108 'ai':109 'anthrop':46,110 'auggi':1,5 'augment':6,50 'base':71 'break':103 'budget':66 'build':79 'built':82 'built-in':81 'bun':17,76 'bun-nat':75 'cadenc':98 'capabl':96 'chang':104 'claud':111 'configur':72 'context':52 'control':67 'current':30 'deploy':88 'design':19 'differenti':74 'engin':45 'escal':63 'execut':65 'expect':105 'extract':61 'fact':60 'featur':43 'first':57 'gate':95 'head':38 'interfac':25 'irregular':100 'javascript':106 'key':73 'lifecycl':85 'llm':114 'long':22 'long-run':21 'manag':86 'memori':29,51,58 'modular':2,10 'nativ':77 'npm':35 'openai':47,112 'openrout':48,113 'oper':62 'organiz':24 'persist':28 'pluggabl':44 'pre':101 'railway':87 'releas':97 'run':23 'runtim':4,12 'shell':64 'sqlite':56 'sqlite-first':55 'stabl':31 'step':80 'support':89 'swappabl':49 'tool':54 'toward':39 'transport':53 'turn':94 'turn-gat':93 'typescript':15 'version':32 'written':13 'x':41 'yaml':70 'yaml-bas':69","created_at":"2026-06-07T12:49:36.926830+00:00","updated_at":"2026-06-07T12:49:36.926830+00:00","problems":[{"fix":"Run 'bun install' in the project root or add auggy via 'bun add auggy'.","cause":"auggy is not installed locally or dependencies are missing (e.g., after cloning without bun install).","error":"error: Cannot find module 'auggy'"},{"fix":"Change 'const { Auggy } = require(\"auggy\")' to 'import { Auggy } from \"auggy\"' and ensure your package.json has '\"type\": \"module\"'.","cause":"CommonJS require was used instead of ESM import. Auggy is an ESM-only package.","error":"TypeError: auggy_1.Auggy is not a constructor"},{"fix":"Use correct subpath: 'auggy/src/kernel' or import from main entry: 'auggy'.","cause":"Using wrong import path; auggy/kernel is not a valid subpath.","error":"Error: Cannot find module './kernel' imported from auggy/kernel"},{"fix":"Update Bun: run 'bun upgrade' or download a newer version from https://bun.sh.","cause":"The system has an older version of Bun installed (below 1.2.0).","error":"Error: Unsupported engine - bun must be >=1.2.0"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/looselyorganized/augment-1#readme","github":"https://github.com/looselyorganized/augment-1","docs":null,"changelog":null,"pypi":null,"npm":"auggy","openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}