为16,894个Obsidian文件构建混合检索器

对16,894个markdown文件进行grep搜索需要11至66秒（取决于搜索词），并返回数百个低相关性的匹配结果。向量搜索能返回语义相关的内容，却会遗漏您输入的精确函数名。而混合检索器融合了两种方法，能在23毫秒内（端到端，包括查询嵌入）从单个83 MB的SQLite文件中返回正确答案，且无需任何API调用。¹

执着的笔记者面临的问题不是收集，而是检索。Obsidian让记录变得毫无阻力。当文件积累到一定数量后，仓库就变成了只写数据库：添加容易，查询不可能。按文件名搜索在文件名变得毫无意义时就失效了。全文搜索在同一关键词出现在400个文档中时就失效了。标签在您忘记给某些内容打标签时就失效了。

一位HN评论者请求了解我为Obsidian仓库构建的检索系统的完整架构。²以下便是全部内容：分块策略、嵌入模型、双索引SQLite架构、带有实际数据的融合算法，以及在数百次查询系统后发现的失败模式。

摘要

该检索器将FTS5 BM25关键词搜索与Model2Vec向量相似度搜索相结合，通过倒数排名融合（RRF）合并为一个统一的排名列表。所有数据都在本地运行，存储在单个SQLite数据库中：来自16,894个文件的49,746个文本块，共83 MB。完整重建索引需要四分钟。增量更新在十秒内完成。系统通过钩子与Claude Code集成，使智能体无需将文件加载到上下文中即可访问仓库的知识。BM25捕获精确标识符和函数名。向量搜索跨不同术语捕获语义匹配。RRF无需分数校准即可合并两者。坦诚的权衡是：标签丰富的浅层内容可能排名高于结构不佳的深层内容，因为BM25奖励关键词密度而非深度。

核心要点

适用于拥有大型仓库的笔记者。 根据我的经验，当文件数超过几千时，单独的全文搜索就变得不可用——而现有的Obsidian搜索插件（Smart Connections、Omnisearch）在应用内部建立索引，而非作为外部库供其他工具查询。¹在BM25之上添加向量搜索能捕获那些您记得概念但忘了关键词的查询。检索器完全运行在SQLite上，无需外部服务、无需GPU、无需API费用。Model2Vec以CPU速度进行嵌入，因为该模型是30 MB的静态词向量，而非transformer。³

适用于构建检索系统的开发者。 RRF是需要最少调优的融合方法。公式仅使用排名位置而非原始分数，因此您永远不需要校准BM25分数与余弦距离之间的关系。从k=60和等权重开始。仅在基于自身数据测量失败案例后再进行调优。sqlite-vec扩展将向量KNN搜索引入SQLite，无需单独的向量数据库。⁴

适用于Claude Code用户。 检索器作为钩子可调用的库运行。PreToolUse钩子在智能体开始工作前查询仓库。智能体看到的是2-3 KB带有文件路径归属的精准结果，而非加载整个文件。该集成保持上下文窗口精简，同时让智能体访问16,894个文件的知识。

最小可行版本。 最简单的起点：在您的markdown文件上创建FTS5虚拟表（仅BM25，无嵌入）。当关键词搜索开始遗漏语义匹配时，添加sqlite-vec和Model2Vec。最后添加RRF融合。每层独立运作。完整技术栈仅需Python 3、一次30 MB的模型下载，以及pip install model2vec sqlite-vec。无需GPU、无需Docker、无需外部服务。16,894个文件的总磁盘占用：83 MB。

想要完整的操作指南？ Obsidian AI基础设施参考涵盖了仓库架构、插件配置、MCP服务器设置、增量索引方案和故障排除——是本文架构深度解析的配套分步指南。

为什么关键词搜索在大规模下会失效

全文搜索在仓库规模下以可预测的方式崩溃。使用BM25排名的FTS5擅长精确匹配：搜索requestAnimationFrame，每个包含该精确词元的文件都会出现，按词频和文档长度排名。⁵Robertson和Zaragoza的概率相关性模型综述证实了BM25的优势：该算法在关键词密集型查询上表现良好，且只需最少的参数调优。¹⁴其失败模式是同义词和概念匹配。搜索”如何处理认证失败”，BM25会分别返回每个包含”认证”或”失败”的文件，用边缘相关的内容稀释结果。

