1. 项目概述为AI智能体构建持久记忆的“大脑”如果你用过Claude Code、OpenClaw这类AI智能体开发工具一定遇到过这样的困扰每次开启新会话智能体就像得了“健忘症”完全不记得上次聊了什么。你费尽心思教会它的项目结构、关键决策、甚至刚刚讨论过的代码逻辑只要窗口一关一切归零。更糟的是在长对话中智能体受限于上下文窗口会自动压缩早期信息那些至关重要的设计思路和约束条件可能在你最需要的时候被悄悄“遗忘”。这正是mnemon-dev/mnemon要解决的核心痛点。它不是一个普通的记忆库而是一个LLM监督的持久化记忆系统专门为AI智能体设计。你可以把它理解为智能体的“外置大脑”——一个独立运行、跨会话共享、且能随着时间积累知识的记忆中枢。最吸引人的是它采用了一种名为“LLM监督”的架构模式你的主智能体比如Claude Opus扮演“指挥官”负责判断什么值得记住、什么时候该回忆而Mnemon这个独立的二进制程序则扮演“执行者”负责所有确定性的计算工作比如存储、图索引、搜索和记忆衰减。这种分工既保证了记忆的智能性又避免了在记忆管道中嵌入另一个LLM带来的额外成本和复杂性。想象一下这样的场景你正在用Claude Code开发一个微服务项目。第一天你详细解释了服务的架构、数据库选型为什么用PostgreSQL而不是MongoDB以及API设计规范。第二天当你继续开发时Claude不仅能立刻回忆起这些上下文还能基于之前的决策给出连贯的建议。甚至一周后当你问“我们当初为什么选择这种认证方案”时它能从记忆图中精准提取出当时的讨论和权衡点。这就是Mnemon带来的“复利效应”——记忆越积累价值越大。2. 核心设计思路为什么是“LLM监督”与“四图架构”2.1 打破传统记忆方案的局限在深入Mnemon之前我们先看看市面上常见的几种AI记忆方案以及它们各自的短板LLM嵌入式记忆像Mem0、Letta这类工具直接在记忆处理管道中内置了一个LLM。每次记忆操作存储、检索都需要调用一次API推理。优点是记忆质量高但代价是额外的token消耗和延迟成本会随着使用频率线性增长。文件注入式记忆比如Claude自带的“代码记忆”功能本质是在会话开始时将一个文件的内容读入上下文。它无法实现跨会话记忆且受限于上下文窗口大小无法处理大量历史信息。MCP服务器模式通过Model Context ProtocolMCP将记忆功能暴露为工具供LLM调用。这解决了标准化问题但记忆逻辑该记什么、怎么记仍然需要开发者自己实现缺乏一套开箱即用的、基于认知语义的协议。Mnemon的“LLM监督”模式巧妙地避开了这些陷阱。它不替代你的主LLM做判断也不在管道中增加新的推理环节。你的Claude订阅本身就是智能层Mnemon只是为它提供了一个标准化的“记忆操作手册”和高效执行的“记忆仓库”。2.2 “四图架构”超越向量检索的关联记忆大多数记忆工具依赖向量相似度搜索即RAG的常见做法。这有个根本问题它只能找到“语义相似”的内容但无法捕捉记忆之间丰富的关系类型。比如时间关系“在讨论A方案之后我们决定采用B方案。”实体关系“用户‘张三’是‘项目X’的管理员。”因果关系“因为服务器负载过高所以我们决定引入缓存。”语义关系“微服务架构”和“领域驱动设计”在概念上相关。Mnemon底层采用四图混合存储时序图按时间顺序连接记忆节点维护事件的先后脉络。实体图识别并链接人物、地点、组织、项目等实体。因果图建立“原因-结果”、“问题-解决方案”等逻辑链条。语义图传统的向量嵌入空间用于相似性匹配。这种设计让记忆召回变得“意图感知”。当你问“我们上次关于这个错误的解决方案是什么”系统不仅会搜索语义相关的“错误”记录还会沿着因果图找到与之链接的“解决方案”节点结果更精准。2.3 意图原生协议让LLM用“母语”操作记忆这是Mnemon另一个精妙的设计。传统的数据库操作使用INSERT、SELECT这类SQL词汇这对LLM来说是一种“外语”需要额外学习且容易出错。Mnemon定义了三个核心原语直接映射到LLM的认知词汇表remember对应“记住这个”。LLM判断一段信息有价值后就发出这个指令。背后会自动处理去重、冲突检测并选择合适的图进行关联存储。link对应“关联那个”。用于显式地在两条已有记忆之间建立特定类型时序、因果等的连接。recall对应“回忆一下”。发起一次记忆检索。默认会启动混合检索同时进行基于图的遍历沿着关系链查找和可选的向量搜索然后用RRF倒数排名融合算法合并结果确保召回率和准确率的平衡。这个协议的输出也是为LLM量身定做的——结构化的JSON包含了记忆内容本身、关联的边、重要性分数、访问次数等丰富的“信号”而不仅仅是干巴巴的数据库行。这让LLM能更全面地理解记忆的上下文和价值。3. 系统集成与工作流钩子驱动的无感记忆Mnemon追求“零用户侧操作”。安装配置好后你完全不用手动运行mnemon命令。记忆的整个生命周期由智能体通过**钩子Hooks**自动驱动。我们以与Claude Code的集成为例拆解这个无缝的流程3.1 四大生命周期钩子当你执行mnemon setup后它会自动检测你的Claude Code环境并部署以下四个钩子文件到你的项目或全局目录如~/.claude/hooks/Prime钩子 (session_start.sh)在会话开始时触发。它的核心任务是加载“行为指南”guide.md到上下文中。这份指南是记忆系统的“宪法”详细规定了智能体在什么情况下应该回忆记忆、什么样的信息值得被记住、以及如何将记忆操作委托给子智能体以节省主上下文的token。没有它智能体就不知道记忆规则。Remind钩子 (user_prompt_submit.sh)在用户提交问题后、LLM开始思考前触发。它会提醒智能体“在回答之前先根据当前问题回忆一下相关的历史记忆并判断是否需要将对话中的新信息记下来。”这确保了智能体的思考是建立在已有知识基础上的。Nudge钩子 (stop.sh)在LLM生成完回答后触发。这是一个“事后检查”点提醒智能体回顾刚才的交互“在刚才的对话中有没有产生值得长期保存的洞察或结论如果有现在记住它。”Compact钩子 (pre_compact.sh)在Claude Code即将进行上下文压缩前触发。这是防止记忆丢失的关键防线。它会指令智能体“上下文马上要被裁剪了请快速扫描即将被移除的旧消息提取出其中最关键的见解并保存到持久化记忆中。”3.2 技能文件与行为指南的分工除了钩子Mnemon还会部署两个关键文件技能文件 (SKILL.md)相当于“工具说明书”。它用Claude能理解的格式定义了remember、link、recall这三个命令的语法、参数和示例。智能体通过阅读这个文件来学会如何“使用”Mnemon。行为指南 (~/.mnemon/prompt/guide.md)相当于“操作规程”或“决策手册”。它规定了何时以及为何要使用那些技能。例如回忆的时机当用户的问题涉及项目历史、技术决策、或个人偏好时应主动发起recall。记忆的标准以下信息值得remember1) 重要的技术决策及原因2) 复杂的项目上下文3) 用户明确表示重要的信息4) 从错误中总结的教训。子代理委托执行remember命令时应委托给一个更轻量级的模型如Claude Sonnet来执行以节省主会话Opus的token。实操心得定制你的记忆规则guide.md是高度可定制的。如果你主要用Claude做代码审查可以强化“记住代码坏味道和修复模式”的规则。如果是用于创意写作则可以改为侧重“记住角色设定和情节伏笔”。修改这个文件是让Mnemon贴合你工作流的最有效方式。文件采用Markdown格式逻辑清晰Claude理解起来毫无压力。3.3 子代理委托高效省钱的执行策略这是一个非常实用的设计细节。记忆的“判断”记什么由强大的主模型如Claude Opus做出但实际的“执行”运行mnemon remember命令可以委托给一个更便宜、更快的子模型如Claude Sonnet或Haiku。为什么这样做因为执行remember命令本身只是一个格式化的调用不需要很强的推理能力。在主会话中执行会占用宝贵的长上下文token而委托出去则几乎零成本。行为指南里通常会包含这样的指令“当你决定要记住一段信息时请生成一个包含完整记忆内容的JSON块并指示子代理‘请执行mnemon remember [JSON]’。”这样记忆操作就被优雅地“卸载”了保持了主会话的整洁和高效。4. 安装、配置与多平台集成实战4.1 核心安装与验证Mnemon是Go语言编写的单二进制文件安装极其简单。对于macOS或Linux用户首推Homebrewbrew install mnemon-dev/tap/mnemon对于Go开发者也可以直接通过go install安装go install github.com/mnemon-dev/mnemonlatest安装后务必验证一下mnemon --version # 输出类似mnemon version 0.1.04.2 集成Claude Code一键配置这是最常用的场景。在你的项目根目录或任意目录下运行mnemon setup这个命令会启动一个交互式配置向导自动检测它会查找你的Claude Code安装和配置文件。模式选择询问你是进行**项目级Local安装还是全局Global**安装。项目级记忆钩子和技能只对当前项目生效。推荐用于大多数情况隔离性好。全局安装到~/.claude/目录对所有Claude Code项目生效。方便但如果你有项目不需要记忆功能可能会产生干扰。部署文件根据你的选择自动创建或修改~/.claude/hooks/下的钩子脚本并部署SKILL.md技能文件。生成指南在~/.mnemon/prompt/目录下创建初始的guide.md行为指南。配置完成后重启你的Claude Code会话。你会发现在会话开始后系统消息里会自动加载一段关于记忆系统的说明记忆功能就此生效。4.3 集成OpenClawOpenClaw是另一个流行的AI智能体框架。Mnemon通过插件机制与之集成命令更简洁mnemon setup --target openclaw --yes--yes参数表示非交互式直接使用默认配置。这条命令会将Mnemon技能作为插件安装到~/.openclaw/plugins/。配置OpenClaw的网关使其能调用Mnemon。同样部署行为指南。完成后需要重启OpenClaw网关进程来加载新插件。4.4 集成NanoClaw容器化环境NanoClaw在Linux容器中运行智能体集成方式略有不同体现了Mnemon设计的灵活性在宿主机上安装Mnemon使用上述任一方法在运行NanoClaw的机器上安装mnemon二进制。在NanoClaw项目中使用技能NanoClaw的Claude Code技能目录中有一个现成的/add-mnemon技能。在项目内运行这个技能Claude会帮你修改项目的Dockerfile将宿主机上的mnemon二进制和配置目录挂载到容器内。添加一个容器内可用的Mnemon技能。配置存储卷确保容器的记忆能持久化到宿主机。隔离与共享一个精妙的设计是你可以为每个WhatsApp群组NanoClaw的典型用例配置独立的记忆存储避免交叉干扰。同时也可以设置一个全局的只读记忆库用于共享一些公共知识如公司规章制度。注意事项容器挂载路径在配置容器卷挂载时要确保宿主机上的~/.mnemon目录或你自定义的MNEMON_DATA_DIR有正确的权限允许容器内的进程读写。通常需要将目录的所有者改为容器运行时使用的用户ID如1000。4.5 记忆存储隔离多项目并行不悖你可能会担心所有项目都用同一个记忆库会不会混乱Mnemon提供了命名存储功能来完美解决。假设你同时进行“工作项目A”和“个人学习B”# 创建两个独立的记忆库 mnemon store create work_project_a mnemon store create personal_learning_b # 切换到工作项目上下文 mnemon store set work_project_a # 或者通过环境变量设置 export MNEMON_STOREwork_project_a # 现在所有在这个终端/session中运行的mnemon命令都会读写work_project_a这个库。 # 当你切换到个人学习时 export MNEMON_STOREpersonal_learning_b这样你可以通过环境变量MNEMON_STORE为不同的终端会话、不同的自动化脚本指向不同的记忆库实现完全隔离。默认的存储名是default。5. 高级功能与深度配置解析5.1 混合检索策略图遍历与向量搜索的融合Mnemon的recall命令之所以强大在于其默认启用的意图感知混合检索。其工作流程如下查询解析首先系统会尝试从你的查询中提取意图和关键实体。图遍历检索以上述实体为起点在时序、实体、因果、语义四图中进行遍历寻找直接和间接关联的节点。例如查询“上周解决的数据库超时问题”系统会先在实体图中找到“数据库”在因果图中找到“超时”和“解决”的关系链在时序图中限定“上周”的范围。向量语义检索可选如果你配置了本地的Ollama服务Mnemon会使用你指定的嵌入模型如nomic-embed-text将查询和所有记忆内容进行向量化执行近邻搜索。结果融合使用**RRF倒数排名融合**算法合并两种检索方式的结果。RRF的基本原理是一个记忆项在两种检索结果中的排名越靠前排名数字越小其最终得分越高。公式可以简化为score 1/(k rank_in_graph) 1/(k rank_in_vector)。这保证了即使某条记忆在向量搜索中不相似但只要在图关系中高度相关也能被召回。如何启用向量搜索确保已安装并运行 Ollama 。拉取一个嵌入模型如ollama pull nomic-embed-text。设置环境变量或写入配置export MNEMON_EMBED_ENDPOINThttp://localhost:11434 export MNEMON_EMBED_MODELnomic-embed-text重启你的智能体会话混合检索即自动生效。5.2 记忆的生命周期管理衰减、强化与清理记忆不是只进不出的。Mnemon实现了模拟人类记忆的保留生命周期重要性衰减每条记忆都有一个初始的重要性分数。如果一条记忆长时间不被recall访问其重要性会随时间缓慢衰减。这模拟了“不常用的记忆会变模糊”。访问计数强化每次成功召回一条记忆它的访问次数就会增加并轻微提升其重要性分数。这模拟了“经常回忆的知识更牢固”。垃圾回收系统会定期或手动触发扫描所有记忆。重要性分数低于某个阈值的、且长时间未被访问的记忆会被标记为“可清理”。在下次压缩或手动清理时这些记忆会被归档或删除释放空间。你可以通过命令行工具查看和管理记忆的生命周期状态# 查看记忆库状态包括记忆数量、平均重要性等 mnemon status # 手动触发垃圾回收谨慎使用 mnemon gc --dry-run # 先预览哪些记忆会被清理 mnemon gc --confirm # 执行清理5.3 去重与冲突解决当智能体试图remember一条看似重复的信息时Mnemon不会简单丢弃或重复存储而是执行智能去重语义去重计算新记忆与已有记忆的语义相似度如果启用了嵌入。如果相似度超过阈值如95%则视为重复。冲突检测如果新记忆与旧记忆在关键事实如“项目截止日期”上表述矛盾系统会检测到冲突。解决策略默认策略是“跳过”完全重复的“合并”相似但互补的将新信息补充到旧节点中对于冲突的可以选择“保留两者并标记冲突”或“用新的覆盖旧的”取决于配置。所有这些行为都可以在guide.md中通过提示词引导智能体去处理。5.4 环境变量详解Mnemon的配置主要通过环境变量完成以下是核心变量环境变量默认值描述MNEMON_DATA_DIR~/.mnemon所有记忆数据、配置和日志的根目录。可以改为网络存储路径实现多机共享需注意文件锁。MNEMON_STOREdefault当前会话使用的记忆库名称。用于实现多租户隔离。MNEMON_LOG_LEVELinfo日志级别 (debug,info,warn,error)。调试问题时设为debug可以看到详细的钩子调用和记忆操作日志。MNEMON_EMBED_ENDPOINThttp://localhost:11434Ollama API地址。如果你将Ollama部署在另一台机器或Docker容器中需要修改此地址。MNEMON_EMBED_MODELnomic-embed-text用于生成文本嵌入向量的模型名称。确保Ollama中已拉取该模型。配置建议对于普通用户通常只需要关心MNEMON_STORE来切换项目。高级用户可以通过MNEMON_DATA_DIR将记忆库放在同步盘如iCloud Drive, Dropbox中实现不同电脑间的记忆同步但需注意并发写入可能带来的问题。6. 故障排查与常见问题实录即使设计再精良在实际部署和运行中也可能遇到问题。以下是我在深度使用Mnemon过程中遇到的一些典型情况及解决方法。6.1 钩子未触发记忆功能不生效症状Claude Code会话开始后没有看到关于记忆系统的提示对话中也不会自动回忆或记忆。排查步骤检查钩子安装位置运行ls -la ~/.claude/hooks/全局安装或ls -la .claude/hooks/项目安装。确认能看到session_start.sh,user_prompt_submit.sh等文件。检查钩子内容查看session_start.sh确认其内容包含加载guide.md的命令。有时安装脚本可能因权限问题未能成功写入。检查Claude Code版本某些旧版本的Claude Code可能对钩子的支持不完整。确保你使用的是最新版本。查看Mnemon日志设置export MNEMON_LOG_LEVELdebug然后重新启动Claude Code。在~/.mnemon/logs/目录下查看最新的日志文件搜索“hook”、“prime”等关键词看是否有错误信息。常见原因与解决权限问题钩子脚本没有执行权限。运行chmod x ~/.claude/hooks/*.sh。路径问题guide.md不在~/.mnemon/prompt/目录下。重新运行mnemon setup --force可以重新部署所有文件。配置冲突如果你同时有全局和项目级钩子Claude Code可能会以某种优先级加载。建议清理掉一个只保留一种安装方式。6.2 记忆召回结果不相关或为空症状智能体似乎尝试了recall但返回的结果风马牛不相及或者说“没有相关记忆”。排查步骤确认记忆已存储手动运行mnemon list --limit 5查看最近是否成功存储了记忆。如果没有说明remember环节可能失败了。检查guide.md规则回忆的触发和判断极度依赖指南中的规则。检查你的~/.mnemon/prompt/guide.md看其中关于“何时回忆”的规则是否过于严格或模糊。测试混合检索手动运行一个召回测试分别观察图检索和向量检索的结果# 模拟一个查询查看详细输出 mnemon recall 项目架构设计 --verbose在输出中你会看到分别来自“graph”和“vector”如果启用的结果列表。如果某一项结果为空说明对应的检索路径有问题。检查向量模型如果启用了向量搜索运行ollama ps确认嵌入模型正在运行。尝试用 Ollama 直接测试该模型ollama run nomic-embed-text test sentence。常见原因与解决指南规则不当智能体可能因为你的问题不符合指南中定义的“值得回忆”的场景而根本没有发起recall。尝试在对话中更明确地提及历史或修改guide.md放宽回忆条件。图关系未建立新存储的记忆是孤立的节点没有通过link与其他记忆建立关系。导致图遍历检索时无法通过关系链找到它。确保你的指南鼓励智能体在remember时也思考关联性。向量模型不匹配使用的嵌入模型不适合你的语言或领域例如用英文模型处理中文。尝试更换Ollama中的嵌入模型并更新MNEMON_EMBED_MODEL环境变量。6.3 性能问题响应变慢或内存占用高症状集成Mnemon后感觉Claude Code的响应速度变慢或者系统资源占用明显增加。排查步骤检查记忆库大小运行mnemon status查看记忆节点和边的数量。如果数量巨大例如超过10万检索和去重操作自然会变慢。监控钩子执行时间在debug日志级别下观察每个钩子脚本的执行耗时。特别是pre_compact.sh在长上下文压缩时它需要扫描大量文本可能比较耗时。检查Ollama资源如果启用了向量搜索Ollama服务可能会占用大量CPU和内存。使用系统监控工具如htop查看ollama进程的资源使用情况。优化建议定期清理对于不再活跃的项目使用mnemon store export备份后删除旧的存储库或使用mnemon gc清理低重要性记忆。调整指南修改guide.md让智能体更“挑剔”地选择记忆内容避免存储过多琐碎信息。例如增加“只有影响未来决策的结论才值得记忆”这样的规则。升级硬件或调整配置如果使用Ollama考虑为机器增加内存或者为Ollama分配更少的线程通过Ollama的启动参数。禁用向量搜索如果对语义检索需求不强可以暂时注释掉环境变量MNEMON_EMBED_MODEL回退到纯图检索性能会有显著提升。6.4 与OpenClaw/NanoClaw集成失败症状在OpenClaw中调用Mnemon技能无响应或在NanoClaw容器中找不到mnemon命令。排查步骤OpenClaw确认插件已安装检查~/.openclaw/plugins/目录下是否有mnemon相关文件。检查OpenClaw网关配置确认网关的配置文件中正确引用了Mnemon插件。查看OpenClaw网关日志通常有详细的插件加载和错误信息。NanoClaw确认宿主机安装在宿主机上运行which mnemon确认二进制文件存在且路径正确。检查Dockerfile挂载使用/add-mnemon技能后检查生成的Dockerfile确认volumes部分正确挂载了宿主机上的~/.mnemon目录和mnemon二进制路径到容器内。检查容器内路径进入容器 (docker exec -it container_name /bin/bash)检查挂载的目录和文件是否存在以及权限是否正确。解决思路这类集成问题多半是路径或配置错误。仔细对比Mnemon的安装路径、容器的挂载路径以及框架期望的插件路径。使用绝对路径而非相对路径通常是更安全的选择。7. 开发与扩展理解代码结构与未来方向对于想要贡献代码或基于Mnemon进行二次开发的开发者了解其代码结构和设计哲学至关重要。7.1 项目结构与核心模块Mnemon的Go代码结构清晰遵循了标准项目布局cmd/mnemon/存放所有CLI命令的入口定义基于Cobra框架如remember.go,recall.go,store.go。internal/核心业务逻辑外部项目不应直接导入。graph/四图时序、实体、因果、语义的数据结构和算法实现。storage/存储抽象层。目前主要是sqlite/实现未来可以轻松添加postgres/,neo4j/等适配器。memory/记忆生命周期管理衰减、GC、去重的核心逻辑。embedding/向量嵌入相关的客户端和接口目前主要对接Ollama。pkg/可以安全对外暴露的库如协议定义、工具函数等。docs/设计文档和图表。scripts/构建和开发脚本。核心流程追踪以一次remember调用为例CLI层 (cmd/mnemon/remember.go) 解析参数。调用internal/memory/manager.go的Remember方法。Manager 调用internal/storage接口存储原始内容。同时启动异步任务通过internal/graph模块分析内容提取实体、因果关系并创建相应的图节点和边。如果启用了嵌入还会调用internal/embedding客户端生成向量并存储。最后更新记忆的元数据如重要性、访问时间。7.2 编译与测试对于开发者项目提供了完善的Makefile# 克隆代码 git clone https://github.com/mnemon-dev/mnemon.git cd mnemon # 安装依赖 (Go modules会自动处理) go mod download # 运行单元测试 make test # 构建二进制文件到当前目录 make build # 输出 ./bin/mnemon # 构建并安装到 $GOBIN (通常是 ~/go/bin) make install # 运行端到端集成测试需要本地运行Claude Code测试环境 make test-e2e开发建议在修改核心逻辑如图算法、存储层后务必运行make test。项目包含了对去重、衰减、混合检索等复杂逻辑的单元测试能有效防止回归错误。7.3 未来架构记忆网关与协议抽象Mnemon的愿景不仅是做一个工具更是定义一套LLM与记忆系统交互的协议标准。当前版本将协议remember/link/recall和存储引擎SQLite耦合在一起但这只是开始。未来的方向是清晰的分层架构协议层定义标准的、意图原生的记忆操作APIgRPC或HTTP。任何智能体框架Claude Code, OpenClaw, 自定义Agent都可以通过这个协议与记忆系统对话。适配器层实现协议层到不同存储后端的转换。SQLite适配器是第一个未来可以有PostgreSQL适配器适合多实例共享、Neo4j适配器原生图数据库性能更优、甚至云服务适配器。存储层具体的数据库。这种解耦带来巨大灵活性智能体侧优化不同框架可以基于同一协议独立优化何时调用recall、如何构建remember的提示词。存储侧优化数据库专家可以专注于为图遍历、向量混合查询设计更高效的索引和算法而不必关心上层的LLM交互逻辑。如果你对实现新的存储适配器感兴趣可以重点关注internal/storage/interface.go中定义的接口。实现这些接口并在cmd/mnemon/serve.go中注册新的适配器理论上就能让Mnemon支持任何一种数据库后端。7.4 贡献指南项目社区欢迎各种贡献报告Bug在GitHub Issues中提供清晰的重现步骤、环境信息和日志。功能建议先查阅docs/DESIGN.md中的未来方向然后在Issues中讨论你的想法。提交代码Fork仓库在特性分支上开发确保通过make test然后提交Pull Request。代码风格遵循标准的Go规范并使用有意义的提交信息。一个对新手友好的贡献起点是丰富文档尤其是翻译、添加更多集成示例如与其他LLM CLI的集成或编写教程。另一个方向是开发辅助工具比如一个图形化的记忆库浏览器或者一个分析记忆图谱的可视化工具。
为AI智能体构建持久记忆：LLM监督与四图架构解析
1. 项目概述为AI智能体构建持久记忆的“大脑”如果你用过Claude Code、OpenClaw这类AI智能体开发工具一定遇到过这样的困扰每次开启新会话智能体就像得了“健忘症”完全不记得上次聊了什么。你费尽心思教会它的项目结构、关键决策、甚至刚刚讨论过的代码逻辑只要窗口一关一切归零。更糟的是在长对话中智能体受限于上下文窗口会自动压缩早期信息那些至关重要的设计思路和约束条件可能在你最需要的时候被悄悄“遗忘”。这正是mnemon-dev/mnemon要解决的核心痛点。它不是一个普通的记忆库而是一个LLM监督的持久化记忆系统专门为AI智能体设计。你可以把它理解为智能体的“外置大脑”——一个独立运行、跨会话共享、且能随着时间积累知识的记忆中枢。最吸引人的是它采用了一种名为“LLM监督”的架构模式你的主智能体比如Claude Opus扮演“指挥官”负责判断什么值得记住、什么时候该回忆而Mnemon这个独立的二进制程序则扮演“执行者”负责所有确定性的计算工作比如存储、图索引、搜索和记忆衰减。这种分工既保证了记忆的智能性又避免了在记忆管道中嵌入另一个LLM带来的额外成本和复杂性。想象一下这样的场景你正在用Claude Code开发一个微服务项目。第一天你详细解释了服务的架构、数据库选型为什么用PostgreSQL而不是MongoDB以及API设计规范。第二天当你继续开发时Claude不仅能立刻回忆起这些上下文还能基于之前的决策给出连贯的建议。甚至一周后当你问“我们当初为什么选择这种认证方案”时它能从记忆图中精准提取出当时的讨论和权衡点。这就是Mnemon带来的“复利效应”——记忆越积累价值越大。2. 核心设计思路为什么是“LLM监督”与“四图架构”2.1 打破传统记忆方案的局限在深入Mnemon之前我们先看看市面上常见的几种AI记忆方案以及它们各自的短板LLM嵌入式记忆像Mem0、Letta这类工具直接在记忆处理管道中内置了一个LLM。每次记忆操作存储、检索都需要调用一次API推理。优点是记忆质量高但代价是额外的token消耗和延迟成本会随着使用频率线性增长。文件注入式记忆比如Claude自带的“代码记忆”功能本质是在会话开始时将一个文件的内容读入上下文。它无法实现跨会话记忆且受限于上下文窗口大小无法处理大量历史信息。MCP服务器模式通过Model Context ProtocolMCP将记忆功能暴露为工具供LLM调用。这解决了标准化问题但记忆逻辑该记什么、怎么记仍然需要开发者自己实现缺乏一套开箱即用的、基于认知语义的协议。Mnemon的“LLM监督”模式巧妙地避开了这些陷阱。它不替代你的主LLM做判断也不在管道中增加新的推理环节。你的Claude订阅本身就是智能层Mnemon只是为它提供了一个标准化的“记忆操作手册”和高效执行的“记忆仓库”。2.2 “四图架构”超越向量检索的关联记忆大多数记忆工具依赖向量相似度搜索即RAG的常见做法。这有个根本问题它只能找到“语义相似”的内容但无法捕捉记忆之间丰富的关系类型。比如时间关系“在讨论A方案之后我们决定采用B方案。”实体关系“用户‘张三’是‘项目X’的管理员。”因果关系“因为服务器负载过高所以我们决定引入缓存。”语义关系“微服务架构”和“领域驱动设计”在概念上相关。Mnemon底层采用四图混合存储时序图按时间顺序连接记忆节点维护事件的先后脉络。实体图识别并链接人物、地点、组织、项目等实体。因果图建立“原因-结果”、“问题-解决方案”等逻辑链条。语义图传统的向量嵌入空间用于相似性匹配。这种设计让记忆召回变得“意图感知”。当你问“我们上次关于这个错误的解决方案是什么”系统不仅会搜索语义相关的“错误”记录还会沿着因果图找到与之链接的“解决方案”节点结果更精准。2.3 意图原生协议让LLM用“母语”操作记忆这是Mnemon另一个精妙的设计。传统的数据库操作使用INSERT、SELECT这类SQL词汇这对LLM来说是一种“外语”需要额外学习且容易出错。Mnemon定义了三个核心原语直接映射到LLM的认知词汇表remember对应“记住这个”。LLM判断一段信息有价值后就发出这个指令。背后会自动处理去重、冲突检测并选择合适的图进行关联存储。link对应“关联那个”。用于显式地在两条已有记忆之间建立特定类型时序、因果等的连接。recall对应“回忆一下”。发起一次记忆检索。默认会启动混合检索同时进行基于图的遍历沿着关系链查找和可选的向量搜索然后用RRF倒数排名融合算法合并结果确保召回率和准确率的平衡。这个协议的输出也是为LLM量身定做的——结构化的JSON包含了记忆内容本身、关联的边、重要性分数、访问次数等丰富的“信号”而不仅仅是干巴巴的数据库行。这让LLM能更全面地理解记忆的上下文和价值。3. 系统集成与工作流钩子驱动的无感记忆Mnemon追求“零用户侧操作”。安装配置好后你完全不用手动运行mnemon命令。记忆的整个生命周期由智能体通过**钩子Hooks**自动驱动。我们以与Claude Code的集成为例拆解这个无缝的流程3.1 四大生命周期钩子当你执行mnemon setup后它会自动检测你的Claude Code环境并部署以下四个钩子文件到你的项目或全局目录如~/.claude/hooks/Prime钩子 (session_start.sh)在会话开始时触发。它的核心任务是加载“行为指南”guide.md到上下文中。这份指南是记忆系统的“宪法”详细规定了智能体在什么情况下应该回忆记忆、什么样的信息值得被记住、以及如何将记忆操作委托给子智能体以节省主上下文的token。没有它智能体就不知道记忆规则。Remind钩子 (user_prompt_submit.sh)在用户提交问题后、LLM开始思考前触发。它会提醒智能体“在回答之前先根据当前问题回忆一下相关的历史记忆并判断是否需要将对话中的新信息记下来。”这确保了智能体的思考是建立在已有知识基础上的。Nudge钩子 (stop.sh)在LLM生成完回答后触发。这是一个“事后检查”点提醒智能体回顾刚才的交互“在刚才的对话中有没有产生值得长期保存的洞察或结论如果有现在记住它。”Compact钩子 (pre_compact.sh)在Claude Code即将进行上下文压缩前触发。这是防止记忆丢失的关键防线。它会指令智能体“上下文马上要被裁剪了请快速扫描即将被移除的旧消息提取出其中最关键的见解并保存到持久化记忆中。”3.2 技能文件与行为指南的分工除了钩子Mnemon还会部署两个关键文件技能文件 (SKILL.md)相当于“工具说明书”。它用Claude能理解的格式定义了remember、link、recall这三个命令的语法、参数和示例。智能体通过阅读这个文件来学会如何“使用”Mnemon。行为指南 (~/.mnemon/prompt/guide.md)相当于“操作规程”或“决策手册”。它规定了何时以及为何要使用那些技能。例如回忆的时机当用户的问题涉及项目历史、技术决策、或个人偏好时应主动发起recall。记忆的标准以下信息值得remember1) 重要的技术决策及原因2) 复杂的项目上下文3) 用户明确表示重要的信息4) 从错误中总结的教训。子代理委托执行remember命令时应委托给一个更轻量级的模型如Claude Sonnet来执行以节省主会话Opus的token。实操心得定制你的记忆规则guide.md是高度可定制的。如果你主要用Claude做代码审查可以强化“记住代码坏味道和修复模式”的规则。如果是用于创意写作则可以改为侧重“记住角色设定和情节伏笔”。修改这个文件是让Mnemon贴合你工作流的最有效方式。文件采用Markdown格式逻辑清晰Claude理解起来毫无压力。3.3 子代理委托高效省钱的执行策略这是一个非常实用的设计细节。记忆的“判断”记什么由强大的主模型如Claude Opus做出但实际的“执行”运行mnemon remember命令可以委托给一个更便宜、更快的子模型如Claude Sonnet或Haiku。为什么这样做因为执行remember命令本身只是一个格式化的调用不需要很强的推理能力。在主会话中执行会占用宝贵的长上下文token而委托出去则几乎零成本。行为指南里通常会包含这样的指令“当你决定要记住一段信息时请生成一个包含完整记忆内容的JSON块并指示子代理‘请执行mnemon remember [JSON]’。”这样记忆操作就被优雅地“卸载”了保持了主会话的整洁和高效。4. 安装、配置与多平台集成实战4.1 核心安装与验证Mnemon是Go语言编写的单二进制文件安装极其简单。对于macOS或Linux用户首推Homebrewbrew install mnemon-dev/tap/mnemon对于Go开发者也可以直接通过go install安装go install github.com/mnemon-dev/mnemonlatest安装后务必验证一下mnemon --version # 输出类似mnemon version 0.1.04.2 集成Claude Code一键配置这是最常用的场景。在你的项目根目录或任意目录下运行mnemon setup这个命令会启动一个交互式配置向导自动检测它会查找你的Claude Code安装和配置文件。模式选择询问你是进行**项目级Local安装还是全局Global**安装。项目级记忆钩子和技能只对当前项目生效。推荐用于大多数情况隔离性好。全局安装到~/.claude/目录对所有Claude Code项目生效。方便但如果你有项目不需要记忆功能可能会产生干扰。部署文件根据你的选择自动创建或修改~/.claude/hooks/下的钩子脚本并部署SKILL.md技能文件。生成指南在~/.mnemon/prompt/目录下创建初始的guide.md行为指南。配置完成后重启你的Claude Code会话。你会发现在会话开始后系统消息里会自动加载一段关于记忆系统的说明记忆功能就此生效。4.3 集成OpenClawOpenClaw是另一个流行的AI智能体框架。Mnemon通过插件机制与之集成命令更简洁mnemon setup --target openclaw --yes--yes参数表示非交互式直接使用默认配置。这条命令会将Mnemon技能作为插件安装到~/.openclaw/plugins/。配置OpenClaw的网关使其能调用Mnemon。同样部署行为指南。完成后需要重启OpenClaw网关进程来加载新插件。4.4 集成NanoClaw容器化环境NanoClaw在Linux容器中运行智能体集成方式略有不同体现了Mnemon设计的灵活性在宿主机上安装Mnemon使用上述任一方法在运行NanoClaw的机器上安装mnemon二进制。在NanoClaw项目中使用技能NanoClaw的Claude Code技能目录中有一个现成的/add-mnemon技能。在项目内运行这个技能Claude会帮你修改项目的Dockerfile将宿主机上的mnemon二进制和配置目录挂载到容器内。添加一个容器内可用的Mnemon技能。配置存储卷确保容器的记忆能持久化到宿主机。隔离与共享一个精妙的设计是你可以为每个WhatsApp群组NanoClaw的典型用例配置独立的记忆存储避免交叉干扰。同时也可以设置一个全局的只读记忆库用于共享一些公共知识如公司规章制度。注意事项容器挂载路径在配置容器卷挂载时要确保宿主机上的~/.mnemon目录或你自定义的MNEMON_DATA_DIR有正确的权限允许容器内的进程读写。通常需要将目录的所有者改为容器运行时使用的用户ID如1000。4.5 记忆存储隔离多项目并行不悖你可能会担心所有项目都用同一个记忆库会不会混乱Mnemon提供了命名存储功能来完美解决。假设你同时进行“工作项目A”和“个人学习B”# 创建两个独立的记忆库 mnemon store create work_project_a mnemon store create personal_learning_b # 切换到工作项目上下文 mnemon store set work_project_a # 或者通过环境变量设置 export MNEMON_STOREwork_project_a # 现在所有在这个终端/session中运行的mnemon命令都会读写work_project_a这个库。 # 当你切换到个人学习时 export MNEMON_STOREpersonal_learning_b这样你可以通过环境变量MNEMON_STORE为不同的终端会话、不同的自动化脚本指向不同的记忆库实现完全隔离。默认的存储名是default。5. 高级功能与深度配置解析5.1 混合检索策略图遍历与向量搜索的融合Mnemon的recall命令之所以强大在于其默认启用的意图感知混合检索。其工作流程如下查询解析首先系统会尝试从你的查询中提取意图和关键实体。图遍历检索以上述实体为起点在时序、实体、因果、语义四图中进行遍历寻找直接和间接关联的节点。例如查询“上周解决的数据库超时问题”系统会先在实体图中找到“数据库”在因果图中找到“超时”和“解决”的关系链在时序图中限定“上周”的范围。向量语义检索可选如果你配置了本地的Ollama服务Mnemon会使用你指定的嵌入模型如nomic-embed-text将查询和所有记忆内容进行向量化执行近邻搜索。结果融合使用**RRF倒数排名融合**算法合并两种检索方式的结果。RRF的基本原理是一个记忆项在两种检索结果中的排名越靠前排名数字越小其最终得分越高。公式可以简化为score 1/(k rank_in_graph) 1/(k rank_in_vector)。这保证了即使某条记忆在向量搜索中不相似但只要在图关系中高度相关也能被召回。如何启用向量搜索确保已安装并运行 Ollama 。拉取一个嵌入模型如ollama pull nomic-embed-text。设置环境变量或写入配置export MNEMON_EMBED_ENDPOINThttp://localhost:11434 export MNEMON_EMBED_MODELnomic-embed-text重启你的智能体会话混合检索即自动生效。5.2 记忆的生命周期管理衰减、强化与清理记忆不是只进不出的。Mnemon实现了模拟人类记忆的保留生命周期重要性衰减每条记忆都有一个初始的重要性分数。如果一条记忆长时间不被recall访问其重要性会随时间缓慢衰减。这模拟了“不常用的记忆会变模糊”。访问计数强化每次成功召回一条记忆它的访问次数就会增加并轻微提升其重要性分数。这模拟了“经常回忆的知识更牢固”。垃圾回收系统会定期或手动触发扫描所有记忆。重要性分数低于某个阈值的、且长时间未被访问的记忆会被标记为“可清理”。在下次压缩或手动清理时这些记忆会被归档或删除释放空间。你可以通过命令行工具查看和管理记忆的生命周期状态# 查看记忆库状态包括记忆数量、平均重要性等 mnemon status # 手动触发垃圾回收谨慎使用 mnemon gc --dry-run # 先预览哪些记忆会被清理 mnemon gc --confirm # 执行清理5.3 去重与冲突解决当智能体试图remember一条看似重复的信息时Mnemon不会简单丢弃或重复存储而是执行智能去重语义去重计算新记忆与已有记忆的语义相似度如果启用了嵌入。如果相似度超过阈值如95%则视为重复。冲突检测如果新记忆与旧记忆在关键事实如“项目截止日期”上表述矛盾系统会检测到冲突。解决策略默认策略是“跳过”完全重复的“合并”相似但互补的将新信息补充到旧节点中对于冲突的可以选择“保留两者并标记冲突”或“用新的覆盖旧的”取决于配置。所有这些行为都可以在guide.md中通过提示词引导智能体去处理。5.4 环境变量详解Mnemon的配置主要通过环境变量完成以下是核心变量环境变量默认值描述MNEMON_DATA_DIR~/.mnemon所有记忆数据、配置和日志的根目录。可以改为网络存储路径实现多机共享需注意文件锁。MNEMON_STOREdefault当前会话使用的记忆库名称。用于实现多租户隔离。MNEMON_LOG_LEVELinfo日志级别 (debug,info,warn,error)。调试问题时设为debug可以看到详细的钩子调用和记忆操作日志。MNEMON_EMBED_ENDPOINThttp://localhost:11434Ollama API地址。如果你将Ollama部署在另一台机器或Docker容器中需要修改此地址。MNEMON_EMBED_MODELnomic-embed-text用于生成文本嵌入向量的模型名称。确保Ollama中已拉取该模型。配置建议对于普通用户通常只需要关心MNEMON_STORE来切换项目。高级用户可以通过MNEMON_DATA_DIR将记忆库放在同步盘如iCloud Drive, Dropbox中实现不同电脑间的记忆同步但需注意并发写入可能带来的问题。6. 故障排查与常见问题实录即使设计再精良在实际部署和运行中也可能遇到问题。以下是我在深度使用Mnemon过程中遇到的一些典型情况及解决方法。6.1 钩子未触发记忆功能不生效症状Claude Code会话开始后没有看到关于记忆系统的提示对话中也不会自动回忆或记忆。排查步骤检查钩子安装位置运行ls -la ~/.claude/hooks/全局安装或ls -la .claude/hooks/项目安装。确认能看到session_start.sh,user_prompt_submit.sh等文件。检查钩子内容查看session_start.sh确认其内容包含加载guide.md的命令。有时安装脚本可能因权限问题未能成功写入。检查Claude Code版本某些旧版本的Claude Code可能对钩子的支持不完整。确保你使用的是最新版本。查看Mnemon日志设置export MNEMON_LOG_LEVELdebug然后重新启动Claude Code。在~/.mnemon/logs/目录下查看最新的日志文件搜索“hook”、“prime”等关键词看是否有错误信息。常见原因与解决权限问题钩子脚本没有执行权限。运行chmod x ~/.claude/hooks/*.sh。路径问题guide.md不在~/.mnemon/prompt/目录下。重新运行mnemon setup --force可以重新部署所有文件。配置冲突如果你同时有全局和项目级钩子Claude Code可能会以某种优先级加载。建议清理掉一个只保留一种安装方式。6.2 记忆召回结果不相关或为空症状智能体似乎尝试了recall但返回的结果风马牛不相及或者说“没有相关记忆”。排查步骤确认记忆已存储手动运行mnemon list --limit 5查看最近是否成功存储了记忆。如果没有说明remember环节可能失败了。检查guide.md规则回忆的触发和判断极度依赖指南中的规则。检查你的~/.mnemon/prompt/guide.md看其中关于“何时回忆”的规则是否过于严格或模糊。测试混合检索手动运行一个召回测试分别观察图检索和向量检索的结果# 模拟一个查询查看详细输出 mnemon recall 项目架构设计 --verbose在输出中你会看到分别来自“graph”和“vector”如果启用的结果列表。如果某一项结果为空说明对应的检索路径有问题。检查向量模型如果启用了向量搜索运行ollama ps确认嵌入模型正在运行。尝试用 Ollama 直接测试该模型ollama run nomic-embed-text test sentence。常见原因与解决指南规则不当智能体可能因为你的问题不符合指南中定义的“值得回忆”的场景而根本没有发起recall。尝试在对话中更明确地提及历史或修改guide.md放宽回忆条件。图关系未建立新存储的记忆是孤立的节点没有通过link与其他记忆建立关系。导致图遍历检索时无法通过关系链找到它。确保你的指南鼓励智能体在remember时也思考关联性。向量模型不匹配使用的嵌入模型不适合你的语言或领域例如用英文模型处理中文。尝试更换Ollama中的嵌入模型并更新MNEMON_EMBED_MODEL环境变量。6.3 性能问题响应变慢或内存占用高症状集成Mnemon后感觉Claude Code的响应速度变慢或者系统资源占用明显增加。排查步骤检查记忆库大小运行mnemon status查看记忆节点和边的数量。如果数量巨大例如超过10万检索和去重操作自然会变慢。监控钩子执行时间在debug日志级别下观察每个钩子脚本的执行耗时。特别是pre_compact.sh在长上下文压缩时它需要扫描大量文本可能比较耗时。检查Ollama资源如果启用了向量搜索Ollama服务可能会占用大量CPU和内存。使用系统监控工具如htop查看ollama进程的资源使用情况。优化建议定期清理对于不再活跃的项目使用mnemon store export备份后删除旧的存储库或使用mnemon gc清理低重要性记忆。调整指南修改guide.md让智能体更“挑剔”地选择记忆内容避免存储过多琐碎信息。例如增加“只有影响未来决策的结论才值得记忆”这样的规则。升级硬件或调整配置如果使用Ollama考虑为机器增加内存或者为Ollama分配更少的线程通过Ollama的启动参数。禁用向量搜索如果对语义检索需求不强可以暂时注释掉环境变量MNEMON_EMBED_MODEL回退到纯图检索性能会有显著提升。6.4 与OpenClaw/NanoClaw集成失败症状在OpenClaw中调用Mnemon技能无响应或在NanoClaw容器中找不到mnemon命令。排查步骤OpenClaw确认插件已安装检查~/.openclaw/plugins/目录下是否有mnemon相关文件。检查OpenClaw网关配置确认网关的配置文件中正确引用了Mnemon插件。查看OpenClaw网关日志通常有详细的插件加载和错误信息。NanoClaw确认宿主机安装在宿主机上运行which mnemon确认二进制文件存在且路径正确。检查Dockerfile挂载使用/add-mnemon技能后检查生成的Dockerfile确认volumes部分正确挂载了宿主机上的~/.mnemon目录和mnemon二进制路径到容器内。检查容器内路径进入容器 (docker exec -it container_name /bin/bash)检查挂载的目录和文件是否存在以及权限是否正确。解决思路这类集成问题多半是路径或配置错误。仔细对比Mnemon的安装路径、容器的挂载路径以及框架期望的插件路径。使用绝对路径而非相对路径通常是更安全的选择。7. 开发与扩展理解代码结构与未来方向对于想要贡献代码或基于Mnemon进行二次开发的开发者了解其代码结构和设计哲学至关重要。7.1 项目结构与核心模块Mnemon的Go代码结构清晰遵循了标准项目布局cmd/mnemon/存放所有CLI命令的入口定义基于Cobra框架如remember.go,recall.go,store.go。internal/核心业务逻辑外部项目不应直接导入。graph/四图时序、实体、因果、语义的数据结构和算法实现。storage/存储抽象层。目前主要是sqlite/实现未来可以轻松添加postgres/,neo4j/等适配器。memory/记忆生命周期管理衰减、GC、去重的核心逻辑。embedding/向量嵌入相关的客户端和接口目前主要对接Ollama。pkg/可以安全对外暴露的库如协议定义、工具函数等。docs/设计文档和图表。scripts/构建和开发脚本。核心流程追踪以一次remember调用为例CLI层 (cmd/mnemon/remember.go) 解析参数。调用internal/memory/manager.go的Remember方法。Manager 调用internal/storage接口存储原始内容。同时启动异步任务通过internal/graph模块分析内容提取实体、因果关系并创建相应的图节点和边。如果启用了嵌入还会调用internal/embedding客户端生成向量并存储。最后更新记忆的元数据如重要性、访问时间。7.2 编译与测试对于开发者项目提供了完善的Makefile# 克隆代码 git clone https://github.com/mnemon-dev/mnemon.git cd mnemon # 安装依赖 (Go modules会自动处理) go mod download # 运行单元测试 make test # 构建二进制文件到当前目录 make build # 输出 ./bin/mnemon # 构建并安装到 $GOBIN (通常是 ~/go/bin) make install # 运行端到端集成测试需要本地运行Claude Code测试环境 make test-e2e开发建议在修改核心逻辑如图算法、存储层后务必运行make test。项目包含了对去重、衰减、混合检索等复杂逻辑的单元测试能有效防止回归错误。7.3 未来架构记忆网关与协议抽象Mnemon的愿景不仅是做一个工具更是定义一套LLM与记忆系统交互的协议标准。当前版本将协议remember/link/recall和存储引擎SQLite耦合在一起但这只是开始。未来的方向是清晰的分层架构协议层定义标准的、意图原生的记忆操作APIgRPC或HTTP。任何智能体框架Claude Code, OpenClaw, 自定义Agent都可以通过这个协议与记忆系统对话。适配器层实现协议层到不同存储后端的转换。SQLite适配器是第一个未来可以有PostgreSQL适配器适合多实例共享、Neo4j适配器原生图数据库性能更优、甚至云服务适配器。存储层具体的数据库。这种解耦带来巨大灵活性智能体侧优化不同框架可以基于同一协议独立优化何时调用recall、如何构建remember的提示词。存储侧优化数据库专家可以专注于为图遍历、向量混合查询设计更高效的索引和算法而不必关心上层的LLM交互逻辑。如果你对实现新的存储适配器感兴趣可以重点关注internal/storage/interface.go中定义的接口。实现这些接口并在cmd/mnemon/serve.go中注册新的适配器理论上就能让Mnemon支持任何一种数据库后端。7.4 贡献指南项目社区欢迎各种贡献报告Bug在GitHub Issues中提供清晰的重现步骤、环境信息和日志。功能建议先查阅docs/DESIGN.md中的未来方向然后在Issues中讨论你的想法。提交代码Fork仓库在特性分支上开发确保通过make test然后提交Pull Request。代码风格遵循标准的Go规范并使用有意义的提交信息。一个对新手友好的贡献起点是丰富文档尤其是翻译、添加更多集成示例如与其他LLM CLI的集成或编写教程。另一个方向是开发辅助工具比如一个图形化的记忆库浏览器或者一个分析记忆图谱的可视化工具。
