Nocturne Memory: A Rollbackable Long-Term Memory Server for MCP Agents

The amnesia problem Nocturne Memory targets

Most agent memory lives inside the product that created it. The README puts the case bluntly: ChatGPT's memory belongs to ChatGPT, Claude's to Claude, and "换个模型，一切归零" (switch models and everything resets to zero). If you move between Claude Code, Gemini CLI, Codex and Cursor in the same week, each one starts from an empty shell.

Nocturne Memory is a separate MCP server that holds the memory itself. The README's diagram shows one Nocturne Memory store with Claude, Gemini and GPT connecting to it in turn, so the store is not a feature of any one model. The stated audience is anyone running an MCP-capable client: Claude Code, Claude Desktop, Gemini CLI, OpenAI Codex, Cursor, OpenClaw, Antigravity, GitHub Copilot, Cherry Studio, and any client supporting stdio or SSE transport. The project also describes itself as a drop-in replacement for OpenClaw. The README's framing goes further than tooling, calling it a framework for an AI to grow from an empty shell into a persona, and it supports namespace isolation so multiple personas can hold separate memory spaces.

How the memory store is structured and retrieved

Memory is addressed by path, not by embedding similarity. The README's example calls show reads against URIs such as system://boot, core://work_jobstation/commercialization and core://nocturne/salem/dynamics. That is a tree with named nodes, which is why the project calls the structure graph-like and why the Memory Explorer screenshot is described as tree browsing.

The retrieval flow in the README's examples is explicit. A new session calls read_memory("system://boot") first, which loads only the core settings the user designated. Everything else is fetched on demand with search_memory and further read_memory calls. The README claims that in a memory library of 969,000 characters, the first message loads only 7.2K characters, and that over a 30-day window 78 percent of the library was recalled at some point. Those are the project's own figures from its own deployment; treat them as a description of the intended behaviour rather than an independent measurement.

Storage sits on SQLite or PostgreSQL, per the README badges and the docker-compose.yml. The compose file defines a postgres:16-alpine service with a healthcheck on pg_isready, a backend service built from ./backend running python run_sse.py, and nginx built from ./frontend exposing port 80. The backend healthcheck curls http://localhost:8233/health. Snapshots and backups are separate named volumes mounted at /app/snapshots and /app/backups, which is where the rollback story physically lives.

Installing Nocturne Memory and connecting a client

The README calls this a two-step install and requires Python 3.10+ plus Node.js, because the Dashboard frontend is built on first start. Clone the repository and install the backend dependencies:

git clone https://github.com/Dataojitori/nocturne_memory.git
cd nocturne_memory
pip install -r backend/requirements.txt

After that, point your MCP client at the server. The README's instruction to its own installer prompt is specific about which file to use: Antigravity should point args at backend/mcp_wrapper.py, which the README says solves a Windows CRLF problem, while other clients point at backend/mcp_server.py. Generate the JSON your client expects from that rule. The README does not print a complete config block for every client, so check the client's own MCP documentation for the surrounding keys.

If you only want to see the memory model before deploying anything, the project runs a public demo endpoint. For OpenAI Codex, add to .codex/config.toml:

[mcp_servers.nocturne_memory_demo]
url = "https://misaligned.top/mcp"

The README states the demo is read-only and exposes only read_memory and search_memory. Writes require your own instance.

For the Docker path, the compose file expects an environment file that does not ship in the repository. Its own comment says to run the setup script first, and the POSTGRES_PASSWORD variable is declared with a required-value expression that fails the compose run if it is unset:

python scripts/setup_docker.py

The script generates .env with credentials, according to the compose comment. Then docker compose up brings up PostgreSQL, the backend and nginx, with nginx published on ${NGINX_PORT:-80}.

Rollback, review and the human confirmation gate

The distinguishing feature is that memory writes are versioned. The README's screenshots describe a Review and Audit view with a visual diff where changes can be accepted or rolled back, and a version safety net where each AI operation is backed up automatically and cleanup requires human confirmation.