向量搜索解决了同义词问题。嵌入查询并找到嵌入空间中距离接近的文本块。”如何处理认证失败”能匹配关于”登录错误恢复”和”会话过期处理”的内容，因为嵌入捕获了跨不同术语的语义相似性。⁶Karpukhin等人通过密集段落检索（DPR）证明，密集嵌入在开放域问答的top-20准确率上比BM25高出9-19%，正是因为密集表示捕获了超越词汇重叠的语义。¹⁵其失败模式恰好相反：向量搜索会遗漏精确标识符。搜索函数名_rrf_fuse，向量搜索会返回关于融合和排名算法的内容，但可能将实际的函数定义排在概念性解释之后。

两种方法都无法单独覆盖两种失败模式。以下用一个查询来说明差异（不是优越性的证明——聚合评估需要黄金测试集，而系统目前还没有）。查询”PostToolUse hook for context compression”从每种方法返回不同的前三名结果：

BM25找到了精确的钩子文件和设置引用（关键词匹配”PostToolUse”），但遗漏了概念性的上下文工程笔记。向量搜索找到了压缩策略笔记（语义匹配”context compression”），但遗漏了具体的钩子实现。RRF将对概念和实现都重要的笔记提升到了前列，将策略笔记和钩子文件分别放在第一和第二位。¹³

MS MARCO段落排名的研究在网络搜索基准测试中支持了这一模式：混合检索始终优于单独使用BM25或密集检索，在同时包含特定术语和抽象概念的查询上增益最大。⁷¹⁶

架构：三层叠加效应

系统有三个独立层。每层都可以独立运作，但组合在一起会产生叠加效应。

第一层：信号摄入。 一个733行的Python评分流水线对每个传入信号在四个维度上评分：相关性、可操作性、深度和权威性。得分0.55及以上的信号自动路由到12个领域文件夹之一。得分在0.40到0.55之间的信号排队等待人工审核。低于0.40的信号被丢弃。该流水线在14个月内处理了7,771个信号，无需人工标注。¹摄入层决定什么进入仓库。检索层使其可被找到。

第二层：检索。 下文详述的混合搜索引擎。引擎在标题边界处对每个文件进行分块，使用Model2Vec嵌入文本块，并在SQLite中同时使用vec0表进行向量KNN搜索和FTS5虚拟表进行BM25搜索。查询同时运行在两个索引上，RRF将结果融合为统一的排名列表。

第三层：集成。 Claude Code钩子将检索器接入智能体的工作流程。钩子在提示提交时触发，查询仓库获取相关上下文，并将最佳结果注入对话。智能体看到的是带有来源归属的精准文本块，而非原始文件内容：

# Illustrative output (format matches production, content simplified)
## Relevant Memory Context

### OAuth Token Rotation (security-patterns)
Rotate tokens on 401 response. Store refresh token in keychain,
not environment variable. Implement retry with backoff...

### Session Expiration Handling (auth-architecture)
Three expiration modes: absolute (24h), sliding (30min idle),
refresh (7d with rotation). Hook into 401 interceptor...

每个结果携带章节标题和来源项目，上限为500词元预算以避免上下文膨胀。

检索器还支持第二个集成点：PostToolUse钩子在工具输出进入对话前对其进行压缩。原始工具输出包含时间戳、排序伪影和冗余格式，这些在不同运行之间会变化。检索器用稳定、精准的子集替换原始数据。智能体永远看不到噪声，只看到相关摘要。一个附带好处是：由于检索器的输出对于相同查询是确定性的（相同索引状态产生相同排名结果），压缩后的输出有助于提示缓存。对未更改数据的重复查询产生相同的上下文块，CLI的自动提示缓存可以复用缓存前缀。

更广泛的基础设施故事解释了钩子、技能和智能体如何组合成模型周围的可编程层。

这些层在设计上是解耦的。信号摄入评分对嵌入一无所知。检索器对信号路由规则一无所知。但摄入确保仓库包含高质量内容，检索为任何查询呈现正确的子集，集成将该子集交付给智能体而不造成上下文膨胀。我撰写过关于上下文作为关键资源的理论框架。检索器是其实际实现。

分块：检索质量的起点

分块决定了搜索结果的粒度。块太大，向量搜索会返回整个文件，而其中只有一段是相关的。块太小，嵌入会丢失语义匹配所需的上下文。RAG流水线的研究证实，对于大多数用例，块大小对检索质量的影响大于模型选择，200-500词元的块在段落级检索任务中表现最佳。¹⁸

