magnemo Skill 技能

技能简介

magnemo 是一款面向 AI Agent 的「受治理记忆层」（Governed Memory Layer），核心解决生产级 Agent 的第一瓶颈：记忆治理。不同于传统 RAG 框架专注检索优化，magnemo 从设计层面引入「记忆宪法」机制——每一条事实携带溯源元数据，每一次 Agent 写入必须经过人工审核队列才能成为「正典」（canonical），每一次决策结果都会记录到信任账本（Trust Ledger）。Magnemo 打包了完整的四动词 MCP 服务器（retrieve / stage / bootpack / handoff），零外部依赖，Python 3.10+ 标准库即可运行。

核心能力

• 受治理写入：Agent 的写入操作只能到达暂存区（staging），无法直接修改正典存储，确保持久记忆的每一步都有人的参与
• 四动词 MCP 接口：通过标准 MCP 协议暴露 retrieve（检索）、stage（暂存）、bootpack（启动包）、handoff（交接）四个动词，与主流 Agent 运行时无缝集成
• 信任账本（Trust Ledger）：每一次 promote / reject 决策均以追加方式永久记录，信任账本驱动 L0~L3 自主等级计算，Agent 的每个操作类别都有可追溯的权限来源
• KAIROS 重要性排序：对暂存队列中的记忆候选按后果权重、新颖度、操作者信号、来源权重自动计算重要性评分，人类优先阅读最重要的待审内容
• 引导启动包（Boot Pack）：每次 Agent 唤醒时，通过 magnemo bootpack 渲染一份完整的新会话引导文档，包含宪章（Charter verbatim）、正典摘要、开放线程和最近交接记录，Agent 从不真正「从零开始」
• 边界遥测（Boundary Telemetry）：每次会话结束时记录上下文使用率、触发原因、截断内容，形成可审计的交接历史，解决「上下文墙」处的隐性信息丢失问题
• 污染传播机制（Taint Propagation）：来自不可信源的写入自动携带污染标记，污染通过派生关系遗传，只有human手动清除，阻止注入攻击通过派生关系自我洗白
• 原生三种形态：可作为独立工具直接使用（native），可挂载并治理已有 Markdown 笔记库（mount-and-govern），也可作为 Mem0 / Zep / RAG 等记忆系统的治理网关（gateway）
• 零依赖设计：纯 Python 3.10+ stdlib，无运行时外部依赖，可审计性强，适合安全敏感的生产环境

安装配置

环境要求

• Python 3.10 或更高版本
• 推荐在虚拟环境（venv / uv / conda）中安装，避免系统依赖冲突
• MCP 客户端（如 Claude Code、Cursor、任意兼容 MCP 的 Agent 运行时）

安装步骤

方式一：通过 pip 安装（推荐）

pip install magnemo

如果遇到 externally-managed-environment 错误，使用 uv tool install magnemo 或在虚拟环境中安装。

方式二：通过 uv 安装

uv tool install magnemo

方式三：开发模式源码安装

git clone 
cd magnemo
pip install -e .

安装完成后，magnemo 命令行工具和 magnemo-mcp MCP 服务器均可用。

MCP 配置

在项目根目录创建或更新 .mcp.json，添加 magnemo 服务器：

{
  "mcpServers": {
    "magnemo": {
      "command": "magnemo-mcp",
      "env": {
        "MAGNEMO_VAULT": "/absolute/path/to/vault",
        "MAGNEMO_AGENT": "my-agent",
        "MAGNEMO_SCOPE": "ops,shared",
        "MAGNEMO_PARTITIONS": "ops,shared"
      }
    }
  }
}

关键环境变量说明：MAGNEMO_VAULT 指向记忆库的绝对路径；MAGNEMO_AGENT 为当前 Agent 实例标识；MAGNEMO_SCOPE 和 MAGNEMO_PARTITIONS 控制 Agent 可访问的记忆分区。

使用步骤

第一步：初始化记忆库

magnemo init ./vault

这会在指定目录创建一个结构化的 Markdown 记忆库，包含 ops / shared / dev 等示例分区，以及 _staging（暂存）、_index（索引）、_ledger（账本）等管理目录。

第二步：验证安装完整性

magnemo doctor --mount .mcp.json

doctor 子命令会检查 Python 环境、记忆库结构、MCP 配置文件和账本状态，确保一切就绪。

第三步：渲染启动引导包

magnemo bootpack --stdout

