N.E.K.O. (Project N.E.K.O.) review: an open source AI catgirl companion that installs from a one-click package or Docker

What N.E.K.O. actually is, and who it is built for

The README defines the acronym as Networked Emotional KNowledging Organism and describes the project as a digital life rather than a tool. That framing matters, because it determines which features exist and which do not. The core features table lists proactive companionship, realtime voice plus ChatCompletion text dialogue, realtime visual understanding, a five-layer memory system, five avatar forms (Live2D, VRM, MMD, PNGTuber and a cat desktop pet), agent tool execution through CUA, OpenClaw A2A and plugins, a plugin SDK with a store, and support for 14+ AI providers including OpenAI, Gemini, Qwen and DeepSeek, with free models available out of the box.

The README is unusually direct about the negative space. It states that N.E.K.O. is not a task automation tool and not a roleplay skin, and it positions the agent capability as a means of living alongside you rather than the purpose of the product. The comparison table contrasts it with general agents such as OpenClaw and Hermes, which it describes as execution engines that take an instruction and finish, and with text roleplay frontends such as SillyTavern, which it describes as requiring you to assemble the model and maintain context or world books by hand. The intended audience is someone who wants the companion layer itself integrated: voice, vision, avatar, memory and cross-device sync in one install.

The project is not only a desktop app. The README lists a Steam build that is already free, a Steam Workshop for sharing characters, models and voice packs, a mobile client in internal testing, and K.U.R.O., a separate AI-native game built on the same ecosystem. Cross-scenario memory sync is stated as a goal: the same companion across desktop, mobile, games and smart hardware.

The five-layer memory system and how the pieces connect

The memory design is the most concrete engineering claim in the README. It names five tiers: working memory, recent memory, fact memory, reflection memory and personality memory. The README does not publish the retrieval algorithm, the storage backend, or the promotion rules between tiers, so the layering is best read as a taxonomy the project commits to rather than a mechanism you can audit from the documentation alone. What it does imply is that the companion is expected to accumulate state across sessions, which is why the Docker migration problem described below is more serious than a typical config change.

The runtime shape is visible in the repository layout and in pyproject.toml. The stack is Python with FastAPI and uvicorn as the server, websockets for realtime transport, and a local_server directory alongside main_logic, main_routers, memory, brain, plugin and frontend directories. Dependencies include the OpenAI, google-genai and anthropic clients, dashscope for Qwen, browser-use for browser automation, pyautogui plus pywinauto and pygetwindow on Windows for desktop control, pytesseract for OCR, and pyrnnoise for noise suppression. Platform-specific integrations for Bilibili and Twitch are declared directly in the project metadata, which tells you the social and streaming features are first-class rather than plugin-only.

The avatar layer is separate from the language layer. The README lists motion capture and full-screen tracking alongside the five avatar formats, and the frontend directory plus build_frontend.sh and build_frontend.bat suggest a compiled frontend served by the local server. The Docker deployment exposes ports 48911 and 48912 mapped to container ports 80 and 443, so the interface is reached through a browser or a packaged client rather than a native window alone.

Installing N.E.K.O.: one-click packages, Docker Compose, and a first run

The README gives three paths. On Windows, macOS and Linux there is a one-click package: unzip and run N.E.K.O.exe, N.E.K.O.app or n.e.k.o. The README notes that macOS users must manually clear the system quarantine flag first. For Linux there is a Docker deployment, which the README calls the recommended Compose route.

The Compose file uses the published image and mounts a single ./neko-home directory plus ./logs. Ports 48911 and 48912 on the host map to 80 and 443 in the container.

version: '3.8'
services:
  neko-main:
    image: docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest
    container_name: neko
    restart: unless-stopped
    ports:
      - "48911:80"
      - "48912:443"
    volumes:
      - ./neko-home:/home/neko
      - ./logs:/app/logs
    networks:
      - neko-network
networks:
  neko-network:
    driver: bridge

Start it with Compose. The README lists docker-compose logs -f, docker-compose down and docker-compose restart as the routine commands.

docker-compose up -d
docker-compose logs -f

After startup the README says the following directory structure appears next to the compose file: neko-home for configuration, data, SSL and the OpenFang agent, logs for application output, and docker-compose.yml itself.

当前目录/
├── neko-home/    # 用户主目录（配置、数据、SSL、OpenFang agent）
├── logs/         # 应用日志
└── docker-compose.yml

There is also a docker run variant for people who do not want Compose. It creates the bridge network, sets a base path variable, and mounts the same two directories.

NEKO_BASE_PATH="/home/neko/neko-data" && \
docker network create --driver bridge neko-network 2>/dev/null || true
docker run -d \
  --name neko \
  --restart unless-stopped \
  -p 48911:80 \
  -p 48912:443 \
  -v "${NEKO_BASE_PATH}/neko-home:/home/neko" \
  -v "${NEKO_BASE_PATH}/logs:/app/logs" \
  --network neko-network \
  docker.gh-proxy.org/ghcr.io/project-n-e-k-o/n.e.k.o:latest

For a source checkout, pyproject.toml pins requires-python to ==3.11.*, so the interpreter must be exactly 3.11. There is a uv.lock and an exported requirements.txt, and the repository contains launcher.py alongside launcher_core.

The Docker upgrade trap: a container that starts healthy with none of your data

The README documents a migration that deserves more attention than it usually gets. Older versions split data and certificates across ./N.E.K.O and ./ssl mounts. The current layout merges both into ./neko-home. The README states plainly that pulling the new image and starting it produces an empty data directory: the container comes up, API keys are regenerated from environment variables, and everything looks normal, but personality, memory, plugins and models are gone. The old data is not deleted, it is simply no longer mounted.

