NxMem教程：837星仿人类记忆Agent上下文引擎，Event到LTM全流水线

📌 项目：NxcoreAI/NxMem | 星数：837（2026-09-23） | 协议：AGPL-3.0 | 语言：TypeScript | GitHub

一句话定位："把人类记忆的'短时→长时'过程，做成一条可观测、可评测的 Agent 记忆流水线。" Nexcore Context Engine（NxMem）为 LLM Agent 提供可持久化、可检索、可推理的长期记忆：对话与文档摄入为事件（Event），经 LLM 抽取为结构化事实（Fact），时间轴融合后按策略准入短期记忆（STM），再通过"做梦"式巩固沉淀为长期记忆（LTM）。

和 Open Glean 这种面向用户的问答应用不同，NxMem 是给 Agent 开发者用的记忆基础设施；和 HarnessRouter 管"路由"不同，它管的是"记住什么、忘掉什么、怎么想起来"。

🧠 记忆模型：Event → Fact → STM → LTM

引擎把记忆生命周期拆成若干可独立观测的层：

Event ──parse──▶ Segment ──LLM抽取──▶ Fact ──时间轴融合──▶ STM ──做梦巩固──▶ LTM
 (原始事件)      (解析片段)      (结构化事实)    (时间线)    (短期记忆)      (长期记忆)

• Event / Segment：一次原始输入及其解析产物
• Fact：LLM 抽取出的、带时间与来源声明的结构化事实，是检索的基本单元
• STM：刚通过准入判断的事实，权重高、易失效
• LTM：经做梦巩固后的稳定记忆，支持 revise / weaken / archive 等生命周期操作

核心特性表覆盖：多源摄入（.txt/.md/.json/.docx、Agent 写入、对话流，统一归一为 MemoryEvent）、LLM 事实抽取（带时间与来源、支持批量与幂等写入）、时间轴融合、STM 准入（由 LLM 判定并附准入原因与证据）、做梦巩固、混合检索、记忆图、Context Pack、权限与幂等、评测闭环。

🌙 做梦巩固：七维评分沉淀长期记忆

NxMem 最有辨识度的设计是 Dreaming（做梦巩固）：定时或手动触发，用七维评分把 STM 巩固为 LTM，动作包括创建 / 修订 / 冲突消解。七维评分的定义、分数锚点与校准样例在项目里的 STM到LTM七维评分Prompt.md 中有完整说明——这种把"记忆巩固"做成可校准 prompt 的做法，比黑盒式记忆库透明得多。

检索侧是混合检索：关键词 + 向量（bge-m3）+ 图召回 + 交叉编码器重排，输出带分数分解的候选。记忆图存在 Neo4j 里（STM/LTM 节点与关系，支持全文 + 向量索引，提供只读图查询 API）。最终组装成 Context Pack：profile / task / recent 三类上下文，附引用（citation）与权限快照。

工程上还强调幂等写入、权限快照、来源引用，调试接口支持 includeInactive 查看被过滤项——这些都是长期记忆系统上线后最容易踩坑的地方。

🛠️ 技术栈与快速开始

技术栈：pnpm workspaces monorepo，后端 Fastify + TypeScript + tsx，前端 React 18 + Vite 5，图存储 Neo4j，本地存储 SQLite/JSON，LLM 走 OpenAI 兼容（默认 qwen3.7-flash 经 DashScope），Embedding 默认 bge-m3 经 SiliconFlow。

# 安装依赖
pnpm install

# 启动后端 + 前端（并行）
pnpm dev

# 或分别启动
pnpm --filter @nexcore/backend dev   # 后端 http://localhost:3101
pnpm --filter @nexcore/web dev       # 调试台 http://localhost:5173

运行前提：Node.js 22+、pnpm 10+，Neo4j 5.x 可选（用于图存储与向量/全文检索）。打开 http://localhost:5173 进入调试台，可写入测试记忆事件并查看解析、事实、STM、LTM 与融合时间轴。

一条链路跑通：

curl -X POST http://localhost:3101/context/agent-memory \
  -H 'content-type: application/json' \
  -d '{
    "content": "用户偏好：回答要短，但要给验证证据。",
    "idempotencyKey": "basic-memory-demo-1",
    "sourceApp": "agent",
    "sourceId": "chat-session-demo"
  }'

curl 'http://localhost:3101/context/search?q=验证证据&layer=all&limit=5'

项目还内置 LongMemEval 与 LoCoMo 评测链路，端到端可复现——对记忆系统来说，有基准比有功能更重要。

⚖️ 优缺点