neuromem

AI Agent 多层记忆框架

基于 PostgreSQL 构建的 Python 记忆库，为 AI agent 提供开箱即用的多层记忆。利用 PostgreSQL 生态 pgvector 向量检索、pg_search 全文检索（BM25）、图检索、KV 检索等能力实现混合记忆检索。

• ingest() 自动提取记忆：Fact（持久事实，含双时间线 + 程序性记忆）、Episode（带时间戳的情景记忆）、Graph（实体关系图谱）
• digest() 9 步反思引擎，从历史记忆中归纳 Trait（用户特质），经历 behavior → preference → core 三层升级；支持两阶段反思 + Zettelkasten 记忆关联
• recall() 混合检索（向量 + BM25 RRF 融合 + 图谱 boost + 时间衰减 + 关联扩展 + 前瞻降权），零额外代码组装进 prompt

架构概览

neuromem 把全部记忆类型——向量、图谱、对话、KV、文档、情感画像——存放在单一 PostgreSQL 中， 分层为 Facade / Service / Provider：NeuroMemory 是唯一入口，业务逻辑在 Service 层， Embedding、LLM、对象存储三类 Provider 均通过构造函数注入、可插拔替换。

完整架构说明与 API 参考见 官网文档。

LoCoMo 基准测试成绩

在 LoCoMo 长对话记忆基准（ACL 2024）上的对比成绩（Judge: GPT-4o-mini）：

各框架使用不同的 Judge LLM，分数不完全可比。neuromem 的 0.802 来自 13 轮迭代优化（起点 0.125，+541%）。

文档

安装

# 基础安装（包含核心功能）
pip install neuromem

# 或安装所有可选依赖（推荐）
pip install neuromem[all]

依赖自动安装: SQLAlchemy、asyncpg、pgvector、httpx 等核心依赖会自动安装。

外部依赖

neuromem 需要以下外部服务（不包含在 pip 包中）：

1. PostgreSQL 18 + pgvector + pg_search（必需）

neuromem 使用 ParadeDB 镜像，内置 PostgreSQL 18、pgvector 和 pg_search（BM25 全文检索）。

docker run -d --name neuromem-db -p 5432:5432 \
  -e POSTGRES_USER=neuromem -e POSTGRES_PASSWORD=neuromem -e POSTGRES_DB=neuromem \
  paradedb/paradedb:0.24.1-pg18

该镜像已预装 pgvector 与 pg_search，无需手动 CREATE EXTENSION。对应的连接串为 postgresql+asyncpg://neuromem:neuromem@localhost:5432/neuromem。

pg_search 说明：pg_search 提供 BM25 关键词检索，与向量检索融合为混合排序（RRF）。若 pg_search 不可用，系统自动降级到 PostgreSQL 内置的 tsvector 全文检索，功能仍可正常使用。

2. Embedding Provider（必需，三选一）

• 本地模型（无需 API Key）：pip install sentence-transformers，使用本地 transformer 模型
• SiliconFlow：siliconflow.cn，需要 API Key
• OpenAI：platform.openai.com，需要 API Key

3. LLM API Key（必需，用于自动提取记忆和反思）

• OpenAI 或 DeepSeek

4. MinIO/S3（可选，仅用于文件存储）

docker run -d --name neuromem-minio -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=neuromem -e MINIO_ROOT_PASSWORD=neuromem123 \
  minio/minio:latest server /data --console-address ":9001"

快速开始

import asyncio
from neuromem import NeuroMemory, SiliconFlowEmbedding, OpenAILLM

async def main():
    async with NeuroMemory(
        database_url="postgresql+asyncpg://neuromem:neuromem@localhost:5432/neuromem",
        embedding=SiliconFlowEmbedding(api_key="your-key"),
        llm=OpenAILLM(api_key="your-openai-key"),  # 必需，用于自动提取记忆
        auto_extract=True,  # 默认启用，像 mem0 那样实时提取记忆
    ) as nm:
        # 1. 存储对话消息 → 自动提取记忆（facts/episodes/relations）
        await nm.ingest(
            user_id="alice", role="user",
            content="I work at ABC Company as a software engineer"
        )
        # → 后台自动提取：fact: "在 ABC Company 工作", relation: (alice)-[works_at]->(ABC Company)

        # 2. 混合检索（向量 + BM25 RRF 融合 + 图谱 boost + 时间衰减）
        result = await nm.recall(user_id="alice", query="Where does Alice work?")
        for r in result["merged"]:
            print(f"[{r['score']:.2f}] {r['content']}")

        # 3. 反思：从记忆归纳用户特质（可选，定期调用或自动触发）
        result = await nm.digest(user_id="alice")
        print(f"分析了 {result['memories_analyzed']} 条记忆")

