内容
<p align="center">
<img src="assets/memorywhale-logo-sm.png" alt="MemoryWhale logo" width="160" />
</p>
<h1 align="center">MemoryWhale</h1>
<p align="center">
<a href="https://github.com/wuisabel-gif/MemWhale/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/wuisabel-gif/MemWhale/ci.yml?branch=main&label=CI&logo=github" alt="CI"/></a>
<a href="https://github.com/wuisabel-gif/MemWhale/releases"><img src="https://img.shields.io/github/v/release/wuisabel-gif/MemWhale?color=2b43dd&label=release" alt="release"/></a>
<a href="https://crates.io/crates/memorywhale-cli"><img src="https://img.shields.io/crates/v/memorywhale-cli?color=2b43dd&label=crates.io" alt="crates.io"/></a>
<img src="https://img.shields.io/badge/license-MIT-2b43dd" alt="license MIT"/>
<img src="https://img.shields.io/badge/Rust-000000?logo=rust&logoColor=white" alt="Rust"/>
<img src="https://img.shields.io/badge/SQLite-003B57?logo=sqlite&logoColor=white" alt="SQLite"/>
<img src="https://img.shields.io/badge/local--first-no%20upload-168a69" alt="local-first, nothing uploaded"/>
<img src="https://img.shields.io/badge/Runs%20on-Jetson-76B900?logo=nvidia&logoColor=white" alt="Runs on Jetson"/>
</p>
<p align="center">
🐬 <b>姊妹项目：</b> <a href="https://github.com/wuisabel-gif/Delphin">Delphin</a> — 双工通信层（在智能体思考时与其对话）。MemoryWhale 是内存层 — 参见 <a href="ECOSYSTEM.md">ECOSYSTEM.md</a>。
</p>
Shell 历史记录模糊地记住命令。它不保存调试情况：机器、工作目录、确切的标志、错误输出以及关于尝试的说明。当终端崩溃、SSH 会话断开或滚动条滚走时，该上下文就会消失 — 而您（或您的 AI 智能体）重新调试已经解决的问题。
**MemoryWhale 将命令、参数、输出、错误和整个会话记录到本地 SQLite 中，以便已经失败的内容仍然可搜索** — 跨越崩溃、SSH 会话断开和机器切换。所有内容都保留在您的机器上；不会上传任何内容。
<p align="center">
<img src="assets/demo.gif" alt="使用 mw-run 捕获失败的构建，然后使用 mw context 重新调用其确切的错误" width="820" />
</p>
## 安装
Linux x86_64/aarch64（包括 Jetson）和 macOS 的预编译二进制文件 — 无需 Rust 工具链：
```bash
curl -fsSL https://raw.githubusercontent.com/wuisabel-gif/MemWhale/main/install.sh | sh
```
安装到 `~/.local/bin`（可使用 `PREFIX=/usr/local` 重写）。其他方式：
```bash
# cargo（仅构建 CLI — 无 Tauri/GTK）
cargo install memorywhale-cli
# Homebrew（macOS/Linux）
brew tap wuisabel-gif/memorywhale https://github.com/wuisabel-gif/MemWhale
brew install memorywhale
```
Debian/Ubuntu/Jetson：从 [发布页面](https://github.com/wuisabel-gif/MemWhale/releases) 获取 `.deb` 文件并运行 `sudo apt install ./memorywhale_*.deb`。
首次运行：输入 `mw` — 它会自我解释并提供自动记录每个新终端的选项。这就是整个设置。
## 快速体验
```bash
mw --notes "Jetson build debugging" # 记录整个 shell 会话（退出停止）
mw --live # 同上，但自动保存 — 能够在 SSH 会话断开后继续运行
mw-run -- cargo check # 运行一个命令，捕获其输出 + 退出代码
mw list && mw show 1 # 检查已记录的会话
mw search "linker error" # 在命令、输出和记录中查找
mw context --last-error # 最近的失败及其确切的错误
mw-serve # 网页仪表盘（可在无桌面环境的主机上运行，例如 Jetson）
```
每个运行的命令都存储命令、每个参数作为可搜索的行、工作目录、退出代码、标准输出、标准错误和您的备注。捕获的输出会过滤常见的机密格式（令牌、密钥、`password=`）后再保存到 SQLite 中。完整的标志和帮助：[docs/CLI.md](docs/CLI.md)。
## AI 智能体
编码智能体会忘记每次会话之间的所有内容。`mw-mcp` 是本地内存上的模型上下文协议服务器 — 注册一次，Claude Code/Codex/Cursor 就可以直接查询过去的失败，而不是重新推导：
```bash
claude mcp add memorywhale -- mw-mcp
```
或者，无需任何设置，将紧凑的摘要粘贴到任何智能体或聊天中：
```bash
mw context --last-error
```
参见 [integrations/](integrations/README.md) 了解 MCP 工具和 Claude Code 技能，该技能知道何时调用内存。
## 网页仪表盘（单机或团队）
`mw-serve` 将您的内存作为本地网页提供服务 — 在无桌面环境的主机上很有用，桌面环境无法打开，并且适用于团队：在具有数据的机器上运行它，网络上的每个人都看到相同的错误，而不是询问复制粘贴。
```bash
mw-serve # 绑定 0.0.0.0:7071
# 本机： http://localhost:7071/
# 在局域网上： http://<machine-ip>:7071/ （使用 hostname -I 查找 IP 地址）
```
在共享或不受信任的网络上，需要令牌 — 第一次 `?token=` 访问会设置一个 cookie，以便链接继续有效：
```bash
MEMORYWHALE_TOKEN=some-shared-secret mw-serve
# 打开一次： http://<machine-ip>:7071/?token=some-shared-secret
```
仪表盘列出命令运行和会话，为每个会话打开一个可读的详情页（包含从历史记录中挖掘的建议下一步骤），在启动时自动恢复中断的记录，并包含一个 `/graph` 视图：每个命令都是一个节点 **按运行频率大小**，而两个或多个命令共享的参数成为 **桥梁** （橙色），揭示哪些工具共享工作流。
<p align="center">
<img src="assets/knowledge-graph.svg" alt="MemoryWhale 知识图谱" width="560" />
</p>
## 跨终端的项目
每个 `mw` 记录一个终端。使用相同的 `project:<name>` 在备注中标记相关的会话，仪表盘会将它们合并为一个时间有序的时间线：
```bash
mw --notes "project:pop_playlist git history" # 终端 1
mw --notes "project:pop_playlist server testing" # 终端 2
```
要无需输入 `mw` 即可自动记录每个新终端，请使用 `mw global on`（`mw global off` 停止）。完整的操作程序：[SOP.md](SOP.md)。
## 在机器之间共享内存
内存是每个机器独有的，但您可以移动它：
```bash
mw export project:demo # 捆绑：Markdown + JSON + SQLite 副本
mw import path/to/bundle # 合并到此机器（跳过重复项）
mw push jetson # 快照 → scp → 远程 mw import，任意 SSH 主机
```
没有任何第三方参与；它使用您自己的 `scp`/`ssh`。
## 为什么我创建了它
我在一个 Jetson 和我的笔记本电脑上运行同一个机器人仓库 — 用于 USC 自主水下车辆项目。代码库是共享的，但终端历史记录不是。命令、错误、构建日志和调试尝试都存在于运行它们的机器上。
这对 AI 辅助调试和团队协作来说是一个真正的问题。如果队友询问为什么某事失败，我不总是能检索到解释它的终端滚动条。如果终端关闭或机器更改，确切的上下文就会消失：运行了什么命令、什么标志、返回了什么错误、已经尝试了什么。
目标很简单：使终端感觉像具有长期记忆一样，以便我可以搜索旧尝试、在关闭后恢复确切的错误，并为 AI 智能体提供足够的历史记录，以便在不重新开始的情况下继续调试。
## 开发
仓库是一个 Cargo 工作区：`crates/mw-cli`（CLI，无 GUI 依赖项）、`crates/mw-memory`（检索）和 `src-tauri`（桌面应用程序）。
```bash
cargo build -p memorywhale-cli # 仅 CLI — 快速，无需 GTK/WebKit
npm install && npm run tauri:dev # 完整的桌面应用程序（需要 Tauri 系统依赖项）
```
- Linux/Jetson 系统依赖项、shell 钩子、systemd 仪表盘服务、补全、man 页面：[linux/README.md](linux/README.md)（`linux/install.sh --all`）
- 在 Jetson 上设置时遇到的实际问题和解决方法： [DEBUG.md](DEBUG.md)
## 致谢和学习资料
MemoryWhale 在研究了两个原始项目后创建：
- **CodeWhale** by **Hmbown**: <https://github.com/Hmbown/CodeWhale>
- **MemPalace** by the **MemPalace project**: <https://github.com/MemPalace/mempalace>
CodeWhale 教会了我，作为一个 Rust-first 开发工具，可以如何组织终端工作流、命令执行、安全边界和面向智能体的运行时理念。MemPalace 教会了我本地优先的内存：在您自己的机器上保留技术上下文，您仍然可以在几个月后搜索它。MemoryWhale 是我自己的项目，从这些经验中构建；它不依赖于那些仓库。
## 项目治理
- [理念](PHILOSOPHY.md) — 项目背后的通信和内存理念。
- [贡献](CONTRIBUTING.md) — 如何做出有用的更改。
- [行为准则](CODE_OF_CONDUCT.md) — 协作的标准。
- [宪章](CONSTITUTION.md) — 在相同的原则、职责和保护措施下管理用户、贡献者、维护者和 AI 智能体。