That is the failure mode to internalize. A healthy container is not evidence that your state survived. The README's migration guide insists the export step runs before the container is removed, and it warns that the judge of whether data lives only in the container writable layer is what the container actually has mounted, not whether the host directory contains files. For deployments that followed an older README, the host N.E.K.O directory was mounted at /root/Documents/N.E.K.O while the service never wrote there, so a populated-looking host directory can be a shell while the real data sits inside the container. The guide uses docker inspect to list mount destinations and branches on whether /home/neko is already present.

MOUNTS=$(docker inspect neko --format '{{range .Mounts}}{{println .Destination}}{{end}}' 2>/dev/null)

The guide also notes the container runs as uid/gid 1000, matching the first normal user on most distributions, so ownership usually needs no adjustment. It warns against using mv to merge old directories into neko-home, because moving into an existing directory nests an extra level; it recommends merging by content with old files winning on name collisions. If the old container is already gone and the host N.E.K.O directory is empty, the README says that data cannot be recovered, and that this mount change exists specifically to fix the underlying problem.

Where N.E.K.O. is the wrong choice

If you want deterministic task automation, this is the wrong tool and the README says so. Its own comparison puts general agents such as OpenClaw and Hermes in the category of execution engines, while N.E.K.O. calls task execution one means of shared living rather than the goal. A workflow that needs reproducible runs, auditable steps and a clean exit code is better served by an agent framework, and the README's own suggestion is to call such an agent from N.E.K.O. through A2A rather than to replace it.

If you want a text roleplay frontend you control end to end, the trade-off runs the other direction. The README frames N.E.K.O. as zero-configuration and end-to-end integrated, which is exactly the property that removes the ability to swap in your own context assembly or world book pipeline. Integration and control are in tension here, and the project has deliberately chosen integration.

The Python pin is a harder constraint than it looks. requires-python is ==3.11.*, not >=3.11, so a host running 3.12 or 3.13 will not satisfy the metadata without a separate interpreter or a container. The dependency list also carries platform conditionals: pywin32, pywinauto and pygetwindow are Windows-only, pyobjc is macOS-only, and pyrnnoise is excluded on Intel macOS because its wheel ships an arm64-only librnnoise.dylib with no source distribution to fall back on. The pyproject comment states that utils/audio_processor.py loads it through ctypes and degrades to no noise suppression when the module is missing, so Intel Mac users get a functionally reduced build rather than an install failure. Anyone expecting feature parity across operating systems should read the conditionals before assuming it.

How N.E.K.O. differs from SillyTavern and from general agent frameworks

The clearest alternative in the README's own framing is SillyTavern, the text roleplay frontend. The difference is architectural, not cosmetic. SillyTavern gives you a prompt assembly layer and expects you to connect a model and maintain context or world books yourself. N.E.K.O. ships the whole stack: realtime voice through a Realtime API plus text through ChatCompletion, visual understanding, an avatar with motion capture, a five-tier memory system, and a plugin SDK with a store. You give up the ability to reshape the prompt pipeline; you gain a system where the companion's appearance, voice and memory are already wired together.

The second alternative is the general agent, represented in the README by OpenClaw and Hermes. Those take an instruction, execute it and stop. N.E.K.O. treats that capability as a callable limb through A2A and keeps the relationship layer as the primary surface. If your success criterion is tasks completed per hour, the agent framework wins on focus. If your criterion is continuity of a persona across sessions and devices, the agent framework has no equivalent of the five memory tiers or the avatar layer.

A third option worth naming is the Steam build, which is free and listed on the store. It is the same project packaged for people who do not want to touch Docker or Python at all, with Steam Workshop for sharing characters, models and voice packs. The self-hosted path exists for people who want the data and the runtime on their own machine, and the README states the core driver is Apache-2.0 and runs locally.

Maintenance, licence and what the last push date tells you

The repository is not archived, and the last push was on 2026-08-20. The most recent release is v0.9.0, tagged The Beginning of NekoVerse, dated the same day, following v0.8.3 on 2026-06-27 and a nightly build on 2026-08-06. That cadence is roughly one tagged release every two months with nightly builds in between, which is consistent with a project that is still adding surface area rather than one in maintenance mode.

Licensing is straightforward on the core: the README states the core driver is Apache-2.0 and always open source, and the repository contains LICENSE and NOTICE files. The README also says contributions may be shipped in the Steam and app store versions, which is worth reading carefully if you plan to contribute code rather than use it. The plugin SDK and the Steam Workshop create a second layer of content with its own terms, and the README does not describe those terms. This is not legal advice; if you intend to redistribute N.E.K.O. or bundle it into a product, read LICENSE and NOTICE and the Workshop terms yourself.

Upgrade cost is dominated by two things: the Python pin, which means upgrades may require rebuilding an environment rather than bumping a package, and the mount layout, which the README already changed once in a way that silently orphans data. The nightly channel exists for people who want to track changes ahead of tagged releases, and the README does not document rollback from a nightly to a tagged build, so treat that channel as one-way until you confirm otherwise.

Editorial conclusion

Adopt N.E.K.O. if you want a locally running companion with realtime voice, visual understanding and persistent memory, and you are willing to accept a Python 3.11-only stack and a Docker migration that can silently start with an empty data directory. Skip it if you want a task automation engine or a pure text roleplay frontend, because the project says outright it is neither. Before committing, verify that your Python is exactly 3.11, that the GPU and avatar pipeline you plan to use is documented for your platform, and that your existing Docker mounts match the ./neko-home layout before you pull :latest.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes