Oh My Pi 本地记忆引擎 oh-my-pi/pi-mnemopiSQLite 记忆存储、混合召回与 MCP 集成完全指南【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本指南以 Oh My Pi 仓库中的packages/mnemopi包为核心系统讲解其本地 SQLite 记忆引擎的架构、配置与实战用法。oh-my-pi/pi-mnemopi是 Mnemosyne 记忆引擎的 Bun/TypeScript 移植版面向 Agent 场景提供持久化记忆能力读完本文你将掌握Mnemopi门面与BeamMemory引擎的使用、MNEMOPI_*环境变量与构造器选项的完整语义、本地 ONNX 嵌入与 OpenAI 兼容远程嵌入的切换方式以及 CLI 与 MCP 工具集的接入方法。一、包定位一个不依赖本地 LLM 的轻量记忆引擎oh-my-pi/pi-mnemopi在 packages/mnemopi/README.md 中被明确定位为 Local SQLite memory engine for Oh My Pi agentsOh My Pi Agent 的本地 SQLite 记忆引擎由 packages/mnemopi/package.json 中的描述进一步确认description: Local SQLite memory engine for Oh My Pi agents。它提供四类核心能力Mnemopi面向 remember/recall/stats/sleep 工作流的小型门面facadeBeamMemory底层的 working/episodic 记忆引擎承担真正的存储与检索逻辑MCP 工具定义与分发器用于宿主集成可选的本地 ONNX 嵌入通过fastembed与可选的 OpenAI 兼容嵌入/LLM 端点。一个关键边界必须明确该包不捆绑、也不下载本地 GGUF 格式的 LLM。LLM 路径只支持宿主后端或 OpenAI 兼容的远程端点当未配置任何 LLM 时系统自动走确定性启发式路径如规则化的事实抽取与基于词频的摘要不会因缺少大模型而瘫痪。这一点在 packages/mnemopi/src/config.ts 中也有呼应DEFAULT_EMBEDDING_MODEL BAAI/bge-small-en-v1.5嵌入默认完全本地化。从依赖声明看packages/mnemopi/package.jsonfastembed与onnxruntime-node均为可选 peer 依赖peerDependenciesMeta标记为 optional运行时环境需要bun 1.3.14。二、快速上手remember / recall / stats / sleepREADME 给出的最小可用示例即是完整的四条核心工作流先继承原样并补充细节import { Mnemopi } from oh-my-pi/pi-mnemopi; const memory new Mnemopi({ dbPath: ./mnemopi.db, bank: project }); const id memory.remember(The deployment target is stable-cluster., { source: notes, importance: 0.8, veracity: true, }); const results memory.recall(deployment target, 5); console.log(id, results[0]?.content); memory.close();要点解析new Mnemopi({ dbPath, bank })dbPath指定 SQLite 文件位置bank指定记忆库bank名未传时默认为default见 packages/mnemopi/src/core/memory.ts 构造函数this.bank options.bank ?? default。remember(content, options)写入一条记忆。source用于标记来源源码默认conversation见toRememberOptionsimportance为 0.0–1.0 的重要性打分默认 0.5veracity是置信度标签。recall(query, topK)默认取前 5 条topK 5返回带score的RecallResult[]。close()门面拥有数据库句柄时负责关闭若传入外部db对象则不关闭见构造函数中this.#ownsDb options.db undefined的逻辑。veracity的合法取值在 packages/mnemopi/src/types.ts 中定义为stated | inferred | tool | imported | unknown | (string {})而 Beam 层packages/mnemopi/src/core/beam/types.ts进一步扩展到likely_true | true | false | contested等。每种 veracity 都有对应的召回权重stated: 1.0、inferred: 0.7、imported: 0.6、tool: 0.5、unknown: 0.8packages/mnemopi/src/config.ts 的VERACITY_WEIGHT_DEFAULTS并可通过MNEMOPI_STATED_WEIGHT等环境变量覆盖。这意味着你写入记忆时的置信度标注会直接影响后续召回的排序。除了面向对象式调用包还导出了模块级便捷函数同样在 packages/mnemopi/src/core/memory.tsremember(content, opts)、recall(query, topK, opts)、getStats(bank)、get(memoryId, bank)、forget(memoryId, bank)、update(memoryId, content, importance, bank)、sleep(dryRun, bank)、sleepAllSessions(dryRun, bank)等。这些函数通过懒创建的默认实例工作首次调用时按bank参数实例化Mnemopi并缓存defaultFor()逻辑setBank(name)可切换默认 bank。三、配置详解构造器选项与 MNEMOPI_* 环境变量Mnemopi构造器直接接受 LLM 与嵌入相关选项当构造器选项缺省时MNEMOPI_*环境变量作为回退默认值生效。README 的配置示例完整继承如下import { Mnemopi } from oh-my-pi/pi-mnemopi; import type { Model } from oh-my-pi/pi-ai; // 1. 纯 FTS 模式完全禁用嵌入 const ftsOnly new Mnemopi({ noEmbeddings: true }); // 2. 远程嵌入OpenAI 兼容端点 const remoteEmbeddings new Mnemopi({ embeddingModel: text-embedding-3-small, embeddingApiUrl: https://api.openai.com/v1, embeddingApiKey: process.env.OPENAI_API_KEY, }); // 3. 远程 LLMOpenAI 兼容端点 const remoteLlm new Mnemopi({ llm: { baseUrl: https://api.openai.com/v1, apiKey: process.env.OPENAI_API_KEY, model: gpt-4.1-mini, }, // Equivalent aliases: llmBaseUrl, llmApiKey, llmModel. }); // 4. 直接注入 pi-ai 的 Model 对象 declare const smolModel: Model; const piAiLlm new Mnemopi({ llm: smolModel }); // 5. 动态 LLM函数形式的完成器可做 OAuth 令牌刷新等 const dynamicLlm new Mnemopi({ llm: async (prompt, opts) { const token await getFreshOauthToken(); return await completeWithPiAi(prompt, { token, maxTokens: opts?.maxTokens, temperature: opts?.temperature, }); }, });从源码看resolveRuntimeOptionspackages/mnemopi/src/core/memory.tsllm选项支持四种形态并被逐一归一化false显式禁用 LLM函数MnemopiLlmCompletion作为complete回调宿主可在此注入动态令牌或自定义调用ModelApipi-ai 的模型对象通过isPiAiModel判定后直接透传普通配置对象{ baseUrl, apiKey, model, maxTokens, ... }等价别名llmBaseUrl/llmApiKey/llmModel同样被支持。嵌入侧同样存在组合优先级embeddings: false或noEmbeddings: true都会关闭嵌入embeddingModel/embeddingApiUrl/embeddingApiKey可平铺传入也可放进embeddings: { model, apiUrl, apiKey, provider, maxInputChars }嵌套对象。3.1 Banks 与宿主作用域scopingMnemopi自身只通过构造器选项如bank暴露 bank 概念并不硬编码 coding-agent 的项目作用域。Oh My Pi 的 coding-agent 包装层在其之上叠加mnemopi.scoping配置提供三种模式global所有项目共享一个 bankper-project每个项目隔离独立的记忆库per-project-tagged项目本地写入 全局召回可见。其中per-project-tagged模式下包装层负责组合项目本地留存 全局召回可见性包本身仍只暴露 banks 与构造器级的 LLM/嵌入选项。这种设计让底层引擎保持通用把作用域策略留给宿主决定。3.2 常用环境变量回退完整清单README 列出并在源码 packages/mnemopi/src/config.ts 中确认的环境变量环境变量含义默认值/取值MNEMOPI_DATA_DIR/MNEMOPI_DB_PATH默认存储位置~/.hermes/mnemopi/data与其中的mnemopi.dbDEFAULT_DATA_DIR/DEFAULT_DB_FILENAMEMNEMOPI_DB_PAGE_SIZE新建文件型数据库的 SQLite 页大小512–65536 之间的 2 的幂或os请求检测到的系统页大小不设置则保留 SQLite 默认值MNEMOPI_NO_EMBEDDINGS1强制纯 FTS 召回置为非空即生效embeddingsDisabled判定MNEMOPI_EMBEDDING_MODEL嵌入模型名默认BAAI/bge-small-en-v1.5MNEMOPI_EMBEDDING_API_URL/MNEMOPI_EMBEDDING_API_KEYOpenAI 兼容嵌入端点API URL 默认https://openrouter.ai/api/v1key 依次回退OPENROUTER_API_KEY、OPENAI_API_KEYMNEMOPI_LLM_ENABLED1/MNEMOPI_LLM_BASE_URL/MNEMOPI_LLM_API_KEY/MNEMOPI_LLM_MODELOpenAI 兼容 LLM 端点llmEnabled默认true其余默认空MNEMOPI_EMBEDDING_MAX_INPUT_CHARS单条嵌入输入的最大字符数默认 81920表示不限制MNEMOPI_EMBEDDING_DIM覆盖嵌入维度缺省时按模型查表见EMBEDDING_DIMS3.3 召回打分权重进阶调参从源码 packages/mnemopi/src/config.ts 可以看到召回是多路特征加权MNEMOPI_VEC_WEIGHT默认 0.5向量相似度权重MNEMOPI_FTS_WEIGHT默认 0.3全文检索权重MNEMOPI_IMPORTANCE_WEIGHT默认 0.2重要性权重。三者经normalizedRecallWeights()归一化和为 1若三者全为 0 则回退到 0.5/0.3/0.2。此外还有时间维度MNEMOPI_RECENCY_HALFLIFE默认 168 小时控制近因衰减MNEMOPI_TEMPORAL_HALFLIFE_HOURS默认 24 小时控制时间相关性衰减。RecallResultpackages/mnemopi/src/types.ts中同时携带score、vec_score、fts_score、importance_score、recency_score、temporal_score等分项分数便于排查每次命中的来源构成。四、嵌入Embeddings机制本地 ONNX、远程 API 与优雅降级packages/mnemopi的嵌入管线集中在 packages/mnemopi/src/core/embeddings.tsembed()的解析顺序为显式注入的 providerwithMnemopiRuntimeOptions作用域内的embeddings.provider测试/宿主覆盖的 providerproviderOverrideAPI 模型模型名以openai/开头、包含text-embedding或MNEMOPI_EMBEDDINGS_VIA_API1时→ 走POST {baseUrl}/embeddings内置 401 令牌刷新、429 退避重试fetchWithRetry最多 3 次尝试、指数退避2**attempt * 1000ms与 30 秒超时本地 fastembedFlagEmbedding.initONNX 运行时。4.1 本地 fastembed 的模型与缓存README 明确说明本地嵌入使用fastembednpm 包其默认BGESmallENV15模型为384 维并采用该包的 CLS pooling 加向量归一化路径。源码 packages/mnemopi/src/config.ts 维护了一张模型→维度对照表EMBEDDING_DIMSBAAI/bge-small-en-v1.5→ 384BAAI/bge-base-en-v1.5→ 768BAAI/bge-large-en-v1.5→ 1024中文系BAAI/bge-small-zh-v1.5→ 512、bge-base-zh-v1.5→ 768、bge-large-zh-v1.5→ 1024多语言intfloat/multilingual-e5-small/base/large→ 384/768/1024BAAI/bge-m3→ 1024BAAI/bge-multilingual-gemma2→ 3584OpenAItext-embedding-3-small→ 1536、text-embedding-3-large→ 3072。本地模型缓存目录默认位于~/.hermes/cache/fastembedFASTEMBED_CACHE_DIR。源码还内置了两类缓存自愈逻辑值得在运维层面知晓损坏模型隔离quarantineCorruptModelFile当初始化报 Protobuf parsing failed 且错误中提到的.onnx文件确实位于缓存根目录内时将该文件原子改名为.corrupt-ts并重试初始化避免截断的模型文件永久阻塞本地嵌入不完整缓存清理clearIncompleteModelCache当模型目录缺少 graph 文件model.onnx而报 Model file not found 时删除不完整目录与残留的.tar.gz分卷强制重新下载。这两处均有对应测试corrupt-model-quarantine.test.ts、truncated-model-cache-recovery.test.ts等。4.2 输入截断策略head/tail 双侧保留长会话留存的完整多轮文本经常超出嵌入模型的上下文窗口BGE/E5 默认 512 tokenbge-m3 与 OpenAI text-embedding-3 为 8192llama.cpp/embeddings服务会直接拒绝超长请求OpenAI 则静默右截断。为此embed()会先经过capInputs()超过MNEMOPI_EMBEDDING_MAX_INPUT_CHARS默认 8192 字符0禁用的输入被clipToWindow()处理——保留头部话题铺垫与尾部最新对话语义最密集中间以\n\n[...]\n\n省略标记连接从而让向量同时捕捉开场话题与收尾内容避免所有长会话退化成近乎相同的前缀向量。4.3 查询向量缓存与退化路径embedQuery()使用容量 512 的 LRU 缓存queryCache缓存键由provider 身份 模型名 API base URL 文本共同构成queryCacheKey()因此同一进程内指向不同 provider/模型的多个Mnemopi实例不会互相污染缓存。当嵌入完全不可用如本地模型加载失败、API 未配置时embed()返回null召回自动降级为 FTS 重要性 近因的启发式排序——这正是noEmbeddings: true模式下同样可用的原因。五、CLI 命令mnemopi 可执行文件package.json将mnemopi暴露为 binbin: { mnemopi: src/cli.ts }。README 给出四条核心命令mnemopi remember Use stable-cluster for production deploys mnemopi recall production deploy target mnemopi stats mnemopi sleep实际 CLIpackages/mnemopi/src/cli.ts支持的完整命令集比 README 更丰富COMMANDS注册表如下命令别名说明store content [source] [importance]remember存储一条记忆默认 sourcecli、importance0.5并开启实体抽取extractEntities: truerecall query [top_k]search混合打分召回默认 top_k5逐条输出 ID、内容前 150 字符与 scoreupdate id content [importance]edit更新记忆内容与重要性delete idforget删除指定记忆stats—汇总 working/episodic/triples 数量、banks 与 DB 路径export file.json—导出 working/episodic/scratchpad/consolidation 为 JSONimport file.json—从导出 JSON 导入报告 inserted/skipped/overwritten 统计sleepconsolidate对所有会话执行 consolidate内部为sleepAllSessions(false)scratchpad read\|write\|clear [content]sp管理临时草稿区bank list\|create\|delete [name]—管理记忆库diagnosedoctor对数据库运行 PII 安全的诊断检查runDiagnostics全部通过返回 0mcp [args]—启动 MCP 服务器一个值得注意的实现细节CLI 的短生命周期命令store/sleep/import在关闭数据库前会先memory.flushExtractions()见withMemory()确保后台事实抽取与嵌入写入先于句柄关闭落盘避免静默丢失密集召回行。六、MCP 集成23 个工具定义与分发器packages/mnemopi提供完整的 MCP 工具定义与分发器packages/mnemopi/src/mcp-tools.ts服务端入口为 packages/mnemopi/src/mcp-server.ts。工具集覆盖记忆生命周期的全部操作写入/检索mnemopi_remember支持content、importance0.0–1.0、source、scopesession/global/channel/自定义、valid_until过期时间、extract_entities实体抽取、extract结构化事实抽取、metadata、veracity、author_id/author_type/channel_id、bank、mnemopi_recallquery、top_k/limit、temporal_weight、query_time、temporal_halflife、vec_weight/fts_weight/importance_weight、作者/频道过滤、mnemopi_get、mnemopi_update、mnemopi_forget、mnemopi_invalidate标记过期/被取代可带replacement_id共享表面记忆mnemopi_shared_rememberkind 限定为meta | preference | correction | identity写入独立 shared DB、mnemopi_shared_recall、mnemopi_shared_forget、mnemopi_shared_stats事实三元组mnemopi_triple_addsubject/predicate/object附valid_from、source、confidence、mnemopi_triple_query支持按 subject/predicate/object 过滤与as_of时间点查询生命周期与治理mnemopi_sleepdry_run预演、all_sessions全量合并、mnemopi_stats、mnemopi_validate对记忆执行 attest/update/invalidate/delete 四种验证动作、mnemopi_diagnose草稿与图mnemopi_scratchpad_write/read/clear、mnemopi_graph_query从种子记忆按max_hops、edge_type、min_weight遍历记忆图、mnemopi_graph_link声明两条记忆间的语义边weight默认 0.5迁移mnemopi_export/mnemopi_import导入时会把行重定向到目标 bank 的 session/channel 上下文避免跨库串扰。所有工具均接受bank参数回退到MNEMOPI_MCP_BANK环境变量再回退default并在每次调用结束时flushExtractions()再关闭句柄。宿主可通过handleToolCall(name, args)分发调用、getToolDefinitions()获取 schema 列表。七、BeamMemory 引擎内部working / episodic / sleep 机制BeamMemorypackages/mnemopi/src/core/beam/index.ts是真正承载存储与检索的引擎。其DEFAULT_CONFIG给出引擎级默认值配置项默认值说明workingMemoryLimit1000工作记忆条数上限workingMemoryTtlHours24工作记忆 TTL小时recencyHalflifeHours72近因衰减半衰期vecWeight/ftsWeight/importanceWeight0.5 / 0.3 / 0.2召回三路权重maxEpisodeChars100_000单条情景记忆最大字符数引擎按两级记忆组织MemoryRow相关字段见 packages/mnemopi/src/types.tsworking memory工作记忆当前会话的高频短期记忆带importance、recall_count、last_recalled、valid_until、superseded_by等字段用于支持主动淘汰与取代episodic memory情景记忆由sleep流程将工作记忆合并consolidate而来带summary_of、tier层级、degraded_at、event_date、episode_type字段并通过degradeEpisodic()按层级MNEMOPI_TIER2_DAYS30 天、MNEMOPI_TIER3_DAYS180 天权重 1.0/0.5/0.25逐步降级压缩。sleep(dryRun)/sleepAllSessions(dryRun)是合并入口dryRuntrue仅预演不落盘同时支持consolidateToEpisodic(summary, sourceWmIds, ...)手动将若干工作记忆汇总为一条情景记忆。remember(..., { extract: true })会触发后台事实抽取extractAndStoreFacts抽取结果落入三元组表triples与注解表annotations抽取任务由pendingExtractions集合跟踪flushExtractions()确保落盘。引擎还提供memoriaRetrieve()、factRecall()、getContaminated()污染记忆排查、health()健康检查默认 24 小时陈旧阈值与exportToDict()/importFromDict()迁移用。引擎默认启用MNEMOPI_AUTO_MIGRATE1packages/mnemopi/src/config.ts打开数据库时会自动执行注解/三元组分拆迁移e6-triplestore-split见 packages/mnemopi/src/core/migrations/e6-triplestore-split.ts迁移前自动备份设MNEMOPI_AUTO_MIGRATE0可关闭并保留待迁移数据。八、验证与测试仓库为packages/mnemopi准备了完整测试套件运行方式继承 READMEbun --cwd packages/mnemopi test bun --cwd packages/mnemopi run checktest脚本为bun test --parallelcheck脚本为oxlint . oxfmt --check ... tsgo -p tsconfig.json --noEmit见 packages/mnemopi/package.json。packages/mnemopi/test/下的测试覆盖了本文涉及的核心机制嵌入与向量optional-embeddings.test.ts无嵌入降级、degrade-vector.test.ts、embeddings-multilingual.test.ts、native-vector-parity.test.ts、fastembed-runtime.test.ts、fastembed-model-cache.test.ts、corrupt-model-quarantine.test.ts、embedding-input-cap.test.ts、db-page-size.test.ts页大小配置Beam 引擎beam-store.test.ts、beam-recall-unit.test.ts、beam-consolidate-unit.test.ts、beam-e3-e4-e6.test.ts、memory-banks.test.tsbank 隔离门面与召回memory-facade.test.ts、temporal-recall.test.ts、polyphonic-recall.test.ts、veracity-consolidation.test.ts、query-cache-synonyms.test.ts、weibull-mmr-intent.test.tsCLI 与 MCPcli.test.ts、cli-stats-parity.test.ts、mcp-server.test.ts、provider-all-15-tools.test.ts迁移与恢复migrate-triplestore-split.test.ts、recovery.test.ts、truncated-model-cache-recovery.test.ts。若你的宿主是 Oh My Pi 的 coding-agent还可参考仓库docs/目录下的记忆相关文档如 docs/mnemosyne-memory-backend.md、docs/memory.md了解其与整体 Agent 体系的衔接方式。九、适用边界与前提运行环境需要 Bunengines.bun 1.3.14本地嵌入还需可选安装fastembed2.1.0与onnxruntime-node1.21.0。LLM 边界包内不提供本地 GGUF 推理LLM 仅走宿主后端或 OpenAI 兼容远程端点未配置时自动使用确定性启发式路径功能不中断但抽取/摘要质量受限。数据位置默认存储位于~/.hermes/mnemopi/data/mnemopi.db可通过MNEMOPI_DATA_DIR/MNEMOPI_DB_PATH重定向bank 数据按.../banks/name/目录组织BankManager。召回质量向量召回依赖嵌入可用性纯 FTS 模式noEmbeddings下召回依赖全文检索与重要性/近因权重长文本的嵌入截断策略默认 8192 字符可按需调高例如 Qwen3-Embedding 的 32k 上下文场景。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Oh My Pi 本地记忆引擎 @oh-my-pi/pi-mnemopi：SQLite 记忆存储、混合召回与 MCP 集成完全指南
Oh My Pi 本地记忆引擎 oh-my-pi/pi-mnemopiSQLite 记忆存储、混合召回与 MCP 集成完全指南【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本指南以 Oh My Pi 仓库中的packages/mnemopi包为核心系统讲解其本地 SQLite 记忆引擎的架构、配置与实战用法。oh-my-pi/pi-mnemopi是 Mnemosyne 记忆引擎的 Bun/TypeScript 移植版面向 Agent 场景提供持久化记忆能力读完本文你将掌握Mnemopi门面与BeamMemory引擎的使用、MNEMOPI_*环境变量与构造器选项的完整语义、本地 ONNX 嵌入与 OpenAI 兼容远程嵌入的切换方式以及 CLI 与 MCP 工具集的接入方法。一、包定位一个不依赖本地 LLM 的轻量记忆引擎oh-my-pi/pi-mnemopi在 packages/mnemopi/README.md 中被明确定位为 Local SQLite memory engine for Oh My Pi agentsOh My Pi Agent 的本地 SQLite 记忆引擎由 packages/mnemopi/package.json 中的描述进一步确认description: Local SQLite memory engine for Oh My Pi agents。它提供四类核心能力Mnemopi面向 remember/recall/stats/sleep 工作流的小型门面facadeBeamMemory底层的 working/episodic 记忆引擎承担真正的存储与检索逻辑MCP 工具定义与分发器用于宿主集成可选的本地 ONNX 嵌入通过fastembed与可选的 OpenAI 兼容嵌入/LLM 端点。一个关键边界必须明确该包不捆绑、也不下载本地 GGUF 格式的 LLM。LLM 路径只支持宿主后端或 OpenAI 兼容的远程端点当未配置任何 LLM 时系统自动走确定性启发式路径如规则化的事实抽取与基于词频的摘要不会因缺少大模型而瘫痪。这一点在 packages/mnemopi/src/config.ts 中也有呼应DEFAULT_EMBEDDING_MODEL BAAI/bge-small-en-v1.5嵌入默认完全本地化。从依赖声明看packages/mnemopi/package.jsonfastembed与onnxruntime-node均为可选 peer 依赖peerDependenciesMeta标记为 optional运行时环境需要bun 1.3.14。二、快速上手remember / recall / stats / sleepREADME 给出的最小可用示例即是完整的四条核心工作流先继承原样并补充细节import { Mnemopi } from oh-my-pi/pi-mnemopi; const memory new Mnemopi({ dbPath: ./mnemopi.db, bank: project }); const id memory.remember(The deployment target is stable-cluster., { source: notes, importance: 0.8, veracity: true, }); const results memory.recall(deployment target, 5); console.log(id, results[0]?.content); memory.close();要点解析new Mnemopi({ dbPath, bank })dbPath指定 SQLite 文件位置bank指定记忆库bank名未传时默认为default见 packages/mnemopi/src/core/memory.ts 构造函数this.bank options.bank ?? default。remember(content, options)写入一条记忆。source用于标记来源源码默认conversation见toRememberOptionsimportance为 0.0–1.0 的重要性打分默认 0.5veracity是置信度标签。recall(query, topK)默认取前 5 条topK 5返回带score的RecallResult[]。close()门面拥有数据库句柄时负责关闭若传入外部db对象则不关闭见构造函数中this.#ownsDb options.db undefined的逻辑。veracity的合法取值在 packages/mnemopi/src/types.ts 中定义为stated | inferred | tool | imported | unknown | (string {})而 Beam 层packages/mnemopi/src/core/beam/types.ts进一步扩展到likely_true | true | false | contested等。每种 veracity 都有对应的召回权重stated: 1.0、inferred: 0.7、imported: 0.6、tool: 0.5、unknown: 0.8packages/mnemopi/src/config.ts 的VERACITY_WEIGHT_DEFAULTS并可通过MNEMOPI_STATED_WEIGHT等环境变量覆盖。这意味着你写入记忆时的置信度标注会直接影响后续召回的排序。除了面向对象式调用包还导出了模块级便捷函数同样在 packages/mnemopi/src/core/memory.tsremember(content, opts)、recall(query, topK, opts)、getStats(bank)、get(memoryId, bank)、forget(memoryId, bank)、update(memoryId, content, importance, bank)、sleep(dryRun, bank)、sleepAllSessions(dryRun, bank)等。这些函数通过懒创建的默认实例工作首次调用时按bank参数实例化Mnemopi并缓存defaultFor()逻辑setBank(name)可切换默认 bank。三、配置详解构造器选项与 MNEMOPI_* 环境变量Mnemopi构造器直接接受 LLM 与嵌入相关选项当构造器选项缺省时MNEMOPI_*环境变量作为回退默认值生效。README 的配置示例完整继承如下import { Mnemopi } from oh-my-pi/pi-mnemopi; import type { Model } from oh-my-pi/pi-ai; // 1. 纯 FTS 模式完全禁用嵌入 const ftsOnly new Mnemopi({ noEmbeddings: true }); // 2. 远程嵌入OpenAI 兼容端点 const remoteEmbeddings new Mnemopi({ embeddingModel: text-embedding-3-small, embeddingApiUrl: https://api.openai.com/v1, embeddingApiKey: process.env.OPENAI_API_KEY, }); // 3. 远程 LLMOpenAI 兼容端点 const remoteLlm new Mnemopi({ llm: { baseUrl: https://api.openai.com/v1, apiKey: process.env.OPENAI_API_KEY, model: gpt-4.1-mini, }, // Equivalent aliases: llmBaseUrl, llmApiKey, llmModel. }); // 4. 直接注入 pi-ai 的 Model 对象 declare const smolModel: Model; const piAiLlm new Mnemopi({ llm: smolModel }); // 5. 动态 LLM函数形式的完成器可做 OAuth 令牌刷新等 const dynamicLlm new Mnemopi({ llm: async (prompt, opts) { const token await getFreshOauthToken(); return await completeWithPiAi(prompt, { token, maxTokens: opts?.maxTokens, temperature: opts?.temperature, }); }, });从源码看resolveRuntimeOptionspackages/mnemopi/src/core/memory.tsllm选项支持四种形态并被逐一归一化false显式禁用 LLM函数MnemopiLlmCompletion作为complete回调宿主可在此注入动态令牌或自定义调用ModelApipi-ai 的模型对象通过isPiAiModel判定后直接透传普通配置对象{ baseUrl, apiKey, model, maxTokens, ... }等价别名llmBaseUrl/llmApiKey/llmModel同样被支持。嵌入侧同样存在组合优先级embeddings: false或noEmbeddings: true都会关闭嵌入embeddingModel/embeddingApiUrl/embeddingApiKey可平铺传入也可放进embeddings: { model, apiUrl, apiKey, provider, maxInputChars }嵌套对象。3.1 Banks 与宿主作用域scopingMnemopi自身只通过构造器选项如bank暴露 bank 概念并不硬编码 coding-agent 的项目作用域。Oh My Pi 的 coding-agent 包装层在其之上叠加mnemopi.scoping配置提供三种模式global所有项目共享一个 bankper-project每个项目隔离独立的记忆库per-project-tagged项目本地写入 全局召回可见。其中per-project-tagged模式下包装层负责组合项目本地留存 全局召回可见性包本身仍只暴露 banks 与构造器级的 LLM/嵌入选项。这种设计让底层引擎保持通用把作用域策略留给宿主决定。3.2 常用环境变量回退完整清单README 列出并在源码 packages/mnemopi/src/config.ts 中确认的环境变量环境变量含义默认值/取值MNEMOPI_DATA_DIR/MNEMOPI_DB_PATH默认存储位置~/.hermes/mnemopi/data与其中的mnemopi.dbDEFAULT_DATA_DIR/DEFAULT_DB_FILENAMEMNEMOPI_DB_PAGE_SIZE新建文件型数据库的 SQLite 页大小512–65536 之间的 2 的幂或os请求检测到的系统页大小不设置则保留 SQLite 默认值MNEMOPI_NO_EMBEDDINGS1强制纯 FTS 召回置为非空即生效embeddingsDisabled判定MNEMOPI_EMBEDDING_MODEL嵌入模型名默认BAAI/bge-small-en-v1.5MNEMOPI_EMBEDDING_API_URL/MNEMOPI_EMBEDDING_API_KEYOpenAI 兼容嵌入端点API URL 默认https://openrouter.ai/api/v1key 依次回退OPENROUTER_API_KEY、OPENAI_API_KEYMNEMOPI_LLM_ENABLED1/MNEMOPI_LLM_BASE_URL/MNEMOPI_LLM_API_KEY/MNEMOPI_LLM_MODELOpenAI 兼容 LLM 端点llmEnabled默认true其余默认空MNEMOPI_EMBEDDING_MAX_INPUT_CHARS单条嵌入输入的最大字符数默认 81920表示不限制MNEMOPI_EMBEDDING_DIM覆盖嵌入维度缺省时按模型查表见EMBEDDING_DIMS3.3 召回打分权重进阶调参从源码 packages/mnemopi/src/config.ts 可以看到召回是多路特征加权MNEMOPI_VEC_WEIGHT默认 0.5向量相似度权重MNEMOPI_FTS_WEIGHT默认 0.3全文检索权重MNEMOPI_IMPORTANCE_WEIGHT默认 0.2重要性权重。三者经normalizedRecallWeights()归一化和为 1若三者全为 0 则回退到 0.5/0.3/0.2。此外还有时间维度MNEMOPI_RECENCY_HALFLIFE默认 168 小时控制近因衰减MNEMOPI_TEMPORAL_HALFLIFE_HOURS默认 24 小时控制时间相关性衰减。RecallResultpackages/mnemopi/src/types.ts中同时携带score、vec_score、fts_score、importance_score、recency_score、temporal_score等分项分数便于排查每次命中的来源构成。四、嵌入Embeddings机制本地 ONNX、远程 API 与优雅降级packages/mnemopi的嵌入管线集中在 packages/mnemopi/src/core/embeddings.tsembed()的解析顺序为显式注入的 providerwithMnemopiRuntimeOptions作用域内的embeddings.provider测试/宿主覆盖的 providerproviderOverrideAPI 模型模型名以openai/开头、包含text-embedding或MNEMOPI_EMBEDDINGS_VIA_API1时→ 走POST {baseUrl}/embeddings内置 401 令牌刷新、429 退避重试fetchWithRetry最多 3 次尝试、指数退避2**attempt * 1000ms与 30 秒超时本地 fastembedFlagEmbedding.initONNX 运行时。4.1 本地 fastembed 的模型与缓存README 明确说明本地嵌入使用fastembednpm 包其默认BGESmallENV15模型为384 维并采用该包的 CLS pooling 加向量归一化路径。源码 packages/mnemopi/src/config.ts 维护了一张模型→维度对照表EMBEDDING_DIMSBAAI/bge-small-en-v1.5→ 384BAAI/bge-base-en-v1.5→ 768BAAI/bge-large-en-v1.5→ 1024中文系BAAI/bge-small-zh-v1.5→ 512、bge-base-zh-v1.5→ 768、bge-large-zh-v1.5→ 1024多语言intfloat/multilingual-e5-small/base/large→ 384/768/1024BAAI/bge-m3→ 1024BAAI/bge-multilingual-gemma2→ 3584OpenAItext-embedding-3-small→ 1536、text-embedding-3-large→ 3072。本地模型缓存目录默认位于~/.hermes/cache/fastembedFASTEMBED_CACHE_DIR。源码还内置了两类缓存自愈逻辑值得在运维层面知晓损坏模型隔离quarantineCorruptModelFile当初始化报 Protobuf parsing failed 且错误中提到的.onnx文件确实位于缓存根目录内时将该文件原子改名为.corrupt-ts并重试初始化避免截断的模型文件永久阻塞本地嵌入不完整缓存清理clearIncompleteModelCache当模型目录缺少 graph 文件model.onnx而报 Model file not found 时删除不完整目录与残留的.tar.gz分卷强制重新下载。这两处均有对应测试corrupt-model-quarantine.test.ts、truncated-model-cache-recovery.test.ts等。4.2 输入截断策略head/tail 双侧保留长会话留存的完整多轮文本经常超出嵌入模型的上下文窗口BGE/E5 默认 512 tokenbge-m3 与 OpenAI text-embedding-3 为 8192llama.cpp/embeddings服务会直接拒绝超长请求OpenAI 则静默右截断。为此embed()会先经过capInputs()超过MNEMOPI_EMBEDDING_MAX_INPUT_CHARS默认 8192 字符0禁用的输入被clipToWindow()处理——保留头部话题铺垫与尾部最新对话语义最密集中间以\n\n[...]\n\n省略标记连接从而让向量同时捕捉开场话题与收尾内容避免所有长会话退化成近乎相同的前缀向量。4.3 查询向量缓存与退化路径embedQuery()使用容量 512 的 LRU 缓存queryCache缓存键由provider 身份 模型名 API base URL 文本共同构成queryCacheKey()因此同一进程内指向不同 provider/模型的多个Mnemopi实例不会互相污染缓存。当嵌入完全不可用如本地模型加载失败、API 未配置时embed()返回null召回自动降级为 FTS 重要性 近因的启发式排序——这正是noEmbeddings: true模式下同样可用的原因。五、CLI 命令mnemopi 可执行文件package.json将mnemopi暴露为 binbin: { mnemopi: src/cli.ts }。README 给出四条核心命令mnemopi remember Use stable-cluster for production deploys mnemopi recall production deploy target mnemopi stats mnemopi sleep实际 CLIpackages/mnemopi/src/cli.ts支持的完整命令集比 README 更丰富COMMANDS注册表如下命令别名说明store content [source] [importance]remember存储一条记忆默认 sourcecli、importance0.5并开启实体抽取extractEntities: truerecall query [top_k]search混合打分召回默认 top_k5逐条输出 ID、内容前 150 字符与 scoreupdate id content [importance]edit更新记忆内容与重要性delete idforget删除指定记忆stats—汇总 working/episodic/triples 数量、banks 与 DB 路径export file.json—导出 working/episodic/scratchpad/consolidation 为 JSONimport file.json—从导出 JSON 导入报告 inserted/skipped/overwritten 统计sleepconsolidate对所有会话执行 consolidate内部为sleepAllSessions(false)scratchpad read\|write\|clear [content]sp管理临时草稿区bank list\|create\|delete [name]—管理记忆库diagnosedoctor对数据库运行 PII 安全的诊断检查runDiagnostics全部通过返回 0mcp [args]—启动 MCP 服务器一个值得注意的实现细节CLI 的短生命周期命令store/sleep/import在关闭数据库前会先memory.flushExtractions()见withMemory()确保后台事实抽取与嵌入写入先于句柄关闭落盘避免静默丢失密集召回行。六、MCP 集成23 个工具定义与分发器packages/mnemopi提供完整的 MCP 工具定义与分发器packages/mnemopi/src/mcp-tools.ts服务端入口为 packages/mnemopi/src/mcp-server.ts。工具集覆盖记忆生命周期的全部操作写入/检索mnemopi_remember支持content、importance0.0–1.0、source、scopesession/global/channel/自定义、valid_until过期时间、extract_entities实体抽取、extract结构化事实抽取、metadata、veracity、author_id/author_type/channel_id、bank、mnemopi_recallquery、top_k/limit、temporal_weight、query_time、temporal_halflife、vec_weight/fts_weight/importance_weight、作者/频道过滤、mnemopi_get、mnemopi_update、mnemopi_forget、mnemopi_invalidate标记过期/被取代可带replacement_id共享表面记忆mnemopi_shared_rememberkind 限定为meta | preference | correction | identity写入独立 shared DB、mnemopi_shared_recall、mnemopi_shared_forget、mnemopi_shared_stats事实三元组mnemopi_triple_addsubject/predicate/object附valid_from、source、confidence、mnemopi_triple_query支持按 subject/predicate/object 过滤与as_of时间点查询生命周期与治理mnemopi_sleepdry_run预演、all_sessions全量合并、mnemopi_stats、mnemopi_validate对记忆执行 attest/update/invalidate/delete 四种验证动作、mnemopi_diagnose草稿与图mnemopi_scratchpad_write/read/clear、mnemopi_graph_query从种子记忆按max_hops、edge_type、min_weight遍历记忆图、mnemopi_graph_link声明两条记忆间的语义边weight默认 0.5迁移mnemopi_export/mnemopi_import导入时会把行重定向到目标 bank 的 session/channel 上下文避免跨库串扰。所有工具均接受bank参数回退到MNEMOPI_MCP_BANK环境变量再回退default并在每次调用结束时flushExtractions()再关闭句柄。宿主可通过handleToolCall(name, args)分发调用、getToolDefinitions()获取 schema 列表。七、BeamMemory 引擎内部working / episodic / sleep 机制BeamMemorypackages/mnemopi/src/core/beam/index.ts是真正承载存储与检索的引擎。其DEFAULT_CONFIG给出引擎级默认值配置项默认值说明workingMemoryLimit1000工作记忆条数上限workingMemoryTtlHours24工作记忆 TTL小时recencyHalflifeHours72近因衰减半衰期vecWeight/ftsWeight/importanceWeight0.5 / 0.3 / 0.2召回三路权重maxEpisodeChars100_000单条情景记忆最大字符数引擎按两级记忆组织MemoryRow相关字段见 packages/mnemopi/src/types.tsworking memory工作记忆当前会话的高频短期记忆带importance、recall_count、last_recalled、valid_until、superseded_by等字段用于支持主动淘汰与取代episodic memory情景记忆由sleep流程将工作记忆合并consolidate而来带summary_of、tier层级、degraded_at、event_date、episode_type字段并通过degradeEpisodic()按层级MNEMOPI_TIER2_DAYS30 天、MNEMOPI_TIER3_DAYS180 天权重 1.0/0.5/0.25逐步降级压缩。sleep(dryRun)/sleepAllSessions(dryRun)是合并入口dryRuntrue仅预演不落盘同时支持consolidateToEpisodic(summary, sourceWmIds, ...)手动将若干工作记忆汇总为一条情景记忆。remember(..., { extract: true })会触发后台事实抽取extractAndStoreFacts抽取结果落入三元组表triples与注解表annotations抽取任务由pendingExtractions集合跟踪flushExtractions()确保落盘。引擎还提供memoriaRetrieve()、factRecall()、getContaminated()污染记忆排查、health()健康检查默认 24 小时陈旧阈值与exportToDict()/importFromDict()迁移用。引擎默认启用MNEMOPI_AUTO_MIGRATE1packages/mnemopi/src/config.ts打开数据库时会自动执行注解/三元组分拆迁移e6-triplestore-split见 packages/mnemopi/src/core/migrations/e6-triplestore-split.ts迁移前自动备份设MNEMOPI_AUTO_MIGRATE0可关闭并保留待迁移数据。八、验证与测试仓库为packages/mnemopi准备了完整测试套件运行方式继承 READMEbun --cwd packages/mnemopi test bun --cwd packages/mnemopi run checktest脚本为bun test --parallelcheck脚本为oxlint . oxfmt --check ... tsgo -p tsconfig.json --noEmit见 packages/mnemopi/package.json。packages/mnemopi/test/下的测试覆盖了本文涉及的核心机制嵌入与向量optional-embeddings.test.ts无嵌入降级、degrade-vector.test.ts、embeddings-multilingual.test.ts、native-vector-parity.test.ts、fastembed-runtime.test.ts、fastembed-model-cache.test.ts、corrupt-model-quarantine.test.ts、embedding-input-cap.test.ts、db-page-size.test.ts页大小配置Beam 引擎beam-store.test.ts、beam-recall-unit.test.ts、beam-consolidate-unit.test.ts、beam-e3-e4-e6.test.ts、memory-banks.test.tsbank 隔离门面与召回memory-facade.test.ts、temporal-recall.test.ts、polyphonic-recall.test.ts、veracity-consolidation.test.ts、query-cache-synonyms.test.ts、weibull-mmr-intent.test.tsCLI 与 MCPcli.test.ts、cli-stats-parity.test.ts、mcp-server.test.ts、provider-all-15-tools.test.ts迁移与恢复migrate-triplestore-split.test.ts、recovery.test.ts、truncated-model-cache-recovery.test.ts。若你的宿主是 Oh My Pi 的 coding-agent还可参考仓库docs/目录下的记忆相关文档如 docs/mnemosyne-memory-backend.md、docs/memory.md了解其与整体 Agent 体系的衔接方式。九、适用边界与前提运行环境需要 Bunengines.bun 1.3.14本地嵌入还需可选安装fastembed2.1.0与onnxruntime-node1.21.0。LLM 边界包内不提供本地 GGUF 推理LLM 仅走宿主后端或 OpenAI 兼容远程端点未配置时自动使用确定性启发式路径功能不中断但抽取/摘要质量受限。数据位置默认存储位于~/.hermes/mnemopi/data/mnemopi.db可通过MNEMOPI_DATA_DIR/MNEMOPI_DB_PATH重定向bank 数据按.../banks/name/目录组织BankManager。召回质量向量召回依赖嵌入可用性纯 FTS 模式noEmbeddings下召回依赖全文检索与重要性/近因权重长文本的嵌入截断策略默认 8192 字符可按需调高例如 Qwen3-Embedding 的 32k 上下文场景。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考