server-noonien

<p align="center"><img src="assets/icon.png" width="112" alt="server-noonien"></p>

# server-noonien

[![CI](https://github.com/sequico/server-noonien/actions/workflows/ci.yml/badge.svg)](https://github.com/sequico/server-noonien/actions/workflows/ci.yml)
[![CodeQL](https://github.com/sequico/server-noonien/actions/workflows/codeql.yml/badge.svg)](https://github.com/sequico/server-noonien/actions/workflows/codeql.yml)
[![npm
version](https://img.shields.io/npm/v/server-noonien.svg)](https://www.npmjs.com/package/server-noonien)
[![License: MPL 2.0](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](LICENSE) [![Node ≥
22](https://img.shields.io/badge/node-%E2%89%A522-brightgreen.svg)](https://nodejs.org)

**Shared, serverless, conflict-free memory for AI agents — with peer-to-peer sync.**

`server-noonien` is a drop-in replacement for the official
[`@modelcontextprotocol/server-memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)
knowledge graph — the same entities, observations and relations — that **converges across machines**
with no central server, no database and no merge conflicts.

Its headline feature is **peer-to-peer sync**: the `nooniend` daemon replicates each node's shard
directly to the others, so several machines share one memory with **no shared folder** — only IP
reachability over a VPN or a LAN.

## Table of contents

- [Why server-noonien](#why-server-noonien)
  - [The problem](#the-problem)
  - [How server-noonien solves it](#how-server-noonien-solves-it)
- [Comparison](#comparison)
- [The three commands](#the-three-commands)
- [Share across machines](#share-across-machines)
  - [Peer to peer — `nooniend` (recommended)](#peer-to-peer--nooniend-recommended)
    - [The daemon HTTP API](#the-daemon-http-api)
  - [Shared area — `file` and `s3`](#shared-area--file-and-s3)
- [Configuration](#configuration)
  - [Shared variables](#shared-variables)
  - [Server variables](#server-variables)
  - [Daemon variables](#daemon-variables)
- [How it works](#how-it-works)
  - [Compaction](#compaction)
  - [Deletion and collection](#deletion-and-collection)
- [Drop-in compatibility](#drop-in-compatibility)
- [Security](#security)
- [Development](#development)
- [Why the name `noonien`?](#why-the-name-noonien)
- [Documentation](#documentation)
- [License & Disclaimer](#license--disclaimer)
  - [Support the Project](#-support-the-project-passive-monetization)

## Why server-noonien

### The problem

Agent memory today is local, and the official memory server is a single JSONL file that every
mutation reads and rewrites in full. That breaks the moment you have more than one machine:

- **It lives on one host.** Switch machine and your agent has forgotten everything.
- **Sharing it over a synced folder loses writes.** The server serializes mutations *in-process
  only*: two hosts each load the whole graph, mutate their own copy and write it back, so the last
  write silently discards the other's — and the sync tool forks the file into conflict copies
  instead of merging it.
- **The alternatives want a server, a database or a cloud.** The mainstream "shared memory" products
  are something you have to host, or they ship your memory off your machines.

### How server-noonien solves it

`server-noonien` removes the shared file and the central server at the root, and keeps the drop-in
tool surface:

- **Every node keeps its own memory.** Each machine writes only its own append-only shard
  (`<node>.jsonl`); a shard has a single writer by design, so no two nodes ever write the same file
  and noonien itself never forks one — a shared area's syncer still can, and a conflict copy is
  just another shard to fold.
- **Shards merge, they do not overwrite.** The graph is a CRDT — an **LWW-Element-Set** ordered by
  `(HLC, node, sequence)` — whose merge is idempotent, commutative, associative and convergent. Any
  two machines that have seen the same operations hold the **identical** graph, in any order, so
  there is no "last write wins" data loss.
- **No shared area, no central server.** The shards travel **directly between machines** with the
  `nooniend` daemon — only IP reachability, over a VPN or a LAN — so several machines share one
  memory with **no shared folder** and **no service to host**. Prefer a folder or a bucket you
  already have? `file` and `s3` work too: the transport is a choice, not a lock-in.
- **Local-first and offline-friendly.** Every node reads and writes its own shard on disk and keeps
  a full local replica, so it keeps working offline; the mesh reconverges when the network returns.
- **Drop-in for the official server.** The same nine tools, inputs and outputs, so it slots under
  the `memory` server name with no agent changes.

## Comparison

`server-noonien` vs the official memory server vs hosted memory services:

| | `server-noonien` | Official `server-memory` | Hosted memory services |
| --- | --- | --- | --- |
| Multi-machine | Yes — per-node shards, one graph | No — one local file | Yes, via the service |
| Sharing a synced folder | Safe — append-only, conflict-free | Unsafe — whole-file read-modify-write | N/A |
| Needs a server / database | No | No | Yes |
| Needs a cloud account | No | No | Yes |
| Works offline | Yes (`file` backend) | Yes | No |
| Storage | Folder or S3-compatible bucket, your choice | One JSONL file | Their cloud |
| Drop-in for the official tools | Yes — same nine tools | — | No |
| Migration | `noonien import memory.jsonl` | — | Export/import dance |
| Model | Explicit knowledge graph | Explicit knowledge graph | Often vector/semantic |
| License | MPL-2.0 | MIT | Proprietary |

**Hosted** is a category, not a product: it covers services that host your memory for you.
`server-noonien` is the local-first opposite — you own the storage and there is no account.

**A shared area is required** for the `file`/`s3` backends — a folder or an object store every node
can reach. `nooniend` removes that requirement: it replicates the shards directly between nodes.

## The three commands

One npm package, **`server-noonien`**, ships **three commands** (Node.js **≥ 22**). Install it once
and all three land on your `PATH`:

```sh
npm install -g server-noonien
```

| Command | Role | How it runs |
| --- | --- | --- |
| **`server-noonien`** | the MCP memory server | short-lived, **spawned by the MCP client** over stdio |
| **`noonien`** | the maintenance CLI | **one-shot**, run by hand |
| **`nooniend`** | the peer-to-peer replication daemon | **long-lived**, one per machine |

Only `server-noonien` matches the package name, so it is the only command `npx` can run by package
name. Run the other two with `--package`, or from the global install above:

```sh
npx -y server-noonien                       # the MCP server (no argument serves over stdio)
npx -y -p server-noonien noonien help       # the maintenance CLI
npx -y -p server-noonien nooniend           # the replication daemon
```

From a clone — for development, or to run code not yet on npm:

```sh
git clone https://github.com/sequico/server-noonien.git
cd server-noonien && npm install && npm run build

node dist/index.js      # server-noonien — the MCP server
node dist/noonien.js   # noonien    — the maintenance CLI
node dist/gossip.js     # nooniend   — the replication daemon
```

### `server-noonien` — the MCP server

The entry every MCP client uses. With **no argument** (or `serve`) it speaks MCP over **stdio**, so
you don't run it yourself — the client spawns it and it lives for the session. Point your client at
it; it works on one machine out of the box, and [sharing across machines](#share-across-machines) is
the next step. In OpenCode (V2):

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "memory": {
        "type": "local",
        "command": ["npx", "-y", "server-noonien"],
        "environment": { "NOONIEN_DIR": "~/.noonien" }
      }
    }
  }
}
```

Other clients wrap the same command and environment in their own envelope; from a clone the command
is `["node", "/path/to/server-noonien/dist/index.js"]`. Because the tool surface is identical, you can
replace the `memory` server entry with `server-noonien` and change nothing else.

### `noonien` — the maintenance CLI

| Command | Does |
| --- | --- |
| `noonien serve` | run the MCP memory server over stdio (the same as `server-noonien`) |
| `noonien import <file>` | import an official `server-memory` JSONL file (writes its own `<node>-import` shard, so it runs online) |
| `noonien export` | print the folded knowledge graph as JSON |
| `noonien merge` | fold every shard and report the merged state |
| `noonien compact` | maintain this node's shard now: prune shadowed operations and, only where it is safe, physically delete its tombstones — the same rule the server applies (`NOONIEN_GC`; with a daemon that owns the directory it keeps the whole view and leaves the shard to the daemon) — and report why when it keeps them |
| `noonien query <text>` | search entities and print the matching subgraph |
| `noonien help` | list the commands; `noonien --version` prints the version |

### `nooniend` — the daemon

A long-lived service, **one per machine**, that replicates the shard directory peer to peer. It
takes no arguments and is configured entirely through environment variables — the shared
`NOONIEN_DIR` and `NOONIEN_NODE_ID` ([Shared variables](#shared-variables)) plus the daemon's
`NOONIEND_*` ([Daemon variables](#daemon-variables)). See [Peer to
peer](#peer-to-peer--nooniend-recommended) for the setup.

## Share across machines

`noonien` merges shards; it does not move them by itself. How the shards travel between machines is
your choice: **peer to peer** (a companion daemon — the recommended default) or a **shared area** (a
folder or a bucket that already exists). The MCP server always reads and writes its own local shard;
only the transport differs.

### Peer to peer — `nooniend` (recommende