How midorin-linux/nekoai works
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: src/lib.rs Agent · src/lib.rs Memory · src/lib.rs Discord · main.rs CLI
Components 22
Rust backend
Workspace that runs the Discord agent and supporting services.
- CLI · Executable entry point that gates setup, loads config, and boots the agent.
nekoai-rs/cli/src/main.rs - Setup · Wizard and CLI/env fallback logic that builds or merges runtime configuration.
nekoai-rs/setup/src/lib.rs - Config · JSON config loading and secret handling for runtime settings.
nekoai-rs/config/src/lib.rs - Discord · Serenity/Poise-style adapter for slash commands, prefix commands, and event handling.
nekoai-rs/discord/src/lib.rs - Agent · Builds context, manages runtime/session state, and invokes the model provider.
nekoai-rs/agent/src/lib.rs - Context · Combines system instructions, conversation history, and recalled memory into model input.
nekoai-rs/agent/src/context.rs - Provider · Abstracts OpenAI-compatible model backends behind a common interface.
nekoai-rs/agent/src/provider.rs - Session · Shared session and lifecycle concepts used by the agent and platform layers.
nekoai-rs/domain/src/agent/session.rs - Domain · Low-coupling agent-domain types and abstractions shared across crates.
nekoai-rs/domain/src/lib.rs - Memory · Short-, mid-, and long-term memory orchestration with embeddings and storage.
nekoai-rs/memory/src/lib.rs - Short term · In-memory conversation state used during active sessions.
nekoai-rs/memory/src/short_term.rs - Mid term · Intermediate memory tier used to preserve and retrieve session-relevant content.
nekoai-rs/memory/src/mid_term.rs - Long term · Persistent semantic memory fed by background extraction and vector search.
nekoai-rs/memory/src/long_term.rs - Vector DB · Common interface with in-memory and Qdrant implementations.
nekoai-rs/memory/src/vector_db/mod.rs - Tools · Callable capabilities exposed to the agent, including Discord-domain tools and external utilities.
nekoai-rs/tools/src/lib.rs - Infra · 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 · Standalone React Router/Vite frontend scaffold that is present but not integrated with the Rust runtime.
nekoai-gui/app/root.tsx
Other components
- Qdrant · Durable vector store backing mid- and long-term memory when enabled.
- Discord API · Discord service used for bot events, messages, and command execution.
- Model API · OpenAI-compatible inference endpoint used by the provider abstraction.
- SearXNG · Optional web search and fetch backend used by search tools.
- MCP servers · Optional external tool servers bridged through the MCP client support.
Connections 25
- 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.