搜索、嵌入与检索增强生成

Memories 支持对已授权的普通记忆和知识卡片进行关键词与语义检索。文档导入接受 UTF-8 文本和 Markdown，并创建普通的加密知识卡片。PDF/DOCX/二进制文件不会自动提取；显式导入前请先转换为文本。私密内容、凭据和文件资产不参与检索。

快速开始

CLI 和运行中的守护进程应使用相同的主目录/配置。升级或更改模型配置后重启守护进程。按通常方式初始化/解锁，然后：

memories rag ingest VAULT_ID notes.md --title "Research notes"
memories memory search VAULT_ID "Chinese English keywords"
memories rag search VAULT_ID "keywords" --mode bm25 --match-mode all
memories rag model-install
memories rag index VAULT_ID
memories rag search VAULT_ID "Find similar meaning" --mode vector
memories rag search VAULT_ID "Find evidence" --mode hybrid --limit 8
memories rag status VAULT_ID
memories rag ask VAULT_ID "What does the evidence say?"

rag ask 需要在守护进程配置中提供生成 URL。要在不使用嵌入模型的情况下使用词法 RAG，添加 --mode bm25；生成 URL 仍为必需。memory_search 仍采用词法搜索。高级搜索返回文档分块，包含资产/修订 ID、稳定分块哈希、原始 UTF-8 字节偏移、分数和引用标签。[S1] 标识某次结果中的来源；普通 memory read 应使用其 id 和 revision 字段，而非分块哈希。

中文 BM25 与分块

中文和混合语言文本通过 Jieba 分词。标题、正文和安全元数据参与 FTS5 BM25 排名，权重为 5/1/2。any（默认）组合关键词；all 要求所有查询词；phrase 要求原始短语。严格的 all/phrase 约束也会过滤向量/混合候选项。查询会被转义，不会被解释为任意 FTS 运算符。

文本在句子/段落边界附近拆分为最多 768 个 Unicode 字符的分块，通常重叠 128 个字符。返回偏移指向原始 UTF-8 正文。搜索限制为请求最多 100 条结果、64 个词法词项和 1,024 个查询字节。基础 memory search 按文档归组分块；高级 RAG 检索返回单独分块。--cards-only 缩小检索范围。

索引在查询之间复用。保险库修改、同步或策略变更使其缓存索引失效；锁定/重启会清除全部索引和向量。它们不会以明文持久化，也不会加入加密同步载荷。每个缓存保险库上限为 10,000 个分块、16 MiB 源文本/元数据和 32 MiB 向量；最多缓存两个保险库。大型资料库仍受性能所述底层完整状态持久化限制影响。

进程内 EmbeddingGemma

默认嵌入后端通过原生 ONNX 推理使用 Google 的 EmbeddingGemma 300M Q4。它在 Memories 守护进程内运行，无需 Ollama、Python 或独立推理服务。应用包含推理引擎，并在创建会话前明确禁用 ONNX 遥测；模型/分词器文件（约 209 MiB）由应用安装一次：

memories rag model-install

安装器下载固定版本的 onnx-community/embeddinggemma-300m-ONNX，验证 SHA-256，支持分段下载/重试，且绝不会替换已有但不匹配的文件。已验证文件会被复用。默认目录为所选 Memories 主目录下的 models/embeddinggemma。通过 rag.local_model_dir 提供现有目录；其中必须包含 Q4 ONNX 图、外部数据和分词器/配置文件。更改模型文件后重启守护进程。权重单独受 Gemma 使用条款和禁止使用政策约束；安装器会写入声明和上游模型卡。

[rag]
local_model_dir = "./models/embeddinggemma"
local_threads = 4
max_tokens = 2048
# Optional mirror of the exact pinned files:
# model_download_base_url = "https://your-mirror.example/embeddinggemma"

相对模型路径相对于配置文件所在目录解析。较低的 local_threads 限制 CPU 使用；max_tokens 限制分词器输入，设置低于分块 token 数时可能截断长输入。嵌入是 768 维归一化向量。模型分别使用查询/文档任务前缀。rag index 预热索引；向量/混合检索也会按需计算缺失嵌入。步骤之间检查五分钟操作预算；保险库/模型保持不变且未锁定时，重试可复用已完成批次。

客户提供的模型 URL

Gemini Embedding 是在线 API，并非离线 EmbeddingGemma 模型。添加 rag.embedding 选择远程提供商；省略它则保持本地嵌入。使用完整操作 URL，并配置服务所要求的模型：

