Norn

Norn

为 AI 编码 Agent 提供持久、可见的记忆。

在线网站 · 发行版本 · 快速入门 · 连接 AI 工具

你的 AI 每次会话结束都会忘记你。Norn 是一个本地 MCP 服务，可在每次会话和项目中记住你的决策、偏好和项目背景，适用于 Claude Code、Cursor 和任何 MCP 客户端。与大多数记忆工具不同，它完全本地运行且内容完全可查看：你可以通过仪表板准确查看它存储的内容，并忘记任何不需要的内容。

快速入门

**所需条件：**只需 Node.js 20 或更高版本——无需单独安装 Norn，下面的命令会自动获取它。运行 node --version 检查；如果未安装或版本低于 v20，请从 nodejs.org 下载 LTS 版本。

连接到 Claude Code——只需一条命令，无需克隆：

claude mcp add norn -- npx -y @samad001z/norn-server

或在终端中使用 CLI——按需运行，或安装 norn 命令：

npx @samad001z/norn-core list           # no install — npx fetches it each time
npm install -g @samad001z/norn-core     # or put the `norn` command on your PATH

其他任何 MCP 客户端——将以下内容添加到其 MCP 配置中：

{
  "mcpServers": {
    "norn": {
      "command": "npx",
      "args": ["-y", "@samad001z/norn-server"]
    }
  }
}

重启你的工具。Norn 会注册四个工具：remember、recall、forget、list。

**可选——标记可能的冲突：**在上面的配置中添加 "env": { "NORN_DETECT_CONFLICTS": "1" } ，Norn 就会显示可能互相矛盾的记忆，供你在仪表板中处理。此功能默认关闭；首次发现候选项时会下载一个小型额外模型，而且绝不会自行更改你的存储内容。

不确定配置该放在哪里？《将 Norn 连接到你的 AI 工具 》指南提供了适用于 Claude Desktop、Cursor、Windsurf、 VS Code + GitHub Copilot 和 Gemini CLI 的精确复制粘贴式设置说明，还包含面向新手的“所需条件”介绍 和故障排查。（VS Code + Copilot 使用 servers 键，而不是 mcpServers。）

**验证是否已连接：**告诉你的助手 “记住我更喜欢 pnpm，而不是 npm。”，然后在新聊天中询问 “我更喜欢哪个包管理器？”——它应该会调用 Norn 的 recall 工具，回答 pnpm。

首次调用 remember 或 recall 时会下载一个本地嵌入模型 （all-MiniLM-L6-v2，约 25 MB），之后即可完全离线运行。

git clone https://github.com/samad001z/Norn.git
cd Norn
npm install
npm run build -w @samad001z/norn-core && npm run build -w @samad001z/norn-server
claude mcp add norn -- node "$(pwd)/server/dist/index.js"

查看效果

记忆会跨会话保留，且检索基于语义：匹配的是含义，而非关键词。

会话 1

你：记住，我们通过 Vercel 从 main 分支部署到生产环境。

Claude 调用 remember("deploy to production from the main branch on Vercel", project: "acme")

会话 2，第二天，在全新的上下文窗口中

你：我们如何发布到生产环境？

Claude 调用 recall("how do we ship to prod")

即使查询与存储的笔记没有共同关键词，Norn 仍会返回“通过 Vercel 从 main 分支部署到生产环境。”

使用 memory：显式操作，而非自动记录

Norn 不会记录你的会话。它是一个记忆存储，而不是日志记录器——绝不会在你不知情的情况下捕获你的提示词、代码编辑或终端命令。只有 Agent 调用 remember() 时才会创建记忆，这有两种情况：

• 你提出要求。 “记住，我们从 main 部署到 Vercel。” Agent 会调用 remember(...) 并保存这条记忆。
• **Agent 自行决定，**在它判断某条信息值得留到下次会话时——比如一项决定、一种偏好或一条约束。

