# midorin-linux/nekoai architecture

> Architecture diagram of the GitHub repository midorin-linux/nekoai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/midorin-linux/nekoai
- Repository: https://github.com/midorin-linux/nekoai

## Overview

1. **Repository shape**
   - The repo is split into a Rust backend workspace in `nekoai-rs/` and a separate React Router frontend scaffold in `nekoai-gui/`.
   - The backend is the system that actually runs the Discord agent; the GUI is present but appears independent and not wired into the Rust runtime.

2. **Top-level runtime entry**
   - `nekoai-rs/cli` is the executable entry point (`neko` / `nekoai-cli`).
   - It handles startup, setup gating, config loading, and then boots the Discord agent.
   - `justfile` and the root `docker-compose.yml` support local development and service orchestration, especially around Qdrant.

3. **Configuration and setup boundary**
   - `config` owns JSON config loading plus secret handling (`SecretKey`).
   - `setup` owns the first-run wizard and CLI/env fallback logic; it can merge with an existing config rather than replacing it.
   - The setup flow is a key boundary because it determines Discord token, provider/model settings, memory backend settings, and tool permissions before the agent starts.

4. **Discord integration layer**
   - `discord` is the platform adapter. It uses Serenity + Poise-style command routing and event handling to expose the agent through Discord.
   - It supports slash commands and prefix commands, with command modules for `/ask`, `/clear`, and `/history`.
   - This layer also contains session resolution logic so Discord messages map to a stable conversation/session key.

5. **Agent core**
   - `agent` is the execution core: runtime, context, session, and provider adapter live here.
   - It assembles the prompt/context from system instructions, conversation history, and recalled memory, then invokes the model provider.
   - The core is designed around a “provider” abstraction, which fits the README’s OpenAI-compatible model support and preset setup options.

6. **Domain model boundary**
   - `domain` contains shared types and agent-domain abstractions used across crates.
   - This is the lowest-coupling layer for session/runtime concepts, so higher-level crates can share model and lifecycle definitions without depending on platform-specific code.

7. **Memory subsystem**
   - `memory` is a three-tier memory system: short-term, mid-term, and long-term.
   - It includes embedding logic, storage orchestration, and vector DB abstractions.
   - The runtime uses in-memory storage for short-term state and Qdrant-backed vector search for mid/long-term memory, which means the architecture splits transient conversation state from persistent semantic recall.

8. **Vector database and extraction flow**
   - `memory/src/vector_db` provides both `inmemory` and `qdrant` implementations behind a common interface.
   - Mid-term and long-term collections are created at startup when Qdrant is used.
   - Long-term memory is not just storage; it is fed by background extraction intervals, so there is a separate async path that distills session content into durable entries.

9. **Tooling and external capability layer**
   - `tools` defines callable capabilities exposed to the agent.
   - It includes Discord-domain tools (`message`, `channel`, `guild`, `member`, `role`, `thread`, `voice`, `invite`, `emoji`, `schedule`), plus file/search/MCP-related utilities.
   - Web search and fetch are optional and depend on SearXNG; MCP client support indicates the tool layer can also bridge to external tool servers.

10. **Infrastructure services inside the app**
   - `infra` provides cross-cutting runtime services such as logging, metrics, an event bus, an HTTP server, and web-UI agent glue.
   - Logging is configured for daily-rotated file output, and metrics/instrumentation sit outside the agent’s business logic.
   - This crate is the main internal “platform services” boundary that other crates depend on without owning those concerns themselves.

11. **Startup and data flow**
   - The main flow is: Discord event/command → session resolution → memory recall → context assembly → agent inference with tools → response back to Discord.
   - On `/clear`, the current session is reset while short-term memory can still be promoted to mid-term in the background.
   - On `/history`, the Discord layer reads recent session state directly for display, which is separate from the model’s context window construction.

12. **Operational dependencies**
   - External systems that materially affect architecture are Discord, an OpenAI-compatible model endpoint, Qdrant for durable vector memory, and optional SearXNG for web search/fetch.
   - The system also reads `.config/INSTRUCTION.md` at startup as a system prompt source, making local repository config part of the runtime behavior.
   - The backend expects Rust stable and uses Docker mainly to run Qdrant.

13. **Frontend status**
   - `nekoai-gui/` is a Vite/React Router scaffold with its own `package.json`, `app/`, and build tooling.
   - Based on the repo contents, it looks like a separate UI project rather than a core dependency of the agent runtime.

14. **Documentation as architecture source**
   - `docs/architecture.md` and `docs/workflow/*.md` appear to describe the intended runtime and operational workflow.
   - For an architecture diagram, the important cut lines are: Discord adapter, agent core, memory subsystem, tools/external integrations, and infra services.

