NexAgent is an AI agent built for real-world, long-running use.

It is not just a one-shot CLI demo, and it is not just a thin prompt wrapper around a model. NexAgent is built around a more specific goal: keep an agent online, place it inside the chat apps you already use, give it memory and tools, let it manage background work, and make it capable of improving over time.

Two ideas define the project today:

• Self-evolution: not only prompt engineering, but also memory, skills, tools, and source-level self-improvement.
• Elixir/OTP: supervision trees, GenServers, process isolation, and hot code loading for fault tolerance, concurrency, and long-lived operation.

At a Glance

If you only remember three things about NexAgent, they should be:

• What it is: a long-running AI agent that lives in chat apps
• What it can do: memory, tools, skills, scheduled jobs, and background tasks
• Why it can keep running: Elixir/OTP plus built-in self-evolution paths

flowchart TD
    A["Chat Apps<br/>Telegram / Feishu / Discord / Slack / DingTalk"] --> B["Gateway"]
    B --> C["InboundWorker"]
    C --> D["Runner"]
    D --> E["Sessions + Memory"]
    D --> F["Tools + Skills"]
    D --> G["Cron + Subagent"]
    D --> H["Reflect + Upgrade Code"]
    H --> I["CodeUpgrade + UpgradeManager"]

What You Can Build

Key Features

Why NexAgent

Many agent projects are good at finishing a single task. NexAgent is focused on a different set of questions: once an agent is actually deployed into chat environments and kept online, how should sessions, memory, jobs, failure handling, and self-improvement be organized?

Why self-evolving

NexAgent is not differentiated by “one more tool” or “one more model.” Its real difference is that evolution is treated as a core system capability.

That path is layered:

• SOUL.md: adjust behavior, tone, and values
• MEMORY.md / HISTORY.md / daily logs: accumulate long-term experience
• Skills: turn new abilities into reusable building blocks
• Tools: expand what the agent can actually do
• Code: use reflect and upgrade_code to inspect and modify the agent itself

That is why “self-evolving” is not just a slogan here. It is a direction that runs from prompt and memory all the way down to source code.

Why Elixir/OTP

If an agent only runs once in a while, the runtime matters less. If it needs to stay online, manage multiple chat surfaces, run background work, recover from failures, and eventually hot-upgrade itself, OTP stops being an implementation detail and becomes part of the product.

NexAgent already follows that path in code:

• Application manages infrastructure, workers, and channel lifecycles through a supervision tree
• Gateway manages chat app connections
• InboundWorker consumes inbound messages and routes sessions
• SessionManager, Tool.Registry, Cron, and Subagent run as long-lived services
• CodeUpgrade and UpgradeManager handle hot updates, versioning, and rollback paths

That is why Elixir/OTP is not background trivia in this project. It is one of the main reasons the project exists in this form.

What Makes It Different

NexAgent is not trying to solve “how do we wrap one more model call.” It is trying to solve a more operational set of problems:

Install

From source

Requirements:

• Elixir ~> 1.18
• Erlang/OTP

Install dependencies:

git clone https://github.com/gofenix/nex-agent.git
cd nex-agent
mix deps.get

Quick Start

1. Initialize

mix nex.agent onboard

You can also point the CLI at a specific instance:

mix nex.agent -c /path/to/config.json -w /path/to/workspace onboard

On first run, NexAgent creates the config and workspace for that instance:

~/.nex/agent/
├── config.json
├── tools/
└── workspace/
    ├── AGENTS.md
    ├── SOUL.md
    ├── USER.md
    ├── skills/
    ├── sessions/
    └── memory/
        ├── MEMORY.md
        ├── HISTORY.md
        └── YYYY-MM-DD/log.md

2. Configure your model

The most direct path is to set provider, model, and API key through the CLI:

mix nex.agent config set provider openai
mix nex.agent config set model gpt-4o
mix nex.agent config set api_key openai sk-xxx

If you want to use Ollama:

mix nex.agent config set provider ollama
mix nex.agent config set model llama3.1

Default providers:

• anthropic
• openai
• openrouter
• ollama

Provider access is unified through req_llm, so NexAgent no longer needs a separate handwritten client module for each provider.

Config file location:

~/.nex/agent/config.json

If you pass --config and do not set defaults.workspace, the workspace defaults to Path.dirname(config.json)/workspace for that instance.

3. Chat

The CLI is a host shell for the agent runtime. Capability-specific actions stay inside the agent loop through tools and skills; the CLI itself only manages sessions and runtime state.

Single message:

mix nex.agent -m "hello"

Interactive mode:

mix nex.agent

4. Run the gateway

mix nex.agent gateway

Check status:

mix nex.agent status

Target a specific instance:

mix nex.agent -c /path/to/config.json status
mix nex.agent -c /path/to/config.json -w /path/to/workspace gateway

Stop the gateway:

mix nex.agent gateway stop

