ai-memory-importer为 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-memoryai-memory-importer 是 ai-memory 项目中的独立可选 companion crate用于将外部记忆语料oh-my-claudecode / OMC 扁平 Markdown wiki 目录以及 ChatGPT、Claude Desktop 等平台导出的通用对话记录导入正在运行的 ai-memory 服务器。本文围绕 companions/ai-memory-importer/README.md 展开结合 src/main.rs 的完整源码实现讲解两种导入模式的用法、安全契约、幂等重放机制与底层 hook 流水线原理读完后你可以独立完成一次从外部语料到 ai-memory 记忆库的受控迁移。一、定位与设计刻意隔离的独立 companionai-memory-importer 与 ai-memory 主工作区是刻意隔离的它的 Cargo.toml 自带独立的[workspace]段仅依赖 crates.io 上的公共 crateanyhow、clap、reqwest、serde、sha2、tokio、walkdir 等并且不参与根目录的cargo test --workspace测试。这意味着它既可以随仓库源码构建也可以脱离主工作区单独编译作为运维侧的独立工具使用。从实现看它本质上是一个无状态 HTTP 客户端不直接打开 ai-memory 的 SQLite 数据库不触碰 wiki 文件系统只通过两个 HTTP 端点与服务器交互——GET /api/v1/workspaces/{ws}/projects/{proj}/pages预检与冲突检测和POST /admin/write-page页面写入以及对话导入专用的POST /hook/batchhook 事件批量重放。二、导入源一OMC 扁平 Markdown wiki 目录2.1 扫描规则omc-wiki子命令接受一个 oh-my-claudecode / OMC 风格的扁平 Markdown wiki 目录。源码中的plan_omc_wikimain.rs明确规定了扫描边界只读取顶层*.md文件WalkDir设置min_depth(1)和max_depth(1)不递归子目录默认跳过index.md和以session-log-开头的文件可用--include-session-logs显式放行文件按文件名排序保证计划输出顺序确定每个文件生成确定性的目标路径omc/slug.mdslug 由文件名小写化、非字母数字字符折叠为-、首尾-修剪后得到slugifymain.rs若两个源文件 slug 化后撞车如A B.md与a-b.md会直接报 duplicate destination path collision 中止规划。2.2 YAML frontmatter 映射每个 Markdown 文件会先经过parse_markdownmain.rs解析可选的---包裹的 YAML frontmatter再映射为POST /admin/write-page请求体字段frontmatter 字段写入字段说明titletitle缺失时回退为正文第一个#标题kindkind页面类型直接透传tiertier仅接受working/episodic/semantic/procedural缺省为semantic未知 tier 在规划阶段即报错tagstags支持 YAML 序列或单个字符串两种写法pinnedpinned布尔值--pinned命令行开关可与 frontmatter 取或其他未知字段忽略只有端点支持的元数据才会被映射正文其余部分body原样写入。frontmatter 缺title时first_h1会从正文提取首个#行作为标题。三、导入源二通用外部对话external-conversation3.1 极简交换格式external-conversation子命令只接受一个刻意设计得足够小的通用 JSON envelope格式如下与 main.rs 中的ConversationEnvelope结构一一对应{ project: my-project, source: chatgpt, session_id: exported-conversation-id, messages: [ { role: user, content: What evidence supports this claim? }, { role: assistant, content: The source supports only part of it. } ] }role只允许system、user、assistant三种反序列化时使用#[serde(deny_unknown_fields)]和枚举白名单未知字段与未知角色一律解析失败面向 ChatGPT、Claude Desktop、Markdown 等具体产品的导出适配器刻意不放进本仓库它们只需要输出上述通用 envelope 即可project与 CLI 的--workspace都是显式参数目标工作区/项目必须已存在除非传--create-destination源文件只读取一次适配器应先把完整 JSON 导出写盘再调用导入器。3.2 从对话到有序 hook 事件导入器把对话重放进 ai-memory 的公共 hook 流水线一次完整导入严格生成一条有序事件序列session-start→ 逐条消息 →session-endplan_external_conversationmain.rssession-start携带session_id、model external:source、external_source与external_session_iduser消息映射为标准user-prompt事件body 为session_idprompt 来源标记assistant/system消息映射为经过验证的external.assistant-message/external.system-message扩展事件body 含title取首行并截断到 160 字节、message、来源标记并携带extensionai-memory-importer与source_eventassistant-message|system-message查询参数session-endbody 携带transcript_sha256指纹让后续合并阶段可以识别同一份转录。整条序列通过POST /hook/batch一次性提交。从服务端实现看批量端点crates/ai-memory-hooks/src/router.rs是内联处理的与单发/hook的先应答 202 再异步落盘不同/hook/batch会在响应窗口内同步完成每个条目的副作用因此 SessionEnd 写入会话页与 handoff 的效果在返回前已落定处理真实错误时采用 fail-fast 语义。这正是导入器选择/hook/batch的原因——顺序可保证、副作用可等待。3.3 专用 wire 身份external-import导入后的会话使用专用的agentexternal-importwire 身份绝不会伪装成真实的codex或claude-code身份测试external_plan_is_ordered_bounded_and_does_not_impersonate_a_live_agent专门断言了这一点。其设计效果是ai-memory core 对未知 agent 的容忍边界会把该身份归入封闭的other桶无需为核心添加产品专属的 agent 类型SessionStart 观察记录为external:sourceassistant/system 观察保留扩展来源ai-memory-importerextension source_event阅读记忆的读者因此能区分这是一次显式导入以及它的来源厂商。Claude 记忆图memory graph导入与 Qdrant 集合导入目前仍是 roadmap 项仓库中没有任何代码桩。四、安全契约默认 dry-run写入只走管理端点导入器把安全边界当作一等公民README 与源码实现完全一致默认 dry-run只有显式传--apply才进入真实写入真实模式强制要求显式--workspace、--project和--manifest-out pathrun_omc/run_conversation开头即校验真实写入只使用POST /admin/write-page从不直接打开 ai-memory 的 SQLite 或 wiki 文件也从不删除页面目标 workspace/project 必须已存在除非传--create-destinationpreflight_project对 404 才放行创建目标页面已存在会中止导入除非传--overwrite写入前还会对每个页面做一次page_exists复查。注意这是尽力而为的保护——并发写者仍可能在复查与写入之间抢占因此应避免多个导入/写入任务并发冲向同一目标第一个真实写入错误即停止同时把已完成的写入与失败检查点写回 manifest路径处理 fail-closed绝对路径、..、不安全的源/目标路径、保留的内部前缀都会被拒绝validate_source_rel与validate_destination_pathmain.rs。保留前缀包括_rules、_internal、.git、sessions、session-logs、procedures、decisions、gotchas且目标路径必须以.md结尾dry-run 默认不打印完整页面正文只有--show-body才会输出认证只来自环境变量AI_MEMORY_AUTH_TOKEN以Bearer方案附加到每个请求刻意不提供 CLI token 参数外部对话在创建任何 manifest 或 HTTP 请求之前就完成完整解析、schema 校验、边界限制与净化测试malformed_or_hostile_source_fails_before_manifest_or_http用非法 URL 验证了零副作用承诺。五、边界、净化与脱敏对话导入的双重防线外部对话导入对输入施加了严格的资源上限全部以源码常量形式存在main.rs上限值超出时行为单个源文件2 MiB直接拒绝消息条数128 条直接拒绝全部消息内容合计1 MiB直接拒绝user 消息单条16 KiB按 hook 持久化上限 UTF-8 安全截断assistant/system 扩展消息单条2,000 字节同上空消息净化后—拒绝且必须至少含一条 user 消息截断通过truncate_utf8main.rs保证不切在多字节 UTF-8 字符中间dry-run 输出与 manifest 都会报告截断计数。对话正文在重放前还会做客户端侧凭证脱敏sanitize_external_textmain.rs覆盖四类正则规则PEM 私钥块-----BEGIN ... PRIVATE KEY-----整段替换为[REDACTED PRIVATE KEY]常见凭证格式github_pat_*、ghp_/gho_/ghu_/ghs_/ghr_类 GitHub token、sk-*、AWSAKIA*替换为[REDACTED CREDENTIAL]Bearer token值保留Bearer前缀api_key/access_token/auth_token/token/secret/password等键值对中的值含引号与裸值形式替换为$1$2[REDACTED]。随后正文还会穿过 ai-memory 服务端常规净化器作为第二道边界——先本地脱敏、再服务端净化构成双重防线。六、幂等与恢复稳定会话 ID ingest_key manifest导入器的可重跑性是核心设计目标围绕三个机制实现稳定会话 ID由(workspace, project, source, session_id)与导入版本external-conversation-v1经 SHA-256 派生格式为external-32位十六进制stable_external_session_idmain.rs稳定 ingest_key每个重放事件都带一个由(版本, 稳定会话ID, 事件序号, 事件名, body)派生的 64 位十六进制 ingest_keyevent_ingest_key服务端据此去重转录指纹transcript_sha256随session-end发送——转录不变则 key 全部相同转录追加新消息后前面事件的 key 不变、末尾 SessionEnd 获得新 key因此重跑中断的导入是安全的而给导出追加消息会触发新的 SessionEnd 重跑持久化 manifest--apply模式要求--manifest-outmanifest 在计划阶段即写入随后在每次写页/每批事件后原子更新先写同目录.tmp文件再 renameatomic_writemain.rs记录每个条目的statusplanned/written/failed、page_id、path、checkpoint与错误信息。一次真实对话导入就是一个有序 hook 批次。若服务器只接受了前缀accepted_indices不连续或failed_index存在manifest 会被标记为failed并记录已接受数量与失败索引HookBatchAck::accepted_every_event要求全部索引连续命中main.rs重跑同一源文件即可依靠稳定 key 安全续传。另外本项目没有 inbox 或 watch-folder 模式导入始终是一次显式的一次性操作。七、完整命令行速查7.1 OMC wiki 导入# 1) dry-run只打印计划摘要默认 cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \ omc-wiki --dir /path/to/omc/wiki --workspace default --project my-project # 2) dry-run把计划写入 manifest cargo 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 # 3) 真实导入需要 AI_MEMORY_AUTH_TOKEN AI_MEMORY_AUTH_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.json7.2 外部对话导入# 1) dry-run默认 cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \ external-conversation --file /path/to/conversation.json --workspace default # 2) dry-run 并打印净化后的事件体 cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \ external-conversation --file /path/to/conversation.json \ --workspace default --show-body # 3) 真实重放 AI_MEMORY_AUTH_TOKEN... \ cargo run --manifest-path companions/ai-memory-importer/Cargo.toml -- \ external-conversation --file /path/to/conversation.json \ --workspace default --apply \ --manifest-out /tmp/conversation-import-manifest.json7.3 通用选项一览选项适用子命令说明--server-url URL两者ai-memory 服务器地址默认http://127.0.0.1:49374也读AI_MEMORY_SERVER_URL环境变量URL 的 path 部分被视为 base path代理部署场景--create-destination两者读预检返回 404 时允许/admin/write-page自动创建 workspace/project--overwriteomc-wiki替换已存在的目标页面--include-session-logsomc-wiki包含session-log-*页面--show-body两者dry-run 时打印完整页面正文 / 净化后的事件体--pinnedomc-wiki置顶所有导入页面与 frontmatterpinned取或--diromc-wikiOMC wiki 源目录--fileexternal-conversation通用对话 JSON 文件--workspace/--project两者目标工作区 / 项目--apply下为必填--manifest-out path两者持久化 manifest--apply下为必填认证统一通过AI_MEMORY_AUTH_TOKEN环境变量提供HTTP 层使用 reqwest 的bearer_auth注入Authorization: Bearer ...头ImportClient::requestmain.rs服务器 URL 解析时会拆出 origin 与 base path保证带反代前缀的地址也能正确拼出/hook/batch与/admin/write-page。八、验证与测试从仓库根目录执行# 格式、单测、clippy针对 importer 自身 cargo fmt --check --manifest-path companions/ai-memory-importer/Cargo.toml cargo test --manifest-path companions/ai-memory-importer/Cargo.toml cargo clippy --manifest-path companions/ai-memory-importer/Cargo.toml --all-targets -- -D warnings # 根仓库卫生检查保持独立 cargo fmt --check git diff --checkimporter 的单元测试值得细读它们是理解行为契约的最佳文档main.rs 中的测试覆盖了 frontmatter 解析、未知 tier 拒绝、index.md/session-log-*跳过、路径穿越拒绝、slug 撞车检测、dry-run 不创建 HTTP 客户端、写请求 JSON 形状、API 列表响应新旧两种形态裸数组与{pages:[...]}包装、Bearer 认证、事件序列与external-import身份、稳定 ID 幂等与追加重放、凭证脱敏、恶意输入零副作用以及用TcpListener起真实回环服务器验证 preflight 单批/hook/batch的完整往返live_import_round_trips_preflight_and_one_ordered_hook_batch。九、Roadmap仓库中已明确的后续规划包括Claude Code 记忆图导出导入、带用户自定义 schema 映射的 Qdrant 集合导入以及在 OMC 导入稳定后增加可选的确定性规范化处理。十、适用前提与边界使用前请确认目标 ai-memory 服务器正在运行且/hook与/admin端点可达服务器地址默认http://127.0.0.1:49374可通过--server-url或AI_MEMORY_SERVER_URL覆盖写入需要有效的AI_MEMORY_AUTH_TOKEN。OMC 模式只处理顶层 Markdown 文件并写入omc/前缀对话模式要求源文件遵守本文第三节的通用 envelope 与全部边界限制导入是显式一次性操作不提供常驻监听模式。【免费下载链接】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），仅供参考