neural-memory

NeuralMemory — AI Agent 的联想记忆

一种受生物学启发的记忆系统，使用扩散激活而非关键词／向量搜索。记忆构成一个神经网络图，神经元通过 20 种类型的突触相连。经常共同访问的记忆会加强彼此的连接（Hebb 学习）。过时的记忆会自然衰减。系统会自动检测矛盾。

为什么不直接使用向量搜索？ 向量搜索会找出与你的查询相似的文档。NeuralMemory 则通过图遍历查找概念上相关的记忆——即使关键词或嵌入没有重叠。“我们对身份验证做了什么决定？”会同时激活时间、实体和概念神经元，并找出它们的交集。

设置

1. 安装 NeuralMemory

pip install neural-memory

首次使用时会自动创建位于 ~/.neuralmemory/ 的大脑和配置。

2. 安装 OpenClaw 插件（推荐）

该插件占用专属的记忆槽位——会在每次 Agent 运行前自动注入上下文，并在运行后自动捕获记忆。

# Install from npm
npm install -g neuralmemory

添加到 ~/.openclaw/openclaw.json：

{
  "plugins": {
    "load": {
      "paths": ["<path-to-installed-plugin>"]
    },
    "entries": {
      "neuralmemory": {
        "enabled": true,
        "config": {
          "pythonPath": "python",
          "brain": "default",
          "autoContext": true,
          "autoCapture": true
        }
      }
    },
    "slots": {
      "memory": "neuralmemory"
    }
  }
}

插件功能：

• 自动注册 6 个工具（nmem_remember、nmem_recall、nmem_context、nmem_todo、nmem_stats、nmem_health）
• before_agent_start 钩子：将工具说明和相关记忆作为上下文注入（在 /new 后仍会保留）
• agent_end 钩子：从对话中自动提取事实、决定和待办事项
• 可配置：contextDepth（0-3）、maxContextTokens（10000-10000）

安装后，构建插件：

cd <path-to-installed-plugin>
npm run build

此操作会将 TypeScript 编译为 dist/ 中的 JavaScript。插件入口点为 dist/index.js。

Windows 安装

在 Windows 上，请在 openclaw.json 路径中使用正斜杠或转义的反斜杠：

{
  "plugins": {
    "load": {
      "paths": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/neuralmemory"]
    }
  }
}

查找安装路径：

npm list -g neuralmemory --parseable

如果 openclaw plugins list 未显示该插件：

1. 确认 openclaw.json 中的路径指向软件包根目录（即 package.json 所在位置）
2. 确保已运行 npm run build（dist/ 文件夹必须存在，且其中包含编译后的 .js 文件）
3. 在插件配置中使用 python 而非 python3（Windows 默认设置）

替代方案：MCP 配置（手动）

如果你更倾向于使用 MCP 而非插件，请添加到 ~/.openclaw/mcp.json：

{
  "mcpServers": {
    "neural-memory": {
      "command": "python",
      "args": ["-m", "neural_memory.mcp"],
      "env": {
        "NEURALMEMORY_BRAIN": "default"
      }
    }
  }
}

在 Windows 上，请使用 "python"（而非 "python3"）。此方式可提供全部 63 个 MCP 工具，但没有自动注入上下文／自动捕获钩子。

3. 验证

nmem stats

你应该会看到大脑统计信息（神经元、突触、纤维）。

故障排除

症状	原因	解决方法
openclaw plugins list 未显示插件	插件路径错误或尚未构建	运行 npm run build，并确认 openclaw.json 中的路径
Agent 在终端中运行 nmem remember	Agent 混淆了 CLI 和工具	插件现在会通过 systemPrompt 自动注入工具说明
Agent 在 /new 后忘记工具	新会话中没有工具说明	插件现在会在每次 before_agent_start 时注入 systemPrompt
python3 not found（Windows）	Windows 使用 python 而非 python3	在插件配置中设置 pythonPath: "python"
超时错误	机器运行缓慢或大脑规模较大	在插件配置中增加 timeout（最大值为 120000ms）

工具参考

核心记忆工具

