ZenBrain Memory

Name: ZenBrain Memory
Author: zensation.ai

本地服务

zensation.ai记忆与知识271 周前更新

代码仓库访问官网

关于 ZenBrain Memory

ZenBrain Memory 是面向 AI Agent 的 MCP 服务，用于保存跨会话记忆。它以本地 SQLite 文件管理五类记忆，不需要账户或网络调用；默认按词汇重合检索，不调用 LLM。

主要功能

01五层记忆存储与检索
02按内容启发式自动路由
03合并情景记忆为语义事实
04按 ID 和层级删除记忆
05SQLite 本地存储，无账户

适用场景

01为 AI Agent 保留跨会话信息
02检索经历、事实、流程与核心记忆
03清理工作记忆或更正长期记忆

MCP 相关

该 MCP 服务通过 stdio 为 MCP 客户端提供五个记忆工具：存储、检索、删除、合并和查看状态。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "ai-zensation-zenbrain": {
      "command": "npx",
      "args": [
        "-y",
        "@zensation/mcp"
      ],
      "env": {
        "ZENBRAIN_DB": "<ZENBRAIN_DB>",
        "ZENBRAIN_CONTEXTS": "<ZENBRAIN_CONTEXTS>"
      }
    }
  }
}

启动命令npx -y @zensation/mcp

需要配置的环境变量

ZENBRAIN_DBPath to the SQLite file that holds the memory. A leading ~/ means your home directory; a relative path depends on where the client starts the server (some start it in /), so give an absolute or ~/ path. Use ':memory:' for a store that is discarded when the process exits.

ZENBRAIN_CONTEXTSComma-separated context domains, passed to the cross-context layer. No tool uses that layer yet, so the value currently has no effect.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@zensation/mcp0.3.0stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
type	enum	否	路由提示。'auto'（默认）根据内容决定。auto \| fact \| episode \| procedure \| core
steps	array	否	过程的有序步骤。可选：如果未提供，则从内容中提取步骤（编号或项目符号行；否则将每行视为一步）。
tools	array	否	过程使用的工具。
source	string	否	来源，例如 'user'、'ai'、'import'。
content	string	是	要存储的记忆，使用自然语言描述。
context	string	否	上下文领域，例如 'work'、'personal'、'learning'。
outcome	string	否	过程实现的目标。
confidence	number	否	确定程度（0–1）。高于 0.9 时归入核心记忆。
emotionalWeight	number	否	情感显著性（0–1）。省略时根据内容检测。高于 0.5 时归入情景记忆。

详细介绍

@zensation/mcp

状态：早期版本。 工具范围刻意保持精简，1.0 版本发布前仍可能有所变化。底层的记忆层与 ZenBrain 论文所述的相同，基准测试对这些记忆层进行了测量。

一个 MCP 服务，可为任何 MCP 客户端——Claude Desktop、Claude Code、Cursor，或你自己的客户端——提供一种能够跨对话留存的记忆。

五个工具，一个本地 SQLite 文件，无需账号，也不会发起网络请求。

工具	功能
`zenbrain_store`	将内容写入长期记忆。路由会自动进行，按首次匹配原则处理：`steps` 或“How to”“Steps:”和“workflow:”等措辞会创建一条流程；情感权重高于 0.5 时会创建一段情景记忆；置信度高于 0.9 时会创建一条固定核心记忆；其他内容则作为语义事实。每次调用都会新增一条记忆；再次存储相同的核心记忆时，会更新原有记忆。
`zenbrain_recall`	在情景、语义、流程和核心记忆层中搜索与查询相关的内容；只有在指定工作记忆时才会搜索该层。结果按 0 到 1 的分数排序，每条结果都包含其 id 和所属层；若某层没有匹配项，则会返回近期的情景记忆和事实，或该层最成功的流程，分数为 0，排在所有命中项之后；`minScore` 大于 0 时则不会返回这些结果。每个核心记忆块的分数为 0.5 或 0.8。
`zenbrain_forget`	根据 `zenbrain_recall` 返回的 id 和所属层永久删除一条记忆，并一并删除整合时与之关联的内容：删除一段情景记忆时会删除由此生成的事实；删除此类事实时会删除整合到该事实中的所有情景记忆；两种情况都会删除该内容在工作记忆中的副本。`alsoForgotten` 会列出一并删除的内容。单独存储且从未整合过的记忆会保留其长期记忆条目（召回结果中的 `duplicates` 会列出这类副本）；请删除长期记忆结果，而不要删除工作记忆槽位，因为它只是副本。若要更正一条记忆，请先删除，再存储更正后的版本。
`zenbrain_consolidate`	执行一轮维护：在最近的 100 段情景记忆中，情感权重高于 0.5 的内容会转为语义事实，且仅转换一次；工作记忆槽位会衰减，相关度为 0.01 或更低的槽位会被移除。不会删除长期记忆中的内容。
`zenbrain_health`	查看各层的占用情况：正在使用的槽位数、情景记忆数、事实数及待复查的事实数、流程数和核心记忆块数。

安装

