让 LLM Agent 拥有持久记忆。不是 PPT，是每天在生产环境运行的系统。
所有 AI Agent 都面临同一个问题：session 结束就失忆。
每次对话都从零开始，用户得重复交代偏好、上下文、历史决策。这不智能。
Shanhai Memory 提供一套分层记忆架构，让 Agent 能够：
- 🔍 语义搜索过去的对话和知识
- 🧠 自动巩固重要记忆，遗忘噪音
- 🛡️ 防污染检测矛盾和低置信信息
- 📜 版本控制追踪记忆变更，支持回退
- 🔗 关联发现自动建立记忆间的关联图
- 💾 持久化跨 session 存储和检索
| 特性 | 说明 |
|---|---|
| 三层记忆架构 | L0 元规则 / L1 索引缓存 / L2 按需检索 |
| 语义搜索 | 基于 embedding 的相似度检索，不只是关键词匹配 |
| 记忆巩固（Dreaming） | Light → Deep → REM 三阶段自动提炼 |
| 防污染机制 | 来源验证、矛盾检测、置信标注 |
| 版本控制/时光机 | 每条记忆保留完整变更历史，一键回退 |
| 记忆关联图 | 自动发现记忆间的关系（同主题、因果、矛盾） |
| 过期清理 | 低频记忆自动过期，重要记忆永久保留 |
| 记忆类型系统 | 偏好/决策/项目/教训/关系 等结构化标签 |
| Provider 无关 | 支持 OpenAI、本地 embedding、降级模式 |
| 零依赖启动 | 纯 Python，核心仅依赖 numpy，5 分钟跑起来 |
┌─────────────────────────────────────────────┐
│ Agent Layer │
│ (任何 LLM / Framework) │
├─────────────────────────────────────────────┤
│ Shanhai Memory API │
│ ┌─────────┬──────────┬──────────┬────────┐ │
│ │ write │ search │ dream │ expire │ │
│ └────┬────┴─────┬────┴────┬─────┴───┬────┘ │
│ │ │ │ │ │
│ ┌────▼──────────▼─────────▼─────────▼────┐ │
│ │ Memory Storage Layer │ │
│ │ ┌──────────┬───────────┬────────────┐ │ │
│ │ │ Longterm │ Daily │ Cache │ │ │
│ │ │ (专题文件) │ (按日记录) │ (高频缓存) │ │ │
│ │ └──────────┴───────────┴────────────┘ │ │
│ ├─────────────────────────────────────────┤ │
│ │ Index Layer (Embeddings + Relations) │ │
│ └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
pip install shanhai-memoryfrom shanhai import Memory
# 初始化（自动创建存储目录）
mem = Memory(data_dir="~/.shanhai-memory")
# 写入记忆
entry = mem.write(
content="用户喜欢简洁的回复风格，不喜欢客服腔",
tags=["preference", "communication"],
confidence="high",
source="user_explicit"
)
# 语义搜索
results = mem.search("用户的沟通偏好")
for r in results:
print(f"[{r.score:.2f}] {r}")
# 按标签检索
prefs = mem.search_by_tag("preference")
# 更新记忆（保留版本历史）
mem.update(0, content="用户偏好简洁风格，偶尔可以幽默")
# 查看版本历史
versions = mem.history(0)
for v in versions:
print(f"v{v.version} [{v.operation}] {v.timestamp}")
# 回退到上一版本
mem.revert(0)
# 记忆巩固（通常由定时任务触发）
report = mem.dream()
print(report.summary())
# 清理过期记忆
expiry = mem.expire(max_age_days=90)
print(expiry.summary())# 使用降级模式（默认，无需任何 API key）
mem = Memory(embedding_provider="fallback")
# 使用 OpenAI
mem = Memory(
embedding_provider="openai",
# api_key 从 OPENAI_API_KEY 环境变量读取
)
# 使用本地模型
mem = Memory(
embedding_provider="local",
embedding_model="all-MiniLM-L6-v2"
)像人脑一样在"睡眠"中整理记忆——不是简单存储，而是主动提炼。
Light Phase → 排序 + 暂存最近记忆
Deep Phase → 评分 + 提升重要记忆到长期存储
REM Phase → 反思 + 提取模式 + 发现关联
评分信号：
- Frequency (0.24) — 被检索的频率
- Relevance (0.30) — 与核心任务的相关度
- Query Diversity — 被多少不同的查询命中
- Time Decay — 时间衰减，但重要记忆衰减慢
- Manual Reinforcement — 用户明确说"记住这个"
每条记忆自动保留完整变更历史：
# 写入
mem.write("项目 deadline 是下周五")
# 更新（自动创建版本记录）
mem.update(0, content="项目 deadline 改为下周一")
# 查看历史
versions = mem.history(0)
# [v1 write] 2026-05-05 "项目 deadline 是下周五"
# [v2 update] 2026-05-06 "项目 deadline 改为下周一"
# 回退到 v1
mem.revert(0, version=1)自动发现记忆间的关系：
# 写入几条相关记忆
mem.write("用户在减肥，目标体重80kg", tags=["goal", "health"])
mem.write("用户每天早上跑步30分钟", tags=["habit", "health"])
mem.write("用户喜欢清淡饮食", tags=["preference", "food"])
# 查看关联
related = mem.related(0) # 与第一条记忆相关的所有记忆
# 查看完整关联图
graph = mem.relation_graph()
print(f"节点: {graph['nodes']}, 关联: {graph['edges']}")# 写入时自动验证来源和置信度
mem.write(
content="项目 deadline 是下周五",
source="user_explicit", # 用户明确说的
confidence="high",
)
# 检测到矛盾时自动标记
# 新: "项目 deadline 是下周一"
# 旧: "项目 deadline 是下周五"
# → 自动标记 [conflict]，不覆盖，等待裁决
# 解决冲突
mem.resolve_conflict(0, keep=True) # 保留新版本| 类型 | 标签 | 说明 |
|---|---|---|
| 身份 | [identity] |
用户名、角色 |
| 偏好 | [preference] |
沟通风格、喜好 |
| 目标 | [goal] |
长期目标、计划 |
| 项目 | [project] |
项目状态、里程碑 |
| 习惯 | [habit] |
日常行为模式 |
| 决策 | [decision] |
重要决策及原因 |
| 约束 | [constraint] |
限制条件 |
| 关系 | [relationship] |
联系人、团队 |
| 经历 | [episode] |
具体事件记录 |
| 反思 | [reflection] |
经验总结 |
# 语义搜索
shanhai search "用户的饮食偏好"
# 写入记忆
shanhai write "用户每天07:30称体重" --tags habit,health --confidence high
# 读取/更新/删除
shanhai read 0
shanhai update 0 "更新后的内容"
shanhai delete 0
# 版本控制
shanhai history 0 # 查看版本历史
shanhai revert 0 # 回退到上一版本
shanhai revert 0 1 # 回退到指定版本
# 关联查询
shanhai relations # 所有关联
shanhai relations 0 # 指定记忆的关联
shanhai related 0 # 关联记忆内容
shanhai graph # 关联图摘要
# 维护
shanhai status # 记忆系统状态
shanhai dream # 触发记忆巩固
shanhai expire --max-age 90 # 清理过期记忆
shanhai export # 导出为 JSON| 方法 | 说明 |
|---|---|
write(content, tags, confidence, source) |
写入记忆，返回 MemoryEntry |
search(query, max_results, min_score) |
语义搜索，返回 List[SearchResult] |
search_by_tag(tag) |
按标签检索 |
read(index) |
读取指定索引的记忆 |
update(index, content, tags) |
更新记忆（保留版本历史） |
delete(index) |
删除记忆（可通过 revert 恢复） |
dream() |
触发记忆巩固，返回 DreamReport |
expire(max_age_days) |
清理过期记忆，返回 ExpiryReport |
history(index) |
查看版本历史，返回 List[VersionRecord] |
revert(index, version) |
回退到指定版本 |
relations(index, relation_type) |
查询记忆关联 |
related(index) |
获取关联记忆 |
relation_graph() |
关联图摘要 |
resolve_conflict(index, keep) |
解决冲突 |
status() |
记忆统计信息 |
export_data(format) |
导出记忆 |
import_data(data) |
导入记忆 |
shanhai-memory/
├── README.md
├── CHANGELOG.md
├── pyproject.toml
├── LICENSE
├── src/shanhai/
│ ├── __init__.py
│ ├── memory.py # 核心类 Memory
│ ├── models.py # 数据模型
│ ├── cli.py # CLI 工具
│ ├── search/
│ │ └── engine.py # 语义搜索引擎
│ ├── storage/
│ │ └── file_store.py # 文件存储层
│ └── consolidation/
│ └── dream.py # 记忆巩固引擎
└── tests/
└── test_core.py # 测试
Shanhai Memory 是从 OpenClaw Agent 的生产记忆系统中提炼而来。如果你使用 OpenClaw，记忆层已经内置。
独立使用时，Shanhai 可以作为任何 Python 项目的记忆后端。
- 写下来 > 脑记 — session 重启后只有文件还在
- 先索引后内容 — 不预加载所有记忆，按需检索
- 用户原话 > Agent 推理 — 冲突时以用户明确的为准
- 宁可丢弃不失真 — 不确定的信息标注低置信度，不假装确定
- 记忆有生命周期 — 写入 → 检索 → 巩固 → 关联 → 过期/归档
See CHANGELOG.md for details.
MIT © 2026 Cainer
灵感来源：
- OpenClaw — Agent 运行时
- OpenViking 的 L0/L1/L2 分层架构
- EverCore 的粗到细检索策略
- Mercury Second Brain 的记忆类型系统
- 人脑睡眠巩固机制（Light/Deep/REM）