Sense MCP

感觉

多项目生态系统的环境相关性。在每次人工智能对话中，你的投资组合中的先前工作都会自动出现，根据新旧程度进行加权，并根据你正在做的事情进行塑造。

的问题

你不做一个项目。你在一个生态系统中工作——研究为出版物提供支持，由三个repos之外的决策形成的代码，一个可以追溯到六个月前你写的笔记的咨询线索。相关部分很少出现在您当前正在查看的项目中。

AI编码代理有能力，但在上下文中对此视而不见。内存和RAG工具解决了单个项目的召回问题。跨项目组合的相关性是另一个问题。将上下文无歧视地倾倒在一个提示中，会将有用的跨项目联系埋在数量之下。搜索要求你知道你在找什么——这意味着它无法发现你不知道存在的联系。

痛苦是具体的：你正在一个仓库中构建，而上周另一个项目的会话跟踪中记录了重要的决定。你正在写作，你需要的概念在你一个月没有打开的研究笔记中得到了探索。背景就在那里。你永远不会在哪里。

什么意义

Sense为您的项目组合建立索引，并自动将相关上下文注入到每个对话中。你不搜索。你不粘贴。您工作时的先前工作表面。

它作为一个 主控程序 服务器用于 克劳德代码，配有一个在每次提示时都会开火的配套钩子。结果：你的人工智能合作伙伴对它正在处理的整个投资组合都有外围意识，而不仅仅是它所在的回购。

这有什么不同

环境，未调用。 自动查询钩子在每个提示符处都会触发。上下文无需询问即可到达。这是主要的交互模式——不是你键入的搜索框，而是一个始终在后台运行的层，塑造可见的内容。

轨迹感知。 Sense不会孤立地对待每个提示。它跟踪对话的语义轨迹——积累查询嵌入，通过Frenet-Serret几何计算局部曲率（delta kappa）——并将最近的上下文融入到每次搜索中。当对话集中在一个话题上时，搜索范围会缩小。当它发散时，光圈变宽。您发送的查询是由之前的查询形成的。

知识代谢。 昨天的会议记录和去年的参考文件并不一样。感觉对它们的权重不同——最近的工作面更容易处理，旧的文档会褪色，基础参考会常青。不同类型的内容有不同的半衰期，因为它们是不同类型的知识。

与配对时 振动线束，哪些表面也会根据你所做的事情而变化。探索拓宽了视野——跨项目的联系，意想不到的邻接。Building将其缩小到当前项目中的代码和文档。根据您的工作模式，同一语料库看起来不同。

来源分类，多样性结构化。 文件分为不同类型（痕迹、代码、研究、文档、参考等），每种类型都有不同的衰减率和模式处置。基础文档可以被赋予认知权重——这是一种内容重要性的优先权，将研究框架和主要出版物置于大量临时内容之上，而不管查询或模式如何。结果分为确认时段（相关性最高）、分歧时段（挑战当前框架的内容）和意外发现时段（来自您没有查看的项目）。时隙分配是自适应的：当排名靠前的结果相关性紧密时，确认范围扩大，多样性缩小；当结果传播开来时，多样性就得到了充分的分配。目标是建立富有成效的联系，而不仅仅是最近的匹配。

从反馈中学习。 Sense自动标记其显示的每个结果（有用或噪声），并跟踪人为更正。标签通过贝叶斯先验反馈到检索权重中——文件能够更容易地证明有用的表面，持续的噪声得到抑制。反馈存储仅附加最新胜利语义用于权重计算，因此完整的校正历史记录可作为训练数据。

快速启动

需要Python 3.11+和 紫外线.

安装并注册

选项A-- uvx （零安装，直接运行）：

claude mcp add sense \
  -e OPENAI_API_KEY=sk-... \
  -e SENSE_ROOT=/path/to/your/project \
  -- uvx --from git+https://github.com/m3data/sense-mcp sense-mcp

选项B-- uv tool install （建议用于吊钩支撑）：

uv tool install sense-mcp --from git+https://github.com/m3data/sense-mcp
claude mcp add sense \
  -e OPENAI_API_KEY=sk-... \
  -e SENSE_ROOT=/path/to/your/project \
  -- sense-mcp

这两个选项都使用Claude Code将Sense注册为MCP服务器。选项B还安装 sense-mcp-hook 环境上下文命令（如下）。

配置（可选）

对于默认设置， OPENAI_API_KEY 和 SENSE_ROOT env变量就足够了。要进行更深入的定制，请创建 sense.toml 在您的项目根目录中或指向一个 SENSE_CONFIG:

cp sense.example.toml sense.toml

看 sense.example.toml 对于所有选项：语料库路径、排除目录、分类规则、衰变半衰期、模式配置文件。

启用环境上下文（推荐）

伴随钩子在每个用户提示时都会触发，并将前3个相关结果作为 `` 标签。这就是Sense环境化而非按需的原因。

添加 .claude/settings.json:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "type": "command",
        "command": "sense-mcp-hook"
      }
    ]
  }
}

需要 uv tool install （选项B）-钩子在每个提示符上运行，需要亚秒级的启动，因此 uvx 冷启动太慢了。

钩门发出提示长度、冷却和继续信号。它以只读模式打开SQLite数据库，并与正在运行的MCP服务器安全共存。会话状态（重新显示惩罚、查询历史、冷却时间）通过文件锁定的JSON存储在钩子和MCP服务器之间共享，因此两个调用者都为同一会话上下文做出了贡献并从中受益。