That gate is the interesting design decision. An agent that can rewrite its own long-term memory without oversight is one bad summarisation away from losing context permanently, and the project's answer is to make destructive operations wait for a person. The cost is that memory maintenance is not fully autonomous: someone has to review diffs. For a personal assistant running on your own machine that is a reasonable trade. For an unattended pipeline writing memory continuously, it is a bottleneck the README does not address.

The README also does not document what a rollback does to memories written after the snapshot you restore, or how snapshot retention is configured. The compose file mounts a snapshots volume but the README section on rollback is visual, not procedural. Verify retention behaviour yourself before you rely on it as your only backup.

Where Nocturne Memory is the wrong tool

Vector RAG is the approach this project positions itself against, and for some workloads that positioning is wrong. If your retrieval problem is fuzzy: find me the passage in a large corpus that is semantically near this question, embeddings handle it with no schema and no curation. Nocturne Memory asks you to build a named tree and to decide what belongs at core://work_jobstation/commercialization. That curation is the point, but it is work, and it does not scale to ingesting thousands of documents.

The second limitation is operational. The README's own quick path is a public demo that is read-only, so any real use means running a server. The Docker path needs PostgreSQL plus a generated .env, and the non-Docker path needs Python 3.10+ and a Node.js build step. If you want memory as a hosted feature with no infrastructure, a platform's built-in memory is the cheaper answer, at the cost of being locked to that platform.

Third, the documentation is uneven across languages. Several release titles are in Chinese, including 2.5.4 (Boot 预设切换 & 孤儿恢复) and 2.5.2 (重大Bug修复 & 中文支持), and the primary README is Chinese with a separate README_EN.md. The repository notes a docs/testing.md for backend testing. If you cannot read Chinese, you are working from a translation that may lag the primary document.

How it differs from embedding-based memory layers

The closest comparison is a vector-store memory layer such as Mem0 or a RAG pipeline over a document store. Those systems chunk text, embed it, and retrieve by similarity. You do not name anything, and you do not decide what is canonical.

Nocturne Memory inverts both. Retrieval is by explicit URI, and the boot node is a small, human-chosen set of core facts loaded at session start. The README's claim that a 7.2K-character first message covers a 969,000-character library is only possible because someone decided what belongs in system://boot. The advantage is determinism: the same query returns the same node, and a wrong memory can be edited or rolled back rather than re-embedded. The disadvantage is that an agent cannot discover a memory nobody filed under a findable name.

A second difference is portability. A memory store bound to one vendor's API cannot move. An MCP server is a process your client connects to, so the memory outlives any particular model. That is the strongest argument in the README, and it is architectural rather than a feature claim.

Maintenance, licence and what to check before adopting

The repository is not archived and the last push was on 2026-08-27, so it is current as of this writing. Releases have been frequent: 2.5.6 on 2026-08-09 covers MCP 2.0 compatibility and long-form improvements, 2.5.4 on 2026-05-31 covers boot preset switching and orphan recovery, and 2.5.2 on 2026-05-23 covers bug fixes and Chinese support. The upgrade cost is the usual self-hosted one: pull the repository, reinstall backend/requirements.txt, and rebuild the frontend, since Node.js is involved on first start.

The licence is MIT, which permits commercial use and modification provided the copyright notice and permission notice are retained. That is a permissive licence, and it means the project carries no warranty; you are responsible for your own data protection and backups. Nothing here is legal advice.

The practical risk is data. Your memory store is the asset, not the code. The compose file gives you a postgres_data volume plus snapshots_data and backups_data, and the README's review screen implies versioned history, but neither the README nor the compose file states a retention policy or an export format. Before you put months of memory into it, confirm how to get the data out and where the snapshots actually land on disk.

Editorial conclusion

Adopt Nocturne Memory if you run more than one MCP-capable client and want a single memory store that survives a model switch, and if you are willing to run the server yourself. Skip it if you want a managed service, if a single platform's built-in memory is enough, or if you cannot run PostgreSQL for the Docker path. Before committing, verify that backend/mcp_server.py is the correct entry point for your client, that backend/mcp_wrapper.py is used on Antigravity, and that your client's transport matches what you deploy.

Frequently asked questions

Official sources

1. Dataojitori/nocturne_memory on GitHub
2. License: MIT
3. Project website
4. README
5. Releases