asyncio.run(main())

核心操作流程

neuromem 的核心使用围绕三个操作：

插入记忆（自动模式，默认）：

• 对话驱动：ingest() 存储对话 并自动提取记忆（推荐，像 mem0）
• 自动提取 fact（持久事实）、episodic（情景记忆），可选 graph（实体关系三元组）

召回记忆（recall）：

• await nm.recall(user_id, query) — 向量 + BM25 RRF 融合 + 图谱 boost + 时间衰减
• 支持按类型过滤（memory_type="fact"）、时间范围过滤、时间旅行查询（as_of）

反思与特质归纳（digest）（可选，定期调用或自动触发）：

• await nm.digest(user_id) — 9 步反思引擎：
  1. 归纳特质：从 fact/episodic 记忆中识别行为模式，生成 trait（特质）
  2. 升级特质：behavior → preference → core 三层递进升级
  3. 矛盾处理：检测与已有特质的矛盾，触发专项反思
  4. 更新画像：整合情感数据，更新用户情感画像

ingest() 默认 auto_extract=True，每次调用自动提取记忆。digest() 专注于从已有记忆中归纳特质和更新情感画像。默认每 20 条消息自动触发一次（reflection_interval=20）。

逻辑关系：

对话进行中 → 存储消息 (ingest) → 自动提取 fact/episodic/graph
     ↓
agent 需要上下文 → 召回记忆 (recall) → 向量+BM25 RRF 融合+图谱 boost
     ↓
定期反思 → 归纳特质 (digest) → trait(behavior→preference→core) + 情感画像

核心特性

记忆分类（V2）

neuromem 基于认知心理学理论，将记忆分为 4 种核心类型：

Trait 三层子类型（全球独一无二的升级链设计）：

辅助系统：

单一 PostgreSQL 架构优势

neuromem 将所有记忆（向量、图谱、对话、KV、文档、情感画像）存储在单一 PostgreSQL 中，而非拼装多个独立数据库。这不是偶然选择，而是刻意的架构决策，带来六大差异化优势：

1. 联合融合排序 — 图谱与向量结果交叉增强，而非各自为政

recall() 中，图三元组不仅提供结构化关系，还参与向量结果的排序：被图三元组覆盖的向量记忆获得加法 boost（双端命中 +0.10，单端命中 +0.04，上限 +0.20），图三元组本身以 source="graph" 进入统一的 merged 列表。竞品（mem0、graphiti）的图和向量存储在不同数据库中，无法实现这种交叉增强。

2. 事务一致性 + 数据治理 — 单库原子操作，零数据不一致风险

delete_user_data() 在一个数据库事务内原子删除 8 张表的用户数据；export_user_data() 在一个快照内导出完整用户画像。竞品需要跨 3-4 个数据库协调删除/导出，任何一个库失败都会造成数据不一致。对于 GDPR/合规场景，单库事务意味着"删除即彻底删除"，无需担心残留。

3. 时间旅行查询 — 记忆版本化与时间点回溯

利用 PostgreSQL 原生能力实现记忆版本化：查询某个时间点的记忆快照、回滚错误更新。这在多库架构中几乎不可能实现——你无法对 Redis 缓存、Neo4j 图谱、Qdrant 向量同时做时间点快照。

4. 跨类型记忆分析 — 让开发者获得记忆系统的可观测性

entity_profile() 通过 SQL JOIN 跨事实记忆、图谱关系、对话历史三种来源，构建一个实体的完整画像和时间线；stats() 提供按类型、按周的记忆分布统计；cold_memories() 发现长期未访问的记忆。这些分析能力让 agent 开发者能够观测和诊断记忆系统的健康状况，而不是把它当成黑盒。

5. 安全与用户隔离 — 框架级强制隔离 + 集中式数据治理

neuromem 的所有 API 都强制要求 user_id 参数，框架层面保证每个查询都包含 WHERE user_id = :uid 过滤——开发者无法绕过隔离边界。所有数据存储在单一 PostgreSQL 中，可统一应用备份策略、审计日志和访问控制，数据治理只需管理一个数据库，而非 3-4 个不同技术栈的数据库。

6. 部署极简 — 一个 PostgreSQL 搞定一切

开发者只需 docker compose up -d db 即可拥有完整的记忆存储——向量检索、全文检索、图查询、KV 存储全部内置。生产环境只需一个托管 PostgreSQL（如 AWS RDS、Supabase），无需额外运维 Redis、Neo4j、Qdrant 等专用数据库。

LLM 驱动的记忆提取与反思