Main entry points: [`nekoai-rs/agent/src/lib.rs`](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/agent/src/lib.rs) (Agent), [`nekoai-rs/memory/src/lib.rs`](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/lib.rs) (Memory), [`nekoai-rs/discord/src/lib.rs`](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/discord/src/lib.rs) (Discord), [`nekoai-rs/cli/src/main.rs`](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/cli/src/main.rs) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Rust backend"]
  node_cli["CLI<br/>runtime entry<br/>[main.rs]"]
  node_setup["Setup<br/>first-run config<br/>[lib.rs]"]
  node_config["Config<br/>settings loader<br/>[lib.rs]"]
  node_discord["Discord<br/>platform adapter<br/>[lib.rs]"]
  node_agent["Agent<br/>execution core<br/>[lib.rs]"]
  node_context["Context<br/>prompt assembly<br/>[context.rs]"]
  node_provider["Provider<br/>model adapter<br/>[provider.rs]"]
  node_session["Session<br/>runtime state<br/>[session.rs]"]
  node_domain["Domain<br/>shared model<br/>[lib.rs]"]
  node_memory[("Memory<br/>[lib.rs]")]
  node_short_term["Short term<br/>ephemeral state<br/>[short_term.rs]"]
  node_mid_term[("Mid term<br/>recall layer<br/>[mid_term.rs]")]
  node_long_term[("Long term<br/>durable recall<br/>[long_term.rs]")]
  node_vector_db[("Vector DB<br/>storage backend<br/>[mod.rs]")]
  node_tools["Tools<br/>capability layer<br/>[lib.rs]"]
  node_infra["Infra<br/>platform services<br/>[lib.rs]"]
end

subgraph group_frontend["React GUI"]
  node_gui["GUI<br/>react scaffold<br/>[root.tsx]"]
end

node_qdrant[("Qdrant<br/>external vector db")]
node_discord_api["Discord API<br/>external platform"]
node_model_endpoint["Model API<br/>external LLM"]
node_searxng["SearXNG<br/>external search"]
node_mcp_servers["MCP servers<br/>external tools"]

node_cli -->|"boot gate"| node_setup
node_cli -->|"load config"| node_config
node_setup -->|"write/merge"| node_config
node_cli -->|"start bot"| node_discord
node_cli -->|"start core"| node_agent
node_discord -->|"resolve session"| node_session
node_discord -->|"invoke agent"| node_agent
node_agent -->|"build prompt"| node_context
node_agent -->|"call model"| node_provider
node_agent -->|"recall/write"| node_memory
node_agent -->|"use tools"| node_tools
node_agent -->|"shared types"| node_domain
node_memory -->|"active state"| node_short_term
node_memory -->|"session recall"| node_mid_term
node_memory -->|"durable recall"| node_long_term
node_memory -->|"vector store"| node_vector_db
node_vector_db -->|"persistent backend"| node_qdrant
node_provider -->|"LLM endpoint"| node_model_endpoint
node_tools -->|"discord tools"| node_discord_api
node_tools -->|"search/fetch"| node_searxng
node_tools -->|"mcp bridge"| node_mcp_servers
node_infra -->|"runtime services"| node_agent
node_infra -->|"support adapter"| node_discord
node_discord -->|"events/messages"| node_discord_api
node_gui -.->|"separate app"| node_infra