分块器在H2（##）标题边界处分割，保留markdown结构。⁸一篇关于OAuth令牌轮换的笔记如果有三个H2章节，就会变成三个文本块，每个块都足够自包含，使嵌入能捕获其含义。索引器将标题文本和父笔记标题作为元数据与每个块一起存储，即使块文本本身很稀疏，也能为BM25匹配提供上下文。

# chunker.py: H2 splitting with heading context
MIN_CHUNK_CHARS = 30
MAX_CHUNK_CHARS = 2000

def _split_at_headings(body):
    sections = []
    current_heading = ""
    current_lines = []
    for line in body.split("\n"):
        if line.startswith("## "):
            if current_lines:
                text = "\n".join(current_lines).strip()
                if text:
                    sections.append((current_heading, text))
            current_heading = line[3:].strip()
            current_lines = []
        else:
            current_lines.append(line)
    if current_lines:
        text = "\n".join(current_lines).strip()
        if text:
            sections.append((current_heading, text))
    return sections

分块器将超过2,000个字符的章节进一步分割：首先在H3边界处，然后在段落间断处。它丢弃少于30个字符的章节。分块器还会跳过Related、See Also、Links和References章节，这些通常是wiki链接列表而非可搜索的内容。

有两个设计选择对检索质量至关重要。第一，索引器将标题上下文字符串（"OAuth Token Rotation | note | security, authentication"）存储在单独的列中，并在FTS5中以较低的权重（0.3）索引，而块文本的权重为1.0。当块正文不包含搜索词时，BM25仍然能匹配标题，但标题匹配的得分低于正文匹配。第二，分块器提取frontmatter标签和笔记类型并将其包含在标题上下文中，因此搜索”security”能匹配标记为security的笔记，即使正文使用了不同的术语。

嵌入：30 MB模型，零API调用

嵌入模型是Model2Vec的potion-base-8M，一个拥有760万参数、生成256维向量的静态词嵌入模型。³在MTEB基准测试套件中，potion-base-8M达到了all-MiniLM-L6-v2 89%的性能（平均50.03对比56.09），推理速度最高可达500倍，使其在消费级硬件上索引大型语料库成为现实。⁹¹⁷需要注意的是：该模型的MTEB检索子分数明显较低（31.71），而分类（64.44）和STS（73.24）得分较高。MTEB的检索基准测试的是网络语料库上的文档级排名，而非同质markdown文本块上的段落级匹配。当文本块较短、主题集中且词汇一致时，这个差距的影响较小。与基于transformer的嵌入模型不同，Model2Vec不对输入运行注意力层。该模型将句子transformer的知识蒸馏为静态词元嵌入，通过加权平均而非顺序计算来生成向量。⁹

为什么静态嵌入适用于这个用例？短markdown文本块（平均200-400词）包含关于单一主题的集中词汇。这些词元向量的加权平均值落在嵌入空间的有意义区域，因为几乎没有主题外的稀释。实际上，一篇涵盖三个不同主题的2,000词文档往往会产生一个模糊的质心，位于主题聚类之间而非其中。而关于OAuth令牌轮换的文本块则会产生一个与其他认证内容紧密聚类的向量。静态嵌入以牺牲上下文消歧（”bank”在”river bank”与”bank account”中的不同含义）换取原始速度。在每个文本块覆盖一个概念的个人知识库中，歧义代价很小，且论文报告了最高500倍的推理加速。⁹

# embedder.py: lazy-loading Model2Vec in a dedicated venv
DEFAULT_MODEL = "minishlab/potion-base-8M"
EMBEDDING_DIM = 256

class Model2VecEmbedder:
    def __init__(self, model_name=DEFAULT_MODEL):
        self._model_name = model_name
        self._model = None

    def _ensure_model(self):
        if self._model is not None:
            return
        _activate_venv()  # Add memory venv to sys.path
        from model2vec import StaticModel
        self._model = StaticModel.from_pretrained(self._model_name)

    def embed_batch(self, texts):
        self._ensure_model()
        vecs = self._model.encode(texts)
        return [v.tolist() for v in vecs]

