@zensation/mcp
Status: early release. The tool surface is small on purpose and may still
change before 1.0. The memory layers underneath it are the same ones the
ZenBrain paper describes and the
benchmarks measure.
An MCP server that gives any MCP client — Claude
Desktop, Claude Code, Cursor, or your own — a memory that survives the conversation.
Five tools, one local SQLite file, no account and no network call.
| Tool | What it does |
|---|
zenbrain_store | Write something into long-term memory. Routing is automatic, first match wins: steps or wording such as "How to", "Steps:", "workflow:" make a procedure, an emotional weight above 0.5 an episode, a confidence above 0.9 a pinned core memory, anything else a semantic fact. Each call adds a memory; the same core memory stored again is updated. |
zenbrain_recall | Search the episodic, semantic, procedural and core layers for what is relevant to a query; working memory only when you name it. Results come back sorted by score, each with its id and the layer it came from; each layer scores differently, so a procedure or core block that does not match can rank above a real hit. |
zenbrain_forget | Delete one memory for good, by the id and layer zenbrain_recall returned. Only that memory is deleted: a fact that consolidation made from an episode, and the working-memory copy of a recent store, stay — recall again and forget what still returns the content. To correct a memory, forget it and store the corrected version. |
zenbrain_consolidate | One maintenance pass: among the 100 most recent episodes, each with an emotional weight above 0.5 becomes a semantic fact, only once; working-memory slots decay, and those at a relevance of 0.01 or below are removed. Deletes nothing from long-term memory. |
zenbrain_health | How full each layer is: slots in use, episodes, facts and how many are due for review, procedures, core blocks. |
Install
Requires Node.js 22 or newer.
npm install -g @zensation/mcp
{
"mcpServers": {
"zenbrain": {
"command": "npx",
"args": ["-y", "@zensation/mcp"],
"env": {
"ZENBRAIN_DB": "~/.zenbrain/memory.db"
}
}
}
}
| Variable | Default | Meaning |
|---|
ZENBRAIN_DB | ./zenbrain.db | Path to the SQLite file. A leading ~/ means your home directory. A relative path is relative to the directory your client starts the server in — some clients, Claude Desktop among them, may start it in /, where nothing can be written — so give an absolute or ~/ path. :memory: gives a store that is discarded when the process exits. |
ZENBRAIN_CONTEXTS | personal,work,learning,creative | Comma-separated context domains, passed to the cross-context layer. None of the five tools uses that layer yet, so the value currently has no effect. |
The server speaks MCP over stdio. Stdout carries protocol traffic only; diagnostics go
to stderr.
The seven layers
Storing is not filing. Which layer a memory lands in decides how it is retrieved and what
consolidation does with it. The five tools reach working, episodic, semantic, procedural and
core memory; short-term memory shows up only as a counter in zenbrain_health, and
cross-context memory is not wired to any tool.
| Layer | Holds |
|---|
| 7 | Cross-Context Memory | Links between entities of different domains (experimental; no tool uses it) |
| 6 | Core Memory | Pinned facts |
| 5 | Procedural Memory | "How to do X" — skills and workflows |
| 4 | Long-Term Semantic | Facts, with FSRS scheduling |
| 3 | Episodic Memory | Concrete experiences and events |
| 2 | Short-Term / Session | Current conversation context |
| 1 | Working Memory | Active task focus, 7±2 items |
Nothing in long-term memory decays or is deleted on its own; only working memory decays.
Every fact gets an FSRS review schedule, but no tool reports a review, so through this
server the schedule is not advanced. Emotional weight decides routing (above 0.5: an
episode) and which episodes consolidation turns into facts. The algorithms are in
@zensation/algorithms and can be
read line by line.
This server configures no LLM provider, so nothing in it calls a model: routing on
store is a content heuristic, and consolidation runs without generated summaries.
What this release does not do
Worth knowing before you wire it in:
- No embedding provider is configured by default, so recall is lexical, not semantic.
Without vectors, recall ranks by folded token overlap — umlauts and accents are folded,
rarer words weigh more, and an adjacent phrase beats the same words scattered. It will
find "Kieler Foerde" in a note about the "Kieler Förde"; it will not connect "car" to
"automobile". Episodes and facts are ranked over the most recent 500 of each, procedures
over the 500 with the highest success rate. A query that matches nothing returns recent
episodes and facts with
score: 0 but procedures by success rate, with that rate as
score, and every core block comes with 0.5 or 0.8 — so these can rank above a real hit.
Working memory, when you ask for it, ignores the query. Pass an EmbeddingProvider
through the library for true semantic matching — that is the configuration the published
benchmarks were measured with.
- SQLite similarity search is a full scan. Fine for one person's memory; use
@zensation/adapter-postgres
for larger volumes.
- Consolidation is a tool call, not a schedule. Nothing runs it for you.
- The store is a plain file. It is not encrypted. Put it somewhere you would put a
notebook. While the server runs, SQLite keeps
-wal and -shm files next to it.
Using it as a library
The server factory is exported, so you can mount ZenBrain's tools on a server of your own
or drive them in tests. The package is ESM; require() loads it on Node 22.12 and later (on 22.0–22.11, use import).
import { createZenBrainServer } from '@zensation/mcp/server';
import { MemoryCoordinator } from '@zensation/core';
import { SqliteAdapter } from '@zensation/adapter-sqlite';
const coordinator = new MemoryCoordinator({
storage: new SqliteAdapter({ filename: './memory.db' }),
});
const server = createZenBrainServer(coordinator);
Zero-dependency, and where that stops
@zensation/algorithms and @zensation/core pull nothing but each other. That claim is
checked in CI on every push
against the packed tarballs, not against the source tree.
This package is deliberately outside that boundary. An MCP server needs the protocol
SDK, so it carries one. Keeping it in its own package is what lets the core stay clean:
installing @zensation/core never pulls the MCP SDK, and installing this never weakens
the claim the core makes.
About ZenBrain
ZenBrain is a seven-layer, neuroscience-derived memory architecture for LLM agents, built in
TypeScript and published under Apache-2.0; @zensation/algorithms and @zensation/core have no third-party
dependencies. The benchmark results, and the
configuration they were measured in, are reported in the paper; the reproduction packages
are on Zenodo.
Works out of the box without an embedding provider — lexical ranking, nothing extra
to install. The paper's measurements used nomic-embed-text as the embedding provider.
License: Apache-2.0