agent-wal

Agent WAL（Write-Ahead Log）是一个专为智能体（Agent）设计的本地状态持久化解决方案，通过预写日志协议确保关键决策、用户修正和上下文信息在对话压缩过程中不会丢失。

核心用法

该 Skill 通过 scripts/wal.py 脚本提供命令行接口，核心操作包括：

• 即时记录：使用 append 命令在响应前将用户修正（correction）、关键决策（decision）或分析结论（analysis）写入 WAL
• 缓冲机制：通过 buffer-add 批量缓存非紧急条目，在对话压缩前执行 flush-buffer 持久化
• 会话恢复：会话启动时执行 replay 重放未应用的日志条目，恢复丢失的上下文
• 状态管理：使用 mark-applied 标记已处理条目，prune 清理历史记录控制存储空间

显著优点

1. 防丢失保障：解决了 Agent 在长时间对话后因内存压缩丢失用户修正的首要故障模式
2. 零依赖设计：仅使用 Python 标准库（argparse、json、pathlib 等），无第三方包依赖，部署简单
3. 本地安全：所有数据以 JSONL 格式存储于用户主目录下的特定文件夹（~/clawd/memory/wal/），不上传云端，隐私可控
4. 操作幂等：追加写入、状态标记等操作均为幂等，可安全重复执行
5. 透明可审计：明文 JSONL 格式，用户可直接查看和审计所有记录内容

潜在缺点与局限性

1. 来源可信度：目前为个人开发者（T3 级别）维护，虽代码透明但社区支持有限
2. 本地存储限制：仅支持单机本地存储，无法实现分布式或多设备同步
3. 无加密保护：数据以明文形式存储，不适合存储敏感凭证或需要加密保护的场景
4. 存储管理：长期运行可能产生大量日志文件，需手动执行 prune 命令维护，缺乏自动轮转机制
5. 功能单一：专注于日志记录与重放，不包含复杂的数据查询或分析功能

适合的目标群体

• Agent 开发者：需要为 LLM Agent 构建可靠记忆机制的开发者
• 长期对话场景：客服、顾问等需要维护长期上下文关系的应用
• 关键决策系统：医疗、法律等领域需要确保修正和建议不被遗忘的专业 Agent
• 本地优先用户：注重数据隐私，希望完全控制数据存储位置的用户

使用风险

1. 存储空间风险：高频使用可能导致 WAL 文件体积膨胀，建议定期执行 prune 命令并监控磁盘空间
2. 数据隐私：虽然数据不上传云端，但本地 JSONL 文件可能包含敏感对话内容，需确保操作系统级别的文件权限安全
3. 文件完整性：意外断电或系统崩溃可能导致 WAL 文件损坏，重要场景建议定期备份 ~/clawd/memory/wal/ 目录
4. 并发访问：当前实现未明确处理多进程并发写入场景，高并发环境可能需要额外加锁机制

核心功能

agent-wal 为 Claude Code Agent 实现 Write-Ahead Log (预写式日志) 机制，解决对话压缩导致的关键信息丢失问题。通过 scripts/wal.py 提供本地持久化能力，确保用户修正、重要决策、分析结论在会话结束前被可靠保存。

显著优点

1. 安全架构极致：零第三方依赖，仅使用 Python 标准库（argparse, json, os, sys, hashlib, pathlib, datetime），供应链攻击面为零。S级安全评分（95/100），无危险函数、无网络通信、无动态代码执行。

2. 功能精准定位：专注解决 "压缩丢修正" 这一高频痛点，提供 append/buffer-add/replay/mark-applied 完整生命周期管理，支持 corrections/decisions/analysis/state_change 四种动作类型。

3. 集成设计合理：明确的五个触发场景（用户修正、关键决策、预压缩刷新、会话恢复、显式记忆），配合 ~/clawd/memory/wal/ 隔离存储，避免与 Claude Code 默认记忆冲突。

潜在局限

• 存储权限待强化：当前未强制设置目录 0o700/文件 0o600 权限，WAL 记录含敏感操作历史，多用户环境存在读取风险。
• 输入验证偏宽松：action_type 和 payload 未做白名单与长度限制，理论上存在日志注入或膨胀风险。
• T3来源信誉：个人开发者维护，虽代码开源可查，但长期维护与审计深度弱于企业级项目。

适合人群

• 高频使用 Claude Code 且遭遇过 "修正被压缩遗忘" 的开发者
• 需要跨会话保持关键决策与配置状态的自动化工作流
• 对供应链安全敏感、偏好标准库极简方案的技术团队

常规风险

| 风险类型 | 等级 | 说明 |

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

| 供应链攻击 | 极低 | 零依赖，标准库实现 |

| 数据外泄 | 极低 | 纯本地文件操作，无网络 |

| 权限泄露 | 低 | 建议手动加固文件权限 |

| 功能失效 | 中 | 依赖本地磁盘空间与路径可写 |

合规声明：符合 GDPR 数据最小化，无硬编码凭证，无已知 CVE 依赖。认证有效期 90 天，更新需重新审计。