# ZenBrain Memory [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/zensation-ai/zenbrain  
**GitHub Stars:** 27  
**npm Downloads (last month):** 1611  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/zenbrain-memory

## Description
Seven-layer agent memory: episodic, semantic, procedural and core. Local SQLite, no account.

## Tools
Capabilities this server exposes over MCP:

- **zenbrain_store** — Write something into long-term memory so it survives this conversation. Routing is automatic by default, first match wins: `steps`, or wording such as "How to", "Steps:" or "workflow:", make a procedure; an emotional weight above 0.5 (detected, or set via `emotionalWeight`) an episode; a `confidence` above 0.9 a pinned core memory; anything else a semantic fact. Set `type` only when you want to override that. Every call adds a new memory, except that storing the same core memory again updates it; the content is also kept in working memory (the most recent seven) while the server runs, so once seven are held each store replaces the oldest copy there. Long-term memory is never changed by a store. Returns the id of the stored memory. If it may already be stored, check with zenbrain_recall first: storing it again adds a duplicate.
- **zenbrain_recall** — Search long-term memory for anything relevant to a query. By default it searches the episodic, semantic, procedural and core layers; working memory (the most recent stores, held only while the server runs, up to five results) is searched only when named in `layers`. Returns results sorted by score, each with its id and the layer it came from; zenbrain_forget takes both. The score runs from 0 to 1 and says how well a result matches the query; a layer in which nothing matches returns recent memories (or its most successful procedures) at 0, behind every hit, and minScore above 0 leaves them out. Every core block scores 0.5 or 0.8, so a block can rank above a weak hit. Use this before answering when the user refers to something from an earlier session. To see how much is stored rather than what, use zenbrain_health; to save something, use zenbrain_store.
- **zenbrain_forget** — Permanently delete a memory, addressed by the id and layer that zenbrain_recall returned for it, together with what consolidation linked to it; this cannot be undone. Forgetting an episode also deletes the fact zenbrain_consolidate made from it; forgetting such a fact also deletes every episode consolidated into it; both also delete the working-memory copies of that content. Forgetting a working-memory result deletes only that copy. alsoForgotten lists everything deleted besides the memory itself. A memory stored on its own and never consolidated keeps its long-term entry. Use it when the user asks to forget something or a stored memory is wrong; to correct a memory, forget it and store the corrected version with zenbrain_store. An id the layer does not hold is reported as not forgotten, not as an error.
- **zenbrain_consolidate** — Run one consolidation pass: among the 100 most recent episodes, each one with an emotional weight above 0.5 becomes a semantic fact — once, however often the pass runs. Working-memory slots lose relevance with age, and slots whose relevance has dropped to 0.01 or below are removed; that is the only deletion, and nothing in long-term memory is deleted. Run it between sessions or after a batch of zenbrain_store calls, not on every turn; compare zenbrain_health before and after to see the effect.
- **zenbrain_health** — Report how full the memory layers are: working-memory slots in use, interactions held, episodes, facts and how many are due for review, procedures, core blocks. Read-only and cheap, safe to call at any time. It returns counts only; to read the memories themselves, use zenbrain_recall.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "zenbrain-memory": {
    "command": "npx",
    "args": ["-y","@zensation/mcp"],
    "env": {
      "ZENBRAIN_DB": ""
    }
  }
}
```

**Requires environment variables:** `ZENBRAIN_DB` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What ZenBrain Memory does

ZenBrain Memory gives MCP-compatible agents memory that persists beyond a single conversation. Its architecture divides memory into seven layers, spanning short-lived working context and longer-lived facts and procedures. The exposed system is based on the ZenBrain project, whose broader implementation includes episodic, semantic, procedural, and core memory.

The package is designed for local, self-hosted use. Memory can be kept in SQLite, with PostgreSQL also supported by the underlying project. No user account is required, and the library makes no network calls of its own. An embedding model or an LLM can be added separately, but neither is required for the basic system.

## How it works

Agents interact with the memory system through MCP. Stored information remains available across sessions instead of disappearing when a conversation ends. Retrieval works without an embedding provider through lexical ranking; an embedding provider such as `nomic-embed-text` can be added when semantic embeddings are wanted.

ZenBrain also contains 20 algorithm modules: 10 core algorithms and 10 advanced research modules. These implement memory-related mechanisms described by the project, including spaced repetition, Hebbian strengthening, emotional tagging, forgetting curves, and sleep replay. The algorithms and core are written in TypeScript without third-party dependencies.

## Setup and configuration

The MCP package can be launched with `npx` and configured with the `ZENBRAIN_DB` environment variable. A Claude Code installation using a user-scoped server looks like this:

```bash
claude mcp add --scope user zenbrain -e ZENBRAIN_DB=~/.zenbrain/memory.db -- npx -y @zensation/mcp
```

The value of `ZENBRAIN_DB` identifies the SQLite database used for memory. The underlying library targets Node.js 22 or newer. The same MCP server can be configured for Claude Desktop and Cursor.

## Tools and capabilities

- Persist agent memory across sessions
- Organize memory across seven layers
- Store episodic, semantic, procedural, and core information
- Retrieve memories using lexical ranking without an embedding service
- Apply memory algorithms such as spaced repetition and sleep replay
- Use SQLite locally or operate memory storage through PostgreSQL in the broader project

## Limitations and notes

ZenBrain is pre-1.0, so its public API may change before the 1.0 release. The open-source packages provide the algorithm library and hooks for the broader architecture; six Predictive Memory Architecture components used in the production ZenAI system are proprietary and are not included.

Embedding models and LLMs are optional rather than bundled requirements. Without an embedding provider, retrieval uses lexical ranking. The project’s published benchmark measurements were taken with a Python port in a test harness rather than directly with these packages, so those figures should not be treated as measurements of this MCP server.

_Full upstream README: https://allmcps.com/mcp/zenbrain-memory/readme_