实际效果：在Apple M3 Pro上，16,894个文件的完整重建索引在四分钟内完成。增量索引（仅处理变更文件，通过mtime比较检测）在典型一天的编辑后十秒内完成。¹

该模型运行在~/.claude/venvs/memory/的隔离虚拟环境中，以避免与工具链其余部分的依赖冲突。嵌入器在首次使用时延迟加载模型，而非在导入时加载，因此当检索器回退到仅BM25模式时，导入模块的成本为零。

为什么不用更大的模型？两个原因。第一，256维向量使49,746个文本块的SQLite数据库保持在83 MB。更高维度的向量（768或1,024）会使数据库大小增加三到四倍，而对短markdown文本块的质量提升微乎其微。¹⁰第二，基于API的嵌入（例如OpenAI的text-embedding-3-small，每百万词元$0.02）引入了延迟、成本和网络依赖，而这个系统应该支持离线运行。¹¹以API价格计算，完整仓库重新嵌入的费用大约为$0.30，单独来看微不足道，但真正的成本是49,746个文本块的往返延迟以及将个人笔记发送到外部API的隐私影响。

模型哈希机制跟踪嵌入兼容性。索引器存储一个由模型名称和词汇表大小派生的哈希值。如果模型发生变化，增量索引会检测到不匹配并自动触发完整重建索引。

SQLite架构：三张表，一个文件

整个索引存储在一个SQLite文件中（vectors.db，83 MB），使用WAL模式以确保并发读取安全。¹²三张表服务于不同目的：

-- Chunk content and metadata
CREATE TABLE chunks (
    id INTEGER PRIMARY KEY,
    file_path TEXT NOT NULL,
    section TEXT NOT NULL,
    chunk_text TEXT NOT NULL,
    heading_context TEXT DEFAULT '',
    mtime_ns INTEGER NOT NULL,
    embedded_at REAL NOT NULL
);

-- FTS5 for BM25 search (content-synced to chunks)
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id
);

-- sqlite-vec for vector KNN search
CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

FTS5表使用内容同步模式：它直接引用chunks表而非存储文本的副本。⁵一个陷阱是：内容同步表不会自动传播删除操作。索引器必须在从chunks表删除行之前发出显式的INSERT INTO chunks_fts(chunks_fts, rowid) VALUES('delete', ?)命令，否则FTS5索引会悄然变得不一致。BM25查询中的列权重为块文本分配1.0，章节标题0.5，标题上下文0.3：

# vector_index.py: BM25 search with column weights
bm25(chunks_fts, 1.0, 0.5, 0.3) as score

sqlite-vec扩展将256维浮点向量存储为打包的二进制数据，并支持使用余弦距离的KNN查询。⁴Python的struct.pack序列化向量：

def _serialize_vector(vec):
    return struct.pack(f"{len(vec)}f", *vec)

该架构在设计上支持优雅降级。如果sqlite-vec加载失败（扩展缺失、平台不兼容），检索器回退到仅BM25搜索。vec_available属性跟踪向量搜索是否可用。

倒数排名融合：使其生效的数学原理

RRF无需分数校准即可合并两个排名列表。⁷为什么不直接合并原始分数？BM25返回负相关性分数（在SQLite的FTS5实现中，越负代表越相关），而余弦距离返回0到2之间的值。比较这些量纲需要对查询分布敏感的归一化处理。RRF通过仅使用排名位置而非分数来完全绕过这个问题。公式根据文档在每个列表中出现的位置分配分数：

score(d) = Σ (weight_i / (k + rank_i))

其中k是常数（实现中为60，遵循原始Cormack等人的论文⁷），rank_i是文档在结果列表i中的排名，weight_i是可选的每列表权重乘子（两者默认均为1.0）。

以下是一个使用真实排名的演算示例。考虑一个查询：”how does the review aggregator handle disagreements”。五个文本块出现在合并结果中：

第一个文本块获胜，因为它在两个列表中排名都很高。BM25匹配了文本中的”review”、”aggregator”和”disagreements”。向量搜索匹配了代码评审中冲突解决的语义概念。第二个文本块在BM25中排名第一（配置文件中”review”的精确关键词匹配），但在向量搜索中排名第八（配置JSON语义稀疏）。RRF恰当地将其降低了排名。最后一个文本块仅出现在向量结果中，因此它只从一个来源获得了RRF分数。

# retriever.py: RRF fusion core
RRF_K = 60

