NagaAgent: a desktop anime assistant built around streaming tool calls and a graph memory

What NagaAgent actually assembles for you

The project describes itself as a personal assistant framework covering dialogue, memory, MCP, skills and OpenClaw integration. Read the feature list closely and you see it is less a library than a pre-assembled desktop application: a chat window, a Live2D character you can interact with by mouse, text-to-speech, speech recognition, a skill workshop, a forum client, a music player and a floating ball window. The README also lists a game guide component that can read the screen and suggest moves, with plugins such as MAA offered as a way to automate play. The audience is therefore someone who wants an opinionated assistant they can talk to, not someone who wants to call three functions from their own code. The pyproject.toml description names multi-MCP services, streaming voice interaction, a GRAG knowledge graph memory system, a RESTful API and console tray functionality, which is a fair summary of the surface area. The trade-off is that every one of those features is a moving part you inherit.

How the conversation, tool call and memory paths fit together

The changelog is the clearest architecture document here. Entries describe a migration to native Function Calling, an Agentic Tool Loop, and SSE events carrying tool_calls and tool_results that the front end renders as collapsible structured blocks. So the flow is: the front end holds the session, the backend streams model output over SSE, tool invocations are emitted as their own events, and results come back into the loop rather than being flattened into plain text. Memory runs alongside that. The project migrated persistence into a ~/.naga user directory, uses Neo4j through both py2neo and the neo4j driver for local graph memory, and added a cloud memory path (NagaMemory) where, per the changelog, cloud memory takes priority and does not fall back to local Neo4j. A five-tuple extractor feeds the graph, and an entry notes Anthropic SDK compatibility for that extractor. Context compression is described as a three-level scheme using a compress tag and cross-session inheritance. The design point worth noting: graph extraction is an extra model call per turn, and the changelog shows repeated fixes around connection timeouts and status reporting, which tells you the graph layer is the most failure-prone part of the stack.

Installing NagaAgent and getting a first session running

The README states Python 3.11 is required, with the range >=3.11,<3.12 pinned in pyproject.toml, and lists uv and Neo4j as optional. Clone the repository and install the front end first, because the Electron UI is a separate Node project.

git clone https://github.com/Xxiii8322766509/NagaAgent.git
cd NagaAgent
cd frontend
npm install
cd ..

For the backend the README gives two routes, uv or a manual virtual environment. The uv path is the one it recommends.

uv sync

The manual path creates a venv and installs from requirements.txt, which the file header says is kept in sync with pyproject.toml.

python -m venv .venv
source .venv/bin/activate   # Windows: .\.venv\Scripts\activate
pip install -r requirements.txt

Configuration starts from a template. The README's minimal configuration section says to copy config.json.example, and a changelog entry for 5.1.3 states that runtime configuration reads the project root config.json first and falls back to the user data directory only when it is absent. Copy the template into place before first launch.

cp config.json.example config.json

After that, the documented entry point is main.py, with start.bat and setup_venv.bat present for Windows users. The README's quick start promises that a single login configures API keys automatically, so expect to supply credentials through the settings UI rather than editing every key by hand. If you want local graph memory rather than the cloud path, Neo4j has to be running before you rely on recall across sessions.

Where NagaAgent gets in your way

The Python pin is the first constraint. requires-python is >=3.11,<3.12, so a machine on 3.12 or 3.10 will not install cleanly, and the build tooling (PyInstaller in the build dependency group) means packaged builds inherit that pin. Second, the dependency list is heavy for a chat assistant: FastAPI, uvicorn, SSE-Starlette, LiteLLM, LangChain OpenAI and community packages, tiktoken, ChromaDB, two Neo4j clients, edge-tts, sounddevice, mss, pandas and numpy. That is a large supply-chain surface for something whose primary job is conversation. Third, the memory graph is optional in name only. If you skip Neo4j and stay logged out, the changelog indicates you fall back to direct API calls against your own keys, but the graph-based recall that the project markets is then unavailable. Fourth, platform behaviour is uneven: 5.1.5 is a fix for a Windows transparent frameless window disappearing after maximize and restore, and earlier entries cover macOS DMG signing. Desktop window management has been a recurring maintenance cost. Finally, the repository is a desktop app, not a headless service. If you want to embed an agent loop in a backend job, the Electron front end and tray integration are weight you cannot use.

NagaAgent compared with a plain MCP client

The closest alternative in the same problem space is a bare MCP client plus your own chat loop, for example a small script using the openai package and an MCP client library. The difference is where state lives. A bare client is stateless between runs unless you write the store yourself; NagaAgent ships a persistence layer under ~/.naga, a Neo4j graph with a five-tuple extractor, cloud memory with priority over the local graph, and context compression with cross-session inheritance. That is a real difference in approach, not a cosmetic one: the project pays for recall with extra model calls and an external database. The other direction is a general agent framework where you write the agent definition and choose a UI, if any. NagaAgent inverts that by shipping the UI first (Live2D, floating ball, tray, forum) and treating the agent loop as one component among many. If your requirement is reproducible, inspectable tool calls in CI, the bare client wins. If your requirement is a persistent companion that remembers last week, NagaAgent has already built the plumbing.

Licence, upgrade cost and what the changelog tells you about maintenance

The README states dual licensing: AGPL-3.0 for the open source path, with a separate proprietary licence in LICENSE-CLOSED-SOURCE requiring written authorisation, and a commercial contact address. The badge line reads AGPL 3.0 | Proprietary. For anyone distributing a modified NagaAgent, AGPL-3.0 is the operative term and the closed-source route is a negotiation, not a checkbox. This is not legal advice; read LICENSE and LICENSE-CLOSED-SOURCE yourself. On upgrade cost, the changelog is dense: 5.1.3, 5.1.4 and 5.1.5 all landed within nine days of each other in July 2026, and the last push to the repository was on 2026-08-11. The recent entries are mostly bug fixes in specific subsystems (TTS playback, window restore, config read priority, API key handling), which suggests a project that ships often and expects users to track releases rather than sit on a version. There is no documented migration procedure for the config schema in the README, and the 5.1.3 change to config read priority is exactly the kind of change that can silently alter which file your running install reads. Check where your config.json actually lives after upgrading.

What the repository layout implies about running it

The top-level entries are informative. There are three README translations, a SOUL.md, an agentserver directory, apiserver, summer_memory, mcpserver, skills, voice, characters, guide_engine, hooks, vendor, frontend and a naga-backend.spec for PyInstaller. The wheel build in pyproject.toml includes apiserver, agentserver, summer_memory, thinking, ui and voice, so the packaged Python side is broader than the directory list suggests at first glance. vendor and openclaw.LICENSE indicate that OpenClaw is vendored rather than pulled as a dependency, and changelog entries about compiling OpenClaw from source and packaging it confirm that. The practical consequence: building from source is not the same as running a released binary, and the released binaries are the path the project clearly optimises for, given the Windows and macOS packaging fixes. If you plan to modify the backend, budget time for the PyInstaller spec, not just for the Python code.

Editorial conclusion

NagaAgent fits users who want a single desktop assistant that already wires together chat, voice, MCP tools, Live2D and a graph memory, and who are comfortable running Python 3.11 plus a Node front end. Skip it if you need a small embeddable library, or if AGPL-3.0 does not suit your distribution model, because the closed-source path requires written permission under LICENSE-CLOSED-SOURCE. Before adopting, verify that a clean checkout reproduces the uv sync and npm install flow, and confirm which Python interpreter your packaged build actually uses, since pyproject.toml pins >=3.11,<3.12.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. RTGS2017/NagaAgent on GitHub