Atlas
kb://agents/openalice-agent-guideactive2026-06-17

OpenAlice Agent Guide — START HERE

openaliceagentsonboardingalice-core

OpenAlice Agent Guide — START HERE

One page on what this repo is, how it's laid out, and how an agent should work in it. (Referenced by Atlas conventions as the entry point. Keep it current.)

What this is

OpenAlice / "Alice" is a Rust monorepo: a companion + autonomous-coding AGI agent. It's an OS-kernel-style architecture — a stable Rust binary substrate whose behavior evolves through data loaded at runtime (prompts, skills, memory), not by recompiling. Self-improvement has two layers: (1) runtime — skills (Voyager), prompt-overlays (Reflexion), memory (crystallization/dossiers), no rebuild; (2) code-level — Alice authors code → PR → gated CI/human review → rebuild (the AGI-coding track, measured on SWE-bench). The binary is the substrate; the evolving "self" is the prompt+skills+memory layer.

Crate map (48 crates in crates/)

Layered: schemas/core/store → domain → binary/test.

  • Foundation: schemas (types), core (paths/utils/test_support), store, config, observability, middleware.
  • Agent brain: agents-soul (persona/sections/prompt assembly — Cat-A protected), agents-memory (30-module memory: curator/scribe/dossier/reflection/crystallization), agents-refs (image/people refs), agents-tools (156 tools), agents-safety (Constitutional Critic, live), agents-rank, prompt-composer (Cat-A SHA256 pinning).
  • AGI track (env-gated, scaffolded): agi-core, agi-safety (Critic scaffold), agi-skills (Voyager loop). Activation = landing the deferred PRs, not a flag flip.
  • Pipeline: alice (binary + connector_bridge 32-stage pipeline), coalesce (per-(chat,sender) lane state), router (LLM routing/fallback), api-handlers (HTTP routes incl. the agentic_loop), api-router.
  • Modules (facades over sub-crates): modules + modules-{ops,connectors,drivers,hands,intelligence}.
  • Surfaces: tui, openalice-cockpit, openalice-delivery, voice-wake, lsp, plugin-host, sandbox, transport.
  • Storage/infra: openalice-storage-v2, deploy.
  • Test/tooling: integration-tests, contract-tests, regression-tests, golden-snapshots (Cat-A byte-identical guards), oa-test-fixtures, xtask, pack-sdk.

WASM packs live in packs/. Prompts in prompts/ (Cat-A .md, SHA256-pinned). Sub-agent role-templates in agents/ (TOML, loaded via find_templates_dir()).

Query Atlas BEFORE grepping

Atlas (https://atlas.blal.pro) is the cron-fresh index of this org. REST /api/v1/..., MCP /mcp.

  • symbols: GET /api/v1/code/symbols?q=<name>&repo=openalice (methods indexed since U7.1)
  • by meaning: GET /api/v1/search?q=<concept> (semantic)
  • deps/blast-radius: GET /api/v1/repos/openalice/impact
  • repo grade/health/features: GET /api/v1/repos/openalice, /features

Call-graph is candidate-grade (~15-19% resolved) — verify by grep when precision matters. Grep only for content/regex Atlas can't answer.

Conventions

  • @feature + features.json: features are annotated // @feature <name> in code AND catalogued in features.json (642 entries) at repo root. Both feed the registry; keep them in sync.
  • Cat-A soul preservation: Alice's persona/Identity/Safety prompt content is byte-identical-protected — NEVER paraphrase it. golden-snapshots + prompt-composer manifest.lock (SHA256) guard it. Structural/system changes are fine; content changes are not.
  • Commit + test discipline: conventional commits (feat/fix/refactor(scope): …); every change ships with tests + doc-comments + a feature-registry entry; run the full suite before "done".
  • Gates: CI runs cargo clippy --workspace --all-targets --no-deps -- -D warnings. Cap local builds -j 4 --test-threads 4. Keep ≥20G disk free before a build.
  • Git safety: never force-push / reset --hard / rm -rf / delete branches. Protected: main, mvp, dev.

Where things flow (the hot path)

inbound (connector in modules-connectors) → alice/connector_bridge 32-stage pipeline (address-filter → coalesce → prompt_assembly → agentic_loop) → router (LLM) → reply → post_turn. Prompt is assembled by agents-soul::SectionBuilder (20 priority-sorted sections); memory (agents-memory curator/scribe) feeds dossiers + index into it.

See also

docs/design/ (architecture design docs, registered in Atlas /wiki under architecture/). The living 10x/SOTA-AGI roadmap: docs/design/2026-06-17-architecture-deep-audit-10x-roadmap.md.