开发安装

对于贡献者或本地黑客：

cd sense-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

配套仪表板

一个本地网络应用程序，用于实时观察和纠正Sense的相关性判断。

python sense-mcp/dashboard/serve.py
# Open http://localhost:8111

仪表板读取现有的数据存储（sense.db、会话状态、轨迹历史）并呈现：

• 命中率 --会话范围的相关性成功作为英雄指标，按健康状况进行颜色编码
• 查询时间线 --每个钩子触发的查询都有可扩展的结果，显示文件路径、部分、相似性得分、源类型和标签
• 偏差分解 --按结果排名机制：净偏差贡献（正/负），以及显示哪些排名信号处于活动状态的信号徽章（重铺惩罚、主题循环、跨项目提升、模式权重）。将鼠标悬停在任何元素上，即可获得其含义的简明语言解释
• 轨迹信号 --当前语义漂移（收敛/发散/稳定）与delta kappa值
• 反馈流 --自动标签和人工更正的时间顺序日志

单击任何结果标签，在有用和噪波之间切换。更正将写回反馈表 corrected: 条目，并从下一个查询中转移检索权重。

偏差分解使排名机制变得可见——你可以看到 *为什么* 结果排名靠前，而不仅仅是 *那* 确实如此。这是感知检索系统何时被夹带（根据其自身的多样性标准锁相）与连贯（真正浮出水面）的先决条件。

如果使用Claude Code会话挂钩，仪表板将在会话打开时自动启动，并在会话关闭时停止。

工具

sense_search

按自然语言搜索。返回具有相似性得分、时间衰减和内容预览的排名结果。支持可选过滤器： project, source_type, limit, mode.

sense_sync

构建或更新索引。使用SHA-256文件哈希进行更改检测——跳过未更改的文件。可以安全地反复运行。

sense_status

索引统计：按项目和源类型列出的块计数、总令牌数、上次同步时间。

sense_feedback

提交搜索结果的相关性反馈。接受 query_text, file_path, label （有用/噪音），可选 note仪表板要求进行人为更正；你也可以直接调用它。

sense_feedback_stats

收集到的反馈的汇总统计数据：总标签、按来源细分（自动：挂钩、手动、已纠正）、纠正率和每个文件的权重预览。

Slash命令

如果使用Claude Code技能，请复制 skills/sense/ 和 skills/sense-sync/ 进入你的 .claude/skills/ 目录：

• /sense --使用可选标志进行搜索(--project, --type, --limit, --mode)
• /sense （无参数）--根据对话上下文自动合成查询
• /sense-sync --重建索引
• /sense-sync status --显示索引统计信息

配置参考

时间衰减

内容会根据源类型而过时。配置半衰期（以天为单位）：

[decay]
floor = 0.1  # Old content never fully vanishes

[decay.half_lives]
trace = 30          # Session traces
market-research = 60       # Market research
documentation = 90  # General docs
code = 90           # Source code
# Types not listed are evergreen (no decay)

分类规则

规则按顺序进行评估。第一场比赛获胜。每个规则都将文件映射到用于衰减和模式评分的源类型。

上下文查询（轨迹混合）

钩子将最近的对话上下文混合到每个搜索查询中。在中配置 sense.toml:

[hook]
context_window = 5              # Recent queries to blend
context_decay = 0.5             # Exponential decay (older = less weight)
max_context_weight = 0.4        # Cap on context contribution (current message >= 60%)
context_session_timeout = 7200  # Reset after 2 hours of inactivity

轨迹信号会自动调整上限：收敛对话将其缩小到0.2（更紧密的焦点），发散对话将其扩大到0.6（更广泛的背景）。

相关反馈

控制自动标签和人工校正如何影响检索权重：

[feedback]
boost_factor = 0.3       # Weight multiplier range
prior = 2.0              # Bayesian prior — higher = more labels needed to shift weights
weight_cache_ttl = 60    # Seconds before recalculating from feedback table

模式感知检索

与配对时 振动线束，搜索结果受当前工作模式的影响：

模式信号使用 加性偏差模型：上下文偏好（源类型、跨项目、重新呈现历史、主题重复）被总结并作为对基础相关性得分的有界调整。这确保了模式可以重新排序近关系，但永远不会将高度相关的结果隐藏在无关的结果后面——乘法方法在长会话中产生的失败模式。

重修路面的处罚是 轨迹感知当对话出现分歧时，重复出现的内容被视为连贯的锚定（惩罚减半）；当收敛时，它被视为循环（通常适用惩罚）。反夹带扩大了收敛过程中窄模式的多样性，并将已经很宽的模式转向更偶然的模式。

模式配置文件可在中完全配置 sense.toml 在...之下 [mode.profiles.*].

环境变量

设计方向

感官也是一种研究成果。它研究了相关性实现——生物体决定什么是重要的前反思过程——是否可以部分外部化到基础设施中。

反馈回路闭合控制电路：Sense观察→ 汽车标签→ 仪表板呈现观察结果→ 人类纠正→ 重量转移→ 感觉会改变它的表面。观测基础设施本身是可观测的——巴拉迪亚人的切割是可见的。

该系统支撑着人类的相关性实现——它并没有取代它。但通过对工作环境的响应，它参与了产生相关性的耦合动态。

看 DESIGN_DIRECTION_relevance-realisation.md 和 ARCHITECTURE-DECISIONS.md 以了解完整的设计原理。

许可证

Apache 2.0