Memoclaw Skill

核心用法

MemoClaw 是一种 Memory-as-a-Service 解决方案，专为 AI Agent 设计，提供跨会话的持久化记忆存储与检索。核心使用模式围绕「存储-召回」循环：

存储 (`memoclaw store`)：保存文本记忆，支持重要性评分(0-1)、标签分类、内存类型(correction/preference/decision/project/observation/general)、固定(pinned)与锁定(immutable)状态。关键参数包括 --importance（决定检索优先级）、--memory-type（控制衰减半衰期，correction最长180天，observation仅14天）、--namespace（项目隔离）。批量场景可用 ingest（自动提取+去重）或 extract（分句存储）。

召回 (`memoclaw recall`/`context`/`core`)：语义向量搜索是核心能力，支持自然语言查询如"用户偏好什么主题"。recall 返回相似度排序结果，context 组装LLM就绪的上下文块，core 免费返回高重要性基础记忆。免费替代方案包括 search（关键词文本匹配）和 list --sort-by importance。

管理：支持更新、删除、迁移、合并重复项(consolidate)、关系链接(relations)、版本对比(diff)等。watch 可实时流式监控新记忆。

显著优点

1. 零注册 friction：钱包地址即身份，无需邮箱、密码、API密钥，符合加密原生设计哲学
2. 语义检索：基于向量嵌入的相似度搜索，超越关键词匹配，理解"偏好暗色模式"与"喜欢黑色主题"的语义关联
3. 智能衰减：不同 memory_type 内置半衰期，避免记忆无限膨胀，observation自动衰减，correction长期保留
4. 微支付经济模型：100次免费试用后，单次调用$0.005（USDC on Base），无需预付订阅，用多少付多少
5. 多维度组织：namespace（项目隔离）+ agent_id（多Agent隔离）+ tags（灵活分类）+ relations（记忆关联网络）
6. Agent原生设计：CLI输出支持 --json 管道化，与jq等工具无缝集成，提供明确的Agent行为指南（何时存储、何时召回、重要性评分规则）

潜在缺点与局限性

1. 成本累积风险：高频Agent可能快速消耗免费额度，$0.005/次看似低廉，但对话密集型场景下1000次调用即$5，批量无显著折扣
2. 中心化依赖：数据存储于api.memoclaw.com，存在服务中断风险（文档建议"graceful degradation"至本地文件）
3. 内容限制：单条记忆8192字符上限，超大文档需手动拆分
4. CLI功能滞后：--summarize、--include-metadata、--include-relations 等API参数尚未暴露为CLI选项，需直接调用REST API
5. 网络延迟：每次调用需HTTPS往返+钱包签名验证，对比本地向量库（如Chroma）有显著延迟
6. 隐私顾虑：记忆内容传输至第三方服务器，敏感信息（虽未明文禁止）建议本地存储
7. 钱包安全风险：需配置 MEMOCLAW_PRIVATE_KEY，文档建议"dedicated wallet"，但私钥泄露风险客观存在

适合人群

• 多会话AI Agent开发者：需要跨越上下文窗口限制、持久化用户偏好的对话系统
• 多Agent协作架构：同一钱包下不同Agent通过agent_id隔离，共享namespace协作
• Web3/crypto原生项目：x402支付模型与钱包身份天然契合链上应用
• 快速原型验证：100次免费额度足够MVP阶段，无需基础设施投入
• 不愿管理向量数据库的团队：替代自建Pinecone/Weaviate/Chroma的方案

常规风险

| 风险类别 | 具体描述 | 缓解建议 |

|---------|---------|---------|

| **资金安全** | 私钥配置不当导致钱包被盗 | 使用专用低余额钱包，考虑硬件钱包签名流程 |

| **服务中断** | API故障导致记忆不可用 | 文档内置降级策略：本地文件回退 |

| **数据持久性** | 服务商终止或数据丢失 | 定期 `memoclaw export` 备份 |

