MemWhale

<p align="center"> <img src="assets/memorywhale-logo-sm.png" alt="MemoryWhale logo" width="160" /> </p> <h1 align="center">MemoryWhale</h1> <p align="center"><strong>Persistent local debugging memory for developers and coding agents.</strong></p> <p align="center" dir="ltr"><a href="README.md">English README</a> · <a href="docs/i18n/README.ar.md" lang="ar">العربية</a> · <a href="docs/i18n/README.de.md" lang="de">Deutsch</a> · <a href="docs/i18n/README.fr.md">README français</a> · <a href="docs/i18n/README.zh-CN.md">简体中文 README</a> · <a href="docs/i18n/README.zh-TW.md">繁體中文 README</a> · <a href="docs/i18n/README.ko.md">한국어 README</a> · <a href="docs/i18n/README.ja.md">日本語 README</a> · <a href="docs/i18n/README.es.md" lang="es">Español</a> · <a href="docs/i18n/README.pt-BR.md" lang="pt-BR">Português (Brasil)</a></p> <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/local--first-no%20upload-168a69" alt="local-first, nothing uploaded"/> </p> <p align="center"> <img src="assets/recall-demo.gif" alt="A build error comes back; mw context reports it was hit twice and mw search returns the saved fix." width="820" /> </p> **You hit an error. MemoryWhale remembers you've seen it before, and hands back the fix.** MemoryWhale records what actually happened while you debug: commands, output, failures, and the fixes that worked. It stores that evidence in local SQLite so you and your coding agents can find it after the terminal, SSH connection, or agent session is gone. It works with 19 coding agents through MCP, with no account and nothing uploaded. > On [LongMemEval](benchmarks/longmemeval/README.md), a public long-term memory benchmark, search puts a > session holding the answer in its top 5 for **97%** of 470 questions > (retrieval only, no model). > > In a controlled evaluation on project-specific bugs, an agent solved **25%** > without memory and **96%** with it. These are synthetic tasks that > demonstrate the mechanism, not a field study; see > [how it was measured](benchmarks/README.md). **MemoryWhale 0.22.0: Recall Before It Fails · October 21, 2026.** The CLI, web UI, and desktop app share product version 0.22.0; the reusable Rust core is version 0.10.0. See the [release notes](https://github.com/wuisabel-gif/MemWhale/blob/v0.22.0/docs/releases/0.22.0.md) for the upgrade guide. Opening a store migrates it from schema 10 to 16. <p align="center"> <img src="assets/proactive-recall.gif" alt="An agent's make fails with an xcrun error; the capture hook answers that this error was seen once and the fix was xcode-select --install." width="820" /> </p> **Want to contribute?** Start with the [Start here issue](https://github.com/wuisabel-gif/MemWhale/issues/317). Many tasks need no Rust, including translation reviews and documentation fixes. ## Why MemoryWhale - **Remember what actually happened.** Preserve the command, environment, output, failure, and lesson—not only a shell-history line. - **Use one memory across coding agents.** Any compatible stdio MCP client can read and write the same local memory through `mw-mcp`. - **Keep development history local.** MemoryWhale works without an account, hosted service, or per-token memory bill. MemoryWhale records development experience, not everything. It is a debugging memory layer, not an autonomous coding agent, a general-purpose personal memory system, or a replacement for project documentation. ## New in Agent-Native Memory - **Connect and inspect agents.** Install Claude Code or Rho MCP access, capture hooks, and memory-use guidance with `mw integrate`; `mw doctor` checks MCP, hooks, and skills independently. - **Keep provenance explicit.** Schema 10 stores command agents as `claude`, `rho`, or `NULL`. The display/filter label `terminal` means terminal/manual or legacy provenance, not proof that a human ran it. Agent identity is separate from source type such as `command`, `session`, or `note`. - **Share a repository, distinguish worktrees.** Canonical repository IDs group linked worktrees while preserving each worktree root and existing project tags. Discovery reads local Git metadata, not a remote service. - **Use local interfaces.** `mw-serve` provides HTTP MCP at `POST /mcp`; `mw-serve --api` opts into the read-only JSON API. Both use the dashboard's listener; non-loopback access requires a token. - **Fetch GitHub context explicitly.** `mw github context <pr>` reads PR metadata, checks, and reviews through your existing `gh` login. It prints bounded, redacted context without checking out code or automatically saving it to memory. There is no background GitHub sync. ## Install Prebuilt binaries are available for Linux x86_64/aarch64 and macOS: ```bash ( set -eu installer="$(mktemp)" trap 'rm -f "$installer"' EXIT curl -fsSL https://raw.githubusercontent.com/wuisabel-gif/MemWhale/7c3864c743cec9a8fa813dcc0b2459cc2859c849/install.sh -o "$installer" printf '%s %s\n' '3e0cad72b29c1894d5ff5f7c30b099537f96501801c14b6320c12e169a3ac8d6' "$installer" | shasum -a 256 -c - sh "$installer" ) ``` Or install with Cargo or Homebrew: ```bash cargo install memorywhale-cli brew tap wuisabel-gif/memorywhale https://github.com/wuisabel-gif/MemWhale brew install memorywhale ``` After installation or upgrade, check the version and local setup: ```bash mw --version mw doctor ``` Windows users can run MemoryWhale inside [WSL](https://learn.microsoft.com/windows/wsl/). See the [getting-started guide](docs/guides/getting-started.md) for package installs, PATH setup, and platform notes. **Desktop app.** For a window instead of a terminal, the MemoryWhale app shows what your agents were told, the commands and output behind it, and your lessons, and stays in the menu bar to announce each new note. It ships with each release from 0.23 on; see the [desktop guide](docs/guides/desktop.md). ## Sixty-second example ```bash mw global on # capture future interactive shell commands mw-run -- cargo check # capture one command and its output mw remember "the linker needed libssl-dev" mw search "linker error" # recover the failure and its fix mw context --last-error # compact context for any agent or chat mw pet # check your memory store's mood ```  For longer work, `mw --live` records a crash-resistant shell session. `mw tui` opens an interactive terminal browser, while `mw-serve` starts the local web dashboard. ## How it works ```text CAPTURE MEMORY RETRIEVAL shell / mw-run ──────► local SQLite ────────► search / context agent hooks ─────────► evidence + lessons ──► similar failures │ INTERFACES CLI / MCP / TUI / Web / Desktop ``` Capture and retrieval are independent. MCP gives an agent access to existing memory; it does not automatically record normal terminal activity. See the [architecture](docs/architecture.md) and [capture concept](docs/concepts/capture.md) for the complete model. ## Works with your coding agent `mw-mcp` is the common integration seam: a local stdio MCP server exposing six memory tools, also available over HTTP through `mw-serve`. Existing guides cover Claude Code, Rho, Claude Desktop, Cursor, VS Code / GitHub Copilot, Windsurf, Zed, Codex CLI, Cline, Continue, Gemini CLI, Goose, OpenClaw, CrowClaw, Hermes Agent, and other compatible clients. ```bash mw integrate claude mw integrate rho mw doctor ``` Clients do not all provide the same capabilities. MCP supports memory access; automatic execution capture requires a client-specific hook. The [integration matrix](integrations/README.md) distinguishes access, capture, and memory-use guidance and links every verified setup guide. Rho's current hook payload lacks command text and stdout: failures can be recorded as metadata with a sentinel command; successful calls without command text are skipped. The [cross-agent handoff demo](docs/guides/cross-agent-handoff.md) uses fixtures and a simulated Rho client against real MCP, not live agents or a verified Cargo fix. The bundled skill guides memory use; it does not implement automatic task-start recall, failure lookup, or pre-compaction saving. Those lifecycle decisions remain with the client. MCP-authored lessons are pending review by default. ## Who is MemoryWhale for? MemoryWhale is for developers whose debugging context is scattered across terminal scrollback, shell history, machines, and temporary agent sessions. It is especially useful when you: - debug builds, dependencies, Git, environments, or deployments; - use coding agents across sessions or switch between tools; - work over SSH or across multiple development machines; - want recurring failures and their fixes to remain searchable; - prefer local storage over a hosted memory service. See [Use cases](docs/concepts/use-cases.md) for each of these as an end-to-end scenario with real commands. ## Documentation - [Documentation map](docs/README.md) - [Getting started](docs/guides/getting-started.md) - [`mw pet` reference](docs/reference/pet.md) - [Terminal capture](docs/guides/terminal-capture.md) - [Desktop app](docs/guides/desktop.md) - [Agent memory](docs/guides/agent-memory.md) - [CLI reference](docs/reference/cli.md) - [Local JSON API](docs/reference/api.md) - [MCP reference](docs/reference/mcp.md) - [Security and local threat model](docs/SECURITY.md) - [Ecosystem](docs/ECOSYSTEM.md) — Delphin, ContextGC, and MemoryWhale together - [Integration guides and capability matrix](integrations/README.md) ## Contributing MemoryWhale accepts changes that improve capturing, preserving, retrieving, or sharing development experience. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the scope rule, development commands, and pull-request checklist. New contributors can pick a task from the [Start here issue](https://github.com/wuisabel-gif/MemWhale/issues/317). Every pull request also gets an automated review from [Second-Opinion](https://github.com/wuisabel-gif/second-opinion), a GitHub Action from a sister project by the same maintainer. Its comments are suggestions; a person decides what to act on. Setup and limits are in the [Second-Opinion guide](integrations/second-opinion/README.md). Licensed under the [MIT License](LICENSE).