ai-memory-importer：从其他Wiki工具迁移数据完整指南

ai-memory-importer从其他Wiki工具迁移数据完整指南【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memoryai-memory-importer 是 ai-memory 官方的配套数据迁移工具能把其他工具如 oh-my-claudecode / OMC的 Markdown Wiki 记忆安全地导入到运行中的 ai-memory 服务器。本文带你走通从 dry-run 预演到正式写入的完整迁移流程默认只预演不写数据、支持清单manifest断点、全程只通过公开 API 写入让第一次做 Wiki 数据迁移的新手也能放心操作。它是什么一个“只进不出”的安全导入器如果你之前用别的记忆工具积累了大量 Wiki 笔记现在想换到 ai-memory但又不确定旧数据格式是否兼容这个工具就是为你准备的。它的设计原则可以概括为一句话先预演后写入只写入不删除。️默认 dry-run不加--apply时它只扫描源目录并打印“哪些文件会映射到哪里”一个字节都不会写到服务器清单机制每次运行都会生成 JSON 清单记录每个页面的 SHA256 指纹和状态planned / written / failed中断后可对照续跑路径安全拒绝绝对路径、..穿越、保留前缀如decisions/、gotchas/从根源防止写坏目录结构永不删除v1 版本只调用POST /admin/write-page不直接碰 ai-memory 的 SQLite 或 Wiki 文件迁移前准备三件事1. 获取仓库git clone https://gitcode.com/GitHub_Trending/ai/ai-memoryimporter 位于companions/ai-memory-importer/是一个独立的 Cargo 包有自己的 workspace不混入主工程文档见 companions/ai-memory-importer/README.md核心逻辑在 companions/ai-memory-importer/src/main.rs整体设计背景可参考 docs/companion-crates.md。2. 确认 ai-memory 服务器在运行importer 通过 HTTP 与服务器通信默认地址是http://127.0.0.1:49374也可以用--server-url或环境变量AI_MEMORY_SERVER_URL指定其他地址URL 带路径时路径会作为 base path 自动拼接。3. 准备管理员 Token鉴权只认环境变量AI_MEMORY_AUTH_TOKEN故意不提供命令行参数避免 token 泄漏到历史记录。没有现成 token 的话用 CLI 生成一个ai-memory generate-auth-token数据迁移四步法第一步dry-run 预演看看会导入什么cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \ omc-wiki --dir /path/to/omc/wiki --workspace default --project my-project你会看到类似note.md - omc/note.md的映射清单和总数。扫描规则是只读源目录顶层的*.md文件按文件名排序默认跳过index.md和session-log-*每个源文件生成确定性目标路径omc/slug.md小写、非字母数字转连字符两个文件若 slug 冲突会直接中止加--show-body可以在预演时直接打印页面正文方便快速核对内容。第二步生成迁移清单在预演基础上加--manifest-outcargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \ omc-wiki --dir /path/to/omc/wiki --workspace default --project my-project \ --manifest-out /tmp/omc-import-manifest.json清单里每页都有source_sha256指纹与状态是排查“这次到底导入了什么”的权威记录。第三步正式导入live mode确认无误后加三样东西执行正式写入--apply、显式的--workspace/--project、--manifest-out。AI_MEMORY_AUTH_TOKEN你的token \ cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \ omc-wiki --dir /path/to/omc/wiki --workspace default --project my-project \ --apply --manifest-out /tmp/omc-import-manifest.json正式模式的保护逻辑值得了解预检目标先查询目标 workspace/project 是否存在页面冲突即停若目标已有同名页面默认中止并提示改用--overwrite写前复查每写一页前再次检查该路径是否“刚刚被别人写入”避免覆盖并发写入逐页落盘每成功写入一页立即更新清单任何错误都会停下并保留已完成的进度。第四步在 Web 界面验证结果打开 ai-memory 内置的 Web 浏览器/web路径进入目标项目确认导入的页面都在元数据映射哪些字段会被保留importer 会解析 YAML frontmatter但只映射公开写接口支持的字段未知的 frontmatter 直接忽略——这是刻意的设计避免承诺做不到的保留。源字段行为title保留缺失时自动取正文第一个 H1 标题kind原样保留如fact、ruletier仅接受working/episodic/semantic/procedural其他值会在规划阶段就报错缺失时默认semantictags支持数组或单个字符串pinned保留另可用--pinned把导入的所有页面全部置顶body去除 frontmatter 后的正文常见问题速查场景解决办法目标 workspace/project 还不存在加--create-destination允许写入时自动创建目标已有同名页面想覆盖加--overwrite仍会在每次写入前复查想连session-log-*一起导入加--include-session-logs预演时想核对全文加--show-body服务器不在默认地址--server-url或AI_MEMORY_SERVER_URL⚠️ 两点提醒一是非覆盖检查属于尽力而为——极端情况下并发写入仍可能竞争所以迁移时别同时往同一个目标跑其他导入/写入任务二是 v1 目前只支持 OMC 扁平 Wiki 目录Claude Code memory graph 和 Qdrant 集合导入还在路线图上见 companions/ai-memory-importer/README.md 的 Roadmap 一节。小结用 ai-memory-importer 做 Wiki 数据迁移核心就是“先 dry-run、再 manifest、后 --apply”三步走。默认 dry-run 和永不删除的设计意味着你即使误操作也不会丢失现有数据而清单文件让每次迁移都有据可查。迁移完成后导入的页面会像原生页面一样参与检索、固化与跨 agent 交接旧工具里的记忆就此无缝接入 ai-memory。【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考