ai-afterimage Skill 技能

ai-afterimage 是 Claude Code 的「情景记忆外挂」—— 一个 Pre-Write / Post-Write Hook，让 Claude Code 像视觉残留（afterimage）那样在多次会话间保留「曾经写过的代码」记忆，下次写新代码前自动检索 KB 注入相似历史，告别「每次新会话都从零开始重新解释一遍」。

核心能力

• Pre-Write 检索注入：Claude Code 每次 Write / Edit 触发时，hook 先在本地 KB 里搜索相似历史代码，把「你之前写过类似实现」连带上下文注入到 prompt 里，Claude 立即拥有跨 session 的工程经验。
• Post-Write diff 入库：Write/Edit 完成后 hook 自动抽取 diff，把变更存入 KB（含 embedding），供未来检索使用。
• 本地化混合检索：默认 SQLite + FTS5 全文检索，叠加 embedding 相似度搜索；同时可选 PostgreSQL + pgvector 后端，向量检索更精准、并发写更稳。
• churn 跟踪：每个文件 / 函数被修改次数自动统计，重复修改会触发提示「这个函数 24 小时内改了 4 次，可能需求没对齐 / 没修干净 / 需要重设计」，引导 Claude 反思而不是硬堆迭代。
• Codex transcript 解析：v0.6.0 起支持 OpenAI Codex transcript，含 session_meta session_id、response_item 信封解析、apply_patch unified diff 解析，多 harness 记忆互通。
• 完全本地 / 可离线：KB、embedding 模型都在本地，无云端调用，初始下载 ~90MB 模型后即可离线运行。
• CLI 管理命令：afterimage search / ingest / stats / recent / export / clear / config / migrate 一应俱全。

安装配置

• 基础安装：pip install ai-afterimage，默认 SQLite 后端、零配置；afterimage setup 自动创建 ~/.afterimage/ 配置目录、安装 hook 到 ~/.claude/hooks/、写入 ~/.claude/settings.json、下载 ~90MB embedding 模型。
• PostgreSQL 后端（多 session 并发 / 团队共享场景）：pip install ai-afterimage[postgresql]，安装 PostgreSQL + pgvector，建 afterimage 数据库，导出 AFTERIMAGE_PG_PASSWORD=yourpassword 环境变量，~/.afterimage/config.yaml 设置 storage.backend: postgresql。
• 源码安装：git clone https://github.com/DragonShadows1978/AI-AfterImage.git && cd AI-AfterImage && pip install -e ".[embeddings]"。
• 依赖环境：Python 3.10+、Claude Code CLI、Linux 或 macOS（Windows 在计划中）。
• 运行验证：afterimage stats 查看 KB 容量，afterimage search "authentication" 测试检索，afterimage recent 看最近写入。

使用步骤

1. 安装与初始化：pip install ai-afterimage → afterimage setup，自动注入 hook 到 ~/.claude/hooks/ 和 ~/.claude/settings.json。
2. 首次会话：正常启动 Claude Code，Write / Edit 代码时 AfterImage 已经在后台运行；Pre-Write 时如有相似历史会注入「你之前写过这个...」，Post-Write 后自动入库。
3. 检索代码记忆：CLI 跑 afterimage search "authentication middleware" 召回所有相关历史实现；用 --limit / --threshold / --path / --json 调整范围。
4. 导入历史会话（可选）：把已有的 Claude Code transcript 一次性 ingest 进 KB，afterimage ingest 默认从 ~/.claude/transcripts/ 导入，加 -v 看 verbose 日志。
5. 观察 churn 提示：当某个函数被频繁修改，hook 会自动输出 Possible considerations: 段，建议 Claude 暂停重新理解需求而非盲目迭代。
6. PostgreSQL 迁移（可选）：当 SQLite 撑不住（KB > 100K 条 / 需要多 session 并发 / 多人共享）时，运行 afterimage migrate --sqlite ~/.afterimage/memory.db --postgresql 平滑迁移，PostgreSQL 不可用时自动降级回 SQLite。
7. 多 harness 互通：Codex 用户的 transcript 同样可被 ingest，新 session 自动看到两边写过的代码。

适用场景

• 长跨度 Claude Code 使用者：每天写代码 4-6 小时、几周累计上百次 Write/Edit，希望 Claude 自动积累工程记忆。
• 跨 session 工程延续：今天写的 auth 模块、下周回来扩展时新内容要复用上次的设计，Pre-Write 检索自动注入。
• 频繁 bug 反复出现的项目：通过 churn 跟踪自动提示「这个函数反复被改，可能设计有问题」，引导深层反思。
• 团队 / 多设备共享代码记忆：PostgreSQL 后端让团队成员共享同一份 KB，新人也能立即看到前人写过的相似实现。
• Codex + Claude Code 双修：v0.6.0 起支持 Codex transcript 解析，单一 KB 同时服务多个 harness。
• 离线 / 内网开发：完全本地运行、零云端调用，离线 / 内网环境也能享受 AI 编程记忆。
• 隐私敏感场景：所有 KB / embedding 在本地，不上传任何代码到第三方，代码资产 100% 自有。

适用人群

• 重度 Claude Code / Codex 用户（每周 10+ 小时 AI 编程）
• 维护长生命周期工程（持续迭代 3+ 月）的工程师
• 团队 Lead 想给团队装上「集体记忆」基础设施
• 重视代码隐私 / 不能用云端 memory 的企业开发者
• 在多台机器 / 多 worktree 间切换工作的远程工程师

工作原理

ai-afterimage 在 Claude Code 的 PreToolUse（Write/Edit）钩子点上拦截事件，先用 hybrid search（SQLite FTS5 全文 + 本地 embedding 模型）在 KB 里找相似历史代码片段，把命中结果以「你之前写过类似实现」上下文注入 prompt，让 Claude 在写新代码前就看到自己过去的相关实现；Write/Edit 完成后 PostToolUse 钩子抽取 diff 内容，对非 .md / .json 类代码做 chunk → embed → 写入 SQLite（含 FTS5 索引）。embedding 模型默认使用 all-MiniLM-L6-v2（~90MB），全 CPU 可跑；可选切换 PostgreSQL + pgvector 后端用 IVFFlat 加速向量检索。整个流程发生在本地，零云端调用，断网也能正常工作，PostgreSQL 不可达时自动降级回 SQLite 保证 Claude Code 不中断。

官方链接

• PyPI 包：https://pypi.org/project/ai-afterimage/
• 源码仓库：https://github.com/DragonShadows1978/AI-AfterImage
• README（含 churn 提示示意 + PostgreSQL 迁移指南）：https://github.com/DragonShadows1978/AI-AfterImage#readme