Chat Apps

NexAgent is not meant to live only in a terminal.

The goal is to place the agent inside the chat apps you already use, so it becomes part of real communication and workflows.

Currently supported in code:

Telegram

Telegram is the easiest place to start.

1. Create a bot through @BotFather
2. Configure Telegram in config.json or through the CLI
3. Start the gateway

Example:

mix nex.agent config set telegram.enabled true
mix nex.agent config set telegram.token 123456:ABCDEF
mix nex.agent config set telegram.allow_from 10001,10002
mix nex.agent config set telegram.reply_to_message true
mix nex.agent gateway

Other chat apps are currently better configured directly in ~/.nex/agent/config.json.

Feishu and Lark CLI

Feishu is still supported as a chat channel.

What changed is the workspace automation surface:

• NexAgent no longer ships built-in feishu_* business tools for Docs, Sheets, Base, Calendar, Tasks, Drive, chat administration, or search.
• For those operations, use the existing bash tool with external lark-cli.
• lark-cli is not vendored or auto-installed by NexAgent. Install it separately from larksuite/cli.
• If lark-cli is missing, the shell error should be surfaced directly and then followed with an installation hint.

Models

NexAgent currently supports:

• Anthropic
• OpenAI
• OpenRouter
• Ollama

The simplest starting points are usually:

• Cloud model: OpenAI or OpenRouter
• Local model: Ollama

Runner handles the agent loop and then dispatches to the selected provider implementation.

Tools and Skills

Built-in tools

Default built-in tools:

• read
• write
• edit
• list_dir
• bash
• web_search
• web_fetch
• message
• memory_write
• cron
• spawn_task
• skill_discover
• skill_get
• skill_capture
• skill_import
• skill_sync
• tool_list
• tool_create
• tool_delete
• soul_update
• reflect
• upgrade_code

Together, these cover files, shell commands, web access, outbound messaging, long-term memory, scheduling, skill growth, tool growth, and code upgrades.

Custom global tools

Custom Elixir tools live in ~/.nex/agent/workspace/tools/<name>/ and are registered as first-class tools.

• tool_create creates a workspace custom tool
• tool_list inspects built-in and custom tools
• tool_delete removes a custom tool

Skills

Beyond tools, NexAgent has a Markdown-based skills system.

Skills are reusable workflow modules that help the agent:

• package workflows
• standardize recurring tasks
• create reusable instructions for itself

Instance-local runtime skill packages live in workspace/skills/<name>/. Discover them through skill_discover, inspect them through skill_get, and capture new local knowledge packages through skill_capture.

Repository-owned workflow policy can also live in .nex/skills/<name>/SKILL.md. When skill_runtime.enabled is turned on, repo-local Markdown skills are migrated into runtime-managed packages under workspace/skills/rt__*.

Code-based capabilities belong in the tool system, where Elixir modules implement deterministic behavior through Tool.Behaviour.

SkillRuntime E2E testing

• Hermetic end-to-end coverage runs through Runner.run/3, temp workspaces, real Tool.Registry, stubbed LLM calls, and stubbed GitHub responses. These tests run in the default mix test path and are tagged :e2e.
• Live end-to-end coverage is tagged :live_e2e and is excluded from default test runs. Use mix test --only live_e2e when OPENAI_API_KEY is set. The GitHub live import path also requires GH_TOKEN or GITHUB_TOKEN.
• The live GitHub fixture defaults to the repository under test via SKILL_RUNTIME_LIVE_REPO, SKILL_RUNTIME_LIVE_COMMIT_SHA, and SKILL_RUNTIME_LIVE_PATH. In GitHub Actions those default to ${GITHUB_REPOSITORY}, ${GITHUB_SHA}, and test/support/fixtures/skill_runtime/live_packages/live_echo_playbook.
• Default CI runs the hermetic suite through mix test. Live E2E runs only in the dedicated manual/nightly workflow.

Memory and Sessions

NexAgent sessions are not just short-lived context windows. They are persistent conversations with memory layers behind them.

Sessions

Sessions are scoped by channel:chat_id, for example:

• telegram:123456
• discord:channel_id

This keeps different chat surfaces isolated instead of blending everything into one conversation stream.

Basic control commands already exist:

• /new: start a new session
• /stop: stop active tasks for the current session

Memory

The memory system is layered:

• MEMORY.md: long-term memory
• HISTORY.md: searchable history
• daily YYYY-MM-DD/log.md: operational memory and accumulated experience
• Memory.Index: BM25-style retrieval

The point of this design is simple:

• the agent should not start from zero every time
• not everything should be pushed into the prompt
• long-term memory, history, and daily experience should play different roles

Six-Layer Growth

This is one of the defining capabilities of NexAgent.

Its evolution does not happen at a single point. It happens in six layers.

