OpenHuman 记忆引擎 TinyCortex 迁移规范所有权拆分、删除账本与安全边界的工程实践【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman本文解读 OpenHuman 仓库中docs/tinycortex-migration-spec.md这份迁移规范Phase 0.5 / 0.6 阶段。它记录了 OpenHuman 将庞大且持续演进的记忆memory子系统逐步搬迁到独立tinycortexcrate 的完整契约类型统一决策、C 依赖工具链对齐、所有权拆分清单、逐文件删除账本、工作流顺序与安全审查项。读完本文你将理解引擎进 crate、产品策略与 I/O 留在宿主这种拆分模式的落地细节以及如何在保证用户磁盘数据、安全语义MemoryTaint/source_scope不变的前提下完成一次大规模架构迁移。一、文档定位迁移后的常设参考而非过期计划这份规范自述为Post-engine-cutover reference引擎切换后的参考文档。它的状态说明明确记录了迁移关键节点W1–W8 与 crate 自持引擎测试落地于 OpenHuman PR #4794 / #4820persona / coding-session 摄取随后在 #4863 落地剩余的宿主侧整合由 tinycortex-migration-plan-2026-07-22.md 跟踪。规范本身保留了两类永久有效的细节所有权契约ownership contract与删除账本deletion ledger。配套文档体系均以仓库根为基准执行计划tinycortex-memory-migration-plan.md历史执行计划含 §8 修订案逐行漂移账本tinycortex-drift-ledger.mdAPI 缺口审计tinycortex-api-gap-audit.md数据格式平价核对清单tinycortex-parity-checklist.md版本锚点为什么迁移必须钉死 SHA迁移工程中最危险的变量是双方各自演进宿主的记忆引擎在 tinycortex 移植之后仍持续收到性能优化与 bug 修复而 crate 侧也不断合入对齐补丁。规范因此把每个审计基准确认到具体 commitRepoSHA说明tinyhumansai/openhuman7850cf363559bcbb7ba688cbc4fccdb6bd9ce754宿主审计基线main2026-07-04tinyhumansai/tinycortexd1a8c7be2babc8fff7a72ed93861f459f3d6fa58crate 审计基线v0.1.1tinyhumansai/tinycortex33dda943053e61ef585fc39647cf1854344b6323审计基线 #59原生依赖对齐§0.4tinyhumansai/tinycortexa8e10f7dd8ebdb9b0905e1380fefcc6bf5a65207历史切换 gitlink #63/#64D2/D1 漂移关闭tinyhumansai/openhuman5b8a9f2692026-07-22 整合审计基线tinyhumansai/tinycortexdaaaf6ba5f02635c08deae2b2b2ed7fcc8c06b6a2026-07-22 复核 gitlink上游无 tag宿主跟踪已复核的 main 提交tinyhumansai/tinycortex7b4b115当前迁移分支TinyAgents 2.1 对齐 修正所有权文档按内容反推的移植线§0.1引擎特性移植对应2026-06-25 之后、2026-06-28 之前。这份提交级锚定让每一条漂移记录host commit → tinycortex PR都能被独立复核也是删除账本可执行的先决条件。二、类型统一决策§0.5宿主 re-export而不是From转换迁移的第一步不是动存储而是统一类型。宿主的memory/traits.rs与 crate 的types.rs是线兼容双胞胎规范在两种方案中做出明确决策决策宿主 re-export crate 类型pub use tinycortex::memory::{…}frommemory/traits.rs。这是计划中的首选方案。收益是单一事实来源且 30 个消费站点agent/harness、learning、channels/runtime、subconscious、threads等通过 re-export 保持原有 import 路径不变零改动编译。回退方案保留宿主类型 From转换不需要——§0.3 平价审计未发现 serde/API 分歧。MemoryTaint安全关键类型先证明完全一致再 re-exportMemoryTaint驱动外部效应工具门控被污染的潜意识 turn 必须拒绝external_effect工具是安全关键类型。规范要求在 re-export 之前对其 serde 形式、数据库字符串与 fail-closed 默认值做逐字节对比属性宿主memory/traits.rs:25cratetypes.rs:26匹配变体Internal#[default]、ExternalSyncInternal#[default]、ExternalSync✅serdesnake_casesnake_case✅as_db_strinternal/external_syncinternal/external_sync✅from_db_str未知值→ExternalSyncfail-closed→ExternalSyncfail-closed✅要点更严格的污染值是默认值也是未知解码的落点——两侧都保持 fail-closed 到ExternalSync的不变式。因此 re-exportMemoryTaint不会削弱来源追踪provenance。W2 专用 seam 测试钉死这一行为未知 DB 字符串 →ExternalSyncDefault::default()→Internal两个 DB 字符串可往返。sqlite_conn()逃生舱W2 子决策宿主Memorytrait 的sqlite_conn()缺口 G1不属于re-export 的 crate trait。过渡期内将其保留为宿主侧扩展 traitW3 中把内部裸 SQL 调用方迁移到tinycortex::memory::chunks::with_connection并在删除账本中把残留调用数驱赶到零。re-export 覆盖的数据类型包括MemoryEntry、MemoryCategory、MemoryTaint、RecallOpts、NamespaceSummary、GraphRelationRecord、RetrievalScoreBreakdown、NamespaceMemoryHit等以及Memorytrait 的异步 CRUD 表面逃生舱在 W3 退役之前一直留在宿主。三、工具链基线§0.4两个原生库链接冲突的硬仗任何代码迁移之前先要让 crate 在宿主的世界里编译通过。规范给出了逐项检查表检查项结果crate edition2021与宿主一致✅[patch.crates-io] tinycortex { path vendor/tinycortex }根与app/src-tauri两个 Cargo 世界都已预置 ✅CI 子模块检出所有构建/测试泳道均递归检出覆盖vendor/tinycortex✅rusqlite 对齐✅ 已在 #59 解决crate 钉0.32bundled宿主钉0.40.0bundled。两个links sqlite3是硬性 Cargo 错误。修复 升到0.40usize→i64/try_from扫尾同时关闭漂移 D3git2 对齐✅ 已在 #59 解决crate 钉0.19宿主0.21vendored-libgit2。修复 升到0.21 API 差异适配Tag::message、StringArray::Iter、Buf::as_strcrate 以对齐依赖编译✅cargo check --all-targets干净38 个 diff/checkpoint 测试通过宿主根世界带依赖编译✅cargo check --manifest-path Cargo.toml --lib退出码 0[dependencies] tinycortex 0.1激活 子模块33dda94。无multiple packages link to native library错误——确认单一 bundled SQLite 单一 libgit2宿主app/src-tauri世界W1 中验证独立 Cargo 世界 / lockfileGGML_NATIVEOFFmacOS ARMW1 中在 macOS runner 上验证这一小节的价值在于揭示 Rust 生态迁移的真实难点两个 crate 各带一份 C 依赖links sqlite3/links git2必然冲突必须先把版本对齐才能谈功能迁移。同时子模块规则只能 bump 到已合并的 SHA决定了激活时机#59 在上游合并后宿主 gitlink 才 bump 到33dda94[dependencies] tinycortex 0.1正式激活seamsrc/openhuman/memory/tinycortex/接线完成cargo check --lib退出码 0。注意规范给出的行号锚点Cargo.toml:116、src/openhuman/mod.rs:140在后来的整合文档中已被修正为当时的实际位置读者应以当前仓库为准。四、所有权拆分§1什么进 crate什么留宿主这是规范的核心契约由两次审计drift gap audit修正而成分为三张清单。4.1 移入 TinyCortex切换后从宿主删除宿主模块crate 对应随迁的表memory_store/{chunks,content(core),vectors,kv,entity_index,safety}store/、chunks/mem_tree_chunks、mem_tree_chunk_embeddings(reembed_skipped)、vectors、kv_global、kv_namespace、store_meta、mem_tree_entity_index、mem_tree_entity_edges、mem_tree_entity_hotness、mem_tree_ingested_sources、mcp_writes、legacy_markermemory_tree/{tree,retrieval,score,summarise}tree/、retrieval/、score/mem_tree_trees、mem_tree_summaries(embeddings,reembed_skipped)、mem_tree_buffers、mem_tree_scorememory_queue/queue/mem_tree_jobsmemory/ingest_pipeline.rs内部ingest/—memory_diff、memory_entities、memory_graph(engine)、memory_goals、memory_archivist、memory_sources(registry local readers)、memory_tools(engine)、memory_conversations(engine)、memory_search(vector,scoring)同名 crate 模块—memory/traits.rs核心类型tinycortex::memory::{…}re-export—4.2 留在 OpenHuman产品策略、I/O、表面RPC 表面memory/{ops,schemas,schema,read_rpc}、rpc_models.rs。方法名/载荷不变JSON-RPC 兼容是硬约束。Agent 工具memory/tools/、memory/query/、memory_search/tools/、memory_tools(tool surface)——作为 crate 检索原语之上的薄封装 SecurityPolicy门控。Live sync2026-07-09 修订计划 §8 / W-SYNCsync引擎pipeline、per-toolkit Composio provider HTTP client、canonicalize、sync_state、audit/rebuild、sync_status 查询、dispatcher移入 crate置于可选synccargo feature 之后。crate 的永不发起网络调用不变式变成feature 作用域默认构建仍无网络syncfeature 才引入 HTTP Composio client其凭据由宿主注入。宿主保留调度循环tick 驱动 crate类似queue::run_once、凭据/OAuthkeychaincomposio-direct、经新SyncEventSinkseam trait 的事件总线桥、RPC 包装memory/{ops,schemas}/sync.rs、memory_sources/rpc.rs、以及经新SkillDocSinkseam trait 的 UnifiedMemory 写回。MCP 传输留宿主。进程胶水memory/global.rs单例 队列 workermemory/source_scope.rstask-localmemory/chat.rsembeddings provider 接线。修订计划 §8 / W-EMBsrc/openhuman/inference/embeddings/中的 provider实现上迁到tinyagents::harness::embeddings——trait 增加name/model_id/signature签名字节钉死为provider{name};model{model};dims{dims}P10——tinycortex 把EmbeddingBackend桥接到该 trait宿主只留 factory/config/RPC 接线。策略/UXpreferences.rs、remember.rs、tree_policy.rs、util/redact.rs、配置映射。宿主保留的UnifiedMemory命名空间文档层§0.3 关键发现共享 DB 中共存但不迁移的 10 张表——memory_docs、graph_global、graph_namespace、episodic_logepisodic_fts 触发器、event_logevent_fts、event_embeddings、触发器、conversation_segments、segment_embeddings、vector_chunks、user_profile。它们位于memory_store/namespace_store/{init,fts5,events,segments,profile}.rs并保持宿主——crate 是原语基座不是整库的替代品。宿主显式排除的内容存储表面content::wiki_git、content::obsidian、content::obsidian_registry。4.3 适配层 seamsrc/openhuman/memory/tinycortex/镜像src/openhuman/agent/tinyagents/的先例W1 seam 文件包括embeddings.rsEmbeddingBackend/Embedderchat.rsChatProvider/Summariser×2/EntityExtractor/GoalsGeneratorqueue_driver.rsQueueDelegates tokio worker 循环 Sentry/busconfig.rsConfig→MemoryConfigsinks.rsTreeJobSink/TreeLeafSink/SnapshotItemSource/EntityOccurrenceIndexsync.rssync 结果 →DomainEventmod.rs适配器命名空间 兼容性 re-export 边界文档设计要点新引擎消费者直接 importtinycortex::memory::*seam 拥有实现而非充当第二类型漏斗。全部 17 个 W1 seam trait 已确认存在于 crate§0.2。后期 seam 增补2026-07-09 修订W-EMB rebridgeembeddings.rs从openhuman::embeddings改指tinyagents::harness::embeddings::EmbeddingModelcrate 桥接EmbeddingBackend到该 trait。seam 文件保留其底层实现上移。W-SYNC seam 文件sync_sink.rs为随 W-SYNC.1 落地的两个新 crate trait添加宿主适配器不在上述 17 个之列SyncEventSink→MemorySyncStagebus 事件与SkillDocSink→MemoryClient::store_skill_sync即宿主保留的命名空间文档层。五、删除账本§2每个文件删得明明白白迁移不是写完新代码就完事而是必须删除旧引擎。规范规定每个遗留引擎文件仅当其模块的漂移行关闭、缺口解决、且 golden-workspace 平价 harness 在其切换上变绿时才被删除。遗留模块文件数测试文件删除时机前置条件memory_store/66 (11)W3/WP-1漂移 D3 关闭缺口 G1 完全迁移2026-07-22 审计时sqlite_conn()调用点为零平价 P3/P5/P11/P12 绿命名空间层重新安置到namespace_store/作为宿主保留memory_tree/65 (7)W5缺口 G3seal-embed、G62× Summariser解决source_scope白名单复核平价 P7/P11 绿health/tree_policy.rs留宿主G5memory_queue/10 (1)W4漂移 D2 关闭predicate 上迁job payload_json 平价P4/P9宿主 worker 循环 Sentry/degraded 接线保留memory_conversations/7 (1)W7漂移 D1 关闭bus.rs留宿主memory_diff/7 (0)W7git-ledger 平价P9绿memory_entities/3 (0)W7平价 P8 绿memory_graph/3 (0)W7缺口 G2 解决derive-on-read 平价 vs 宿主保留的graph_*memory_goals/7 (0)W7seamGoalsGenerator接线memory_archivist/6 (0)W7TreeLeafSinkseam 接线memory_sources/16 (0)W7 / W-SYNCregistry local readers 随 W7 迁sync.rsdispatcher reconcile.rs随 W-SYNC 迁rpc.rs留宿主memory_sync/引擎—W-SYNC.3漂移 D4 关闭W6 落地crate ingest 上线mocked live Composio 测试对绿sync-status 平价绿调度器/bus/RPC/keychain 留宿主src/openhuman/inference/embeddings/provider 实现—W-EMB.3tinyagents provider 移植合并签名平价P10绿factory.rs(thin)/rpc.rs/schemas.rs/catalog 留宿主memory_tools/10 (1)W7引擎 →tool_memory/tool surface 留宿主memory_search/8 (0)W5vector/scoring→ crateretrieval/scoretools/留宿主memory/ingest_pipeline.rs内部薄入口点保留W6ingest_chat/ingest_document_with_scope签名不变11 个调用点不动2026-07-22 整合实际结果WP-1 命名空间层memory_store/unified/移除并逐字节重新安置为memory_store/namespace_store/G1 再审计发现零个sqlite_conn()调用点。保留的十表产品存储解释了为何memory_store总 LOC 仍是 17.7k 而非计划推测的 9–10k。WP-2 sync默认 provider 的sync()与run_connection_sync已调用 TinyCortex 引擎删除宿主死掉的 Gmail sync parserGitHub/Notion/Linear/ClickUp 产品投影从sync.rs改名normalization.rsD4.1–D4.4 全部关闭。WP-3 embeddings删除宿主 OpenAI、Cohere、Voyage、general Ollama、memory-tree cloud、memory-tree Ollama provider 实现746 生产 LOC 过时的 828 行 raw-coverage 套件。provider 传输现在在 TinyAgents 中只有一份实现OpenHuman 保留选择与凭据/隐私适配器。WP-4 shims删除memory_archivist、memory_search::{scoring,vector}、memory_tools::{types,store}、memory_tree::tools与memory::jobs别名移除未使用的 TinyCortex 类型 facade直接tinycortex::memory::*import 成为约定。seam 生产代码 2,229 行低于 2.5k 退出目标。永不删除保留宿主memory/{ops,schemas,schema,read_rpc,tools,query,tree_source,ingestion,util}、memory/{global,source_scope,chat,sync,preferences,remember,tree_policy,rpc_models,traits(→re-exports)}.rs、memory_sync/的宿主保留外壳仅调度器periodic.rs、bus.rs订阅者、RPC 注册——引擎随 W-SYNC 迁移、memory_store/namespace_store/*、memory_store/content/{wiki_git,obsidian,obsidian_registry}、memory_tree/health/以及新的 seam 目录。六、工作流顺序§3按依赖图推进每个 risky 工作流都是三明治W1 seam 脚手架 → W2 类型/trait re-export → W3 storechunks → W4 queue → W5 treeretrievalscore → W6 ingest →W-SYNCsync 引擎 Composio client→ W7 长尾 → W8 测试移植 golden 平价清扫 删除账本收尾。W-EMB从 tinyagents 继承 embeddings并行运行且 W-EMB.2 必须在 W-SYNC.3 切换之前落地。每个高风险工作流遵循sandwich三明治模式计划 §4tinycortex PR(s)关闭该模块的 drift/gap 账本宿主chore(vendor): bump tinycortex提交宿主切换 PR适配器翻转 遗留删除 宿主侧测试放在同一 PR满足 ≥80% diff 覆盖率门槛。排序遵循引擎依赖图存储先行、表面殿后。W3–W5 是风险核心用户磁盘数据W1–W2 可以快速落地W6–W7 在 W5 之后并行。七、安全审查项§4必须配备专用 seam 测试规范明确列出四类必须由专门 seam 测试钉死的安全项MemoryTaintfail-closed 到ExternalSync——已在 §0.5 证明两侧一致W2 seam 测试钉死。source_scope每轮白名单——必须挺过 W5 检索切换。检索原语query_source/query_topic/drill_down在宿主的 task-local 作用域内运行W5 seam 测试必须断言白名单外的 source 不会被返回。这是安全面source_scope门控永远留在宿主。Composio 凭据处理W-SYNC——crate 仅以脱敏的SecretString持有密钥Debug/Display掩码、跳过序列化生产解析留在宿主 keychaincomposio-directCOMPOSIO_API_KEY环境变量回退仅用于测试seam 测试断言密钥绝不出现在MemoryConfig的Debug输出或客户端错误消息中含 401 路径。Sync 污染来源W-SYNC——每个 crate 侧 sync ingest 必须打上MemoryTaint::ExternalSync戳mock Composio 管道测试钉死此行为。八、现状印证迁移落地后的 OpenHuman规范描述的是迁移执行期状态从当前仓库看这份契约已经生效并继续演进。src/openhuman/memory/README.md记录记忆子系统的实质SQLite/vector 存储、markdown 摘要树、provider sync 管道、摄取、召回/查询/搜索、摄取队列、conversations、people、goals、tool-memory 规则已被提取为独立 crate留在src/openhuman/memory/的正是规范所称的宿主表面——RPC 表面、Agent 工具与 guard 策略门taint/scope/budget 门控其余模块大量以pub use tinymemory_core::…形式 re-export使约 550 个crate::openhuman::memory::…路径继续解析不变——这正是 §0.5 re-export 保持消费站点不动策略的直接落地证据。适配层痕迹同样可见src/openhuman/memory/mod.rs 中存在memory-engine-seamscargo feature默认开启、产品构建关闭以及host.rs/host_impls.rs的 seam 实现install_memory_event_sink、MemoryHostConfig for Config与规范 §1 中宿主进程胶水 事件总线桥的保留项一一对应source_scope.rs作为安全门控仍保留在宿主侧。仓库的集成测试矩阵如tests/memory_roundtrip_e2e.rs、tests/memory_golden_parity_e2e.rs、tests/memory_graph_sync_e2e.rs正是计划 §5 中既有 crate 级集成测试充当每次切换的内置平价 harness的延续。需要说明的是后续整合中该引擎 crate 的命名演进为 tinymemorytinymemory-core且当前 CI 检出该仓库时不包含子模块内容——若在仓库内查看vendor/tinymemory/相关相对链接可能无法解析读者应关注src/openhuman/memory/宿主侧的实际结构。结语这套规范的可复用价值docs/tinycortex-migration-spec.md展示了一条可复制的大模块解耦路径类型先行re-export 保证消费端零改动→ 工具链对齐先解决links原生库冲突→ 所有权三清单进 crate / 留宿主 / 适配 seam→ 删除账本每个文件有删除时机与前置条件→ 安全项专用测试钉死。对于任何想把长期演进的核心引擎拆分为独立 crate 的项目这套引擎进 crate、策略与表面留宿主、submodule patch.crates-io 双世界编译、逐模块平价后再删除的组合拳都是可以直接借鉴的工程模板。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考