工具	用途	使用时机
nmem_remember	存储记忆	在做出决定、遇到错误、获取事实或洞见，以及了解用户偏好后
nmem_recall	查询记忆	执行任务前、用户提及过去的上下文时，或用户询问“还记得吗……”时
nmem_context	获取近期记忆	在会话开始时注入最新上下文
nmem_todo	创建有效期为 30 天的快捷待办事项	跟踪任务

智能工具

工具	用途	使用时机
nmem_auto	从文本中自动提取记忆	重要对话之后——自动记录决策、错误和待办事项
nmem_recall (depth=3)	深度联想回忆	需要跨领域联系的复杂问题
nmem_habits	工作流模式建议	用户重复类似操作序列时

管理工具

工具	用途	使用时机
nmem_health	大脑健康诊断	定期检查、共享大脑之前
nmem_stats	大脑统计信息	快速查看记忆数量
nmem_version	大脑快照和回滚	高风险操作之前、创建版本检查点
nmem_transplant	在不同大脑之间转移记忆	跨项目共享知识

工作流

会话开始时

1. 调用 nmem_context，将近期记忆注入当前上下文
2. 如果用户提到特定主题，调用 nmem_recall 并传入该主题

对话期间

3. 做出决策时：调用 nmem_remember，并设置 type="decision"
4. 出现错误时：调用 nmem_remember，并设置 type="error"
5. 用户表达偏好时：调用 nmem_remember，并设置 type="preference"
6. 用户询问过去发生的事时：调用 nmem_recall 并设置适当的深度

会话结束时

7. 对重要对话片段调用 nmem_auto，并设置 action="process"
8. 此工具会自动提取事实、决策、错误和待办事项

示例

记住一项决策

nmem_remember(
  content="Use PostgreSQL for production, SQLite for development",
  type="decision",
  tags=["database", "infrastructure"],
  priority=8
)

使用扩散激活进行回忆

nmem_recall(
  query="database configuration for production",
  depth=1,
  max_tokens=500
)

通过图遍历而非关键词匹配返回找到的记忆。即使没有共同关键词，也会浮现相关记忆（例如，“部署使用 Docker，并通过 pg_dump 备份”）。

追踪因果链

nmem_recall(
  query="why did the deployment fail last week?",
  depth=2
)

沿着 CAUSED_BY 和 LEADS_TO 突触追踪因果链。

从对话中自动捕获信息

nmem_auto(
  action="process",
  text="We decided to switch from REST to GraphQL because the frontend needs flexible queries. The migration will take 2 sprints. TODO: update API docs."
)

自动提取：1 项决策、1 条事实、1 项待办事项。

主要功能

• 零 LLM 依赖——纯算法实现：正则表达式、图遍历、赫布学习
• 扩散激活——通过神经图进行联想回忆，而非关键词或向量搜索
• 20 种突触类型——时间类（BEFORE/AFTER）、因果类（CAUSED_BY/LEADS_TO）、语义类（IS_A/HAS_PROPERTY）、情感类（FELT/EVOKES）、冲突类（CONTRADICTS）
• 记忆生命周期——短期 → 工作记忆 → 情景记忆 → 语义记忆，并遵循艾宾浩斯衰减
• 矛盾检测——自动检测冲突记忆，并降低过时记忆的优先级
• 赫布学习——“共同放电的神经元会连接在一起”——记忆会随着使用而改善
• 时间推理——因果链遍历、事件序列、时间范围查询
• 大脑版本管理——对大脑状态进行快照、回滚和差异比较
• 大脑移植——在不同大脑之间转移经过筛选的知识
• 越南语 + 英语——全面支持双语提取和情感分析

深度级别

深度	名称	速度	使用场景
0	即时	<10ms	快速事实、近期上下文
1	上下文	~50ms	标准回忆（默认）
2	习惯	~200ms	模式匹配、工作流建议
3	深度	~500ms	跨领域关联、因果链

注意事项

• 记忆存储在本地的 SQLite 数据库中，路径为 ~/.neuralmemory/brains/<brain>.db
• 数据不会发送到外部服务（除非配置了可选的嵌入提供方）
• 大脑隔离：每个大脑彼此独立，不会相互污染
• nmem_remember 会返回用于追踪引用的 fiber_id
• 优先级范围：0（不重要）到 10（关键），默认值为 5
• 记忆类型：事实、决策、偏好、待办事项、见解、上下文、指令、错误、工作流、参考资料