MrFoX-MeM

__ __ ______ __ __ __ __ __ __ | \/ | | ____| \ \ / / | \/ | | \/ | | \ / |_ __| |__ ___ \ V /_____| \ / | ___| \ / | | |\/| | '__| __/ _ \ > <______| |\/| |/ _ \ |\/| | | | | | | | | | (_) / . \ | | | | __/ | | | |_| |_|_| |_| \___/_/ \_\ |_| |_|\___|_| |_| ──────────────────────────────────────────────────── 本地优先 · 代码原生内存 · 零令牌 **唯一完全本地、零令牌的AI内存，理解代码库的结构 — 而不仅仅是聊天记录。**     MrFoX-MeM 摄入代码库，构建知识图谱（文件 → 模块 → 符号，具有`导入`/`引用`边），将所有内容存储**本地**（SQLite + 本地嵌入），并仅将相关部分注入到代理的提示中。它适用于您拥有的任何工具 — Claude Code、Cursor、Cline、Windsurf 或任何 MCP 客户端。 > **减少93%的令牌。** 在此代码库中，`/relevant`切片平均为**798令牌**，而读取它所涉及的整个文件约为**~11k令牌** — 已测量，可重复：`python scripts/benchmark.py`。 ### 为什么它不同 | | **MrFoX-MeM** | claude-mem | mem0 | |-----------------------------------|------------------------------|-----------------------|-----------------| | 内存模型 | **代码结构（图）** | 聊天/观察日志 | 个人事实 | | 构建内存的LLM令牌 | **无 — 确定性** | 花费Claude令牌 | 需要 | | 离线运行，无API密钥 | **是** | 部分 | 默认否 | | 提示注入隔离注入 | **是** | — | — | | 多语言代码图 | **是（tree-sitter，可选）**| — | — | ### 检索栈（全本地，CPU） 本地嵌入（`fastembed` / bge-small，具有纯标准库备用） **+ FTS5 BM25**，与**互惠排名融合**融合，通过**个性化PageRank**在代码图上扩展，由可选的**交叉编码器**重新排序，然后修剪到**tiktoken测量的预算** — 并作为不受信任的数据隔离，因此摄入的代码库不能提示注入您的代理。 - **本地优先 / 私有：** 您的代码和所有内存都保留在`data/mrfox.db`中 — 您摄入的内容永远不会被发送到任何地方。唯一的网络接触是在第一次运行时进行的一次性模型下载（使用纯标准库备用跳过它）。 - **零API令牌用于内存操作：** 嵌入 + 排名在您的CPU上运行 — 无API，无密钥。 - **设计节省令牌：** `/relevant`返回一个令牌有界的块，永远不会是整个文件。 - **查看注入的内容：** UI的会话提要显示每个获取加载的内容。 --- ## 架构 ```mermaid flowchart TD A["您 / 代理<br/>Claude Code · Cursor · Cline · Windsurf · 任意MCP客户端"] A -->|"钩子（stdout）<br/>SessionStart · UserPromptSubmit"| H["钩子/*.py<br/>标准库 · 失败开放<br/>从cwd派生项目"] A -->|"MCP（stdio）<br/>get_relevant_context · search · save_context"| M["mcp/（TypeScript）<br/>薄HTTP客户端"] H -->|"HTTP · 127.0.0.1:8077"| C M -->|"HTTP · 127.0.0.1:8077"| C C["核心/ — FastAPI大脑（仅127.0.0.1）<br/>摄入 · 本地嵌入 · 知识图<br/>混合检索：RRF + PageRank + 可选重新排序<br/>可插拔后端 · /relevant · 提供ui/"] C --> DB[("data/mrfox.db — SQLite / WAL<br/>节点 · 边 · 大块 · 事件 · 嵌入<br/>embed_cache · 运行 · 检索")] C -. 提供 .-> UI["ui/ — 静态Cytoscape知识图"] ``` 组件（参见`CONTRACT.md`了解绑定规范）： | 目录 | 它是什么 | |----------|-------------------------------------------------------------------------| | `core/` | Python FastAPI大脑：存储、摄入、嵌入、树、检索、UI。 | | `mcp/` | TypeScript MCP服务器（stdio）— 核心HTTP API上的薄客户端。 | | `ui/` | 静态Web UI（Cytoscape.js，无构建步骤）用于知识树。 | | `hooks/` | Claude Code钩子脚本，用于智能自动注入 + 设置代码段。 | --- ## 先决条件 - **任意操作系统** — macOS、Linux 或 Windows。`cli.py`启动器完全跨平台（无需`make`/`bash`/`open`）；`make`和`run.sh`是Unix便利，`run.ps1`是Windows版本。 - **Python 3.11+** 和 [**uv**](https://docs.astral.sh/uv/) （[按操作系统安装](https://docs.astral.sh/uv/getting-started/installation/)）。 - **Node.js 18+** 和npm（用于MCP服务器）。 - 无需API密钥。嵌入、排名和存储在本地运行 — 默认后端一次性下载一个小模型；纯标准库备用不需要下载。 --- ## 快速开始 > **任意操作系统，无需`make`/`bash`/`curl`：** `python cli.py setup && python cli.py serve-open`。 > 以下`make`目标是Unix便利路径；`run.ps1`是Windows版本。 ### 1. 设置（venv + 核心依赖 + 构建MCP服务器） ```sh make setup ``` 这会创建`.venv`，安装`requirements.txt`，然后在`mcp/`中执行`npm install && npm run build`（生成`mcp/dist/server.js`）。 ### 2. 摄入项目 在一个终端中启动API（下一步），然后在另一个终端中摄入：摄入通过**HTTP API**（`POST /ingest`）进行，因此它与核心内部保持解耦： ```sh make ingest PATH=/abs/path/to/your/project MRFOX_PROJECT=my-project ``` 摄入是**静态解析** — 它从不执行或导入您的代码，跳过二进制文件和超大文件，并**编辑/跳过秘密**（`.env`、`*.pem`、`id_rsa`、AWS密钥等）。 ### 3. 提供核心API + 打开UI ```sh make serve # 然后在浏览器中打开 http://127.0.0.1:8077/ ``` 或者使用一体化便捷启动器（在后台启动API，等待`/health`，打开UI，跟踪日志，并在Ctrl-C时清理）： ```sh ./run.sh ``` UI渲染交互式知识树（Cytoscape.js）：节点按类型着色，点击节点查看其摘要 + 相关事件，以及一个搜索框，突出显示匹配项。 --- ## 注册MCP服务器 MCP服务器是一个stdio进程，它通过核心API公开工具（`get_relevant_context`、`search_knowledge`、`get_knowledge_tree`、`save_context`、`record_decision`）。首先构建它（`make setup`），然后使用您的代理注册它。 > 将`/abs/path/to/MrFoX-MeM`替换为您克隆它的位置。如果您的路径包含空格，请将其作为单个引用字符串保留。 ### Claude Code ```sh claude mcp add mrfox-mem \ --env MRFOX_API=http://127.0.0.1:8077 \ --env MRFOX_PROJECT=my-project \ -- node "/abs/path/to/MrFoX-MeM/mcp/dist/server.js" ``` 使用`claude mcp list`验证。使用`make mcp`独立启动服务器进行调试。 ### Cursor 添加到`~/.cursor/mcp.json`（或项目的`.cursor/mcp.json`）： ```json { "mcpServers": { "mrfox-mem": { "command": "node", "args": ["/abs/path/to/MrFoX-MeM/mcp/dist/server.js"], "env": { "MRFOX_API": "http://127.0.0.1:8077", "MRFOX_PROJECT": "my-project" } } } } ``` ### Windsurf · GitHub Copilot · Gemini CLI · Cline · 其他 MCP服务器是客户端和操作系统无关的 — 相同的`node .../mcp/dist/server.js` + 两个环境变量在所有地方都适用；只有**配置文件位置和根键不同**每个客户端（例如，Copilot/VS Code使用根键`servers`，而不是`mcpServers`）。复制粘贴，网络验证注册所有**五个客户端**在macOS / Linux / Windows上： > **→ `integrations/MCP-CLIENTS.md`** — 准确的配置文件路径 + JSON/CLI每个客户端，每个操作系统。 **克劳德代码的智能自动注入：** 只有克劳德代码有钩子系统，因此只有它获得**完全自动**的上下文注入（如下）。对于Cursor / Copilot / Gemini CLI / Windsurf，发送一个小的**原生规则文件**，告诉代理在任务开始时调用`get_relevant_context` MCP工具（以及决策时的`save_context`）。准备好的模板 + 它们放置的位置： > **→ `integrations/AUTO-CONTEXT.md`** 和 **`integrations/rules/`** （cursor.mdc，copilot-instructions.md，GEMINI.md，windsurf.md，CLAUDE.snippet.md）。 --- ## 连接克劳德代码钩子（智能自动注入） 钩子调用`/relevant`并打印一个令牌有界的上下文块到stdout，克劳德代码注入： - **`hooks/session_start.py`** — 在**SessionStart**：检测您的git分支 + 最近的提交主题，合成提示，询问`/relevant`（预算≈800令牌），打印上下文。 - **`hooks/user_prompt.py`** — 在**UserPromptSubmit**：从钩子的JSON stdin读取提示，询问`/relevant?...&budget_tokens=1200`，打印上下文。 两者**失败打开**：如果API关闭，它们以退出0静默退出，永远不会阻止您的会话。 要连接它们，请从`hooks/settings.snippet.json`复制`hooks`块到您的`.claude/settings.json`（项目级`<project>/.claude/settings.json`或用户级`~/.claude/settings.json`）并**调整绝对路径**： ```jsonc { "env": { "MRFOX_API": "http://127.0.0.1:8077", "MRFOX_PROJECT": "my-project" }, "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "python3 '/abs/path/to/MrFoX-MeM/hooks/session_start.py'", "timeout": 10 } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "python3 '/abs/path/to/MrFoX-MeM/hooks/user_prompt.py'", "timeout": 10 } ] } ] } } ``` 钩子从环境中读取`MRFOX_API`和`MRFOX_PROJECT` — 在代码段的`env`块（上）或shell中设置它们。参见`.env.example`。 --- ## 查看获取的内容 — 会话提要 每次代理启动对话或发送提示，MrFoX-MeM记录获取并在UI的**会话**选项卡中显示给您 — 因此您可以*看到*确切加载了哪些内存，而不仅仅是相信某些事情发生了。 - **实时提要** — 每个`/relevant`获取都作为一个条目出现：触发器（会话启动/提示/mcp/ui），提示，令牌计数，以及哪些知识树节点 + 过去的决定被注入。点击条目以突出显示图中的那些节点。提要在选项卡打开时自动刷新（~3s），并且不打开时暂停。 - **运行** — 一个*运行*将一个对话的获取和保存的决定分组到一个单独的时间线（轻量级“工作流”视图）。SessionStart钩子为每个对话打开一个运行；后续提示和保存的决定附加到它。 底层通过`GET /retrievals`，`GET /runs`和`GET /run/{id}`支持，使用`/relevant`自动记录（参见`CONTRACT-FEED.md`）。这里不需要LLM令牌 — 全部是本地的。 --- ## Make目标 | 目标 | 执行 | |---------------------------------|--------------------------------------------------------------| | `make setup` | `uv venv` + 安装核心依赖 + `npm install && npm run build` | | `make serve` | 运行核心API：`uvicorn core.api:app --host 127.0.0.1 --port 8077` | | `make ingest PATH=/abs/dir` | 通过`curl`为项目目录执行`POST /ingest`（也使用`DIR=`） | | `make mcp` | 运行`node mcp/dist/server.js` | | `make clean` | 删除venv，`node_modules`，`dist`，`__pycache__`，`data/*.db` | --- ## 扩展它（可插拔后端） 嵌入器和重新排序器在稳定的`Protocol`接口（`core/backends.py`）后面注册，按功能选择，支持降级 - 新模型是插件，无需核心编辑： ```python from core import backends @backends.register("embedder", "my-model") def _make(): return MyEmbedder() # 具有.backend，.dim，和.embed(texts) ``` 在运行时选择后端而无需修改代码（首先加载的获胜）： ```sh MRFOX_EMBEDDER=hashing # 或例如“fastembed,hashing” MRFOX_RERANKER=fastembed # 重新排序器默认为关闭（参见scripts/eval.py） ``` `GET /health`列出已注册的内容。相同的注册表将托管向量索引（sqlite-vec/usearch）和语言解析器后端。 --- ## 部署到另一台机器 所有内容都是路径相对或派生的 — 除了您克隆它之外，不需要每个机器的源代码编辑。 **1. 克隆 + 设置（macOS / Linux / Windows）：** ```sh git clone <repo-url> MrFoX-MeM && cd MrFoX-MeM python cli.py setup # venv + 依赖 + 构建MCP服务器 （或：make setup） ``` **2. 运行服务器** — 前台或作为一个始终开启的服务： ```sh python cli.py serve # 前台（或：make serve） bash scripts/install-service.sh # 后台服务：macOS launchd / Linux systemd --user``` > macOS：服务故意记录到`/tmp`，以便存储库位于`~/Documents`或`~/Desktop`是TCC保护的，因此launchd无法在那里打开日志文件（失败`EX_CONFIG`/78）。 **3. 使其对您的代理可用：```sh # 全局MCP — 每个项目，工具按需，项目由目录派生： claude mcp add mrfox-mem -s user --env MRFOX_API=http://127.0.0.1:8077 \ -- node "$PWD/mcp/dist/server.js" # 斜杠命令在任何存储库中都可用（在Claude Code中输入/mrfox-mem）: cp integrations/commands/mrfox-mem.md ~/.claude/commands/mrfox-mem.md ``` **4. 摄入项目（每个存储库可选）：```sh cd /path/to/project && /mrfox-mem # 在Claude Code中（摄入当前目录） # 或从shell： make ingest PATH=/path/to/project MRFOX_PROJECT=name ``` **5. （可选）自动每个提示注入** — 复制`integrations/`模板（`.mcp.json` + `.claude/settings.json`)到存储库，或添加SessionStart / UserPromptSubmit钩子到`~/.claude/settings.json`全局。钩子派生项目目录，因此一个全局安装服务于每个存储库。（如果您已经运行另一个始终开启的存储注入器，请改为每个项目以避免重复注入。） ### 环境旋钮（可选） | 变量 | 默认值 | 效果 | |---|---|---| | `MRFOX_API` | `http://127.0.0.1:8077` | 核心API基址（仅限环回） | | `MRFOX_PROJECT` | *(派生)* | 固定项目；未设置 → git-root/cwd basename的slug | | `MRFOX_PORT` | `8077` | 服务器端口 | | `MRFOX_EMBEDDER` | `fastembed,hashing` | 嵌入器偏好顺序 | | `MRFOX_RERANKER` | `fastembed,none` | 重新排序器偏好（默认为关闭） | | `MRFOX_ALLOWED_ROOTS` | *(无)* | 将摄入限制到这些根目录（以`os.pathsep`分隔） | --- ## 安全说明 MrFoX-MeM是一个单用户、**仅限localhost**的工具。安全性是内置的，而不是附加的： - **仅绑定到`127.0.0.1`** — 绝不绑定到`0.0.0.0`。由于没有身份验证，因此不要将端口暴露给主机或指向localhost地址以外的`MRFOX_API`。 - **CORS** 锁定到 `localhost` / `127.0.0.1`。 - **摄入时秘密删除：** 匹配秘密模式的文件（`.env`， `*.pem`， `id_rsa`，AWS 密钥，...）被跳过/删除；原始秘密值从未存储在摘要或大块中。 - **无代码执行：** 摄入是静态解析的 - 它从不导入/执行项目代码，并且代码内容或用户输入中没有`eval`/`exec`。SQL 是参数化的。 - **路径安全性：** `/ingest` 验证路径（绝对的，存在，是目录），并拒绝符号链接逃逸/任意文件系统遍历。 - **资源上限：** 最大文件大小，最大文件数，二进制文件跳过 - 以限制资源使用。 - **钩子安全：** 钩子是fail-open且安全的；stdlib only，`subprocess.run([...], shell=False, timeout=…)`用于git，无`eval`/`exec`未受信任内容，输出上限，它们从不记录秘密。 --- 参见 `CONTRACT.md` 了解完整的API接口、模式和组件契约。