这正是关键：由你决定保留什么，这样存储的内容才是有用信息，而非杂音。反过来说，如果你从不提出要求，就不会保存任何内容——因此，长时间工作后仪表板内容稀少是正常的，并非故障。实际工作保存在 git 中；Norn 用于存储你希望日后回想起来的重要信息。

以下几个习惯能让它发挥更大作用：

• 结束任务时说 “记住这次的关键决定”，Agent 就会将其记录下来。
• 提前一次性提供上下文——“记住我的技术栈和约定”——而不是每次会话都重新粘贴。
• 询问 “关于 X，你记得什么？”，让 Agent 按需调用 recall()。

所有以这种方式保存的内容都会显示在仪表板中，你也可以删除其中任何内容。

工作原理

三个本地组件共用一个本地数据库：

Claude Code / Cursor  ──MCP (stdio)──►  Norn MCP server  ┐
                                                          ├──►  ~/.norn/norn.db
        Dashboard (Next.js)  ────────────────────────────┘     (SQLite + sqlite-vec)

• MCP 服务（/server）：通过 stdio 提供 remember、recall、forget、list。
• 存储（/core）：使用 SQLite 和 sqlite-vec，嵌入由本地 MiniLM 模型生成 （无需 API 密钥）。recall 会综合语义相似度和时间近近性，并按令牌预算裁剪结果；remember 会对高度相似的记忆去重。
• 仪表板（/web）：用于浏览和管理所有内容的 Next.js 应用。

三个组件都会解析到同一个存储，因此 Agent 写入的记忆会显示在仪表板中，而你在仪表板中删除的记忆对 Agent 也同样不可用。存储按以下顺序选择：

1. 如果设置了 NORN_DB_PATH，则使用该路径——显式指定的路径始终优先。
2. 从工作目录向上查找最近的项目本地 .norn/norn.db（参见按项目划分的记忆）。
3. 全局路径 ~/.norn/norn.db。

如果没有项目存储，也没有显式指定路径，则采用原有行为：使用单个全局数据库 ~/.norn/norn.db。

按项目划分的记忆

为仓库创建专属记忆，并随仓库一同保存。在项目根目录运行：

npx @samad001z/norn-core init   # or: norn init

这会创建一个 .norn/ 目录，其中保存该项目的 norn.db。由于每个项目都有自己的数据库文件，不同项目间的记忆不会相互混杂：在某个仓库中工作的 Agent 只能看到该仓库的记忆。

如何检测项目

Norn 会像 git 一样查找项目——从工作目录向上遍历，直到找到最近的、包含 .norn/ 目录的祖先目录。在仓库内任意位置运行 Agent（或 CLI），都会解析到同一个存储。存储按以下顺序选择：

1. NORN_DB_PATH，如果已设置——显式指定的路径始终优先。
2. 从工作目录向上查找最近的项目本地 .norn/norn.db。
3. 全局路径 ~/.norn/norn.db——不存在项目存储时采用的原有行为。

即使没有运行 norn init，不同项目在共享的全局存储中仍会相互隔离：每条记忆都会标记其写入时所在的项目根目录（即 scope，由最近的 .git/.norn 祖先目录推导而来，与自由填写的项目标签不同），并且 recall 只会返回当前项目的记忆和全局记忆。独立的数据库文件是主要隔离方式；scope 标记则为共享存储提供了额外保护。

与仓库一起提交记忆

norn export / norn import 从 v1.1 起可用。在更早的版本中， 请直接提交二进制文件 norn.db（这是默认的 norn init 设置）。

norn.db 是二进制 SQLite 文件，其中存储了嵌入向量，因此无法生成可读的 git 差异，并且合并时可能发生冲突。要清晰地对记忆进行版本管理，请改为提交可比较差异的文本导出文件，并让每个检出副本自行重建数据库：

norn export   # writes .norn/memory.json — text, tags, project, ids, timestamps (no vectors)

memory.json 会按确定性顺序排序，因此重新导出未更改的存储时不会产生差异。文件中不存储嵌入向量；导入时会在本地重新生成，因此文件体积小，也便于审查。提交该文件，并使用类似这样的 .norn/.gitignore 忽略二进制存储：