| **成本失控** | 循环调用或高频场景费用激增 | 优先使用免费命令(core/search/list)，监控 `memoclaw status` |

| **记忆污染** | 重复存储、低质量内容稀释召回 | 强制"recall before store"流程，定期运行 `consolidate` |

| **隐私合规** | 用户数据跨境传输、存储 | 避免存储PII/敏感信息，评估GDPR/CCPA合规性 |

整体而言，MemoClaw 是 Agent 记忆基础设施的有力补充，尤其适合已有加密钱包用户和需要快速上线的项目，但生产环境需建立成本监控与降级机制。

核心用法

MemoClaw 是一个面向 AI Agent 的持久化记忆服务，通过 CLI 工具提供语义存储与检索能力。核心工作流包括：

存储记忆：使用 memoclaw store 保存文本，支持重要性评分（0.3-0.95）、标签分类和记忆类型（correction/preference/decision/project/observation/general）。关键特性包括 pinned（免于衰减）和 immutable（永久锁定）。批量存储支持 --file 或 stdin 管道。

检索记忆：提供四级检索策略——core（免费，高重要性基础记忆）、search（免费，关键词匹配）、recall（$0.005，语义向量搜索）、context（$0.01，LLM 就绪的上下文块）。推荐优先使用免费命令，必要时再启用付费语义检索。

记忆管理：完整的 CRUD 操作、命名空间隔离（namespace）、关系链接（supersedes/contradicts/supports）、版本对比（diff）、自动整合（consolidate）和智能衰减（基于 memory_type 的半衰期机制）。

身份与计费：采用去中心化身份模式，以太坊钱包地址即用户 ID。100 次免费调用后，通过 x402 协议进行 USDC 微支付（Base 网络），单次调用 $0.005-$0.01。

显著优点

1. 无缝跨会话持久化：解决 AI Agent 上下文重置导致记忆丢失的根本痛点，支持多会话、多 Agent 共享记忆。
2. 语义检索能力：基于向量嵌入的相似度搜索，突破关键词匹配局限，支持"用户之前说过关于 X 什么"的自然语言查询。
3. 去中心化身份：无需注册账户或管理 API Key，钱包即身份，符合 Web3 原生架构。
4. 智能记忆生命周期：重要性评分 + 记忆类型衰减机制 + Pin 功能，自动平衡记忆新鲜度与重要性。
5. Agent 原生设计：CLI 输出支持 JSON/原始文本格式，便于脚本化和管道处理，提供完整的决策树和最佳实践指南。

潜在缺点与局限性

1. 外部服务依赖：核心功能依赖 api.memoclaw.com 的可用性，网络中断时需降级到本地文件。
2. 成本累积风险：虽然单价极低（$0.005），但高频调用场景下成本可能超预期。免费命令（search/core）与付费命令界限需仔细区分。
3. 钱包管理负担：需妥善保管 MEMOCLAW_PRIVATE_KEY，建议使用专用钱包而非主钱包。
4. 数据保留政策不透明：文档未明确说明服务端数据保留期限、删除机制及是否用于模型训练。
5. CLI 功能滞后：部分 API 功能（如 context 的 summarize/include_metadata）尚未在 CLI 中暴露。

适合人群

• 构建长期运行、需要跨会话记忆的多轮对话 Agent
• 多 Agent 协作系统，需共享上下文和知识库
• Web3 原生应用，偏好去中心化身份和加密支付
• 需要语义检索能力超越简单关键词匹配的 AI 应用

常规风险

• 402 支付错误：免费额度耗尽后未配置 USDC 会导致调用失败
• 409 冲突错误：尝试修改 immutable 记忆会导致失败
• 413 内容过大：单条记忆限制 8192 字符，需分割存储
• 私钥泄露风险：环境变量方式配置私钥，在共享环境可能暴露
• 服务商风险：记忆数据存储于第三方云端，存在潜在的数据主权和隐私合规问题