Neo

Appearance

How Neo works — mechanisms ​

Neo is not just a chat process. It runs as a long-lived system on the user's machine. These are the parts and where they live. Paths are under the Neo home directory (~/.neo/ by default; may be overridden by NEO_HOME).

One corpus. This is both a user-facing overview and one of Neo's runtime self-docs: at install time it is copied verbatim to ~/.neo/docs/self/ (see self-docs), so the file the user reads here and the file Neo reads about itself are literally the same. It is written in the second person ("you") because Neo reads it about itself.

The daemon ​

neo daemon run is the single always-on entrypoint. It:

  • hosts one shared engine (the agent loop) that channel connectors attach to;
  • supervises channel connectors (Telegram, WhatsApp) as child processes, restarting them on crash;
  • runs scheduled jobs (reflection, dream, and any cron tasks);
  • can self-initiate workflows when its capability tier permits.

Live daemon state (pid, current tier, uptime, per-channel status) lives under ~/.neo/daemon/. neo daemon status prints a snapshot. Logs: ~/.neo/daemon/daemon.log. The full narrative reference (autostart, budgets, on-disk layout) is daemon.md.

Capability tiers ​

The daemon runs at a capability tier that bounds what it may do unattended:

  • Tier 0 — read-only floor (read files, search, recall memory). No side effects.
  • Tier 1 — adds general tools / bash.
  • Tier 2 — adds MCP tools and the ability to self-initiate run-action workflows (e.g. the daily briefing).

The tier is set in ~/.neo/config/settings.json under daemon.capabilities.tier and is baked in at daemon boot — changing it requires a daemon restart. To report the current tier, read that file (and ~/.neo/daemon/ for the live value).

Channels ​

Channel connectors bridge the user's phone to the daemon:

  • Telegram (neo-tg) and WhatsApp (neo-wa). Each is a separate, untrusted process that attaches to the shared engine over a local socket.
  • They are owner-allowlisted — only the owner's account reaches you.
  • A channel turn runs under a restricted tool policy (profile mobile_minimal): read-only tools run without asking; anything with side effects (bash, file writes, web, config changes, image generation) surfaces an approval prompt with Allow / Always-allow / Deny buttons. "Always allow" persists per chat+tool.
  • Channel↔session mapping lives in ~/.neo/channels/<channel>.db.

The full setup + security reference is channels.md.

Memory ​

You have a durable memory layer so you don't ask the user to repeat themselves across days. Background passes maintain it:

  • Reflection — a cross-session "noticing" pass (see proactive-messages.md).
  • Dream — periodic memory consolidation/clustering.

Inspect the memory and scheduler directories under ~/.neo/ for specifics rather than asserting exact contents from memory.

Skills, workflows, scheduler ​

  • Skills — ~/.neo/skills/<name>/ — self-contained instruction+script bundles you invoke with the skill tool. Lifecycle + review: skills.md.
  • Workflows — ~/.neo/workflows/<id>/definition.yaml — multi-step, persist-across-restart processes with optional approval gates. Invoked with workflow-run, or fired unattended by the daemon at Tier 2.
  • Scheduler — ~/.neo/scheduler/scheduled_tasks.json — cron rows for recurring jobs. Note: workflow triggers are NOT always in this file (see proactive-messages.md).

How Neo decides which substrate to reach for on an incoming request — answer directly, track inline, background it, hand to a specialist, or spin up a team — is the routing policy in routing.md.

Self-docs — Neo's runtime self-knowledge ​

The documents Neo reads about itself live at ~/.neo/docs/self/. They are the same files a user reads under docs/user/ — the corpus manifest (docs/corpus.json) marks a focused subset with selfDocs: true, and the generator assembles exactly those into templates/self-docs/, which the first-run installer copies to ~/.neo/docs/self/. They are refreshed whenever their content changes (the install is content-hash–gated), so they never drift from the shipped docs.

When a self-knowledge question is about live state (current tier, whether a job ran today), don't rely on these static docs alone — inspect the actual files under ~/.neo/ with your read tools.