OpenViking 日志导入指南用openviking-server ingest把 Claude Code / Codex / OpenCode 等 Agent 日志重放为长期记忆【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenVikingopenviking-server ingest是 OpenViking 官方提供的一款客户端侧日志导入工具它把本机已有的 AI 编码 / Agent harnessClaude Code、Codex、OpenCode、Hermes、OpenClaw对话日志解析成标准消息再经由 OpenViking 既有的会话管线创建会话 → 批量追加消息 → 提交重放进去提交时触发记忆抽取让历史与新增对话沉淀为长期记忆。读完本文你将掌握如何通过ov.conf精确开启某个 harness 的导入、如何用backfill/watch/run三条命令完成存量回填与增量监听、游标与 peer_id 的设计原理以及如何控制导入带来的 LLM 成本与隐私风险。与记忆插件的定位差异互补而非替代OpenViking 针对各 harness 提供了实时记忆插件参见 概览它们在对话进行时挂载捕获而openviking-server ingest解决的是另外两类诉求导入既有日志把安装插件之前的历史会话一次性回填为记忆离线监听新增日志在完全不安装插件、不改动 harness 的前提下轮询读取其日志目录实现增量同步。关键区别在于本工具是 OpenViking 的客户端运行在日志所在机器上通过 SDK 指向本地或远端 server它默认完全关闭不会装上就扫你本地文件所有 harness 必须逐一显式开启后才会被读取。相关实现位于 openviking/ingest 目录。默认关闭双重开关 显式验证该特性默认双重关闭必须显式开启总开关ingest.enabled默认false对应 ingest_config.py 中IngestConfig.enabled的默认值每个 harness 的enabled默认false且未列出的 harness 不会被读取IngestHarnessConfig.enabled默认False存量回填需手动运行命令并支持--dry-run只统计、不写入与--since限定时间窗先行验证。总开关与单个 harness 开关是与关系enabled_harnesses()要求总开关为真同时 harness 自身enabledTrue且mode ! off才生效ingest_config.py。支持的 harness 一览harness状态默认日志路径说明claude_code支持~/.claude/projects/*/*.jsonlappend-only JSONL字节偏移游标codex支持~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonlappend-only JSONLhermes支持~/.hermes/sessions/*.jsonl群聊 agentuser 取原始用户名openclaw支持~/.openclaw/agents/*/sessions/*.jsonl群聊 agentuser 取原始用户名opencode实验性~/.local/share/opencode/opencode.dbSQLite按(time, id)轮询旧版文件存储暂不支持cursor暂缓~/Library/Application Support/Cursor/User/**/state.vscdb无文档、随版本漂移的 KV blob暂未实现这里的 harnessagent 框架指 Claude Code / Codex 等整套工具区别于 OpenViking 里 tool工具调用 的概念。实现上每个 harness 对应一个轻量适配器openviking/ingest/sources/ 下的claude_code.py、codex.py、hermes.py、openclaw.py、opencode.py、cursor.py通过register_source(name)装饰器注册进 registry.py 的SOURCE_REGISTRY新增一个 harness 只需写一个LogSource子类无需改动配置 schema配置键是自由格式的。适配器抽象出两类游标模型sources/base.pyJsonlLogSourceappend-only JSONLClaude Code / Codex / Hermes / OpenClaw字节偏移游标SqliteLogSource关系型 SQLiteOpenCode(time, id)游标、只读轮询。以 claude_code.py 为例每条记录顶层type为user/assistant的才会被解析isSidechain/isMeta的子 agent 合成记录、纯 tool 调用轮次无文本都会被丢弃只保留有实质文本的 user / assistant 轮次并携带model、cwd、git_branch等元信息。在 ov.conf 中开启在ov.conf增加ingest段列出要导入的 harness 并设置其模式{ ingest: { enabled: true, server_url: $OPENVIKING_URL, api_key: $OPENVIKING_API_KEY, account: default, user: default, harnesses: { claude_code: { enabled: true, mode: both }, codex: { enabled: true, mode: backfill }, opencode: { enabled: false, mode: watch, experimental: true }, hermes: { enabled: false, mode: both, user_field: sender }, openclaw: { enabled: false, mode: both, user_field: sender } } } }各字段含义与默认值依据 ingest_config.py 的 pydantic 模型顶层enabled默认false总开关server_url/api_key目标 server 地址与密钥。server_url留空时回退到OPENVIKING_URL或http://localhost:1933因此既能指向本地 server也能指向远端account/user默认default被导入会话的归属账号与用户state_dir游标状态库位置默认~/.openviking/ingestsession_id_prefix默认importOV 会话 id 前缀最终形如import__{harness}__{原生会话id}memory_policy透传给重放会话的 memory_policy空则用 server 默认值。每个 harnessIngestHarnessConfigenabled默认false是否导入该 harnessmodeoff|backfill一次性导入存量|watch监听新增|both默认backfillpaths覆盖该 harness 的默认发现路径可填多个文件/目录/DB 路径poll_interval_seconds默认5.0watch 模式下该 harness 的轮询间隔user_field群聊 harnesshermes / openclaw中存放原始用户名的日志字段名用作 user 侧 peer_id留空用适配器默认值experimental显式开启实验性适配器如 opencode用于声明可能脆弱commit提交策略含commit_token_threshold默认6000待归档 token 达到该值即提交、commit_idle_seconds默认5.0watch 模式下会话空闲该时长后提交、keep_recent_count默认0WM v2 滑动窗口提交后仍在会话中保留的最近消息数0 全部归档。配置模型extra: forbid即不认识的多余键会直接报错而不是被静默忽略——格式错误会在启动时暴露不会伪装成未配置 ingest。环境变量覆盖部署期部署期开关也可用环境变量覆盖优先级高于配置文件定义见 consts.pyOPENVIKING_INGEST_ENABLED1/true/yes/on视为开启OPENVIKING_INGEST_SERVER_URLOPENVIKING_INGEST_API_KEYCLI 使用五个子命令openviking-server ingest命令随 OpenViking 一同安装CLI 定义在 openviking/ingest/cli.py# 查看已注册 harness 及其配置 openviking-server ingest list-sources # 先干跑统计会回填多少 session / 消息不写入 openviking-server ingest backfill --dry-run # 只回填某个 harness、且只回填某日期之后的会话 openviking-server ingest backfill --harness claude_code --since 2026-06-01 # 正式回填存量 openviking-server ingest backfill # 监听新增日志并增量重放前台阻塞 openviking-server ingest watch --harness claude_code # 按每个 harness 配置的 mode 执行先回填再监听 openviking-server ingest run # 查看各会话已导入到哪里读取游标状态 openviking-server ingest status命令细节list-sources列出已注册 harness 及当前生效配置enabled、mode、paths未配置的显示(not configured)并打印ingest enabled与server_url。backfill一次性回填存量参数--harness/-H默认所有已启用 harness、--sinceISO 日期跳过该时间之前开始的会话、--dry-run只统计不写入无需 server 也无需加锁、--reset。--dry-run会输出每个 harness 的sessions / messages统计正式回填会输出Replayed: N sessions / N messages / N commits。watch对mode ∈ {watch, both}的 harness 做增量轮询前台阻塞运行支持--harness过滤通过SIGINT/SIGTERM优雅退出退出时会为所有脏会话做最后提交失败则needs_commit持久化、下次续传。run先对所有mode ∈ {backfill, both}的 harness 执行回填再进入 watch 循环。status展示每个会话的导入进度harness、原生会话 id、已追加消息数、最近提交时间可用--harness过滤。--reset会在重放前删除并重建对应的 OV 会话对应SessionReplayer.reset_session见 replay.py不加--reset时重复运行是幂等的——游标保证不会重复追加。运行回填/监听时CLI 会在状态目录上获取单实例锁SingleInstanceLock避免两个进程同时写游标。peer_id为人类与模型建立画像每条消息都会带上 peer_id解析逻辑见 openviking/ingest/peer.pyassistant 消息{harness}/{模型名}provider 有意义时{harness}/{provider}/{模型名}例如claude_code/claude-opus-4-8、opencode/bytedance_ark/doubao-...源码中以__拼接后经safe_peer_id校验user 消息单用户开发型 harnessclaude_code / codex / opencode取会话 cwd 所在仓库的 git 身份优先user.email其次user.name带每 cwd 缓存无 git 仓库时回退为配置的ingest.user群聊 harnesshermes / openclaw取日志里的原始用户名由user_field指定实现为LogSource.user_peer()的分支sources/base.py。任何包含非 ASCII 字符的标识例如中文或混合文字用户名都会将完整标识编码为无碰撞的ext-base64形式。ext-命名空间为编码身份保留如果 ASCII 身份清理后会成为ext-id系统也会对其编码避免它冒充已有编码身份。新的读取和写入只使用规范 id。旧版本可能把多个混合文字身份或一个混合文字身份与真实 ASCII 身份折叠到同一个 peer 目录中。OpenViking 不会把这些归属不明确的目录自动附加为别名迁移既有数据前运维人员必须先确认其真实归属。工作原理适配器 → 重放器 → 幂等游标重放管线ensure_session → 批量追加 → commit每个 harness 的适配器把日志解析为标准消息NormalizedMessage见 models.py交给重放器SessionReplayer执行reconcile() - 每批 ≤100 条消息: set_pending - append - confirm - commit_if_neededOV 会话 id 形如import__{harness}__{原始会话id}{prefix}__{harness}__{native_session_id}确定且幂等批量上限 100server 端batch_add_messages有 100 条上限replay.py 的_BATCH 100读取侧DEFAULT_READ_LIMIT 100与之对齐sources/base.py记忆抽取只在 commit 时触发由 server 端执行客户端只负责在合适时机提交。崩溃自愈reconcile 与持久化意图每一批的意图目标游标 批大小 server 端追加前的消息数基线会在追加前持久化。如果进程在追加中途崩溃下一次运行reconcile()会比较 server 当前消息数与基线若批已落地则确认不重复追加否则丢弃意图并从已确认游标重新读取。游标只在确认的追加后推进needs_commit保证已追加但未提交的会话后续仍会被抽取replay.py 模块文档。存量回填 vs 增量监听存量回填枚举所有会话从游标读到末尾后逐会话提交一次orchestrator.pysince过滤按SessionRef.started_at比较。监听增量参照 OpenViking 自身的WatchScheduler用定时轮询非文件系统事件 持久游标驱动poller.py漏一拍、休眠或重启后下一拍从游标读到末尾即可自愈。JSONL 用字节偏移游标含半行/截断/轮转处理SQLite 用(time, id)游标只读读取兼容 WAL。JSONL 的轮转/截断处理值得一提游标记录inode当文件被替换inode 变化或游标偏移超过文件大小时自动从头重读sources/base.py。SQLite 侧则以modero只读连接row_complete保证不会越过尚未写完的行如 part 文本未 flush 的消息留给下一拍。游标状态持久化游标状态持久化在~/.openviking/ingest/state.db默认状态目录DEFAULT_INGEST_STATE_DIR ~/.openviking/ingest因此回填与监听都能在重启后续传且不会重复入库。可用openviking-server ingest status查看每个会话的游标进度。成本与隐私提交会触发记忆抽取LLM 调用。一次性回填数月历史可能产生大量调用建议先--dry-run、用--since收窄时间窗、按 harness 分批开启并善用commit_token_threshold/commit_idle_seconds控制提交频率。日志中可能含敏感内容凭据、文件内容。请在受信任的部署中使用并确认server_url指向你期望的 server必要时用环境变量OPENVIKING_INGEST_SERVER_URL/OPENVIKING_INGEST_API_KEY显式覆盖。tool 调用的输入/输出默认按低价值丢弃适配器只解析 user / assistant 的文本轮次仅入库文本消息不保留工具 I/Onormalize.py 只生成textpart空轮次直接返回None丢弃。参见集成能力参考概览 — 各 harness 的记忆插件实时捕获方案部署指南 → CLI —ov.conf/ 凭据配置【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考