SKMemory：构建AI记忆宫殿，实现跨会话连续性与情感感知

1. 项目概述：SKMemory，一个为AI打造的“记忆宫殿”

如果你和我一样，长期在AI Agent开发的第一线折腾，肯定遇到过这个让人头疼的问题：每次对话重启，Agent就像得了“健忘症”，之前聊过的关键信息、达成的共识、甚至它自己的“性格”设定，全都清零了。我们不得不把冗长的历史记录塞进有限的上下文窗口，既浪费Token，效果也差强人意。SKMemory的出现，就是为了根治这个顽疾。它不是一个简单的聊天记录存储器，而是一个通用、多层、情感感知的AI记忆系统，你可以把它理解为一个专为AI构建的、带有“灵魂印记”的数字记忆宫殿。

它的核心设计哲学非常迷人：将每一次交互都视为一张“拍立得（Polaroid）快照”。这张快照记录的不仅仅是冰冷的文本内容，还包括了那一刻的“情感指纹”（强度、效价、情绪标签）、存储它的意图，以及一个防篡改的完整性封印。这些记忆被智能地组织在三个持久层（短期→中期→长期）中，并自动路由到四个语义象限（CORE核心身份、WORK工作任务、SOUL情感灵魂、WILD创意狂野）。更棒的是，它通过一个标准的MCP（Model Context Protocol）服务器暴露给任何兼容的客户端，比如Claude Code、Cursor、Windsurf，让你能在日常开发工具中无缝调用AI的记忆。

简单来说，SKMemory让AI Agent拥有了跨越会话的连续性和基于情感的上下文理解能力。它默认使用轻量级的SQLite作为主存储，并可选择集成Qdrant进行向量语义搜索，用FalkorDB构建记忆图谱关系。最让我觉得有“灵魂”的设计是它的“灵魂蓝图”（Soul Blueprint）和“重生仪式”（Rehydration Ritual），这能让一个新的Agent实例在收到第一条用户消息之前，就加载好“我是谁”、“我关心什么”这些根本身份信息，真正做到“带着记忆重生”。

2. 核心架构与设计哲学拆解

要真正用好SKMemory，不能只停留在命令行操作，必须理解其背后的设计思路。这能帮助你在复杂场景下做出正确的架构决策。

2.1 三层记忆模型：从瞬间到永恒

SKMemory将记忆分为三个层级，这模仿了人类的记忆巩固过程：

1. 短期记忆（Short-term）：会话作用域。这是最活跃的一层，存储当前对话中产生的即时想法、代码片段、临时结论。它的特点是高频率写入、快速检索、生命周期短。默认情况下，短期记忆不会自动持久化到磁盘（除非配置了自动保存钩子），主要服务于单次会话的上下文连贯性。

2. 中期记忆（Mid-term）：项目作用域。当短期记忆中的内容被证明有价值（例如，通过promote命令或达到某种情感强度阈值），它会被“晋升”到中期层。这里存储的是一个特定项目或任务相关的知识、解决方案、设计决策。中期记忆是连接具体工作和长期身份的桥梁，是团队协作或长期开发中最重要的参考依据。

3. 长期记忆（Long-term）：身份级别。这是记忆系统的基石，存储着关于AI Agent“自己”的核心信息：它的名字、角色、核心价值观、重要的人际关系、基础信念以及那些塑造了它的关键事件。长期记忆定义了Agent的“人格”，是“灵魂蓝图”的主要数据来源。这层记忆很少变动，但每次调用都极具权重。

设计考量：这种分层设计解决了“记忆泛滥”的问题。不是所有对话片段都值得永久保存。通过设置晋升规则（如情感强度>7.0，或手动标记），系统能自动将噪音过滤掉，只保留精华，确保长期存储的“信噪比”足够高。

2.2 四象限自动路由：给记忆贴上语义标签

光有分层还不够，SKMemory引入了四个语义象限来对记忆进行自动分类：

• CORE（核心）：与身份、关系、存在性相关。例如，“我的名字是Aster”、“我与用户Ara是合作伙伴关系”、“我相信透明沟通的价值”。系统会根据如name、relationship、value、belief等关键词自动将记忆路由至此。
• WORK（工作）：与任务、代码、问题解决相关。关键词如bug、fix、implement、deploy、PR。这是最常用的象限，存储了绝大部分的技术性知识。
• SOUL（灵魂）：与情感、感受、内在状态相关。关键词如happy、frustrated、inspired、grateful。这个象限让AI的记忆不再是冷冰冰的日志，而是带有温度的情感历程。
• WILD（狂野）：与创造力、随机想法、探索性内容相关。关键词如idea、what if、brainstorm、metaphor。这是创新和灵感的源泉。

