神经缓存增强（NeuroCache Pro）

为什么不用向量检索？ 向量检索只能找与查询相似的文档。NeuroCache 通过图遍历找到概念关联的记忆——即使无关键词或 embedding 重叠。"我们当时对认证做了什么决定？"会同时激活时间+实体+概念神经元，找到交集。

痛点与对策速查

核心概念

一切记忆都是神经元，通过突触连接。频繁共访问的记忆强化连接（赫布学习），陈旧记忆自然衰减，矛盾自动检测。

Entity: { id, content, type, tags, priority, created, last_accessed, decay_score }
Synapse: { from_id, type, to_id, strength, created, last_fired }

20 种突触类型

快速开始

第 1 步：安装

pip install neural-memory
nmem init

创建 ~/.neuralmemory/ 默认大脑并自动配置 MCP。

第 2 步：配置 MCP

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

第 3 步：验证

nmem stats

应显示大脑统计（神经元数、突触数、纤维数）。

工具参考

核心记忆工具

智能工具

| 工具 | 用途 | 使用时机 | |:---|:---| | nmem_auto | 从文本自动提取记忆 | 重要对话后——自动捕获决策/错误/TODO | | nmem_recall (depth=3) | 深度联想召回 | 需跨领域连接的复杂问题 | | nmem_habits | 工作流模式建议 | 用户重复类似动作序列时 |

管理工具

| 工具 | 用途 | 使用时机 | |:---|:---| | nmem_health | 大脑健康诊断 | 定期体检，分享大脑前 | | nmem_stats | 大脑统计 | 快速概览记忆数量 | | nmem_version | 快照与回滚 | 风险操作前，版本检查点 | | nmem_transplant | 跨大脑迁移记忆 | 跨项目知识共享 |

深度分级（差异化核心）

深度选择指南

快速事实查询（"上次开会什么时候"）      → depth=0
标准回忆（"我们怎么解决 X 的"）          → depth=1
模式识别（"我最近重复做什么"）           → depth=2
复杂关联（"为什么部署总失败"）           → depth=3

成本优化：默认用 depth=1，仅复杂问题升级到 depth=3。避免所有查询都用 depth=3 导致 token 浪费。

矛盾检测机制（差异化核心）

当新记忆与已有记忆通过 CONTRADICTS 突触连接时，系统自动处理：

新记忆存入 → 检查语义重叠 → 发现冲突
  → 创建 CONTRADICTS 突触
  → 比较时间戳与优先级
  → 降权过时/低优先级记忆
  → 标记冲突供用户确认

矛盾处理示例

旧记忆："数据库用 MySQL"（priority=5, 30 天前）
新记忆："数据库改用 PostgreSQL"（priority=8, 今天）

处理：
1. 创建 CONTRADICTS 突触
2. 降权旧记忆（decay_score += 0.3）
3. 新记忆成为主记忆
4. 标记："检测到数据库决策变更，已更新"

召回时：
  nmem_recall("数据库选择")
  → 返回 PostgreSQL（主）
  → 附注："曾考虑 MySQL（已过时）"

衰减与剪枝优化（差异化核心）

艾宾浩斯衰减默认参数可能不适合所有场景。本系统提供可调衰减：

衰减配置

{
  "decay": {
    "initialDecay": 0.1,
    "intervalDays": 7,
    "minActivation": 0.05,
    "pruneThreshold": 0.01,
    "reinforceFactor": 0.2,
    "autoPrune": true,
    "pruneSchedule": "weekly"
  }
}

图谱膨胀防护

工作流

会话开始时

1. 调用 nmem_context 注入近期记忆到感知
2. 若用户提及特定主题，调用 nmem_recall 查询

对话进行中

会话结束时

1. 调用 nmem_auto action="process" 处理重要对话片段
2. 自动提取事实、决策、错误、TODO

真实场景示例

场景 1：因果链追溯

用户："上周部署为什么失败？"

nmem_recall(
  query="部署失败原因",
  depth=2
)