• SOUL: who the agent is and which long-term principles it follows
• USER: who the user is and how the agent should collaborate with them
• MEMORY: durable facts about the environment, project, and operational context
• SKILL: reusable workflows and procedural knowledge
• TOOL: deterministic executable capabilities
• CODE: internal implementation upgrades

Soul

SOUL.md adjusts behavior, personality, and values.

User

USER.md captures who the user is, how they prefer to collaborate, and what should stay stable across sessions.

Memory

Through MEMORY.md, HISTORY.md, and daily logs, the agent can keep accumulating durable project and environment facts instead of depending only on the current chat window.

Skills

Through skill_capture, the agent can keep expanding reusable workflows and procedural knowledge. Discovery is unified through skill_discover and skill_get, while trusted package-style skills can be imported and refreshed through skill_import and skill_sync.

Tools

Through tool_create and workspace custom tools, the agent can keep expanding deterministic executable capability.

Code evolution

The code layer has its own explicit upgrade path:

• reflect: inspect module source, history, and diffs
• upgrade_code: submit updated module code
• CodeUpgrade: backup, validate, compile, load, and version code
• UpgradeManager: coordinate code upgrades, hot swaps, and rollback paths

That is what makes NexAgent more than a configurable agent. It is an agent system that is explicitly being built to learn, extend, and upgrade itself across multiple layers.

flowchart LR
    A["Reflect<br/>Read source / history / diff"] --> B["Understand<br/>Find the problem or opportunity"]
    B --> C["Upgrade Code<br/>Submit new code"]
    C --> D["CodeUpgrade<br/>Backup / validate / compile / load"]
    D --> E["UpgradeManager<br/>Hot-swap / rollback protection"]
    E --> F["Agent keeps running"]

Automation

Cron

NexAgent includes a built-in cron tool for scheduled jobs.

Supported operations:

• add jobs
• list jobs
• enable / disable jobs
• trigger jobs manually
• inspect job status

Supported scheduling modes:

• every_seconds
• cron_expr
• at

To reduce long-running cost, cron execution is deliberately lighter:

• narrower tool scope
• less history
• skipped skill loading in lightweight runs
• isolation from the user’s main session

Subagent

spawn_task creates a background subagent for an independent task.

It fits cases like:

• long-running work
• parallelizable subproblems
• background tasks that should not block the main session

When it finishes, the result is sent back through the bus.

Architecture

NexAgent is not a loose collection of scripts. It is a layered, long-running system.

flowchart TB
    subgraph L1["Entry Layer"]
        A["Chat Apps"]
        B["Gateway"]
    end

    subgraph L2["Agent Layer"]
        C["InboundWorker"]
        D["Runner"]
    end

    subgraph L3["Capability Layer"]
        E["Sessions"]
        F["Memory + Memory.Index"]
        G["Tools + Tool.Registry"]
        H["Skills"]
    end

    subgraph L4["Background Layer"]
        I["Cron"]
        J["Subagent"]
    end

    subgraph L5["Code Layer"]
        K["Reflect + Upgrade Code"]
        L["CodeUpgrade + UpgradeManager"]
    end

    A --> B --> C --> D
    D --> E
    D --> F
    D --> G
    D --> H
    D --> I
    D --> J
    D --> K --> L

Another way to read the system is:

• Entry layer: Chat Apps + Gateway
• Agent layer: InboundWorker + Runner
• Capability layer: Tools + Skills + Memory + Sessions
• Background layer: Cron + Subagent
• Six-layer growth model: Soul + User + Memory + Skill + Tool + Code

Core roles in code:

• Gateway: manage chat app connection processes
• InboundWorker: route inbound messages
• Runner: build context and execute the agent loop
• SessionManager: manage persisted sessions
• Memory / Memory.Index: manage long-term memory and retrieval
• Tool.Registry: manage tools dynamically
• Skills: load and execute skills
• Cron: manage scheduled jobs
• Subagent: manage background subagents
• CodeUpgrade / UpgradeManager: manage source-level code upgrades

These parts are held together by an OTP supervision tree instead of being scattered across unrelated scripts.

Security

NexAgent already has some important boundaries in place:

• file access is restricted to allowed roots
• path traversal is validated
• shell execution has a whitelist and dangerous-pattern blocking
• chat apps support allow_from
• cron and subagent execution use more restricted paths

It is not finished, but the direction is clear: this is not meant to become an unrestricted local god-agent by default.

Closing

If you had to compress the project into one line:

NexAgent is a self-evolving AI agent built on Elixir/OTP for long-running, real-world use.

Its differentiator is not just “one more provider” or “a few more tools.” It is the attempt to combine all of these in one system:

• long-running operation
• chat-app presence
• persistent sessions and memory
• extensible tools and skills
• scheduled jobs and background subagents
• source-level self-improvement
• OTP-driven fault tolerance and hot upgrades

If you care about how agents can keep existing in real environments, not just finish a single demo task, that is the path NexAgent is pushing forward.