Skip to content
Back to search

MemWhale

Persistent, local memory for developers and their coding agents. Records commands, output, errors, and the fixes that worked into SQLite and serves them over MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/wuisabel-gif/MemWhale with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/wuisabel-gif/MemWhale'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wuisabel-gif--memwhale/badge.svg)](/listings/wuisabel-gif--memwhale)

HTML

<a href="/listings/wuisabel-gif--memwhale"><img src="/api/listings/wuisabel-gif--memwhale/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prebuilt binaries are available for Linux x86_64/aarch64 and macOS:

(
  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:

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:

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 230 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="assets/memorywhale-logo-sm.png" alt="MemoryWhale logo" width="160" />
  3. </p>
  4. <h1 align="center">MemoryWhale</h1>
  5. <p align="center"><strong>Persistent local debugging memory for developers and coding agents.</strong></p>
  6. <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>
  7. <p align="center">
  8. <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>
  9. <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>
  10. <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>
  11. <img src="https://img.shields.io/badge/license-MIT-2b43dd" alt="license MIT"/>
  12. <img src="https://img.shields.io/badge/local--first-no%20upload-168a69" alt="local-first, nothing uploaded"/>
  13. </p>
  14. <p align="center">
  15. <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" />
  16. </p>
  17. **You hit an error. MemoryWhale remembers you've seen it before, and hands back the fix.**
  18. MemoryWhale records what actually happened while you debug: commands, output,
  19. failures, and the fixes that worked. It stores that evidence in local SQLite so
  20. you and your coding agents can find it after the terminal, SSH connection, or
  21. agent session is gone. It works with 19 coding agents through MCP, with no
  22. account and nothing uploaded.
  23. > On [LongMemEval](benchmarks/longmemeval/README.md), a public long-term memory benchmark, search puts a
  24. > session holding the answer in its top 5 for **97%** of 470 questions
  25. > (retrieval only, no model).
  26. >
  27. > In a controlled evaluation on project-specific bugs, an agent solved **25%**
  28. > without memory and **96%** with it. These are synthetic tasks that
  29. > demonstrate the mechanism, not a field study; see
  30. > [how it was measured](benchmarks/README.md).
  31. **MemoryWhale 0.28.0: Stopped Before It Fails · November 17, 2026.**
  32. The CLI, web UI, and desktop app share product version 0.28.0; the reusable
  33. Rust core is version 0.13.0. See the [release notes](https://github.com/wuisabel-gif/MemWhale/blob/v0.28.0/docs/releases/0.28.0.md)
  34. for the upgrade guide. Opening a store migrates it from schema 10 to 17.
  35. <p align="center">
  36. <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" />
  37. </p>
  38. **Want to contribute?** Start with the [Start here issue](https://github.com/wuisabel-gif/MemWhale/issues/317).
  39. Many tasks need no Rust, including translation reviews and documentation fixes.
  40. ## Why MemoryWhale
  41. - **Remember what actually happened.** Preserve the command, environment,
  42. output, failure, and lesson—not only a shell-history line.
  43. - **Use one memory across coding agents.** Any compatible stdio MCP client can
  44. read and write the same local memory through `mw-mcp`.
  45. - **Keep development history local.** MemoryWhale works without an account,
  46. hosted service, or per-token memory bill.
  47. MemoryWhale records development experience, not everything. It is a debugging
  48. memory layer, not an autonomous coding agent, a general-purpose personal memory
  49. system, or a replacement for project documentation.
  50. ## New in Agent-Native Memory
  51. - **Connect and inspect agents.** Install Claude Code or Rho MCP access,
  52. capture hooks, and memory-use guidance with `mw integrate`; `mw doctor`
  53. checks MCP, hooks, and skills independently.
  54. - **Keep provenance explicit.** Schema 10 stores command agents as `claude`,
  55. `rho`, or `NULL`. The display/filter label `terminal` means terminal/manual
  56. or legacy provenance, not proof that a human ran it. Agent identity is
  57. separate from source type such as `command`, `session`, or `note`.
  58. - **Share a repository, distinguish worktrees.** Canonical repository IDs
  59. group linked worktrees while preserving each worktree root and existing
  60. project tags. Discovery reads local Git metadata, not a remote service.
  61. - **Use local interfaces.** `mw-serve` provides HTTP MCP at `POST /mcp`;
  62. `mw-serve --api` opts into the read-only JSON API. Both use the dashboard's
  63. listener; non-loopback access requires a token.
  64. - **Fetch GitHub context explicitly.** `mw github context <pr>` reads PR
  65. metadata, checks, and reviews through your existing `gh` login. It prints
  66. bounded, redacted context without checking out code or automatically saving
  67. it to memory. There is no background GitHub sync.
  68. ## Install
  69. Prebuilt binaries are available for Linux x86_64/aarch64 and macOS:
  70. ```bash
  71. (
  72. set -eu
  73. installer="$(mktemp)"
  74. trap 'rm -f "$installer"' EXIT
  75. curl -fsSL https://raw.githubusercontent.com/wuisabel-gif/MemWhale/7c3864c743cec9a8fa813dcc0b2459cc2859c849/install.sh -o "$installer"
  76. printf '%s %s\n' '3e0cad72b29c1894d5ff5f7c30b099537f96501801c14b6320c12e169a3ac8d6' "$installer" | shasum -a 256 -c -
  77. sh "$installer"
  78. )
  79. ```
  80. Or install with Cargo or Homebrew:
  81. ```bash
  82. cargo install memorywhale-cli
  83. brew tap wuisabel-gif/memorywhale https://github.com/wuisabel-gif/MemWhale
  84. brew install memorywhale
  85. ```
  86. After installation or upgrade, check the version and local setup:
  87. ```bash
  88. mw --version
  89. mw doctor
  90. ```
  91. Windows users can run MemoryWhale inside
  92. [WSL](https://learn.microsoft.com/windows/wsl/). See the
  93. [getting-started guide](docs/guides/getting-started.md) for package installs,
  94. PATH setup, and platform notes.
  95. **Desktop app.** For a window instead of a terminal, the MemoryWhale app shows
  96. what your agents were told, the commands and output behind it, and your
  97. lessons, and stays in the menu bar to announce each new note. It ships with
  98. each release from 0.23 on; see the [desktop guide](docs/guides/desktop.md).
  99. ## Sixty-second example
  100. ```bash
  101. mw global on # capture future interactive shell commands
  102. mw-run -- cargo check # capture one command and its output
  103. mw remember "the linker needed libssl-dev"
  104. mw search "linker error" # recover the failure and its fix
  105. mw context --last-error # compact context for any agent or chat
  106. mw pet # check your memory store's mood
  107. ```
  108. ![mw pet mood demo](assets/pet-demo.gif)
  109. For longer work, `mw --live` records a crash-resistant shell session. `mw tui`
  110. opens an interactive terminal browser, while `mw-serve` starts the local web
  111. dashboard.
  112. ## How it works
  113. ```text
  114. CAPTURE MEMORY RETRIEVAL
  115. shell / mw-run ──────► local SQLite ────────► search / context
  116. agent hooks ─────────► evidence + lessons ──► similar failures
  117. │
  118. INTERFACES
  119. CLI / MCP / TUI / Web / Desktop
  120. ```
  121. Capture and retrieval are independent. MCP gives an agent access to existing
  122. memory; it does not automatically record normal terminal activity. See the
  123. [architecture](docs/architecture.md) and
  124. [capture concept](docs/concepts/capture.md) for the complete model.
  125. ## Works with your coding agent
  126. `mw-mcp` is the common integration seam: a local stdio MCP server exposing six
  127. memory tools, also available over HTTP through `mw-serve`. Existing guides
  128. cover Claude Code, Rho, Claude Desktop, Cursor, VS
  129. Code / GitHub Copilot, Windsurf, Zed, Codex CLI, Cline, Continue, Gemini CLI,
  130. Goose, OpenClaw, CrowClaw, Hermes Agent, and other compatible clients.
  131. ```bash
  132. mw integrate claude
  133. mw integrate rho
  134. mw doctor
  135. ```
  136. Clients do not all provide the same capabilities. MCP supports memory access;
  137. automatic execution capture requires a client-specific hook. The
  138. [integration matrix](integrations/README.md) distinguishes access, capture, and
  139. memory-use guidance and links every verified setup guide.
  140. Rho's current hook payload lacks command text and stdout: failures can be
  141. recorded as metadata with a sentinel command; successful calls without command
  142. text are skipped. The [cross-agent handoff demo](docs/guides/cross-agent-handoff.md)
  143. uses fixtures and a simulated Rho client against real MCP, not live agents or
  144. a verified Cargo fix.
  145. The bundled skill guides memory use; it does not implement automatic task-start
  146. recall, failure lookup, or pre-compaction saving. Those lifecycle decisions
  147. remain with the client. MCP-authored lessons are pending review by default.
  148. ## Who is MemoryWhale for?
  149. MemoryWhale is for developers whose debugging context is scattered across
  150. terminal scrollback, shell history, machines, and temporary agent sessions. It
  151. is especially useful when you:
  152. - debug builds, dependencies, Git, environments, or deployments;
  153. - use coding agents across sessions or switch between tools;
  154. - work over SSH or across multiple development machines;
  155. - want recurring failures and their fixes to remain searchable;
  156. - prefer local storage over a hosted memory service.
  157. See [Use cases](docs/concepts/use-cases.md) for each of these as an
  158. end-to-end scenario with real commands.
  159. ## Documentation
  160. - [Documentation map](docs/README.md)
  161. - [Getting started](docs/guides/getting-started.md)
  162. - [`mw pet` reference](docs/reference/pet.md)
  163. - [Terminal capture](docs/guides/terminal-capture.md)
  164. - [Desktop app](docs/guides/desktop.md)
  165. - [Agent memory](docs/guides/agent-memory.md)
  166. - [CLI reference](docs/reference/cli.md)
  167. - [Local JSON API](docs/reference/api.md)
  168. - [MCP reference](docs/reference/mcp.md)
  169. - [Security and local threat model](docs/SECURITY.md)
  170. - [Ecosystem](docs/ECOSYSTEM.md) — Delphin, ContextGC, and MemoryWhale together
  171. - [Integration guides and capability matrix](integrations/README.md)
  172. ## Contributing
  173. MemoryWhale accepts changes that improve capturing, preserving, retrieving, or
  174. sharing development experience. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the
  175. scope rule, development commands, and pull-request checklist. New contributors
  176. can pick a task from the [Start here issue](https://github.com/wuisabel-gif/MemWhale/issues/317).
  177. Every pull request also gets an automated review from
  178. [Second-Opinion](https://github.com/wuisabel-gif/second-opinion), a GitHub Action from a sister
  179. project by the same maintainer. Its comments are suggestions; a person decides
  180. what to act on. Setup and limits are in the [Second-Opinion guide](integrations/second-opinion/README.md).
  181. Licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.