Neural Memory

核心用法

NeuralMemory 是一个受生物神经网络启发的持久化记忆系统，专为AI Agent设计。与向量搜索不同，它采用扩散激活（Spreading Activation）机制：记忆以神经元形式存储，通过20种类型化突触（synapses）连接成图。查询时，激活从起始神经元向外传播，沿连接权重找到概念关联的记忆——即使关键词完全不同。

典型工作流：

• 会话开始：调用 nmem_context 注入近期记忆，nmem_recall 检索特定主题
• 决策/错误时：nmem_remember 存储类型化记忆（decision/error/preference）
• 被问及过往：nmem_recall(query, depth=2) 追踪因果链（CAUSED_BY/LEADS_TO）
• 会话结束：nmem_auto 自动提取事实、决策、TODO

深度层级：0级（<10ms即时事实）→ 1级（标准上下文，~50ms）→ 2级（习惯模式，~200ms）→ 3级（深度跨域关联，~500ms）

显著优点

1. 概念关联超越关键词："数据库配置"可激活到"Docker部署使用pg_dump备份"——无共享词汇但概念相关
2. 零LLM依赖：纯算法实现（正则提取、图遍历、Hebbian学习），无API成本与延迟
3. 生物级记忆机制：Hebbian学习（常用记忆强化连接）、Ebbinghaus衰减（陈旧记忆自然弱化）、矛盾自动检测
4. 丰富语义关系：20种突触类型涵盖时间（BEFORE/AFTER）、因果（CAUSED_BY/LEADS_TO）、情感（FELT/EVOKES）、冲突（CONTRADICTS）
5. 完整生命周期管理：短期→工作→情景→语义记忆转化，支持版本快照、脑移植、双语（越南语+英语）

局限性与风险

• 本地存储依赖：SQLite文件（~/.neuralmemory/）需自行备份，无原生云端同步
• 初始化成本：需Python环境+npm插件构建，Windows路径配置易出错
• 无内置Embedding：可选配置外部嵌入服务，否则纯依赖符号关联
• 深度查询延迟：3级深度约500ms，高频调用可能影响交互流畅度
• 提取质量上限：自动提取基于规则/正则，复杂语义仍需人工nmem_remember

适合人群

• 需要跨会话上下文保持的AI Agent开发者
• 追求零外部依赖、本地优先的隐私敏感场景
• 研究认知架构、希望实验生物启发记忆机制的探索者
• 厌倦向量搜索"关键词匹配"局限，需要概念级联想的用户

安全风险

• 本地文件安全：记忆明文存储于SQLite，需保护~/.neuralmemory/目录权限
• 无传输加密：无网络传输（纯本地），但脑移植/共享时需注意文件安全
• 提示注入风险：nmem_auto提取用户输入内容，恶意构造可能污染记忆（建议校验priority/tags）

核心用法

NeuralMemory 是一款为 AI Agent 设计的持久化关联记忆系统，采用生物神经网络原理替代传统向量检索。其核心机制包括：

• 扩散激活检索：通过20种类型化突触（时间、因果、语义、情感、冲突）在神经图中遍历，找到概念相关记忆，即使无关键词重叠
• 赫布学习：频繁共激活的记忆自动强化连接（"一起激发的神经元连在一起"）
• 记忆生命周期：短时→工作→情景→语义四级，遵循艾宾浩斯遗忘曲线自然衰减
• 矛盾检测：自动识别冲突记忆并降低过期内容优先级

使用场景

| 时机 | 操作 |

|------|------|

| 会话开始 | `nmem_context` 注入近期记忆，`nmem_recall` 查询特定主题 |

| 决策/错误/偏好 | `nmem_remember` 分类存储（decision/error/preference） |

| 复杂追溯 | `nmem_recall` depth=2/3 追踪因果链（CAUSED_BY/LEADS_TO） |

| 会话结束 | `nmem_auto` 自动提取事实、决策、待办事项 |

显著优点

1. 零LLM依赖：纯算法实现（正则、图遍历、赫布学习），无API调用成本与延迟
2. 概念关联超越关键词："生产环境数据库配置"可激活关联记忆（如Docker备份策略），无需共享词汇
3. 本地隐私优先：SQLite本地存储，~/.neuralmemory/目录隔离，默认不发送至外部服务
4. 深度推理能力：支持时序推理、因果链追踪、跨域联想（depth 0-3分级）
5. OpenClaw深度集成：独占memory槽位，自动注入上下文与捕获记忆，跨/new会话持久

潜在缺点与局限性

1. 冷启动问题：新大脑无记忆积累时，关联网络稀疏，检索效果依赖初期种子记忆
2. T3来源风险：个人开发者维护（nhadaututtheky），无组织背书，长期维护稳定性存疑
3. 双运行时依赖：需同时配置Python（pip）和Node.js（npm）环境，安装链路复杂
4. Windows兼容性：路径分隔符、python vs python3等细节需手动调整
5. 无分布式能力：SQLite单文件架构，不支持多Agent共享大脑或高并发写入
6. 嵌入模型可选：纯神经图不依赖向量，但若启用语义增强需外部嵌入服务

适合人群

• 需要跨会话长期记忆的AI Agent开发者
• 重视隐私本地存储、拒绝云记忆服务的用户
• 需要因果推理与决策追溯的企业知识管理场景
• 使用OpenClaw框架且希望零配置记忆增强的开发者

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 供应链攻击 | 中 | pip/npm双渠道安装，需验证包名正确性（neural-memory / neuralmemory） |

| 权限过度 | 低 | 全局npm安装建议改用本地安装，检查`~/.neuralmemory/`权限 |

| 数据丢失 | 低 | 建议定期`nmem_version`快照，brain.db单文件损坏无内置冗余 |

| 版本漂移 | 低 | 未锁定依赖版本，生产环境建议指定版本号安装 |