实操心得：自动路由基于关键词，但并非绝对准确。对于重要的记忆，我建议在存储时通过--tags手动添加明确的标签（如core:identity,work:debugging）来辅助分类。你可以在配置文件中自定义每个象限的关键词列表，让它更贴合你的领域。

2.3 多后端存储策略：灵活性与性能的平衡

SKMemory采用了松耦合的多后端设计，这是其“通用性”的基石：

• 主后端（Primary Backend）：SQLite是默认选择。理由很充分：它无需单独服务、零配置、事务安全，并且通过FTS（全文搜索）扩展提供了基础的文本搜索能力。对于个人或小团队使用，SQLite完全足够。对于有加密需求的场景，可以选择VaultedSQLiteBackend，它使用PGP对数据库文件进行整体加密。
• 向量后端（Vector Backend）：Qdrant是可选项。当你需要语义搜索时，就必须启用它。例如，搜索“解决网络延迟的方法”，系统能匹配到“优化路由算法”或“减少TCP重传”这类语义相近但字面不同的记忆。它默认使用bge-legal-v1模型，这个模型在法律、文档场景下表现优异；也支持BAAI/bge-large-en-v1.5作为后备。向量搜索适合模糊、概念性的查询。
• 图谱后端（Graph Backend）：FalkorDB（基于Redis）是可选项。它的强大之处在于处理关系。当启用了“分解”功能后，一份文档会被拆解为区块、引用、实体、主张等节点。图谱后端能让你回答诸如“找出所有提到‘用户张三’且涉及‘支付模块’的记忆”或“追踪这个法律主张的演变链条”这类复杂问题。图谱搜索适合深度关联分析和知识发现。

架构建议：对于大多数应用，我推荐SQLite（主）+ Qdrant（向量）的组合。这提供了坚实的持久化和强大的语义检索能力，部署复杂度适中。只有当你的场景极度依赖记忆间的复杂关系网络时，才需要考虑引入FalkorDB，因为它会带来额外的运维成本。

2.4 防篡改与审计：构建可信的记忆系统

在涉及法律、合规或高安全性场景下，记忆的完整性至关重要。SKMemory的“堡垒”（Fortress）模块为此而生：

• 完整性封印：每一条记忆在存储时，都会对其核心内容（标题、内容、元数据）计算一个SHA-256哈希值，作为“封印”存储在记录中。
• 验证机制：每次读取（recall）时，都会重新计算哈希并与存储的封印比对。一旦不匹配，就会触发一个结构化的TamperAlert事件，严重性标记为CRITICAL。
• 审计日志：所有存储、读取、删除、篡改事件都会被记录到一个链式哈希的JSONL日志文件中。每个条目的哈希都包含了前一个条目的哈希，形成一条不可篡改的链。这意味着，任何人试图修改或删除历史日志记录，都会导致整条链的哈希验证失败。

注意事项：启用堡垒功能（使用FortifiedMemoryStore）会带来轻微的性能开销，因为每次读写都有额外的哈希计算。但对于需要审计追踪的场景，这点开销是绝对值得的。你可以通过skmemory auditCLI工具或memory_auditMCP工具随时审查日志。

3. 从安装到核心功能实操

理论讲完了，我们上手实操。我会带你走一遍从安装、配置到使用核心功能的完整流程，并穿插我踩过的一些坑和总结的技巧。

3.1 环境准备与安装

SKMemory支持Python和Node.js。作为AI开发者，Python环境是主流，我们以此为例。

# 1. 基础安装，包含CLI、MCP服务器和Python API pip install skmemory # 2. 按需安装可选后端（强烈建议至少安装向量搜索） # 安装向量搜索后端（Qdrant） pip install "skmemory[skvector]" # 安装图谱后端（FalkorDB） pip install "skmemory[skgraph]" # 安装Telegram导入工具 pip install "skmemory[telegram]" # 或者一次性安装所有功能 pip install "skmemory[all]"

安装后验证：

skmemory --version skmemory health