# .norn/.gitignore — commit memory.json, ignore the binary store.
# norn.db is binary SQLite (it holds embedding vectors): no readable diffs,
# and it can conflict on merge. memory.json (not listed here) is the
# diffable file you commit; the sidecars below are always transient.
norn.db
norn.db-wal
norn.db-shm
norn.db-journal

norn init（v1.1+）会为你写入完全相同的 .gitignore，因此 memory.json 默认就是要提交的文件。如果你更愿意提交二进制 norn.db——克隆时无需导入，但无法查看可读差异，可以直接删除 norn.db 这一行。

在全新克隆的仓库中，从已提交的文件重建本地数据库：

norn import   # reads .norn/memory.json and regenerates embeddings locally

import 会按 id 执行 upsert，因此可以安全地重复运行；它绝不会重复添加记忆。

试试看：隔离，然后提交并克隆

可独立运行、可复制粘贴的操作指南（使用 npx，无需安装；需要 Node 20+ 和 git）：

# 1. Two separate projects, each with its own committed memory store.
mkdir -p /tmp/demo/alpha /tmp/demo/beta

cd /tmp/demo/alpha
npx @samad001z/norn-core init
npx @samad001z/norn-core remember "Alpha API rate limit is 600 requests per minute per token"

cd /tmp/demo/beta
npx @samad001z/norn-core init
npx @samad001z/norn-core remember "Beta deploys to prod from the main branch on Vercel"

# 2. Isolation: from Beta, ask for Alpha's fact. Beta only ever returns its own
#    (and global) memories — Alpha's note never appears here.
npx @samad001z/norn-core recall "what is the request rate limit"

# 3. Export Alpha's memory to a diffable file and commit it.
cd /tmp/demo/alpha
npx @samad001z/norn-core export                       # writes .norn/memory.json
git init -q && git add .norn/memory.json && git commit -qm "Add project memory"

# 4. Simulate a teammate's fresh clone: bring the export, NOT the binary db.
mkdir -p /tmp/demo/alpha-clone/.norn
cp .norn/memory.json /tmp/demo/alpha-clone/.norn/memory.json

# 5. Rebuild the store from the committed file and confirm recall works.
cd /tmp/demo/alpha-clone
npx @samad001z/norn-core import                       # regenerates embeddings locally
npx @samad001z/norn-core recall "what is the request rate limit"
#   → "Alpha API rate limit is 600 requests per minute per token"

功能

• 跨会话和项目记忆。 不必再手动反复粘贴 CLAUDE.md。
• 查看它知道的一切。 没有黑箱：每条记忆都清晰可见。
• 忘记任何内容，并可撤销。 完全掌控它保留的内容。
• 发现过时的记忆。 对于一段时间未触及的记忆，仪表板会悄悄标记出来，方便你清理。它只会标记，绝不会删除。
• 检测可能的冲突（可选启用）。 设置 NORN_DETECT_CONFLICTS=1 后，Norn 会标记可能互相矛盾的记忆，由你决定保留哪些——它绝不会自动解决冲突、编辑或删除记忆。默认关闭；只有启用后才会下载额外的模型。
• Norn Live：观察 Agent 如何使用记忆。 仪表板中的实时动态流会显示每次发生的 remember、recall 和 forget，以及需要你处理的冲突。请参阅 Norn Live：观察 Agent 如何使用记忆。
• 通过 MCP 集成到你的工具中。 Claude Code、Cursor 和任何 MCP 客户端。
• 本地优先。 你的上下文、嵌入模型和数据库都保留在你的设备上。

隐私

默认在本地运行。存储是磁盘上的 SQLite 文件，嵌入模型在你的设备上运行，数据不会离开设备：无需账户、API 密钥，也不会收集遥测数据。删除 ~/.norn/norn.db，记忆就会消失。

管理你的记忆