• 提取：ingest() 自动从对话中识别事实、事件、关系，附带情感标注（valence/arousal/label）和重要性评分（1-10），content_hash 去重避免重复存储
• 反思 (digest)：9 步反思引擎，从 fact/episodic 中归纳 trait（特质），支持 behavior → preference → core 三层升级、矛盾检测、证据质量四级分级（A/B/C/D）
• 情境标注：trait 从 behavior 层即附带情境标签（work/personal/social/learning/general）
• 访问追踪：自动记录 access_count 和 last_accessed_at，符合 ACT-R 记忆模型

理论基础：Tulving 语义/情景记忆 + Conway 自我记忆系统 + Allport 特质理论 + Mischel CAPS if-then 模式 + Generative Agents (Park 2023) Reflection + Ebbinghaus 遗忘曲线 + ACT-R 记忆模型。

存储架构（V2）

• halfvec 量化：向量使用 halfvec（float16）存储，空间减半，召回损失 <0.3%
• 双时间线（Bi-temporal）：valid_from/valid_until + created_at/expired_at，支持时间旅行查询（recall(as_of=...)）和记忆版本回滚
• content_hash 去重：MD5 快筛，避免重复记忆存储
• 证据链（TraitEvidence 表）：独立存储特质的支持/矛盾证据，避免 JSONB 写放大
• 变更审计（MemoryHistory 表）：记忆每次更新的版本历史
• 反思周期记录（ReflectionCycle 表）：每次反思的元数据追踪

Markdown 导出（数据主权）

一行代码把全部记忆导出为人类可读的 Markdown 文件树，可用 Obsidian / VS Code 直接浏览，或纳入 git 版本管理：

await nm.export_markdown(user_id="alice", dest="/backup/alice")
await nm.export_markdown(user_id="alice", dest="/backup/alice.zip")  # 或直接导出 zip

每条记忆一个 .md（YAML frontmatter + 正文），按类型与月份分目录，另附 MANIFEST.json 机器索引、README.md 人读入口和 _views/ 派生视图。导出具备确定性——同一数据库状态两次导出字节一致，因此 git diff 能直接反映记忆变更。需要 pip install neuromem[markdown]。

路线图

Phase 1（已完成）

• PostgreSQL + pgvector 统一存储
• 向量语义检索
• 时间范围查询和时间线聚合
• KV 存储
• 对话管理
• 文件上传和文本提取
• 图数据库（关系表实现，无 AGE 依赖）
• LLM 记忆分类提取
• 可插拔 Provider（Embedding/LLM/Storage）

Phase 2（已完成）

• 情感标注（valence / arousal / label）
• 重要性评分（1-10）
• 多因子检索（cosine similarity + recency bonus + importance bonus）
• 访问追踪（access_count / last_accessed_at）
• 反思机制（从记忆中生成高层洞察）
• 后台任务系统（ExtractionStrategy 自动触发）
• auto_extract 模式后台自动 digest（reflection_interval 参数）

Phase 3（已完成）

• 基准测试：LoCoMo（ACL 2024，Judge 0.802，13 轮迭代，+541%）
• 联合融合排序（图三元组覆盖度 boost + BM25 RRF 融合）
• 事务一致性 API（delete_user_data / export_user_data）
• 时间旅行查询（记忆版本化 + as_of 召回 + rollback）
• 记忆分类 V2：4 类体系（fact/episodic/trait/document），trait 三层升级链（behavior→preference→core）
• 存储架构 V2：halfvec 量化、双时间线、content_hash 去重、证据链表、变更审计表
• 9 步反思引擎：特质生命周期管理、矛盾检测、证据质量分级（A/B/C/D）、情境标注
• 双时间线：提取 event_time（事件发生时间 vs 系统记录时间），recency 排序使用事件时间
• 前瞻记忆：已过期的未来意图自动降权 0.5x，digest 时自动过期为 historical
• 程序性记忆：识别多步骤工作流（category=workflow），结构化存储 procedure_steps
• Zettelkasten 记忆关联：digest 时建立记忆间双向语义链接，recall 时 1-hop 关联扩展
• 两阶段反思：重要反思先生成关键问题，再检索历史证据验证，提高反思质量

Phase 4（进行中）

• LIST 分区迁移（按 memory_type 分区，查询加速 67-83%）
• 物化视图衰减预计算（mv_trait_decayed）
• 基准测试：LongMemEval（ICLR 2025，超长记忆评测，500 个问题，115k~1.5M tokens）
• 自然遗忘（主动记忆清理/归档机制）
• 多模态 embedding（图片、音频）
• 分布式部署支持

反馈

问题反馈与功能建议请通过 neuromem.cloud 联系我们。

许可证

MIT License，许可证全文随包分发（LICENSE 文件）。

neuromem - 让您的 AI 拥有记忆