Memori Python SDK 3.3 系列演进深度解析Rust 原生内核、混合检索与 BYODB 供应能力全览【免费下载链接】MemoriMemori is agent-native memory infrastructure. A LLM-agnostic layer that turns agent execution and conversation into structured, persistent state for production systems. Built for enterprise, Memori works with the data infrastructure you already run, no rip-and-replace, and deploys across managed cloud, single-tenant cloud, VPC, and on-premises.项目地址: https://gitcode.com/GitHub_Trending/me/Memori本篇指南以仓库根目录 CHANGELOG.md 为核心脉络系统拆解 Memori Python SDK 从 3.3.0rc1 到 3.3.6含 Unreleased 改动的关键演进Rust 原生内核engine-orchestrator/memori_python扩展如何从实验特性逐步成为 BYODB 模式默认路径、dense BM25 混合检索与 tokio 后台增强工作线程的实现细节、TiDB Zero 一键供应、以及 OpenAI/Anthropic/Bedrock 对话注入兼容性修复。读完本文你将掌握各版本开关的精确用法环境变量、构造函数参数、Rust 内核的加载与回退机制、混合检索的权重调优参数以及如何通过仓库内源码与测试用例验证每一项改动。一、3.x 演进的三大主线阅读 CHANGELOG.md 可以发现3.3 系列的所有改动可以归纳为三条相互交织的主线Rust 原生内核从实验到默认3.3.0rc1 以MEMORI_USE_RUST_CORE1实验性引入3.3.2 起在 BYODB 模式下默认启用3.3.6 进一步把本地向量化Memori.embed_texts(...)、recall 查询向量、advanced augmentation 事实向量全部收敛到 Rustfastembed后端。BYODB自带数据库能力的持续增强新增 TiDB Zero 供应、Android 平台支持、预编译 wheels 矩阵并围绕原生引擎修复了一系列真实场景缺陷如 datetime 序列化。LLM 兼容性修复针对 OpenAI 兼容端点对 tool 消息序列的严格要求重写了历史消息注入前的清洗逻辑。文章后续各节分别深入这三大主线并给出对应的源码路径与可验证依据。二、Rust 原生内核从实验开关到默认路径2.1 版本演进时间线版本日期Rust 内核状态关键动作3.3.0rc12026-04-16实验性需显式开启MEMORI_USE_RUST_CORE1提供原生混合检索与 tokio 后台增强发布预编译 wheelssdist 纳入core/crate3.3.22026-04-28BYODB 模式默认启用Rust 检索与增强默认开启加载失败自动回退纯 Python新增 Android wheel3.3.62026-05-27全面巩固本地 embedding 全部走 Rust fastembedAA 事实向量在 Rust worker 内附加修复 datetime 序列化等缺陷2.2 开关优先级与回退语义3.3.2 起按照 changelog 的描述3.3.2 之后 Rust 内核的启用规则是BYODB 模式下只要memori_python扩展加载成功即默认启用Python SDK 仍负责 provider 包装、存储适配器、会话持久化与回退。关闭方式有三种from memori import Memori # 方式一构造函数参数优先级最高覆盖一切环境变量 mem Memori(connmy_conn_factory, use_rust_coreFalse)# 方式二显式禁用环境变量推荐用于故障排查 export MEMORI_DISABLE_RUST_CORE1 # 方式三旧式布尔开关3.3.0rc1 时代的 opt-in 变量 export MEMORI_USE_RUST_CORE0在 memori/_config.py 中可以精确看到这一优先级逻辑if _env_bool(MEMORI_DISABLE_RUST_CORE, False): self.use_rust_core False elif os.environ.get(MEMORI_USE_RUST_CORE) is not None: self.use_rust_core _env_bool(MEMORI_USE_RUST_CORE, False) else: self.use_rust_core True即MEMORI_DISABLE_RUST_CORE1最高优先其次兼容旧变量MEMORI_USE_RUST_CORE3.3.0rc1 中设为1为开启3.3.2 后设为0为关闭两者都未设置时默认开启。而在 memori/init.py 中构造函数参数use_rust_core只要不为None就会在Config()初始化之后覆盖环境变量结果因此它是三者中优先级最高的。如果 Rust 内核加载失败例如未安装对应平台 wheelSDK 会打印警告并回退到纯 Python 路径不会中断业务——这是 3.3.2 明确保证的降级语义。2.3 内核加载机制memori_python扩展发现memori_python是 Rust crateengine-orchestrator目录core/编译产出的 Python 扩展。在 memori/native/_loader.py 中加载顺序为先调用_ensure_onnxruntime_dylib()确保 ONNX Runtime 动态库就绪若设置了MEMORI_PYTHON_LIB环境变量直接按该路径加载若设置了CARGO_TARGET_DIR依次探测release/debug下的libmemori_python.{dylib,so}或memori_python.dll回落到仓库内常见构建目录target/...、core/target/...最后尝试正常import memori_pythonwheel 安装场景。这意味着从源码构建内核后即使不安装 wheel也可以通过设置MEMORI_PYTHON_LIB或CARGO_TARGET_DIR让 SDK 找到本地编译产物便于调试。2.4 适配器结构Python 侧回调桥接Rust 内核并不是黑盒替代而是通过 memori/native/_adapter.py 中的RustCoreAdapter与数据库驱动建立桥接。EngineHandle构造时需要传入四个回调回调职责对应实现fetch_embeddings按 entity 拉取已持久化的事实向量供 Rust 侧做 dense 检索_fetch_embeddings_cbmemori/native/_adapter.pyfetch_facts_by_ids按 ID 批量取回事实内容含 summaries供重排序后返回_fetch_facts_by_ids_cbmemori/native/_adapter.pywrite_batch执行 Rust worker 提交的写操作批次_write_batch_cbmemori/native/_adapter.py内嵌向量化通过NativeEmbedder完成本地文本向量化memori/native/_embeddings.py_write_batch_cb支持的操作类型op_type在_apply_write_op中分发包括entity_fact.create、knowledge_graph.create、process_attribute.create、conversation.update、upsert_fact五种分别落盘到 entity facts、知识图谱三元组、进程属性与对话摘要memori/native/_adapter.py。从源码结构看Rust 侧负责调度与计算Python 侧负责所有数据库读写这种计算与 IO 分离的架构是内核能够透明替换纯 Python 实现的关键。三、混合检索管线dense 召回 BM25 词法重排序3.3.0rc1 首次引入的原生能力是混合搜索 recall 管线dense lexical re-ranking其 Rust 实现在 core/src/search/mod.rs 下分为三个文件core/src/search/api.rs公开入口search_facts融合余弦相似度与 BM25 分数core/src/search/lexical.rsBM25 打分与混合权重选择core/src/search/models.rs候选与结果数据结构。3.1 两阶段打分流程从 core/src/search/api.rs 的实现看检索分两步dense 阶段先用向量余弦相似度从事实池中召回候选集FactCandidate.score即原始余弦分数lexical 阶段对查询做 tokenize对每个候选计算 BM25 词法分数最终rank_score w_cos * cos_score w_lex * lex_score再按rank_score排序且只对前limit个结果做部分排序select_nth_unstable_by避免对全量候选做完整排序。3.2 词法权重可调参数core/src/search/lexical.rs 定义了通过环境变量控制的混合权重首次读取后缓存运行时不再重读环境变量默认值取值范围clamp语义MEMORI_RECALL_LEX_WEIGHT0.15[0.05, 0.40]常规查询的 BM25 权重MEMORI_RECALL_LEX_WEIGHT_SHORT0.30[0.05, 0.40]短查询≤ 2 个 token的 BM25 权重短查询默认给予更高的词法权重因为dense_lexical_weights认为短查询的语义向量信息量有限词法精确匹配更具判别力core/src/search/lexical.rs。tokenize会统一小写、按非字母数字字符切分并用二分查找过滤 40 余个英文停用词core/src/search/lexical.rs。3.3 调用链与测试验证Python 侧入口是 memori/native/_adapter.py 的retrieve_facts它构造{entity_id, query_text, dense_limit, limit}的 JSON payload调用EngineHandle.retrieve(...)得到 JSON 数组后逐条解析为 dict。dense_limit即MEMORI_RECALL_EMBEDDINGS_LIMIT默认 1000见 memori/_config.py控制 dense 阶段候选池大小。仓库内的单元测试直接验证了这条链路test_retrieve_facts_initializes_engine_on_first_use断言首次调用会惰性初始化引擎并精确调用一次engine.retrievetests/test_rust_core.pyRust 侧search_facts_blends_cosine_and_lexical_with_query与lexical_scores_ranks_matching_document_highest则验证了混合打分与 BM25 排序的正确性core/src/search/api.rs、core/src/search/lexical.rs。四、本地向量化fastembed/ONNX 与多平台分发4.1 统一到 Rust fastembed 后端3.3.63.3.6 之前本地 embedding 存在双轨Rust 内核可用时走fastembed否则回退 Pythonsentence-transformers。3.3.6 移除了 Pythonsentence-transformers回退本地向量化统一由 Rustfastembed后端完成覆盖三处Memori.embed_texts(...)、recall 查询向量、advanced augmentation 事实向量。embeddingsoptional extra 保留但变为安装兼容性 no-op见 CHANGELOG.md。Rust 侧的 embedder 实现在 core/src/embeddings/models.rsSentenceTransformersEmbedder内部持有fastembed::TextEmbedding、HuggingFace Hub 缓存的 tokenizer 与向量维度dim模型初始化是惰性的——引擎启动时不加载 ONNX Runtime首次 embedding 时才初始化从而降低冷启动开销。Python 侧则通过 memori/native/_embeddings.py 的_embed_with_native_cache按模型名缓存NativeEmbedder实例线程安全_NATIVE_EMBEDDER_LOCK保护并用_embed_texts_with_cardinality保持输入基数一致性不可嵌入的输入返回空向量占位可嵌入文本逐条对齐向量下标若数量不匹配会抛出RustCoreAdapterErrormemori/native/_embeddings.py。4.2 首次使用的模型下载根据 3.3.0rc1 的说明首次使用 Rust 内核的用户会从 Hugging Face 下载约 25 MB 的 ONNX embedding 模型缓存在~/.fastembed_cache/目录下。默认模型是all-MiniLM-L6-v2memori/_config.py可通过MEMORI_EMBEDDINGS_MODEL环境变量或config.embeddings.model覆盖。注意 memori/native/_loader.py 的模型名归一化all-minilm-l6-v2会被归一化为None即 Rust 侧使用 fastembed 的默认模型其余名称按字面传给EmbeddingModel解析。4.3 ONNX Runtime 自举含 AndroidRust 扩展依赖 ONNX Runtime 动态库。memori/native/_onnxruntime.py 实现了一套完整的自举逻辑固定版本_ORT_VERSION 1.23.2按(系统, 架构)维护资产清单与 SHA-256 校验和linux/macos/windows/android 全覆盖优先复用已配置的ORT_DYLIB_PATH可用MEMORI_ORT_AUTO_DOWNLOAD0关闭自动下载下载资产缓存在~/.cache/memori/onnxruntime/version/使用跨进程文件锁O_CREAT | O_EXCL避免并发重复下载最多重试 3 次解压前做路径穿越防护_is_within_directory下载后校验 SHA-256不匹配则拒绝使用。Android 支持3.3.2即依赖于此cibuildwheel 目标为android_24_arm64_v8a与android_24_x86_64运行时从 Microsoft 的 Android AAR 中下载并选取匹配 ABI 的libonnxruntime.somemori/native/_onnxruntime.py。4.4 预编译 wheels 矩阵与从源码构建3.3.0rc1 起发布的 wheel 标签为cp310-abi3覆盖Python 3.10 ~ 3.14abi3 稳定 ABImanylinux_2_28_{x86_64,aarch64}、macosx_{x86_64,arm64}、win_amd643.3.2 追加 Androidandroid_24_arm64_v8a、android_24_x86_64。对于不受支持的平台sdist 已包含core/Rust crate可在具备 Rust 工具链的机器上从源码构建rust-toolchain.toml与Makefile位于 core/。rust-core/目录在 3.3.0rc1 中更名为core/但 crate 名engine-orchestrator与 Python 扩展名memori_python均未改变公共导入路径不受影响。五、BYODB 供应TiDB Zero 一键开通3.3.65.1 三层入口3.3.6 新增 TiDB Zero BYODB 供应提供三种等价入口from memori import Memori # 入口一SDK 方法 mem Memori.provision( providertidb-zero, buildTrue, tagmy-agent, )# 入口二CLI 命令 export TIDB_ZERO_API_KEYyour_key python -m memori provision tidb-zero # 也支持 --provider 形式 python -m memori provision --provider tidb-zero# 入口三optional extra 安装 pip install memori[tidb-zero]CLI 用法由 memori/provisioning/_manager.py 解析位置参数或--provider两种形式成功后会打印 Provider、Family、脱敏后的 DSNredact_dsn、Claim URL 与过期时间如存在。5.2 供应实现细节供应器注册在 memori/provisioning/providers/tidb_zero.py通过Registry.register_provider(tidb-zero)装饰器注册注册表机制见 memori/provisioning/_registry.py向https://zero.tidbapi.com/v1beta1/instances发送POST请求请求体仅含{tag: tag}默认memori。认证与端点均可配置配置项来源说明API KeyTIDB_ZERO_API_KEY环境变量或api_key参数以Bearer方式注入 Authorization 头端点 URLMEMORI_TIDB_ZERO_URL环境变量或url参数默认官方端点超时timeout参数默认 30 秒标签tag参数实例标识默认memori响应解析parse_tidb_zero_response要求包含instance.connectionString否则抛出ValueError同时提取claimUrl与expiresAt并剔除密码字段_safe_connection_metadata过滤 key 含 password/pwd 的元数据返回的ProvisionResult带有 MySQL 系列 TLS 连接参数mysql_tls_connect_args()。整个供应流程按 MySQL 家族验证MYSQL_PROVIDERS {tidb-zero}且会调用require_mysql_driver前置检查驱动是否安装memori/provisioning/init.py。5.3 缓存与会话get_provision_result支持缓存cacheTrue默认开启以(provider, tag, cache_key_override)为键命中后直接复用已供应的实例避免重复开通memori/provisioning/init.py。provision_memori最终返回一个已就绪的Memori实例buildTrue时会连带完成连接与记忆管线初始化。六、LLM 对话注入兼容性修复6.1 tool 消息序列修复3.3.2#434这是 3.3 系列最有代表性的真实生产缺陷修复。问题现象recall 出来的历史消息被注入对话后OpenAI 兼容端点返回400: An assistant message with tool_calls must be followed by tool messages responding to each tool_call_id根因在 memori/llm/pipelines/conversation_injection.py 的注释中讲得很清楚conversation_message表只持久化(role, content)tool_calls与tool_call_id字段并不会被保存。于是回放一段使用了工具的历史时会注入两类坏消息原本只有tool_calls的 assistant 消息其tool_calls已丢失content 为空对应的roletool消息其tool_call_id已丢失。修复方式是_sanitize_history_for_openai_compat在注入前清洗丢弃roletool消息、丢弃 content 为空的 assistant 消息、并把 Gemini 时代的rolemodel归一化为roleassistant。OpenAI/Anthropic/Bedrock 三条注入路径均经过此清洗memori/llm/pipelines/conversation_injection.py。同时注入消息计数器改为统计清洗后的数量确保持久化与增强阶段的 payload 不会切进当前用户消息。6.2 多轮对话摄取修复3.3.0rc1#83另一个修复针对 AzureOpenAI/OpenAI 客户端此前只有第一轮对话会被记录原因是conversation_id在请求生命周期中解析过晚。修复后在请求早期解析conversation_id保证同一会话的所有轮次都能正确落库见 CHANGELOG.md。6.3 MCP 项目级归属设置3.3.6#4043.3.6 补充了 MCP 客户端配置指引使用工作区派生值为X-Memori-Entity-Id与X-Memori-Process-Id赋值防止跨项目记忆混淆。仓库文档 docs/memori-cloud/mcp/client-setup.mdx 给出了具体配置X-Memori-Entity-Id: ${workspaceFolderBasename}, X-Memori-Process-Id: ${workspaceFolderBasename}归属语义的要点当每个项目只有一个 agent 且需要项目级隔离记忆时两个头取相同值当多个 agent 共享一个实体、但各自需要隔离的会话历史时X-Memori-Entity-Id保持稳定标识如${env:MEMORI_ENTITY_ID}或user_123X-Memori-Process-Id按工作区/agent/集成变化。这对应 Python SDK 中Memori.attribution(entity_id, process_id)的职责校验非空、≤ 100 字符见 memori/init.py。七、发布工程与可观测性7.1 Rust 内核 CI仓库新增.github/workflows/core-ci.yml在core/**、setup.py、memori/_rust_core.py、tests/test_rust_core.py等路径变更时触发覆盖cargo fmt、clippy、单元测试与跨平台 wheel 构建冒烟cibuildwheel。其环境设定了RUSTFLAGS: -D warnings保证 clippy 告警即失败维持内核代码质量基线。7.2 PyPI 发布流水线改造3.3.0rc1 将 PyPI 发布流水线重写为基于cibuildwheelv3.4.0产出符合 PyPI 规范的 wheel 标签纯 Python 回退仍通过 sdist 提供。此外发布工作流新增两个输入输入作用dry_run发布彩排不触碰索引publish_memorisdk控制是否实际发布 SDK 包这允许维护者在正式发版前做完整的彩排验证。7.3 调试日志改造3.3.0rc1 起增强管线中的 debug payload 日志不再依赖MEMORI_DEBUG_AA_PAYLOAD1的 stdout 输出而是统一走标准logging模块的DEBUG级别。需要排查时对memori._rust_core与engine_orchestrator两个 logger 开启 debug 级别即可import logging logging.basicConfig(levellogging.DEBUG) logging.getLogger(memori._rust_core).setLevel(logging.DEBUG) logging.getLogger(engine_orchestrator).setLevel(logging.DEBUG)同时3.3.6 起 debug 输出还会经过_logging.set_truncate_enabled控制的截断策略debug_truncateTrue默认开启长内容被截断见 memori/_config.py。八、面向未来的输入校验UnreleasedUnreleased 部分预告了Memori.recall(...)的输入校验强化与既有limit校验对齐mem.recall(query123) # 抛 TypeError: query must be a string mem.recall(query ) # 抛 ValueError: query cannot be empty这一改动在 memori/init.py 中已经落地非字符串抛TypeError空或纯空白抛ValueErrorlimit非整数抛TypeError、≤ 0 抛ValueError。其价值在于快速失败fail fast——在发出空查询之前就拦截避免对数据库/LLM 路径发起无意义的空 recall。对于依赖错误类型的下游测试仓库测试目录中的pytest.raises(ValueError/TypeError, match...)模式如 tests/storage/test_connection_factory.py展示了同类校验的断言写法。九、如何在本仓库验证以上结论以下文件路径可供读者按图索骥逐一验证本文所述内容Changelog 全貌CHANGELOG.mdRust 内核开关与配置memori/_config.py、memori/init.py适配器与回调桥接memori/native/_adapter.py扩展加载与模型归一化memori/native/_loader.pyONNX Runtime 自举memori/native/_onnxruntime.py混合检索核心core/src/search/api.rs、core/src/search/lexical.rs原生 embeddercore/src/embeddings/models.rsTiDB Zero 供应memori/provisioning/providers/tidb_zero.py、memori/provisioning/_manager.py对话注入清洗memori/llm/pipelines/conversation_injection.py测试用例tests/test_rust_core.pyRust 内核 CI.github/workflows/core-ci.ymlMCP 归属配置文档docs/memori-cloud/mcp/client-setup.mdx十、小结纵观 3.3 系列Memori Python SDK 的演进路径清晰而克制Rust 原生内核并非一次性替换而是以实验开关 → 默认启用 → 全面巩固的三步节奏逐步落地始终保留use_rust_coreFalse/MEMORI_DISABLE_RUST_CORE1/MEMORI_USE_RUST_CORE0与纯 Python 回退作为逃生通道混合检索通过MEMORI_RECALL_LEX_WEIGHT系列参数提供了可调空间TiDB Zero 供应让 BYODB 上手成本显著降低而 tool 消息序列修复则体现了对上游 LLM 协议严格性的务实适配。对于正在评估或使用 Memori 的开发者理解这一演进路径有助于在 BYODB 场景下正确选择开关组合、调优检索权重并借助仓库内测试用例快速验证行为。【免费下载链接】MemoriMemori is agent-native memory infrastructure. A LLM-agnostic layer that turns agent execution and conversation into structured, persistent state for production systems. Built for enterprise, Memori works with the data infrastructure you already run, no rip-and-replace, and deploys across managed cloud, single-tenant cloud, VPC, and on-premises.项目地址: https://gitcode.com/GitHub_Trending/me/Memori创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考