# noonien MCP server

> Provides a shared, conflict-free knowledge graph memory for AI agents using peer-to-peer synchronization.

- Repository: https://github.com/sequico/server-noonien
- Page: https://hostedmcp.org/servers/sequico/server-noonien
- Transport: stdio
- Stars: 3
- License: MPL-2.0
- Latest version: 1.3.0

## Install

### Claude Code

```sh
claude mcp add server-noonien -- npx -y server-noonien
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "server-noonien": {
      "command": "npx",
      "args": [
        "-y",
        "server-noonien"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "server-noonien": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "server-noonien"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"server-noonien","type":"stdio","command":"npx","args":["-y","server-noonien"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "server-noonien": {
      "command": "npx",
      "args": [
        "-y",
        "server-noonien"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add server-noonien -- npx -y server-noonien
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.server-noonien]
command = "npx"
args = ["-y", "server-noonien"]
```

### Gemini CLI

```sh
gemini mcp add -s user server-noonien npx -- -y server-noonien
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "server-noonien": {
      "command": "npx",
      "args": [
        "-y",
        "server-noonien"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `NOONIEND_PEERS` | no | no |  |
| `NOONIEND_TAILSCALE` | no | no |  |
| `NOONIEN_BACKEND` | no | no |  |
| `NOONIEN_DIR` | no | no | Directory holding this machine's shards (default ~/.noonien). |
| `NOONIEN_NODE_ID` | no | no | This node's shard name (default the hostname). Must be unique per machine. |

## Tools (21)

- `create_entities`: Create 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_relations`: Create 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_observations`: Add 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_entities`: Prefer 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_observations`: Prefer this to delete_observations followed by add_observations: replace observation contents on existing entities in place
- `update_relations`: Prefer 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_entities`: Prefer 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_entities`: Delete 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_observations`: Delete 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_relations`: Delete 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_graph`: Read 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. (read-only)
- `search_nodes`: Search 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. (read-only)
- `open_nodes`: Open 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-only)
- `read_conflicts`: Call 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-only)
- `read_changes`: Read 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. (read-only)
- `find_nodes`: Search 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. (read-only)
- `expand_nodes`: Walk 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. (read-only)
- `resolve_conflict`: Settle 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_duplicates`: Propose 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-only)
- `read_history`: Show 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. (read-only)
- `set_observations`: Keep 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.

## FAQ

### 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.