首次运行时，若宪章（Charter）尚未经人工审核提升为正典，输出会以占位符显示「尚未提升」——这是 magnemo 的设计原则：宪法不能被捏造，必须由人撰写和审核。

第四步：与 Agent 交互写入记忆

在 Agent 对话中，通过 MCP 接口调用 stage 动词将关键信息写入暂存区。Agent 通过 MCP 的 stage 工具写入记忆候选，内容进入 _staging 目录等待审核。

第五步：人工审核暂存队列

magnemo review

交互式审核界面以 KAIROS 重要性降序展示待审内容，人类执行 promote（提升）或 reject（拒绝）操作。审核结果追加到 Trust Ledger，形成 Agent 的信任积累历史。

附加命令参考

magnemo ledger       # 查看所有历史决策
magnemo handoff      # 记录会话边界信息
magnemo costs        # 查看记忆载荷成本统计
magnemo chest add    # 添加 vault 备份目标
magnemo gates        # 查看当前权限门控状态

适用场景

• 多 Agent 协作项目：多个 Agent 在同一记忆库上操作，需要人类作为最终审核节点，防止记忆污染扩散
• 高可靠性 AI 工作流：金融、医疗、法律等需要对 AI 输出负责的领域，记忆必须有完整溯源
• 长期上下文管理：当 Agent 需要在长程任务中保持记忆一致性时，通过引导启动包和交接机制避免上下文截断丢失
• AI 记忆安全审计：需要追踪「Agent 的每一条记忆来自哪里、谁审核过」的安全合规场景
• 团队知识沉淀：用 Magnemo 治理团队共享的决策记录和运维知识，Agent 写入必须经过人工确认才能成为团队正典
• 记忆系统网关：已有 Mem0 / Zep 等记忆系统的团队，可在这些系统前加一层 magnemo 治理，所有 AI 记忆过「海关」再放行
• 开发者个人 AI 助手：在 Claude Code / Cursor 等开发工具中用 magnemo 建立长期记忆，让 AI 不遗忘项目上下文和决策历史

适用人群

• AI 应用开发者：需要为 AI Agent 构建可靠记忆层的技术人员
• 安全合规团队：需要对 AI 记忆操作进行审计和治理的组织
• 多 Agent 系统架构师：设计多人 / 多 Agent 协作流程，需要记忆隔离和权限控制
• AI 工程师（LLM 应用）：使用 Claude Code、Cursor 等工具，希望 AI 在长程项目中保持一致记忆的开发者
• 技术创始人 / CTO：构建 AI Native 产品，需要在工程层面确保 AI 行为可追溯、可控

工作原理

magnemo 的核心是一个「记忆宪法」架构，将 Agent 与记忆的交互分为两条严格分离的路径：

读取路径（正典检索）：Agent 通过 retrieve 动词搜索记忆时，只返回经过人工审核的 canonical 记忆，暂存区（staging）内容对 Agent 完全不可见，确保 AI 永远不会读到未经验证的信息。

写入路径（治理审核）：Agent 通过 stage 动词写入的内容首先进入 _staging 目录，同时记录完整的溯源元数据（来源、时间戳、写入者、影响等级）。内容经过 KAIROS 重要性评分后，等待人工审核。人类通过 review 命令审阅并执行 promote（提升）或 reject（拒绝），只有 promote 的内容才会进入 canonical 存储。

信任账本驱动权限：Magnemo v0.5 引入 Trust Ledger 数学模型——每个 Actor（Agent / 人类）根据其历史决策记录计算出一个自主等级（L0~L3），决定该 Actor 在每个操作类别上的权限边界。L4（密钥持有者）始终保留给人类。

边界交接：每次会话结束，Agent 调用 handoff 动词记录上下文使用率、触发原因和截断内容，这些数据进入 _ledger/handoffs.jsonl，下一个会话的 Boot Pack 会自动继承历史边界信息，解决长程任务中的「上下文墙」问题。

官方链接

• PyPI：https://pypi.org/project/magnemo/
• 文档：https://docs.magnemo.org/（如有）
• MCP 协议参考：docs/MCP.md
• 已知限制：KNOWN_LIMITS.md（开源 beta，如实披露）

发布备注：magnemo 由 Silver Valley Technologies Inc.（SVTech Inc.）发布，当前处于 Open Beta 阶段，核心协议设计为三阶段路线图的 Phase 1（受治理召回）。Phase 2（强化/衰减）和 Phase 3（自主治理）仍在规划中。