需要 Node.js 22 或更高版本。

npm install -g @zensation/mcp

配置客户端

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

变量	默认值	含义
`ZENBRAIN_DB`	`./zenbrain.db`	SQLite 文件的路径。以 `~/` 开头表示你的主目录。相对路径相对于客户端启动服务时所在的目录；某些客户端（包括 Claude Desktop）可能会在 `/` 目录中启动，而该目录不可写，因此请使用绝对路径或以 `~/` 开头的路径。`:memory:` 表示使用进程退出时即会丢弃的存储。
`ZENBRAIN_CONTEXTS`	`personal,work,learning,creative`	以逗号分隔的上下文域，会传递给跨上下文层。目前五个工具都不会使用该层，因此此值暂时不起作用。

该服务通过标准输入输出（stdio）使用 MCP 协议。标准输出仅承载协议通信；诊断信息会写入标准错误。

七层结构

存储不等于归档。记忆存入哪一层，决定了它如何被检索，以及整合会如何处理它。五个工具可访问工作记忆、情景记忆、语义记忆、程序记忆和核心记忆；短期记忆只会作为计数器出现在 zenbrain_health 中，跨上下文记忆则未接入任何工具。

	层级	内容
7	跨上下文记忆	不同领域实体之间的关联（实验性；没有工具使用它）
6	核心记忆	固定事实
5	程序记忆	“如何做 X”——技能和工作流
4	长期语义记忆	事实，采用 FSRS 调度
3	情景记忆	具体经历和事件
2	短期／会话记忆	当前对话上下文
1	工作记忆	当前任务焦点，7±2 项

长期记忆中的任何内容都不会自行衰减或删除；只有工作记忆会衰减。每条事实都会获得 FSRS 复习计划，但没有工具会报告复习，因此通过此服务无法推进计划。情绪权重决定路由方式（高于 0.5：归为情景记忆），也决定整合会将哪些情景转化为事实。算法位于 @zensation/algorithms 中，可逐行阅读。

此服务未配置任何大模型提供商，因此其中没有任何内容会调用模型：存储时的路由采用内容启发式规则，整合则在不生成摘要的情况下运行。

此版本不支持的功能

接入前值得了解：

**默认未配置嵌入提供商，因此检索依靠词法匹配，而非语义匹配。**没有向量时，检索会根据折叠后的词元重叠度排序——变音符号和重音符号会折叠处理，较少见的词权重更高，相邻短语优于分散出现的相同词语。它能在一条关于 “Kieler Förde” 的笔记中找到 “Kieler Foerde”，但无法将 “car” 和 “automobile” 关联起来。情景记忆和事实会在各自最近的 500 条中排序，程序记忆则会在成功率最高的 500 条中排序。如果某一层没有匹配查询的内容，就会返回最近的情景记忆和事实，或最成功的程序，score: 0，排在所有匹配项之后；每个核心记忆块的分值为 0.5 或 0.8，因此其排名可能高于分值较低的匹配项。请求工作记忆时，也会采用相同的排序方式。通过库传入 EmbeddingProvider，即可实现真正的语义匹配——已发布基准测试所使用的就是这种配置。
**SQLite 相似度搜索会进行全表扫描。**对于一个人的记忆来说足够用；数据量较大时请使用 @zensation/adapter-postgres。
**整合需要通过工具调用，不会按计划自动执行。**没有任何机制会替你运行它。
**存储文件是普通文件。**它未加密。请将它放在适合存放笔记本的地方。服务运行期间，SQLite 会在其旁边保留 -wal 和 -shm 文件。

作为库使用

服务工厂已导出，因此你可以在自己的服务上挂载 ZenBrain 的工具，或在测试中调用这些工具。该软件包使用 ESM；Node 22.12 及更高版本中的 require() 可以加载它（Node 22.0–22.11 请使用 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);
// connect it to any transport you like — the caller owns the coordinator's lifecycle

零依赖，以及它的边界

@zensation/algorithms 和 @zensation/core 除彼此之外不依赖任何内容。每次推送时都会在 CI 中根据打包后的 tarball 检查这一点，而非检查源代码树：检查脚本。

**此软件包特意不纳入这一边界。**MCP 服务需要协议 SDK，因此此软件包包含了该 SDK。将它单独放在一个软件包中，才能让核心保持干净：安装 @zensation/core 绝不会引入 MCP SDK，而安装此软件包也不会削弱核心所作的零依赖声明。

关于 ZenBrain

ZenBrain 是一种源自神经科学的七层大模型 Agent 记忆架构，使用 TypeScript 构建，并以 Apache-2.0 许可发布；@zensation/algorithms 和 @zensation/core 没有第三方依赖项。基准测试结果及其测量时使用的配置已在论文中报告；复现所需的软件包托管在 Zenodo 上。

开箱即用，无需嵌入提供方——采用词法排序，无需额外安装。在论文中，ZenBrain 与其他系统进行的基准测试使用 nomic-embed-text 作为嵌入提供方；检索消融实验使用了 OpenAI 的 text-embedding-3-small。