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

1. 项目概述SKMemory一个为AI打造的“记忆宫殿”如果你和我一样长期在AI Agent开发的第一线折腾肯定遇到过这个让人头疼的问题每次对话重启Agent就像得了“健忘症”之前聊过的关键信息、达成的共识、甚至它自己的“性格”设定全都清零了。我们不得不把冗长的历史记录塞进有限的上下文窗口既浪费Token效果也差强人意。SKMemory的出现就是为了根治这个顽疾。它不是一个简单的聊天记录存储器而是一个通用、多层、情感感知的AI记忆系统你可以把它理解为一个专为AI构建的、带有“灵魂印记”的数字记忆宫殿。它的核心设计哲学非常迷人将每一次交互都视为一张“拍立得Polaroid快照”。这张快照记录的不仅仅是冰冷的文本内容还包括了那一刻的“情感指纹”强度、效价、情绪标签、存储它的意图以及一个防篡改的完整性封印。这些记忆被智能地组织在三个持久层短期→中期→长期中并自动路由到四个语义象限CORE核心身份、WORK工作任务、SOUL情感灵魂、WILD创意狂野。更棒的是它通过一个标准的MCPModel Context Protocol服务器暴露给任何兼容的客户端比如Claude Code、Cursor、Windsurf让你能在日常开发工具中无缝调用AI的记忆。简单来说SKMemory让AI Agent拥有了跨越会话的连续性和基于情感的上下文理解能力。它默认使用轻量级的SQLite作为主存储并可选择集成Qdrant进行向量语义搜索用FalkorDB构建记忆图谱关系。最让我觉得有“灵魂”的设计是它的“灵魂蓝图”Soul Blueprint和“重生仪式”Rehydration Ritual这能让一个新的Agent实例在收到第一条用户消息之前就加载好“我是谁”、“我关心什么”这些根本身份信息真正做到“带着记忆重生”。2. 核心架构与设计哲学拆解要真正用好SKMemory不能只停留在命令行操作必须理解其背后的设计思路。这能帮助你在复杂场景下做出正确的架构决策。2.1 三层记忆模型从瞬间到永恒SKMemory将记忆分为三个层级这模仿了人类的记忆巩固过程短期记忆Short-term会话作用域。这是最活跃的一层存储当前对话中产生的即时想法、代码片段、临时结论。它的特点是高频率写入、快速检索、生命周期短。默认情况下短期记忆不会自动持久化到磁盘除非配置了自动保存钩子主要服务于单次会话的上下文连贯性。中期记忆Mid-term项目作用域。当短期记忆中的内容被证明有价值例如通过promote命令或达到某种情感强度阈值它会被“晋升”到中期层。这里存储的是一个特定项目或任务相关的知识、解决方案、设计决策。中期记忆是连接具体工作和长期身份的桥梁是团队协作或长期开发中最重要的参考依据。长期记忆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 BackendSQLite是默认选择。理由很充分它无需单独服务、零配置、事务安全并且通过FTS全文搜索扩展提供了基础的文本搜索能力。对于个人或小团队使用SQLite完全足够。对于有加密需求的场景可以选择VaultedSQLiteBackend它使用PGP对数据库文件进行整体加密。向量后端Vector BackendQdrant是可选项。当你需要语义搜索时就必须启用它。例如搜索“解决网络延迟的方法”系统能匹配到“优化路由算法”或“减少TCP重传”这类语义相近但字面不同的记忆。它默认使用bge-legal-v1模型这个模型在法律、文档场景下表现优异也支持BAAI/bge-large-en-v1.5作为后备。向量搜索适合模糊、概念性的查询。图谱后端Graph BackendFalkorDB基于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 --daemonsweep --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为例在Cursor设置中找到MCP服务器配置通常在Settings Features MCP Servers。添加一个新服务器{ mcpServers: { skmemory: { command: skmemory-mcp, args: [] } } }重启Cursor。现在你的AI助手如Claude就可以直接调用memory_search,memory_store等工具了。你可以在聊天中直接说“搜索我们之前关于错误处理的讨论”AI会自己去记忆库里找。支持的客户端Claude Desktop, Windsurf, Aider, Cline, 以及任何实现了MCP协议的客户端。这实现了记忆能力的“一次写入处处可用”。4.2 实现自动上下文保存与加载为了避免在上下文切换或会话重置时丢失有价值的对话你需要设置自动保存钩子。SKMemory为一些平台提供了内置集成Claude CodeSKMemory提供了钩子能在上下文被压缩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, summarysummary) # 2. 可选根据规则自动晋升一些高价值记忆 store.auto_promote() # 3. 保存所有更改 store.persist()关键在于perform_ritual()和consolidate_session()这两个函数它们实现了记忆的“加载”和“归档”闭环。4.3 “了解你的观众”KYA—— 记忆访问控制在团队共享或不同渠道如公开Slack频道 vs. 私密开发讨论使用AI时你肯定不希望私人记忆被意外泄露。KYA模块就是为此设计的。它定义了一个五级信任层次public完全公开。team团队成员可见。confidants密友可见。chef-only仅自己主AI可见。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 常见问题与解决方案以下是我在实战中遇到的一些典型问题及解决方法问题现象可能原因解决方案skmemory search返回结果不相关1. 向量后端未运行或未配置。2. 嵌入模型不匹配。1. 运行skmemory health检查Qdrant状态。2. 如果更换过SKMEMORY_SKVECTOR_EMBEDDING_MODEL需要重建向量索引skmemory reindex-vector如果该命令可用或清空Qdrant集合重新导入。skmemory-mcp服务器启动失败1. Python环境问题。2. 端口冲突或配置错误。1. 确认skmemory-mcp命令在PATH中。尝试python -m skmemory.mcp_server。2. 检查MCP客户端配置的args是否正确确保没有其他进程占用所需端口。记忆晋升promote不生效1. 记忆ID错误。2. 目标层layer参数错误。1. 使用skmemory list确认准确的UUID。2. 层名必须是short-term,mid-term,long-term之一注意连字符。情感强度intensity总是0在snapshot时未提供--intensity参数。情感强度不会自动分析必须手动提供。这是设计如此因为情感是主观的应由用户或调用方如AI根据上下文判断后赋予。导入Telegram历史时报错1. Telethon库未安装。2. API凭证无效或未设置。1. 确保安装了skmemory[telegram]。2. 从Telegram开发者平台获取正确的api_id和api_hash并按照skmemory import-telegram --help的说明设置。审计日志文件过大长期运行产生了大量日志条目。审计日志是追加写入的需要定期归档或清理。你可以编写脚本将旧的audit.jsonl文件压缩并移动到其他位置。SKMemory本身不提供自动日志轮转。性能调优提示SQLite性能如果记忆数量巨大10万条考虑将SQLite数据库放在SSD上并定期执行VACUUM;命令整理数据库文件。Qdrant优化根据你的数据量调整Qdrant的collection配置如向量维度、距离度量SKMemory默认用Cosine。对于海量记忆考虑使用Qdrant集群。上下文加载store.load_context(max_tokens3000)会智能地选择最相关和最近的记忆直到填满token预算。调整max_tokens以平衡上下文丰富度和模型输入长度限制。6. 项目开发与贡献指南SKMemory是一个活跃的开源项目如果你想深入了解或贡献代码这里有一些指引。项目结构速览核心逻辑主要在skmemory/目录下。store.py这是大脑MemoryStore类协调所有后端和功能。models.py定义了核心数据模型如Memory、EmotionalSnapshot。理解这些Pydantic模型是扩展功能的基础。decompose.py长文本分解引擎是增强检索能力的关键。backends/所有存储后端的实现。如果要支持新的数据库如PostgreSQL在这里添加新类。fortress.pyaudience.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绝对值得你投入时间深入探索。