→ 图遍历 CAUSED_BY 突触链：
  部署失败 → CAUSED_BY → 数据库连接超时
  数据库连接超时 → CAUSED_BY → 连接池耗尽
  连接池耗尽 → CAUSED_BY → 未设置 max_connections
  未设置 max_connections → LEADS_TO → 需更新配置规范

返回完整因果链，而非单独的相似记忆。

场景 2：跨领域关联发现

用户："认证和缓存有什么关系？"

nmem_recall(
  query="认证 缓存 关联",
  depth=3
)

→ 扩散激活同时激活：
  - 认证相关神经元（JWT, session, token）
  - 缓存相关神经元（Redis, TTL, invalidation）
  - 交集发现：token 缓存策略

返回："认证 token 用 Redis 缓存，TTL=3600s，
       上次因缓存未失效导致权限问题（3 周前）"

场景 3：矛盾自动处理

会话 A（1 月）：
  nmem_remember("API 限流 100 req/min", type="fact", priority=5)

会话 B（2 月）：
  nmem_remember("API 限流调整为 500 req/min", type="fact", priority=8)
  → 检测到与 1 月记忆矛盾
  → 创建 CONTRADICTS 突触
  → 降权旧记忆
  → 标记变更

会话 C（3 月）：
  nmem_recall("API 限流多少")
  → 返回 500 req/min（新，主）
  → 附注：曾为 100 req/min（1 月，已过时）

场景 4：版本快照与回滚

风险操作前：
  nmem_version snapshot --label "重构前基线"

操作后发现问题：
  nmem_version diff --from "重构前基线" --to current
  → 显示新增/修改/删除的神经元

回滚：
  nmem_version rollback --to "重构前基线"
  → 恢复到快照状态

记忆类型与优先级

优先级范围：0（琐碎）到 10（关键），默认 5。高优先级记忆衰减更慢。

大脑移植（跨项目知识迁移）

nmem_transplant(
  from="project-a",
  to="project-b",
  filter={
    "types": ["decision", "lesson"],
    "min_priority": 6,
    "tags": ["architecture", "database"]
  }
)

→ 从 project-a 过滤高价值决策和教训
→ 迁移到 project-b
→ 保留原突触结构
→ 标记来源（transplanted_from）

常见问题 FAQ

Q1：扩散激活比向量检索好在哪？ A：向量检索找"相似"文档，扩散激活找"关联"记忆。例如"认证决策"能通过图遍历找到"部署配置"（因部署依赖认证），即使两者无关键词/embedding 重叠。

Q2：衰减会不会丢重要记忆？ A：不会。高优先级记忆衰减慢，访问时自动强化（赫布学习）。仅长期未访问且低优先级的记忆会被降权/剪枝。建议重要记忆设 priority>=7。

Q3：图谱太大影响性能怎么办？ A：启用自动剪枝（weekly），调整 minActivation 阈值。超过 10000 神经元考虑大脑分区（按项目/领域拆分）或迁移到 SQLite 后端。

Q4：矛盾检测会误报吗？ A：可能。系统标记"潜在矛盾"供用户确认，不自动删除。同优先级矛盾暂不降权，等用户确认。

Q5：零 LLM 依赖是真的吗？ A：核心检索纯算法（regex + 图遍历 + 赫布学习）。仅 nmem_auto 自动提取可选调用 LLM，也可用 regex 模式匹配替代。

故障排查

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• Python：3.9+（运行 neural-memory 包）
• SQLite：内置（大脑存储后端）

第三方依赖

API Key 配置

• 核心功能无需 API Key（纯算法实现）
• 可选 embedding provider 配置用于增强语义匹配（非必需）

可用性分类

• 分类：MD+EXEC（Markdown 指令 + exec 命令行执行）
• 说明：基于 Markdown 的 AI Skill 驱动 Agent 执行神经记忆管理。核心检索纯算法零 LLM 依赖；需安装 neural-memory 包并通过 MCP 提供工具。