silverfish

<div align="center"> # 🐟 水银鱼 **一款适用于 Mac 的本地优先、100% 私密的记忆伴侣。AI 从未离开过您的机器。** </div> 水银鱼静静地记录您的工作内容，并允许您 *搜索它、询问它、并以您自己的语调写作* — 使用一个大型语言模型，该模型通过 [Ollama](https://ollama.com) 完全在您的 Mac 上运行。无需云服务，无需 API 令牌，无需遥测。您的活动被捕获到一个本地 SQLite 数据库中，每个 AI 请求都发送到 `127.0.0.1`，而不会发送到其他地方。 它也不会将您锁定在一个模型中：水银鱼运行的是您的 Mac 实际可以处理的 Ollama 模型，并且内置的设置向导（`silverfish onboard`）会告诉您针对 *您的* 硬件的模型 — 而不是让您自己研究本地模型的大小。 如果您已经使用类似的本地记忆应用程序，水银鱼可以在第一次运行时导入其现有的数据库 — 您的捕获历史记录将继续保留 — 并且它公开了一个 MCP 接口，以便您的 Claude Desktop / Claude Code / Cursor 集成继续正常工作，而不会有任何数据发送到外部。 --- ## 功能 - **捕获**：每隔几秒钟使用 macOS 无障碍 API 捕获前景活动 — 仅限文本和元数据，**绝不会捕获截图**。应用程序、窗口标题、URL 和聚焦文本，合并成一个可搜索的时间线。 - **私人记忆**：在 SQLite 中使用全文搜索（FTS5）进行私人记忆存储。 - **理解**：使用本地模型理解您的活动：分层摘要（小时 → 天 → 周）、人员/项目/工具的知识图谱，以及提炼的 Wiki + 身份配置文件。 - **辅助**：与您的记忆聊天、早晨简报/晚上总结，以及一个内联的“以我的语调写作”重写功能，它根据您的每个界面学习您的风格。 - **适配您的机器**：四个独立可配置的模型槽位，以及一个设置向导，根据您的实际硬件推荐适合的模型 — 请参见下面的 [选择适合您 Mac 的模型](#选择适合您mac的模型)。 - **集成**：与 MCP 客户端集成，以便 Claude 可以查询您的本地记忆。 ## 隐私保护 - **仅有的** 代码会发出外部请求的代码是 `crates/ai/src/ollama.rs`，并且它拒绝任何非回环（`ensure_local`）的端点。 - MCP 服务器仅绑定到 `127.0.0.1`。 - 密码管理器、银行和登录/ oauth/结账/私密浏览页面默认被屏蔽，不会被捕获；包含秘密信息的字符串在写入前会被编辑。您可以在 `~/.silverfish/config.toml` 中配置这两个功能。 ## 架构 ``` ┌───────────────────────────────────────────┐ Claude Desktop/Code ──▶ │ 水银鱼-mcp（stdio↔HTTP 代理） │ └───────────────┬───────────────────────────┘ │ JSON-RPC over 127.0.0.1:3333 ┌───────────────▼───────────────────────────┐ macOS AX APIs ─────▶ │ 水银鱼d │ （捕获） │ 捕获 · 调度器 · MCP 服务器 │ └───────┬───────────────────────┬───────────┘ │ │ ┌──────────▼─────────┐ ┌──────────▼──────────┐ │ 水银鱼核心 │ │ 水银鱼-ai │ │ SQLite · 配置 │ │ Ollama（127.0.0.1） │ └────────────────────┘ └─────────────────────┘ ``` | 源码 | 角色 | |-------|------| | `silverfish-core` | 配置、SQLite 模式 + 访问层、模型、编辑 | | `silverfish-ai` | 本地 Ollama 客户端 + 单方法-每能力引擎 | | `silverfish-daemon`（`silverfishd`） | 捕获、调度器和本地 MCP 服务器 | | `silverfish-cli`（`silverfish`） | 终端访问您的记忆 | | `silverfish-mcp` | 通用 stdio↔HTTP MCP 桥接器，用于 Claude 客户端 | | `silverfish-bar`（`silverfish-bar`） | 菜单栏应用：右-Option 内联重写 + 本地聊天弹出窗口 | ## 先决条件 在您构建任何内容之前： - **macOS（Apple Silicon）。** 水银鱼的捕获和菜单栏应用是基于仅限 macOS 的无障碍 API 构建的。 - **Rust，通过 [rustup](https://rustup.rs)。** 工作区声明的最低版本是 1.85（`Cargo.toml`中的 `rust-version`），但该仓库在 1.95（参见 `.tool-versions`）下开发和测试 — 通过 rustup 安装当前的稳定 Rust 版本即可满足两者。 - **Xcode 命令行工具** — `xcode-select --install` 足够；您不需要完整的 Xcode 应用程序。 - **[Ollama](https://ollama.com)，已安装 *并正在运行*（`ollama serve`，或直接从您的应用程序文件夹启动 Ollama.app）。** 水银鱼通过 `127.0.0.1:11434` 与其通信，如果没有 Ollama，它将无法正常工作。 ## 选择适合您 Mac 的模型 水银鱼不附带一个指定的模型。它跨四个独立可配置的槽位运行 — `fast`、`chat`、`summarize`、`heavy`（参见 `crates/core/src/config.rs` 中的 `OllamaConfig`）— 任何 Ollama 可以提供的模型都可以放在任何槽位中。重要的是选择您的 Mac 可以实际良好运行的大小。 ### 推荐：让 `silverfish onboard` 选择 `silverfish onboard` 检测您的 Mac 的 RAM 和芯片，将其与维护的硬件层级手册进行匹配，并推荐（并可以拉取和应用）一个针对 *该* 机器量身定制的模型集 — 因此，8-16 GB 的 Mac 不会被推荐 23 GB 的模型，而工作站不会因为过度谨慎而使用小模型。 ```sh ./target/release/silverfish onboard # 试运行：检测 + 推荐，打印它将执行的操作 ./target/release/silverfish onboard --pull --apply # 获取并将推荐写入您的配置中 ``` （您需要先构建水银鱼 — 请参见下面的 [快速入门：菜单栏应用](#快速入门菜单栏应用)。）请参阅 [`docs/onboarding.md`](docs/onboarding.md) 以获取完整的 cookbook 表格，以及如何手动覆盖任何槽位。 ### 手动：自行拉取默认值 如果您更喜欢自己选择标签，或者您使用的机器是硬件探测器无法读取的，水银鱼的开箱即用默认值涵盖了三个不同的 Ollama 标签： ```sh ollama pull llama3.2:3b # 快速：提取、分类 ollama pull qwen3.5:9b # 聊天 + 总结（一个标签，涵盖两个槽位） ollama pull qwen3.6:35b # 深度：最深的每周/每月综合（~23 GB 单独） ``` 拉取所有三个可获得完整的默认配置，总共需要 **33 GB 磁盘空间**。这些只是预装的默认值，而不是要求 — 编辑 `~/.silverfish/config.toml` 中的 `[ollama]` 部分，将任何槽位指向一个较小、较大或您已经拉取的不同模型。 ## 快速入门：菜单栏应用 这是实际产品：一个托盘图标，带有右-Option 内联重写助手和本地聊天弹出窗口。构建、打包并启动它： ```sh cargo build --release scripts/make-dev-cert.sh # 一次性，可选但推荐 — 请先阅读它 scripts/package-app.sh open dist/Silverfish.app ``` `scripts/make-dev-cert.sh` 创建一个稳定的、自签名的本地签名身份。这就是为什么下面提到的无障碍权限在未来重建后仍然有效的原因 — 请参阅 [故障排除](#故障排除) 和 [`docs/dev/packaging.md`](docs/dev/packaging.md)，了解确切的原因。跳过它仍然会生成一个可用的应用程序（`package-app.sh` 采用临时签名并附带警告），但每次重建都会生成一个新的身份，macOS 重置权限，因此您将在每次 `cargo build --release` + `package-app.sh` 循环后重新授予无障碍权限。 ### 授予权限 在第一次启动时，水银鱼会在 **系统设置 ▸ 隐私和安全 ▸ 无障碍** 中预注册自己 — 打开其切换开关。这是它请求的 **唯一** 权限；不需要输入监控，因为右-Option 触发器仅检查修饰键状态，而不是安装系统范围的事件监听器。无障碍仅用于读取聚焦字段的文本并将重写的文本粘贴回去。 如果托盘在您授予权限后显示“↻ 重新启动水银鱼以完成设置”的横幅，请单击它 — 在进程已经启动后授予的权限仅在下一次启动时生效，应用程序会为您重新启动。 ### 使用它 - **点击右-Option**，在文本字段聚焦时重写选定的文本 — 或整个字段，如果未选择任何内容 — 以您自己的学习语调。再次点击右-Option 以要求不同的重写。 - **从托盘图标打开聊天弹出窗口**，向您的本地记忆提问，或获取早晨简报/晚上总结 — 所有这些都由本地模型完全离线回答。 - **暂停捕获**，随时从托盘菜单中。 ### 故障排除 - **"Silverfish.app 无法打开，因为它来自未识别的开发者。"** 构建的 ad-hoc 签名版本会遇到此情况。前往 **系统设置 ▸ 隐私和安全**，找到被阻止的应用程序通知，并点击 **仍然允许**。在 macOS 15（Sequoia）及更高版本上，该按钮有时仅在第一次启动尝试失败后才会出现。 - **Accessibility list 中出现第二个 `silverfishd` 条目。** 水银鱼将后台守护进程与托盘应用程序一起捆绑；根据 macOS 的进程归属行为，守护进程可能会显示为其自己的行项目（“Silverfish” *和* “silverfishd”），而不是被一个权限覆盖 — 两个都需要切换开启。如果捕获似乎没有运行，请检查第二个条目。参见 [`docs/dev/packaging.md`](docs/dev/packaging.md)。 - **每次重建时，无障碍权限都会重置。** 您跳过了 `scripts/make-dev-cert.sh`。临时签名将授予与确切的构建字节绑定，因此任何重新编译都会使其失效；运行 `make-dev-cert.sh` 一次并重新打包，使授予在重建后仍然有效。 ## 高级：CLI 和无头守护进程 如果您不想运行菜单栏应用程序，以下所有内容都是可选的 — 守护进程和 CLI 可以独立工作： ```sh cargo build --release # 一次性检查 ./target/release/silverfish status ./target/release/silverfish ask "昨天我在做什么？" ./target/release/silverfish search "auth migration" ./target/release/silverfish brief morning # 运行守护进程（捕获 + 调度器 + 127.0.0.1:3333 上的 MCP 服务器） ./target/release/silverfishd run ``` 在第一次运行时，授予 **无障碍** 权限时会出现提示（系统设置 → 隐私和安全 → 无障碍），然后重新启动。和打包的应用程序一样，自签名二进制文件在每次重建时都会丢失该权限 — 请参见 [故障排除](#故障排除)。 ## 连接 Claude 客户端（直接 MCP） 如果您正在运行打包的应用程序，`silverfishd` 已经启动（托盘应用程序作为子进程监督它），并且其 MCP 服务器正在 `127.0.0.1:3333` 上监听。按照 MCP 客户端期望的标准格式，将您的 MCP 客户端指向代理二进制文件： ```json { "mcpServers": { "silverfish": { "command": "/path/to/target/release/silverfish-mcp" } } } ``` 提供的工具：`search_memory`、`recent_activity`、`ask_memory`、`get_briefing`、`list_entities`、`search_wiki`、`write_in_my_voice`、`get_identity`。 ## 配置 `~/.silverfish/config.toml`（使用 `silverfish config init` 创建）。主要旋钮：`db_path`（自动从类似应用程序的先前本地内存数据库中采用，如果找到）、`mcp_port`、`capture_interval_ms`、`redact_sensitive`、`[ollama]` 基本 URL + 每个任务的模型路由，以及 `[[capture_blacklist]]` 规则。 ## 开发 ```sh cargo fmt --all cargo clippy --workspace --all-targets -- -D warnings # 严格 + 幼儿园，零警告 cargo test --workspace ``` 参见 `docs/dev/` 以获取 macOS 捕获参考、MCP 合同、栏应用程序行为说明和 [`packaging.md`](docs/dev/packaging.md) 以获取 `.app` 包布局和签名详细信息。 ## License Apache-2.0. 请参阅 [LICENSE](LICENSE)。