[rag.embedding]
protocol = "gemini"
url = "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent"
model = "gemini-embedding-001"
dimensions = 768
api_key_env = "GEMINI_API_KEY"

[rag.generation]
protocol = "gemini"
url = "https://generativelanguage.googleapis.com/v1beta/models/YOUR_MODEL:generateContent"
model = "YOUR_MODEL"
api_key_env = "GEMINI_API_KEY"

在守护进程环境中设置指定的 API 密钥环境变量。不要将密钥值放在 TOML、URL 或命令参数中。Gemini 使用 x-goog-api-key；protocol = "compatible" 使用 Bearer 身份验证，以及通用的 {model,input} 嵌入 / chat-completion JSON 格式。兼容嵌入响应必须包含带索引的 data 条目和 embedding 数组；生成返回 choices[0].message.content。本地服务的密钥可选。远程 URL 必须使用 HTTPS；HTTP 仅允许用于回环。可选嵌入 dimensions 以 Gemini outputDimensionality 或兼容 dimensions 发送，接收时检查并绑定到向量空间键。操作 URL 不接受凭据、查询字符串或片段。

没有隐式公共模型端点。配置远程嵌入 URL 会允许将符合条件的文档分块发送到该地址。生成只发送选定分块和问题；任何存储的凭据/私密/文件内容都不会进入此流水线。这些配置属于守护进程，而非单次 MCP 调用。参见安全。

混合搜索与重排序

向量模式使用余弦相似度。混合模式使用倒数排名融合（k=60）合并 BM25 和向量排名。默认轻量重排序提高词项覆盖和短语匹配的权重。它不声称是训练得到的交叉编码器。如有需要，可配置经过训练的重排序服务：

[rag.rerank]
protocol = "compatible"
url = "https://your-reranker.example/rerank"
model = "YOUR_RERANKER"
api_key_env = "RERANK_API_KEY"

请求为 {model, query, documents, top_n}。响应必须包含 results，为每个候选项提供唯一有效的 index 和有限的 relevance_score。未知/重复条目会导致失败，而不会静默地错误重排文档。--no-rerank 跳过两个可选重排序阶段。

代理、超时与重试

[rag.http]
use_env_proxy = true
proxy_url = "http://127.0.0.1:7890"
retries = 2
backoff_ms = 500
connect_timeout_seconds = 10
timeout_seconds = 60
download_timeout_seconds = 900

显式代理覆盖环境代理发现。支持 HTTP、HTTPS、SOCKS5 和 SOCKS5h URL。带身份验证的代理值可以通过代理环境提供；TOML 代理 URL 不能包含凭据。回环模型/镜像端点始终直接连接。TLS 验证保持启用。

retries 是额外尝试次数（0-5）。模型 API 连接/读取失败、429 和 500/502/503/504 可按指数退避重试；遵守 Retry-After 秒数，最多 30 秒。身份验证/验证错误、不安全重定向和格式错误的模型输出不重试。模型 API 禁用重定向。下载重定向必须使用 HTTPS，每个最终文件均检查哈希。下载超时是逐文件预算。重试生成可能产生额外提供商费用。尝试之间重新检查授权/取消状态。

答案、引用与 MCP

memory_retrieve 向 MCP 客户端提供限定范围的检索；memory_ask 调用配置的生成服务。二者均保留授权的保险库和普通数据限制。它们不能选择任意端点或访问凭据。仅限设备的保险库会拒绝向非回环模型端点发送数据的操作；本地推理和显式配置的回环服务可以使用。旧的 memory_search 和 memory_read 工具继续可用。附带的 Memories 技能为 AI 客户端说明了 memory_retrieve 和 memory_ask。升级后，使用 memories inject all --force 替换旧版已安装技能。

生成将源文本视为不可信数据，且没有应用工具。模型必须返回结构化答案/引用 JSON，引用如 [S1] 必须确实存在于结果中。无效或编造的 ID 会被拒绝。没有证据时不会发起生成调用，结果标记为 insufficient_evidence。引用验证检查引用关系，并不确认每个论断是否有事实支持；重要答案应对照来源审查。

锁定、授权过期/撤销和源状态变更使运行中的工作失效并抑制迟到结果。已经开始的远程请求无法撤回。本版本未向移动端 FFI 添加模型驱动的 RAG 接口；移动端普通搜索获得中文/BM25 改进，并可使用 BM25 检索。