click node_cli "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/cli/src/main.rs"
click node_setup "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/setup/src/lib.rs"
click node_config "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/config/src/lib.rs"
click node_discord "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/discord/src/lib.rs"
click node_agent "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/agent/src/lib.rs"
click node_context "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/agent/src/context.rs"
click node_provider "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/agent/src/provider.rs"
click node_session "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/domain/src/agent/session.rs"
click node_domain "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/domain/src/lib.rs"
click node_memory "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/lib.rs"
click node_short_term "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/short_term.rs"
click node_mid_term "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/mid_term.rs"
click node_long_term "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/long_term.rs"
click node_vector_db "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/vector_db/mod.rs"
click node_tools "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/tools/src/lib.rs"
click node_infra "https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/infra/src/lib.rs"
click node_gui "https://github.com/midorin-linux/nekoai/blob/master/nekoai-gui/app/root.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_setup,node_config,node_discord,node_agent,node_context,node_provider,node_session,node_domain,node_memory,node_short_term,node_mid_term,node_long_term,node_vector_db,node_tools,node_infra toneBlue
class node_gui toneAmber
class node_qdrant,node_discord_api,node_model_endpoint,node_searxng,node_mcp_servers toneNeutral
```

## Components

### Rust backend

Workspace that runs the Discord agent and supporting services.

- [CLI](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/cli/src/main.rs): runtime entry · Executable entry point that gates setup, loads config, and boots the agent. · `nekoai-rs/cli/src/main.rs`
- [Setup](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/setup/src/lib.rs): first-run config · Wizard and CLI/env fallback logic that builds or merges runtime configuration. · `nekoai-rs/setup/src/lib.rs`
- [Config](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/config/src/lib.rs): settings loader · JSON config loading and secret handling for runtime settings. · `nekoai-rs/config/src/lib.rs`
- [Discord](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/discord/src/lib.rs): platform adapter · Serenity/Poise-style adapter for slash commands, prefix commands, and event handling. · `nekoai-rs/discord/src/lib.rs`
- [Agent](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/agent/src/lib.rs): execution core · Builds context, manages runtime/session state, and invokes the model provider. · `nekoai-rs/agent/src/lib.rs`
- [Context](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/agent/src/context.rs): prompt assembly · Combines system instructions, conversation history, and recalled memory into model input. · `nekoai-rs/agent/src/context.rs`
- [Provider](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/agent/src/provider.rs): model adapter · Abstracts OpenAI-compatible model backends behind a common interface. · `nekoai-rs/agent/src/provider.rs`
- [Session](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/domain/src/agent/session.rs): runtime state · Shared session and lifecycle concepts used by the agent and platform layers. · `nekoai-rs/domain/src/agent/session.rs`
- [Domain](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/domain/src/lib.rs): shared model · Low-coupling agent-domain types and abstractions shared across crates. · `nekoai-rs/domain/src/lib.rs`
- [Memory](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/lib.rs): memory system · Short-, mid-, and long-term memory orchestration with embeddings and storage. · `nekoai-rs/memory/src/lib.rs`
- [Short term](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/short_term.rs): ephemeral state · In-memory conversation state used during active sessions. · `nekoai-rs/memory/src/short_term.rs`
- [Mid term](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/mid_term.rs): recall layer · Intermediate memory tier used to preserve and retrieve session-relevant content. · `nekoai-rs/memory/src/mid_term.rs`
- [Long term](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/long_term.rs): durable recall · Persistent semantic memory fed by background extraction and vector search. · `nekoai-rs/memory/src/long_term.rs`
- [Vector DB](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/memory/src/vector_db/mod.rs): storage backend · Common interface with in-memory and Qdrant implementations. · `nekoai-rs/memory/src/vector_db/mod.rs`
- [Tools](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/tools/src/lib.rs): capability layer · Callable capabilities exposed to the agent, including Discord-domain tools and external utilities. · `nekoai-rs/tools/src/lib.rs`
- [Infra](https://github.com/midorin-linux/nekoai/blob/master/nekoai-rs/infra/src/lib.rs): platform services · Cross-cutting services such as logging, metrics, event bus, HTTP, and web-UI glue. · `nekoai-rs/infra/src/lib.rs`

### React GUI

Separate frontend scaffold not wired into the Rust runtime.

- [GUI](https://github.com/midorin-linux/nekoai/blob/master/nekoai-gui/app/root.tsx): react scaffold · Standalone React Router/Vite frontend scaffold that is present but not integrated with the Rust runtime. · `nekoai-gui/app/root.tsx`

### Other components

- **Qdrant**: external vector db · Durable vector store backing mid- and long-term memory when enabled.
- **Discord API**: external platform · Discord service used for bot events, messages, and command execution.
- **Model API**: external LLM · OpenAI-compatible inference endpoint used by the provider abstraction.
- **SearXNG**: external search · Optional web search and fetch backend used by search tools.
- **MCP servers**: external tools · Optional external tool servers bridged through the MCP client support.

## Connections

- CLI → Setup: boot gate · Startup checks first-run state and prepares configuration.
- CLI → Config: load config · Loads runtime configuration before launching services.
- Setup → Config: write/merge · Produces or merges configuration including secrets and provider settings.
- CLI → Discord: start bot · Initializes the Discord adapter after configuration is ready.
- CLI → Agent: start core · Boots the agent runtime used by the Discord bot.
- Discord → Session: resolve session · Maps Discord messages to stable conversation/session identifiers.
- Discord → Agent: invoke agent · Routes slash and prefix commands into agent execution.
- Agent → Context: build prompt · Assembles model input from instructions, history, and memory.
- Agent → Provider: call model · Uses the provider abstraction to run inference.
- Agent → Memory: recall/write · Reads recalled memory and persists new session content.
- Agent → Tools: use tools · Executes tool calls during model-driven workflows.
- Agent → Domain: shared types · Relies on shared agent-domain abstractions.
- Memory → Short term: active state · Tracks transient conversation state for the current session.
- Memory → Mid term: session recall · Stores and retrieves intermediate-term context.
- Memory → Long term: durable recall · Maintains extracted long-term semantic memory.
- Memory → Vector DB: vector store · Uses a common storage interface for vector-backed recall.
- Vector DB → Qdrant: persistent backend · Uses Qdrant for durable mid- and long-term collections.
- Provider → Model API: LLM endpoint · Targets an OpenAI-compatible model service.
- Tools → Discord API: discord tools · Tooling reaches into Discord objects and permissions.
- Tools → SearXNG: search/fetch · Optional web search and retrieval depend on SearXNG.
- Tools → MCP servers: mcp bridge · Can connect to external tool servers through MCP.
- Infra → Agent: runtime services · Provides shared platform services around the core agent.
- Infra → Discord: support adapter · Supplies shared services used by the Discord runtime.
- Discord → Discord API: events/messages · Consumes and responds through the Discord platform.
- GUI → Infra: separate app · Present in the repo but not wired into the Rust runtime.