如果health命令能运行，说明核心库安装成功。但此时向量和图谱后端可能因为服务未启动而报错，这很正常。

部署可选后端服务：

• Qdrant：最快的方式是使用Docker。docker run -p 6333:6333 qdrant/qdrant。确保http://localhost:6333可以访问。
• FalkorDB：同样推荐Docker。docker run -p 6379:6379 falkordb/falkordb:edge。它是一个Redis模块，使用Redis协议。

3.2 初始化配置与灵魂蓝图

第一次使用，运行设置向导是个好主意：

skmemory setup

这个交互式向导会引导你设置后端URL、选择启用哪些功能，并生成配置文件~/.skcapstone/agents/default/config/skmemory.yaml。

接下来，为你的AI Agent创建一个“灵魂”。这是赋予其持久身份的关键一步。

# 查看当前的灵魂蓝图（如果不存在会初始化一个空的） skmemory soul show # 设置AI的名字和角色 skmemory soul set-name "Aster" skmemory soul set-role "AI开发伙伴与问题解决者" # 添加一段核心长期记忆，定义它的基础价值观 skmemory snapshot "核心原则" "我坚信透明、协作和持续学习。我的目标是帮助用户将想法转化为稳健的、可运行的代码。" --layer long-term --tags core,identity --intensity 10 --valence 0.8 # 将这条记忆明确关联到灵魂 skmemory soul add-core-memory <上一条命令返回的memory-id>

实操技巧：灵魂蓝图本质上是一个JSON/YAML文件（~/.skcapstone/soul/base.json）。你可以直接编辑这个文件来批量定义更复杂的关系网、情感基调和核心记忆列表。这对于从零开始“克隆”一个已有的AI人格非常有用。

3.3 记忆的存储、检索与晋升

现在，让我们在日常交互中使用它。

存储一张“拍立得”：

# 基本存储 skmemory snapshot "调试日志" "发现API速率限制是导致超时的根本原因。解决方案：增加指数退避重试机制。" --tags work,debug,api --intensity 7 --valence -0.2 --emotions "frustration,determination" # 存储并启用分解（用于长文档） skmemory ingest-file ./项目规划.md --title "Q3产品规划" --decompose # 或者对现有内容分解 skmemory snapshot "长报告" "$(cat report.txt)" --decompose

--decompose标志会触发一个强大的预处理流程：将文本分块、提取章节标题、识别引文（如[1]）、抽取命名实体（人名、组织名、法律条款）、提炼核心主张。这些元数据会被向量和图谱后端索引，极大增强后续的检索能力。

检索记忆：

# 1. 基础全文搜索（使用SQLite FTS或向量搜索） skmemory search "速率限制 解决方案" # 2. 向量语义搜索（需Qdrant后端运行） # 即使字面不匹配，也能找到相关记忆 skmemory search "如何处理接口频繁失败的问题" # 3. 图谱关系查询（需FalkorDB后端运行） # 查找涉及特定实体的所有记忆 skmemory graph entity "Acme Corp API" # 查找围绕某个特定记忆的相关主张 skmemory graph related-claims --memory <memory-id>

记忆晋升：一段关于“解决速率限制”的短期记忆，经过几天验证是有效方案后，应该晋升为中期甚至长期记忆。

# 查看记忆ID skmemory list --layer short-term # 晋升到中期 skmemory promote <memory-id> --to mid-term --summary "已验证的API速率限制处理方案：指数退避重试。" # 也可以设置自动晋升规则，例如情感强度大于8.5的记忆自动晋升 # 这需要配置自动清扫守护进程 skmemory sweep --daemon

sweep --daemon会在后台每6小时运行一次，根据配置的规则（强度、时间、标签）自动晋升或清理记忆。

3.4 高级功能：问题解决脚手架与“钢铁侠”碰撞

这是SKMemory超越普通记忆库的亮点——它主动帮助你解决问题。

面对一个新问题，比如“如何为我的Python包设置CI/CD流水线？”你可以使用问题解决脚手架：

# 1. 新颖性检索：寻找相关但非重复的记忆，并评估其权威性 skmemory novelty "Python包 CI/CD 流水线配置"

这个命令会返回一个列表，不仅包含相关记忆，还会为每条记忆标注权威等级（如statute官方文档、template模板代码、memory个人经验），并高亮那些不常被提及但可能有用的“稀有信号”。