仪表板支持按项目浏览、搜索和忘记任何记忆（可撤销）。 它从本仓库的克隆副本运行（不属于 npx 服务包），并读取 Agent 写入的同一本地存储——~/.norn/norn.db——因此 Norn 记住的内容都会显示在这里。

在新的终端中运行以下四条命令：

git clone https://github.com/samad001z/Norn.git
cd Norn
npm install          # install dependencies
npm run build:core   # build the store package the dashboard reads through (required)
npm run dev:web      # start the dashboard

然后打开 **http://localhost:3000/app**。

跳过 npm run build:core 是仪表板打开后显示空白的常见原因：Web 应用会从 @samad001z/norn-core 导入已编译的存储代码，因此必须先构建该包一次。之后，重新打开仪表板只需运行 npm run dev:web。

若要让仪表板使用非默认位置的存储，请在运行 dev:web 前将 NORN_DB_PATH 设置为 Agent 使用的同一路径（否则使用默认设置即可）：

NORN_DB_PATH=/path/to/norn.db npm run dev:web

更喜欢使用终端？无需打开仪表板即可检查同一存储：

npm run cli -w @samad001z/norn-core -- init    # give this project its own committed store
npm run cli -w @samad001z/norn-core -- list
npm run cli -w @samad001z/norn-core -- recall "how do we deploy"
npm run cli -w @samad001z/norn-core -- export  # write .norn/memory.json to commit with the repo
npm run cli -w @samad001z/norn-core -- import  # rebuild this checkout's store from memory.json

Norn Live：查看 Agent 如何使用记忆

打开 **http://localhost:3000/app/live**（或点击控制面板侧边栏中的 Live 链接）， 即可实时查看 Agent 如何使用记忆。每次通过 Norn 执行的 remember、recall 和 forget 操作都会记录到本地活动日志，并实时流式显示在信息流中，包括操作方、操作内容、操作时间，以及涉及内容的简短预览。 需要你处理面板会汇总可能存在的冲突（启用检测时），等待你做出决定；在控制面板中解决冲突后，这里也会同步清除。

与 Norn 的其他功能一样，日志保存在本地：事件与记忆存储在同一个 SQLite 文件中，绝不会离开你的设备。页面通过服务器发送事件进行实时推送，连接中断时则会回退到轮询。

**为 Agent 命名。**事件通过可选的工具参数 agentId 或 MCP 配置中的环境变量 NORN_AGENT_ID 进行归属标记。如果两者都未设置，服务会话会获得一个自动生成的 ID，例如 agent-3f9c21——活动仍会按会话分组，只是不会显示名称。如果还想为事件标注模型，请设置 NORN_MODEL；Norn 不会自行猜测。

它是什么，也不是什么：

• 它只记录 Norn 自身的工具。它不是会话记录器——你的提示词、代码和终端都不会触及它。普通的 list 浏览也不会被记录。
• 事件日志记录按设计尽力而为：日志写入失败不会阻止或回滚记忆写入。请将信息流视为操作轨迹，而非审计记录。
• 事件需要服务器版本为 v1.3.0 或更高版本。较旧的服务器不会写入事件，因此信息流会一直为空，直到 npx 命令获取新版本（下次启动时会自动获取最新版本）。
• 目前日志没有大小限制——暂时没有保留上限；日志会随着使用不断增长。日志清理已列入规划。

路线图

• 在现有的 Embedder 接口后支持可替换的嵌入后端（Ollama、兼容 OpenAI 的后端）。
• 在控制面板中直接编辑已有记忆（添加和遗忘功能已可用）。
• 扩大带标签的冲突检测基准测试，以便利用更多数据调整阈值。
• 为活动日志添加保留策略（按时间／数量限制），避免 Norn Live 的历史记录无限增长。
• 集成更多编辑器和 MCP 客户端。

贡献

欢迎贡献。请参阅 CONTRIBUTING.md。简而言之：

npm install
npm run build
npm test -w @samad001z/norn-core

许可证

MIT。请参阅 LICENSE。