Provides a shared, conflict-free knowledge graph memory for AI agents using peer-to-peer synchronization.
Also known as sequico/server-noonien
- Stars
- 3
- Tools
- 21
- Downloads, 30 days
- —
- Latest version
- 1.3.0
- Last commit
- Nov 12, 2026
- License
- MPL-2.0
What is noonien MCP?
noonien provides a shared, conflict-free knowledge graph memory for AI agents using peer-to-peer synchronization. It exposes 21 tools, such as create_entities, create_relations, add_observations.
Summary generated from the project's README
About noonien MCP server
server-noonien provides a decentralized knowledge graph memory for AI agents that synchronizes across multiple machines without a central server or database. It acts as a drop-in replacement for the official @modelcontextprotocol/server-memory, maintaining the same nine tools while adding specialized operations like update_*, merge_entities, and read_conflicts. This system is designed for developers who need their agents to share a consistent memory across different hosts via a local-first approach.
Users can choose between different synchronization methods depending on their infrastructure. The nooniend daemon enables peer-to-peer replication between nodes over a LAN or VPN using only IP reachability. Alternatively, the system supports file or S3 backends for those who prefer using a shared folder or object store. The server is typically spawned by an MCP client over stdio, while the noonien maintenance CLI handles tasks like importing existing JSONL files or exporting the folded graph as JSON snapshots.
What you can do with it
- 1Synchronize agent memory across machinesAn AI agent can share its knowledge graph with other agents on different computers using peer-to-peer replication.
- 2Migrate from official memory serversYou can transition your existing agent data to this system by importing a standard memory JSONL file.
- 3Prevent data loss during synchronizationThe system uses a CRDT model to ensure that multiple machines can write to the memory without causing merge conflicts.
Written from the project's README. Every use case is checked against a quote from it.
How to install noonien MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall noonien MCP in Claude Code
$ claude mcp add server-noonien -- npx -y server-noonienInstall noonien MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"server-noonien": {
"command": "npx",
"args": [
"-y",
"server-noonien"
]
}
}
}Install noonien MCP in VS Code
.vscode/mcp.json
{
"servers": {
"server-noonien": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"server-noonien"
]
}
}
}Install noonien MCP in VS Code CLI
$ code --add-mcp '{"name":"server-noonien","type":"stdio","command":"npx","args":["-y","server-noonien"]}'Install noonien MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"server-noonien": {
"command": "npx",
"args": [
"-y",
"server-noonien"
]
}
}
}Install noonien MCP in Codex
$ codex mcp add server-noonien -- npx -y server-noonienInstall noonien MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.server-noonien] command = "npx" args = ["-y", "server-noonien"]
Install noonien MCP in Gemini CLI
$ gemini mcp add -s user server-noonien npx -- -y server-noonienInstall noonien MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"server-noonien": {
"command": "npx",
"args": [
"-y",
"server-noonien"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for server-noonien 1.3.0 in an isolated container with no network and no keys. It answered and listed 21 tools.
noonien MCP tools 21
Read from the server with tools/listcreate_entitiesActionCreate multiple new entities in the knowledge graph. A name that already exists is skipped and left unchanged — use add_observations to extend it — and only the entities actually created are returned. Observations are stored exactly as given, duplicate contents included.
create_relationsActionCreate multiple new relations between entities in the knowledge graph. Relations should be in active voice. Both endpoints must already exist: one missing name fails the whole call with "Entity with name … not found". A relation that is already present is skipped, so the response lists only the ones added.
add_observationsActionAdd new observations to existing entities in the knowledge graph. Content the entity already holds is not added again, while duplicates within one request are kept as separate occurrences; the response reports what was added per entity. Every named entity must exist — a missing one fails the whole call, so create it with create_entities first. To replace a content use update_observations, to remove one use delete_observations.
update_entitiesActionPrefer this to deleting an entity and re-creating it under another name: rename existing entities and/or change their entity type, keeping their observations and relations. A rename onto a name that already exists is refused rather than merging the two; an unknown name is reported and the batch keeps its other entries.
update_observationsActionPrefer this to delete_observations followed by add_observations: replace observation contents on existing entities in place
update_relationsActionPrefer this to deleting a relation and creating another: change the type of existing relations and/or repoint their endpoints. Each entry is matched by its current from, to and relationType; a missing match is reported, not thrown, so the batch keeps its other entries.
merge_entitiesActionPrefer this to deleting one entity and re-adding its observations and relations to another: merge an entity into another, unioning their observations and repointing its relations. The target keeps its name; the absorbed entity is deleted. It cannot be undone, so pass dryRun first to see the observations joined, the relations repointed and the name that disappears; find_duplicates proposes pairs that look like the same thing.
delete_entitiesActionDelete multiple entities and their associated relations from the knowledge graph. Unknown names are ignored rather than failing, and the message reports how many were deleted and which were not found. The deletion also removes the entity's observations and its incident relations, and it is durable: a tombstone beats a concurrent write from another machine.
delete_observationsActionDelete specific observations from entities in the knowledge graph. Deletion is by content: every occurrence of that content on the entity goes. A batch is not all-or-nothing — the message reports how many were deleted and names the entities that were not found. To replace a content in place use update_observations; to remove the whole entity use delete_entities.
delete_relationsActionDelete multiple relations from the knowledge graph. A relation is matched by its from, to and relationType; one that matches nothing is ignored, and the message reports how many of the requested relations were deleted. Deleting an entity removes its incident relations with it, so this is for dropping one edge while both endpoints stay.
read_graphRead-onlyRead the knowledge graph, or a page of it: the optional limit and offset take a slice of the entities in name order. Use it for the whole graph; for a query use search_nodes, for names you already know use open_nodes, and for the elements more than one node wrote use read_conflicts. A page carries the relations that touch its entities. To read only what changed since your last visit, use read_changes.
search_nodesRead-onlySearch for nodes in the knowledge graph based on a query. The query is matched against entity names, types and observation content; entityType narrows to one exact type, and limit/offset page the matches in name order. For the whole graph use read_graph, and for names you already know use open_nodes. For a search written the way a query is spoken, use find_nodes: it matches whole words and ranks the results.
Show all 21 toolsShow fewer tools
open_nodesRead-onlyOpen specific nodes in the knowledge graph by their names. Names that do not exist are omitted rather than failing, and the result carries every relation touching the entities returned, including relations to entities outside it. Use it when the names are known; for a query use search_nodes, for everything use read_graph.
read_conflictsRead-onlyCall this when a write may have been superseded by another machine, or before trusting an edit: it lists the elements more than one node has written, with what each node left and when it last touched it, so a last-writer-wins resolution is visible instead of silent. Settle a contested element with resolve_conflict.
read_changesRead-onlyRead only what changed in a window you choose: the entities touched in it, as they are now, and the names deleted in it. Use it instead of read_graph when you are coming back to a memory you already know — the whole graph for two changed entities costs the context you came to use. The window reaches five minutes further back than you ask, so a change written by a peer with a slightly lagging clock is not lost, and reading the same window twice is harmless. It also returns until, the moment it stopped at, in this node's clock: pass that back as since and the next read continues from there.
find_nodesRead-onlySearch the graph the way a query is written, not as a literal string: every word must match, a word matches the beginning of a longer one, and the best matches come first. Use it instead of search_nodes when the query is more than one word, or when a word may be spelled differently — ports for port. search_nodes is the literal-substring search and stays for exactly that. A word that matches nothing makes the result empty rather than failing the call.
expand_nodesRead-onlyWalk out from the entities you name: every entity within depth hops, with the relations that touch them. Use it instead of read_graph to assemble the context around a topic, and instead of open_nodes when the neighbours' content matters as much as the entity you started from. The walk ignores direction, stops on cycles, and skips names that do not exist rather than failing. When limit binds, truncated is true and the farthest entities are the ones left out.
resolve_conflictActionSettle an element that more than one machine has written: keep it or drop it with a stamp newer than anything in the log, so the decision wins on every node as the change propagates. Use it after read_conflicts named the element and you have decided how it should stand — re-creating it with the existing tools is not enough, because a write that already exists is skipped, and deleting what is already tombstoned changes nothing. An element that already stands as you ask is left untouched and reported as unchanged, because every write is durable history. An observation needs the entity to exist, and a relation both of its endpoints, exactly as when they were created.
find_duplicatesRead-onlyPropose pairs of entities that may be the same thing, so merge_entities can be used on a pair you would not have noticed. With by: "name" the names are compared after case, spacing, punctuation and a known suffix such as .service are normalised, and overlapping observations raise the score; with by: "content" the observations are compared instead, which is how one fact written twice under two names is found. It is read-only. A score is a hint, not a verdict: read both entities before merging them.
read_historyRead-onlyShow what wrote an entity and when: the operations that touched it, newest first, with their timestamp, node and kind. Use it to tell a fact confirmed yesterday from one nobody has touched in months, which no other tool answers — read_conflicts covers only contested elements, and the graph itself carries no dates. For the current state use open_nodes; for what changed in a window use read_changes.
set_observationsActionKeep one fact current: write key: value on an entity, replacing every observation that key already holds, so a drifted twin cannot survive. Use it instead of update_observations when the value changes over time — a version, a status — and you should not have to remember its previous text. An observation belongs to a key when it is exactly the key or starts with the key, a colon and a space, and a key may not itself contain a colon followed by a space. A missing entity fails as add_observations does: create it with create_entities first.
Configuration
NOONIEND_PEERSNOONIEND_TAILSCALENOONIEN_BACKENDNOONIEN_DIRDirectory holding this machine's shards (default ~/.noonien).
NOONIEN_NODE_IDThis node's shard name (default the hostname). Must be unique per machine.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesequico/server-noonien is public and reachablegithub.com/sequico/server-noonien ↗Pass
- Package names this repository as its sourceserver-noonien names sequico/server-noonien as sourcenpmjs.com/package/server-noonien ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for server-nooniennpmjs.com/package/server-noonien/v/1.3.0#provenance ↗Pass
- Open source license (OSI)MPL-2.0spdx.org/licenses/MPL-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/sequico/server-noonien ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from server-noonienPass
- No critical advisory in the package or its dependencies30 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model21 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledDestructive tools carry destructiveHintPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubserver-noonien
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
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
- Comparison
- The three commands
- Share across machines
- Configuration
- How it works
- Tools
- Drop-in compatibility
- Security
- Development
- Why the name
noonien? - Documentation
- License & Disclaimer
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 servers 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
noonienddaemon — 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?fileands3work 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
memoryserver name with no agent changes — plus theupdate_*,merge_entitiesandread_conflictsextensions, the operations the official nine have no equivalent for.
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, plus extension 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:
npm install -g server-noonien
The s3 backend's @aws-sdk/client-s3 is an optional dependency, loaded only when
NOONIEN_BACKEND=s3 selects it. npm install -g server-noonien --omit=optional skips it when you
never use s3.
| 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:
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:
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:
npx -y server-noonien # the stdio command the client runs
claude mcp add memory -- npx -y server-noonien # register it with Claude Code as the `memory` server
Point your client at it; it works on one machine out of the box, and sharing across machines is the next step. In OpenCode (V2):
{
"$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 nine drop-in tools keep the same
names, inputs and outputs, 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 [--out <dir> --keep <n>] |
print the folded graph as JSON, or write a dated snapshot (graph-<ISO>.json) and delete the oldest beyond n (7 by default); --dry-run prints what it would do and a snapshot never clobbers another |
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 server's own rule: NOONIEN_GC; a daemon that owns the directory keeps the whole view and the shard) — and prune every *-import shard the directory holds |
noonien query <text> |
search entities and print the matching subgraph |
noonien stats |
count the graph, name the largest entities and list what nobody has confirmed in 90 days; --json emits the same numbers as one object |
noonien doctor |
verify the store — parse errors, torn lines, orphan relations, shards untouched for a week — and exit 1 on a defect. Read-only: it repairs nothing |
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) plus the daemon's
NOONIEND_* (Daemon variables). See Peer to
peer 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 (recommended)
The recommended way to share one memory across machines with no shared storage. nooniend is a
long-lived daemon that replicates the local shard directory peer to peer. It only needs IP
reachability, so it runs over any VPN (WireGuard, Tailscale, OpenVPN, Netbird, ZeroTier, …) or a
plain LAN.
Give each machine a unique node id and run one nooniend per machine. Every daemon keeps a
full replica of the others' shards beside its own, in the same local directory the MCP server uses —
no shared folder required:
# on a tailnet
NOONIEN_DIR=~/.noonien \
NOONIEND_TAILSCALE=true \
nooniend
# or, with no self-listing underlay, seed one reachable peer
NOONIEN_DIR=~/.noonien \
NOONIEND_PEERS=ai.example:49778 \
nooniend
The peers find each other — you never list the machines. Configure one discovery source:
NOONIEND_TAILSCALE (from tailscale status), NOONIEND_DNS_SRV (the _nooniend._tcp SRV
records), or NOONIEND_PEERS (a static seed; one is enough, membership then self-propagates).
A discovery source returns candidates, not members: a candidate joins only once it answers
/info, so a machine on the network that does not run nooniend is never adopted.
NOONIEND_ADVERTISE is optional and defaults to the listen host.
How it behaves:
- Never authors operations. Each node's MCP server writes only its own
<node>.jsonl; the daemon keeps replicas of the peers' shards and only ever pushes the shard it authors, so the single-writer rule holds. It also restores the local shard from a peer's replica when the local copy is behind. - Push on change + periodic anti-entropy. On a local change (
NOONIEND_PUSH) and everyNOONIEND_INTERVALseconds it compares the per-shard high-waterseqand moves the delta in whichever direction is behind. Operations are idempotent, so delivery may be best-effort — no consensus, no ordering, only eventual completeness. - Scales past a full mesh. By default it contacts every peer;
NOONIEND_FANOUTcaps that to a random subset per round — which excludes tombstone collection, because a reachable peer the round did not sample suspends it, so the daemon refuses that combination — and at or aboveNOONIEND_DIGEST_MIN_SHARDSit reconciles through a fixed-size digest instead of the full shard list (withNOONIEND_CHANNELSmoving membership onto its own channel). A small mesh keeps behaving exactly like a full mesh, and a peer without the digest capability falls back to the plain list, so a mixed mesh never breaks. - Relays. A node serves every replica it holds, so an offline node keeps converging through any peer that has its shard.
- Discovery and membership. Bootstrap adapters (Tailscale, DNS SRV, a static seed) return
candidates; the peer set then gossips itself. A static
node@host:portseed is explicit intent and enters membership directly; a bare address (a Tailscale or DNS-SRV candidate) joins only once it answers/info, and its id comes from that answer — never from the discovery source — so a device that does not runnooniendis never a member and never blocks collection. A node that comes up is adopted on its next probe, and the sources are re-read everyNOONIEND_DISCOVER_INTERVALseconds, so a joiner is found without a restart. Liveness comes from the exchange results — suspect afterNOONIEND_SUSPECT_AFTERfailures, dead afterNOONIEND_DEAD_AFTER, retried afterNOONIEND_DEAD_RETRY, and forgotten afterNOONIEND_MEMBERSHIP_TTL. A peer that reaches this node is marked alive — its certificate names it under mTLS, otherwise the id it announces on the request — so a peer that recovers is re-engaged at once instead of waiting outNOONIEND_DEAD_RETRY. A caller that is not a peer yet is never adopted from its headers: nothing it sends becomes membership, and its id is never taken on trust. It is offered as a discovery candidate instead — the host the request came from, the port it announces — and the daemon confirms it on/info, exactly like a Tailscale or DNS candidate. That is how a statically-seeded joiner is discovered by the seeds it reached, within a round, and why an address announced for a different host is never even probed. A node's own entry is authoritative; an address that serves a different node is dropped. - Wire and security. A small HTTP/JSON service bound to
NOONIEND_LISTEN(the full wire contract is indocs/protocol.md); a shard accepts only its own node's operations. mTLS with per-peer certificates: the certificate's common name is the node id, so a peer may only push the shard it authors, while reads stay open to any authenticated peer — which is what lets a node relay.NOONIEND_REVOKEDrefuses specific nodes on every route;NOONIEND_DEPARTEDadditionally discards a departed node's replica and lets collection proceed past it. - Observability. Prometheus metrics — liveness, peer health, the stable watermark and, for
collection, how long each peer has been away (
noonien_gossip_absent_seconds) and how many deleted elements are frozen (noonien_gossip_frozen_elements) — plus a per-shard stable watermark (the minimum high-water mark reached on every contactable peer, a conservative causal-stability bound), and status and graph routes for probes and operators — see The daemon HTTP API.
Under systemd, a user unit:
[Unit]
Description=nooniend — peer-to-peer shard replication
After=network-online.target
[Service]
EnvironmentFile=%h/.config/noonien/nooniend.env
ExecStart=%h/.local/bin/nooniend
Restart=on-failure
[Install]
WantedBy=default.target
The daemon HTTP API
nooniend serves a small HTTP/JSON API on NOONIEND_LISTEN (default 0.0.0.0:49778). The full wire
contract — routes and payloads, the operation format, the protocol revision and capabilities, the
size limits and the mTLS model — is specified in docs/protocol.md.
curl -s http://127.0.0.1:49778/health
curl -s http://127.0.0.1:49778/status
curl -s http://127.0.0.1:49778/peers
curl -s http://127.0.0.1:49778/graph | jq '{entities: (.entities|length), relations: (.relations|length)}'
/graph folds everything the node holds, so it is a diagnostic for a normal directory: past 50 000
operations it answers 413 and asks for the shards instead, which serve the same data a page at a
time.
Shared area — file and s3
The file and s3 backends converge through a shared area that already exists and is
replicated outside noonien — a folder or a bucket every node can reach. Point every node at the
same area and each node's shard reaches the others:
NOONIEN_BACKEND=file NOONIEN_DIR=/srv/noonien-shared NOONIEN_NODE_ID=ai server-noonien
# or
NOONIEN_BACKEND=s3 NOONIEN_S3_BUCKET=my-bucket NOONIEN_NODE_ID=ai server-noonien
file— shards are*.jsonlfiles inNOONIEN_DIR; point it at a folder replicated by Syncthing, Dropbox, a git working tree or a shared mount.s3— one object per shard, written with conditional writes retried on contention, waiting the same budget thefilebackend gives a lock, so a competing writer on one node id costs a wait rather than a failed write; uses@aws-sdk/client-s3(an optional dependency, loaded only when selected). Conditional writes need a store that honoursIf-Match/If-None-MatchonPutObject(AWS S3, Cloudflare R2, MinIO do); a store that ignores them is not supported, and a conditional write carrying an ETag the store cannot use — none, or a multipart one — is refused rather than guarded by a token that can never match. Reading is not conditional: a shard object with a multipart ETag reads and stats normally. An object store has no append, so every mutation rewrites the whole shard object (read-modify-write): correct, but O(shard size) per write.
The memory backend keeps shards in process only — for tests and throwaway sessions. See
Configuration for the variables.
What a shared area does not give you: a safe deletion. file/s3 share a graph; they cannot
say whether a peer holds a write it has not delivered yet. So without a daemon the maintenance
prunes only, and a physical deletion happens only where the operator declares the directory
written by this node alone (NOONIEN_GC) — see Deletion and
collection. Convergence is delegated to the syncer as well: noonien
neither verifies nor retransmits, so latency and conflict copies are the syncer's business, and a
conflict copy is just another shard to fold. And the daemon replicates a directory: nooniend
refuses to run with NOONIEN_BACKEND=s3 (or memory), where it would replicate a local folder the
server never uses.
noonien MCP questions
How do I add noonien MCP to Claude Code?
Run claude mcp add server-noonien -- npx -y server-noonien in your terminal. Add --scope user to make it available in every project.
How do I add noonien MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does noonien MCP provide?
It exposes 21 tools, including create_entities, create_relations, add_observations, update_entities, update_observations.
Is it compatible with the official MCP memory server?
Yes, it is a drop-in replacement that uses the same nine tools, inputs, and outputs, allowing it to slot in without agent changes.
Does it require a central database or cloud account?
No, it is a local-first solution that requires no central server, no database, and no cloud account.
Can I use it offline?
Yes, every node keeps a full local replica and writes to its own shard on disk, allowing it to work offline and reconverge when the network returns.