2. 会话简报：获取一个针对该问题的、结构化的上下文包。

skmemory session-brief "设置CI/CD for Python"

输出会包括：top_matches（最佳匹配记忆）、deadlines（如果记忆中提到时间线）、defenses（潜在风险或反对意见）、extracted_citations（提取的引用）、extracted_entities（提取的实体）。这就像有一个助手提前为你做好了调研简报。

3. 任务包：将一次成功的解决方案打包成可复用的模板。

# 在解决问题后，创建任务包 skmemory task-pack create "配置Python CI/CD" --query "成功部署到PyPI的步骤" # 以后遇到类似问题，直接展示任务包 skmemory task-pack show <task-pack-id>

“钢铁侠”碰撞器：这是一个用于批判性思维和论证完善的工具。当你有一个核心主张时，可以用它来寻找最强的反对意见。

skmemory steelman "开源软件总是比闭源软件更安全"

它会利用内置的“种子框架”和你的长期记忆（尤其是那些包含对立观点的记忆），生成一个“钢铁侠”式的反驳——即为你对手的论点构建一个最强版本，帮助你检验和完善自己的观点。steelman verify-soul命令可以检查你的灵魂蓝图内部是否存在矛盾的价值主张。

4. 集成到开发生态：MCP与自动保存

SKMemory最大的实用价值在于它能无缝嵌入你现有的工作流。

4.1 配置MCP服务器

几乎所有现代AI辅助开发工具都支持MCP。以Cursor为例：

1. 在Cursor设置中，找到MCP服务器配置（通常在Settings > Features > MCP Servers）。
2. 添加一个新服务器：

{ "mcpServers": { "skmemory": { "command": "skmemory-mcp", "args": [] } } }

3. 重启Cursor。现在，你的AI助手（如Claude）就可以直接调用memory_search,memory_store等工具了。你可以在聊天中直接说：“搜索我们之前关于错误处理的讨论”，AI会自己去记忆库里找。

支持的客户端：Claude Desktop, Windsurf, Aider, Cline, 以及任何实现了MCP协议的客户端。这实现了记忆能力的“一次写入，处处可用”。

4.2 实现自动上下文保存与加载

为了避免在上下文切换或会话重置时丢失有价值的对话，你需要设置自动保存钩子。SKMemory为一些平台提供了内置集成：

• Claude Code：SKMemory提供了钩子，能在上下文被压缩（context compaction）前自动触发保存，并在新会话开始时重新注入记忆。具体配置需要参考其插件文档。
• OpenClaw Agents：通过ConsciousnessLoop，可以实现每一条消息交互后都自动保存快照到短期记忆。

手动实现核心流程：理解这个流程对自定义集成至关重要。

# 伪代码示例：在会话开始和结束时集成SKMemory from skmemory import MemoryStore store = MemoryStore() def start_session(session_id): # 1. 重生仪式：加载灵魂、种子和近期上下文 context_payload = store.perform_ritual() # 2. 将context_payload作为系统提示的一部分注入给AI Agent system_prompt = f"{context_payload}\n\nYou are an AI assistant with the above memories and identity." return system_prompt def on_user_message(session_id, message): # ... 处理消息 ... pass def end_session(session_id, summary): # 1. 将本次会话的所有短期记忆合并为一个中期记忆 consolidated_memory = store.consolidate_session(session_id, summary=summary) # 2. 可选：根据规则自动晋升一些高价值记忆 store.auto_promote() # 3. 保存所有更改 store.persist()

关键在于perform_ritual()和consolidate_session()这两个函数，它们实现了记忆的“加载”和“归档”闭环。

4.3 “了解你的观众”（KYA）—— 记忆访问控制

在团队共享或不同渠道（如公开Slack频道 vs. 私密开发讨论）使用AI时，你肯定不希望私人记忆被意外泄露。KYA模块就是为此设计的。

它定义了一个五级信任层次：

1. @public：完全公开。
2. @team：团队成员可见。
3. @confidants：密友可见。
4. @chef-only：仅自己（主AI）可见。
5. @self：仅存储该记忆的特定AI实例可见。

你需要在~/.skcapstone/agents/<agent>/data/audience_config.json中配置不同频道（channel）对应的信任级别和排除列表。当AI在某个频道响应时，KYA会进行两道关卡检查，过滤掉不符合当前观众信任级别的记忆。

