{"id":50889222,"url":"https://github.com/idanmann10/vivarium-agent","last_synced_at":"2026-06-15T20:01:35.540Z","repository":{"id":357482441,"uuid":"1234979587","full_name":"idanmann10/vivarium-agent","owner":"idanmann10","description":"Local-first agent runtime with memory, Dream consolidation, world retrieval, CLI, daemon, and live-readiness gates.","archived":false,"fork":false,"pushed_at":"2026-05-20T17:34:45.000Z","size":1853,"stargazers_count":1,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T19:14:43.068Z","etag":null,"topics":["agent-runtime","ai-agents","bun","local-first","mcp","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/idanmann10/vivarium-agent","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/idanmann10.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-10T22:10:14.000Z","updated_at":"2026-05-14T23:15:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/idanmann10/vivarium-agent","commit_stats":null,"previous_names":["idanmann10/vivarium-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/idanmann10/vivarium-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idanmann10%2Fvivarium-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idanmann10%2Fvivarium-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idanmann10%2Fvivarium-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idanmann10%2Fvivarium-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/idanmann10","download_url":"https://codeload.github.com/idanmann10/vivarium-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/idanmann10%2Fvivarium-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34377983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-runtime","ai-agents","bun","local-first","mcp","typescript"],"created_at":"2026-06-15T20:01:33.144Z","updated_at":"2026-06-15T20:01:35.534Z","avatar_url":"https://github.com/idanmann10.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vivarium Agent\n\n[![CI](https://github.com/idanmann10/vivarium-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/idanmann10/vivarium-agent/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n![Runtime: Bun](https://img.shields.io/badge/runtime-Bun-black)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)\n![Local first](https://img.shields.io/badge/local--first-memory-2f855a)\n![Live gate](https://img.shields.io/badge/live%20gate-doctor--live-805ad5)\n\nHermes-shaped local-first agent runtime: memory, tools, providers, Dream consolidation, world retrieval, and a terminal setup path that tells operators exactly what to do next.\n\nVivarium Agent is the per-user runtime for the Vivarium system. It runs goals through typed primitives, records episodes in local state, retrieves skills and traces from subscribed worlds, consolidates experience through Dream, and exposes local operations through CLI, daemon, and MCP-style surfaces.\n\n```text\n __      __ _____ __      __    _     ____  ___  _   _  __  __\n \\ \\    / /|_   _|\\ \\    / /   / \\   |  _ \\|_ _|| | | ||  \\/  |\n  \\ \\  / /   | |   \\ \\  / /   / _ \\  | |_) || | | | | || |\\/| |\n   \\ \\/ /    | |    \\ \\/ /   / ___ \\ |  _ \u003c | | | |_| || |  | |\n    \\__/    |____|   \\__/   /_/   \\_\\|_| \\_\\___| \\___/ |_|  |_|\n            VIVARIUM // local memory // world culture\n```\n\n## Quick Start: Install in one command\n\nInstall into `~/.vivarium`, clone the canonical world beside the agent, install dependencies, add a `vivarium` command to `~/.local/bin`, and launch guided setup:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/idanmann10/vivarium-agent/main/scripts/install.sh | bash\n```\n\nUse `VIVARIUM_INSTALL_DIR`, `VIVARIUM_WORLD_ROOT`, `VIVARIUM_DOMAIN`, and `VIVARIUM_STATE_PATH` to override the default install layout. Use `VIVARIUM_BIN_DIR` to choose where the `vivarium` command is written. Set `VIVARIUM_AGENT_REF` to pin the checkout to a branch, tag, or commit. The installer infers the non-secret GitHub owner, agent repo, world repo, and canonical world ref from the GitHub repository URLs; set `VIVARIUM_GITHUB_OWNER`, `VIVARIUM_AGENT_REPO_NAME`, `VIVARIUM_WORLD_REPO_NAME`, `VIVARIUM_CANONICAL_WORLD_REF`, and `VIVARIUM_PRIVATE_WORLD_REF` when you need explicit overrides or a private world ref.\n\nOn macOS, add the opt-in LaunchAgent deployment when you want the local daemon\ninstalled and started in the same setup pass:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/idanmann10/vivarium-agent/main/scripts/install.sh | VIVARIUM_DAEMON=launchd bash\n```\n\nThis writes `~/Library/LaunchAgents/com.vivarium.agent.daemon.plist`, starts the daemon with `launchctl`, and prints a `vivarium daemon smoke` command for `http://127.0.0.1:8787/status`.\n\nInteractive terminals use the branded ANSI theme automatically. Set `VIVARIUM_COLOR=always` to force it, `VIVARIUM_COLOR=never` or `NO_COLOR` to disable it, or `FORCE_COLOR=1` when a wrapper strips TTY detection. Set `VIVARIUM_THEME=matrix` or `VIVARIUM_THEME=amber` for alternate ASCII-art palettes.\n\n## Terminal-first setup\n\n`vivarium setup --quick` initializes local state, installs the starter pack, creates `live-readiness.local.env` from the template when it is missing, and prints the next terminal commands as a numbered launch sequence:\n\nAfter installation, reload your shell if needed and run:\n\n```bash\n# [1] Prove the local loop\nvivarium run --goal \"validate local setup\" --state-path .vivarium/state.db\n\n# [2] Prepare live readiness\n# Edit live-readiness.local.env locally. Keep it out of git.\nvivarium setup --env-file live-readiness.local.env --domain coding --world-root ../the-world --state-path .vivarium/state.db\nvivarium setup --env-file live-readiness.local.env --domain coding --world-root ../the-world --state-path .vivarium/state.db --confirm-write\n\n# [3] Inspect configured models\nvivarium model --env-file live-readiness.local.env\n\n# [4] Prepare live evidence\nvivarium live evidence-init --path v1-evidence.json\n\n# [5] Run the readiness gate\nvivarium doctor --live --env-file live-readiness.local.env\n\n# [6] Verify the Mac daemon, when installed with VIVARIUM_DAEMON=launchd\nvivarium daemon smoke --status-url http://127.0.0.1:8787/status\n\n# [7] Review launch handoff\nvivarium launch handoff\n\n# [8] Keep moving\nvivarium status\nvivarium help\nvivarium update\n```\n\nFor a source checkout, run the same setup directly:\n\n```bash\nbun install\nvivarium setup --quick --domain coding --world-root ../the-world --state-path .vivarium/state.db\n```\n\nFilled `live-readiness.local.env` files are ignored by git. Do not commit API keys, credential values, provider secrets, or evidence files that contain private paths or private customer data.\n\nWhen the public repository names are already settled, prefill the non-secret GitHub and world values while creating the env file:\n\n```bash\nvivarium setup \\\n  --quick \\\n  --live-env-path live-readiness.local.env \\\n  --domain coding \\\n  --world-root ../the-world \\\n  --state-path .vivarium/state.db \\\n  --github-owner idanmann10 \\\n  --agent-repo vivarium-agent \\\n  --world-repo vivarium-world \\\n  --canonical-world-ref https://github.com/idanmann10/vivarium-world.git \\\n  --private-world-ref git@github.com:idanmann10/vivarium-world-private.git\n```\n\n## Architecture At A Glance\n\nVivarium keeps the agent brain, hands, session log, and credentials behind explicit interfaces:\n\n```mermaid\nflowchart LR\n  CLI[CLI and daemon] --\u003e Brain[runtime brain]\n  Brain --\u003e Session[(session log and memory)]\n  Brain --\u003e Hands[tools and sandbox hands]\n  Hands --\u003e Credentials[credential boundary]\n  Brain --\u003e World[world subscriptions]\n  World --\u003e Commons[canonical and private worlds]\n```\n\n- The brain is `packages/runtime`: Plan, Predict, Execute, Monitor, Recover, Validate, Reflect, Dream, and orchestration.\n- The session log is `packages/state`: runs, episodes, memory, identity, confidence, and publishable artifacts.\n- The hands are `packages/tools` and `packages/providers`: tool dispatch, provider calls, safety checks, and credential injection.\n- The world boundary is `packages/world`: retrieval, subscriptions, proposals, publication, and GitHub paths.\n\nRead [docs/architecture/managed-agent-model.md](docs/architecture/managed-agent-model.md) for the full brain/hands/session/credential model.\n\n## What grows over time\n\nVivarium is built so an agent gets better by living through work instead of being reprompted by hand:\n\n| Layer | What compounds |\n| --- | --- |\n| Episodic memory | Runs, observations, surprises, validations, and recoveries |\n| Procedural memory | Skills promoted by successful reuse and pruned by evidence |\n| Semantic memory | Facts learned from repeated tool, provider, and workflow behavior |\n| Identity | Dream-generated summary of habits, calibration, and stage |\n| World culture | Public skills, traces, anti-patterns, runs, curricula, and trust signals |\n\n## Production Status\n\nThe local runtime, CLI, daemon, world read paths, Dream candidate generation, safety checks, installer, public docs, and documentation gates are implemented and tested. The full `goal.md` v1 cultural-transmission proof is intentionally gated by `doctor --live`; it still requires real provider keys, an internal API credential, other-agent evidence, canonical-world publication evidence, and a two-week follow-up measurement.\n\nOpen-source production readiness means this repository has public setup, contribution, security, release, and verification paths. It does not mean the live v1 evidence loop is complete.\n\n## Release boundary\n\nUse the local gates to verify implementation health:\n\n```bash\nbun run lint\nbun run knip\nbun run public-release:scan\nbun run typecheck\nbun run test\nbun run build\nbun run format:check\n```\n\nUse `doctor --live` for production evidence. A green local test suite is not a substitute for live provider, credential, GitHub, other-agent, or two-week improvement evidence. Full v1 is only ready when a fresh live doctor returns `ok:true`.\n\n## Repository Layout\n\n- `apps/cli` - command surface for init, run, providers, credentials, world operations, publishing, and `doctor --live`.\n- `apps/daemon` - local runtime host with status, run, Dream, HTTP transport, scheduler, and MCP manifest.\n- `packages/core` - pure types, kernel, math, decision thresholds, and Claude Managed Agents compatibility types.\n- `packages/state` - in-memory and SQLite repositories, migrations, memory systems, confidence buckets, and semantic facts.\n- `packages/runtime` - Plan, Predict, Execute, Monitor, Recover, Validate, Reflect, Dream, attention, and orchestration.\n- `packages/tools` - self-tools, external adapters, credentials, anonymization, and safety pipeline.\n- `packages/providers` - Anthropic, OpenAI, OpenAI-compatible, local provider profiles, and routing.\n- `packages/world` - world retrieval, subscriptions, proposals, visibility routing, and GitHub clients.\n- `packages/eval` - deterministic compounding eval helpers.\n\n## Project Policies\n\n- Security reporting and secret-handling rules: [SECURITY.md](SECURITY.md)\n- Support paths: [SUPPORT.md](SUPPORT.md)\n- Contributor expectations: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n- Contribution workflow: [CONTRIBUTING.md](CONTRIBUTING.md)\n- Release checklist: [RELEASING.md](RELEASING.md)\n- License: [MIT](LICENSE)\n- Documentation index: [docs/README.md](docs/README.md)\n\n## Influences\n\n- Superpowers: process-oriented skills and implementation discipline.\n- GStack: role/command-shaped agent tooling and review surfaces.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidanmann10%2Fvivarium-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fidanmann10%2Fvivarium-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fidanmann10%2Fvivarium-agent/lists"}