def _rrf_fuse(self, bm25_results, vec_results,
              bm25_weight=1.0, vec_weight=1.0):
    scores = {}
    for rank, r in enumerate(bm25_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {"rrf_score": 0.0, ...}
        scores[cid]["rrf_score"] += bm25_weight / (self._rrf_k + rank)
        scores[cid]["bm25_rank"] = rank

    for rank, r in enumerate(vec_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {"rrf_score": 0.0, ...}
        scores[cid]["rrf_score"] += vec_weight / (self._rrf_k + rank)
        scores[cid]["vec_rank"] = rank

    return [SearchResult(chunk_id=cid, **data)
            for cid, data in scores.items()]

默认候选池为融合前每个来源30个结果，最多产生60个候选。检索器返回融合后的前10个结果。可选的max_tokens参数按词元预算截断结果，以每词元4个字符估算。

索引：完整与增量

索引器支持两种模式。完整重建索引清空数据库并从零开始重建。增量索引将文件修改时间（mtime_ns）与存储的时间戳进行比较，仅重新处理变更的文件。¹

# index_vault.py: incremental detection
stale = index.get_stale_files(vault_mtimes)  # mtime changed or new
deleted = index.get_deleted_files(vault_paths)  # no longer in vault

嵌入以64个文本为一批运行，以分摊Model2Vec的开销。⁸完整重建索引期间，每500个文件打印一次进度计数。SIGINT处理程序支持优雅关闭，在停止前完成当前文件的处理。

配置文件使用白名单模型控制文件夹索引。仓库有22个允许的文件夹和5个永久排除的文件夹（个人健康笔记、职业文档、Obsidian内部目录）。²⁰索引器仅处理允许文件夹内的文件，跳过其他所有内容。

一个关键的设计选择：索引器在存储前对每个文本块运行凭证过滤器。个人笔记包含在调试期间粘贴的API密钥、bearer令牌、数据库连接字符串和私钥。凭证过滤器匹配21种厂商特定模式（OpenAI密钥、GitHub PAT、AWS访问密钥、Stripe令牌及其他17种）以及11种通用检测器，覆盖数据库URL、JWT、bearer令牌、密码赋值和高熵base64字符串。²⁰过滤器将匹配内容替换为[REDACTED:pattern-name]令牌，并记录触发了哪些模式但从不记录密钥本身。

# chunker.py: credential filtering before storage
cleaned_text, scan_result = clean_content(sub_text)
if not scan_result.is_clean:
    logger.info("Scrubbed %d credential(s) from %s [%s]",
                scan_result.match_count, file_path, sub_heading)

在没有凭证过滤的情况下索引个人笔记，会创建一个可搜索的密钥数据库。过滤器在嵌入前运行，因此向量表示永远不会编码凭证模式。搜索”API key”会返回讨论API密钥管理的笔记，而非包含实际密钥的笔记。

真实的失败模式

在对生产索引进行数百次查询后，四种失败模式已经明确。

关键词密集的浅层内容排名高于深层内容。 一篇标记为security, authentication, oauth的简短笔记，只有三句话的摘要，在BM25中的得分高于一篇2,000词的OAuth实现深度分析——后者仅在引言中使用了一次这些术语，然后转入了具体的协议细节。BM25奖励相对于文档长度的词频，Robertson和Zaragoza将这一特性记录为算法的”词频饱和”组件。⁵¹⁴浅层笔记具有更高的关键词密度。RRF部分纠正了这个问题，因为向量搜索对深层内容排名更高（嵌入捕获了语义深度），但浅层笔记仍然出现在融合结果中，而它可能本不应该出现。

结构化数据索引效果差。 JSON配置文件、YAML frontmatter块和带有变量名的代码片段产生低质量的BM25匹配。搜索”review configuration”会匹配每个包含review键的JSON文件。向量搜索对结构化数据的处理略好，因为嵌入能捕获键值关系，但结构化内容在本质上比散文更难分块。在嵌入前将JSON扁平化为键路径:值对，可以改善配置密集型笔记的检索质量。

文本块边界割裂上下文。 分块器将跨越两个H2章节边界的段落分割为两个文本块。每个块只包含一半的解释。两个块的嵌入效果都不好，因为嵌入缺少完整上下文。分块器通过标题上下文（将父标题携带到元数据中）来缓解这个问题，但正文文本仍然在边界处丧失了连续性。重叠窗口会有所帮助，但会增加文本块数量和数据库大小。

时间相关性不可见。 检索器没有时效性概念。14个月前关于早期架构决策的笔记与昨天关于当前实现的笔记排名相同。对于一个不断演进的知识库，较新的笔记通常会取代较旧的笔记。检索器不知道这一点。

未来计划：扩展路线图

五项改进将解决失败模式并扩展系统能力。

学习排序重排层。 在RRF融合之后，一个轻量级重排器可以根据元数据信号调整分数：笔记时效性、标签与查询领域的相关性、链接密度（被大量链接的笔记通常更具权威性）。重排器将在融合后的前30个结果上运行，而非整个语料库，使延迟保持在23毫秒基线以下。

查询意图分类。 不同的查询需要不同的检索策略。精确标识符查找（_rrf_fuse）应该加大BM25权重。概念性问题（”how does review handle disagreements”）应该加大向量搜索权重。一个根据查询调整bm25_weight和vec_weight的轻量级分类器将在不改变融合架构的情况下提高精度。

时间衰减。 对关于当前状态的查询，略微提高较新笔记的权重。在融合后应用衰减函数，降低最后修改时间超过N个月的文件中文本块的分数。mtime_ns时间戳已存在于架构中；衰减仅需在检索器中添加一个加权函数。

带有黄金查询的评估框架。 系统目前没有自动化的质量测量。一组50-100个精心策划的查询-答案对将支持检索质量回归测试：在分块、嵌入或融合参数的任何更改后运行测试套件，验证recall@10没有退化。BEIR基准测试证明，检索系统在不同查询分布下的nDCG@10可以相差20分以上，这使得领域特定评估不可或缺。¹⁹没有黄金测试集，改进只是轶事性的。

跨笔记关系索引。 Obsidian wiki链接（[[note-name]]）编码了笔记之间的显式关系。当前系统完全忽略了链接结构。将链接目标作为元数据索引，可以让检索器提升那些被许多其他高分笔记链接的笔记中的文本块，类似于仓库的PageRank。

我对完整仓库进行的嵌入空间拓扑分析揭示了这些改进在哪些方面影响最大。密集聚类（AI工具、安全）已经检索良好，因为术语一致。聚类之间稀疏的桥接区域是检索器最困难的地方，也是关系索引和意图分类能提供最大收益的地方。

常见问题

为什么选择SQLite而非专用向量数据库？

整个检索栈运行在一个文件中，零外部依赖。SQLite的WAL模式处理来自多个Claude Code会话的并发读取。sqlite-vec扩展添加向量KNN搜索，无需单独的Pinecone、Weaviate或Qdrant实例。⁴在49,746个文本块下，查询延迟为23毫秒。¹专用向量数据库会为一个83 MB的单用户知识库增加运维复杂性（托管、备份、认证）。

为什么选择Model2Vec而非OpenAI嵌入或更大的模型？

三个原因：延迟、隐私和成本。Model2Vec在本地以CPU速度运行，无需网络调用。³个人笔记永远不离开机器。基于API的嵌入在当前仓库规模下每次完整重建索引大约花费$0.30，¹¹单独来看微不足道，但真正的成本是49,746个文本块的往返延迟以及个人内容的隐私暴露。

什么是倒数排名融合，何时应该使用它？

RRF不需要训练数据、不需要分数校准，除了常数k之外不需要超参数调优。⁷学习型融合模型需要标注的相关性判断进行训练，而个人知识库并不存在这些数据。RRF是产生有用结果门槛最低的融合方法。当组合来自产生不兼容分数类型的检索方法的排名列表时，使用RRF。

本地检索器如何连接到Claude Code？

PreToolUse钩子使用当前提示调用检索器的search()方法，将最佳结果格式化为带有文件路径和章节标题的上下文块，并注入到对话中。智能体看到的是精准的文本块，而非原始文件。max_tokens参数确保注入的上下文符合预算限制。

如何防止检索系统中的密钥被索引？

在存储前对每个文本块运行凭证过滤器。该系统中的过滤器匹配21种厂商特定模式和11种通用检测器，覆盖JWT、bearer令牌和私钥。²⁰它将匹配内容替换为[REDACTED:pattern-name]令牌，并在嵌入前运行，因此向量表示永远不会编码凭证模式。

参考文献