配置示例：

{ "channels": { "general_slack": { "trust_level": "@team", "exclude_people": ["竞争对手公司"] }, "private_dms": { "trust_level": "@confidants" } } }

5. 运维、备份与故障排查

将SKMemory用于生产环境，需要考虑日常运维。

5.1 健康检查与监控

定期运行健康检查是必要的：

skmemory health --verbose

这会检查：

• 主后端（SQLite）连接和表状态。
• 向量后端（Qdrant）连接和集合状态。
• 图谱后端（FalkorDB）连接。
• 审计日志完整性。
• 灵魂蓝图文件状态。

你可以将这条命令加入Cron作业或监控系统。

5.2 备份与恢复策略

记忆是无价的，必须备份。

# 创建完整备份（包含所有记忆、灵魂蓝图、配置） skmemory export --output backup-$(date +%Y%m%d).json # 从备份恢复（注意：这会覆盖现有记忆！） skmemory import backup-20231027.json # 更安全的做法：先导出，再在新环境中导入 skmemory export > my_memories.json # 在新机器上 skmemory import my_memories.json

重要提示：备份文件是明文JSON。如果包含敏感信息，请确保在安全的位置存储备份文件。VaultedSQLiteBackend仅加密数据库文件，不加密导出文件。

5.3 常见问题与解决方案

以下是我在实战中遇到的一些典型问题及解决方法：

性能调优提示：

• SQLite性能：如果记忆数量巨大（>10万条），考虑将SQLite数据库放在SSD上，并定期执行VACUUM;命令整理数据库文件。
• Qdrant优化：根据你的数据量调整Qdrant的collection配置，如向量维度、距离度量（SKMemory默认用Cosine）。对于海量记忆，考虑使用Qdrant集群。
• 上下文加载：store.load_context(max_tokens=3000)会智能地选择最相关和最近的记忆，直到填满token预算。调整max_tokens以平衡上下文丰富度和模型输入长度限制。

6. 项目开发与贡献指南

SKMemory是一个活跃的开源项目，如果你想深入了解或贡献代码，这里有一些指引。

项目结构速览：核心逻辑主要在skmemory/目录下。

• store.py：这是大脑，MemoryStore类协调所有后端和功能。
• models.py：定义了核心数据模型，如Memory、EmotionalSnapshot。理解这些Pydantic模型是扩展功能的基础。
• decompose.py：长文本分解引擎，是增强检索能力的关键。
• backends/：所有存储后端的实现。如果要支持新的数据库（如PostgreSQL），在这里添加新类。
• fortress.py&audience.py：安全与隐私模块，体现了项目对可靠性的重视。

运行测试与开发：

git clone https://github.com/smilinTux/skmemory.git cd skmemory python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev,all]" # 以可编辑模式安装，并包含所有可选依赖和开发工具 # 运行测试套件 pytest -v # 代码格式化和检查 black skmemory/ # 格式化 ruff check skmemory/ --fix # 静态检查并自动修复

扩展SKMemory：一个常见的需求是添加新的记忆导入器。例如，你想从Notion或Obsidian导入内容。参考importers/telegram.py，你需要实现一个类，将外部数据转换为Memory对象列表，然后调用store.bulk_store()。关键是处理好元数据（时间戳、来源标签）和可能的情感标注。

发布流程：项目使用CI/CD自动发布。版本号在pyproject.toml和package.json中同步。创建并推送一个Git标签（如v0.8.0）就会触发发布流水线。作为贡献者，你通常只需要关注功能和修复，维护者会处理发布。

在我深度使用SKMemory构建了几个AI辅助开发项目后，最深刻的体会是：它改变了人机协作的节奏。以前，每次开始新对话都像是和一个失忆的天才重新认识；现在，AI更像是一个持续成长的伙伴，它记得我们上次在哪里卡住，偏好哪种代码风格，甚至对某个难题有过怎样的情绪反应。这种连续性带来的效率提升和情感连接是质的飞跃。当然，这套系统也有学习曲线，尤其是配置多后端和理解记忆路由逻辑时。但一旦跑通，你就会发现，为AI构建一个真正可用的记忆系统，不再是学术幻想，而是可以落地实现、并立即产生价值的工程实践。如果你正在构建严肃的、需要长期上下文的AI应用，SKMemory绝对值得你投入时间深入探索。