MemWhale: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (Codex, Claude, etc.) working in this repo.

Use MemoryWhale as durable terminal memory

This project is a terminal-memory system — use it on yourself. It stores commands, exit codes, stdout/stderr, notes, and whole sessions in a local SQLite database so a future agent session, a different machine, or a different agent can continue from what already happened. Everything is local; nothing is uploaded.

Database: <data_local>/MemoryWhale/memorywhale.sqlite3 (~/.local/share/... on Linux, ~/Library/Application Support/... on macOS).

Recall before you act

Before debugging a build/environment error, check whether it was solved before:

mw search "linker cc not found"      # full-text recall across commands, output, notes
mw context --last-error              # the most recent failure, with its error tail

It shows prior matching runs and what was run right after a past failure (often the fix). Prefer a known-good fix over re-deriving it.

Record as you go

Log notable commands — especially a failure and the fix that worked:

mw-remember --cwd "$(pwd)" --exit-code "$?" \
  --stderr "<error output>" \
  --notes "project:<name> what / why" -- <command> [args]

Record an exploratory stretch as a whole session:

mw --notes "project:<name>"    # ...work...  then: exit  (wait for "recorded session #N")

Tag related work across terminals with the same project:<name> to group it.

Inspect

• mw-view <id> — one memory as a local web page (with suggested next steps).
• mw-serve — dashboard at http://127.0.0.1:7071/; includes /graph and project views.
• mw-recover — import an interrupted session transcript that didn't save.

Repo conventions

• Before changing behavior, read docs/architecture.md and place the change in Capture, Memory, Retrieval, or Interfaces. Keep integrations thin and do not introduce agent-specific behavior into core.
• Before debugging, run a focused test and query MemoryWhale for a recurring failure. Record non-obvious fixes after they are verified.
• The Cargo workspace lives at the repository root. The reusable retrieval crate is crates/memorywhale-core, CLI sources are in crates/mw-cli, the React frontend is in src, and src-tauri contains only the desktop shell.
• Build every helper from the repository root with cargo build --release -p memorywhale-cli --bins. The binaries are mw, mw-remember, mw-run, mw-screenshot, mw-serve, mw-view, mw-recover, and mw-mcp.
• macOS only: after copying a built binary, re-sign it (codesign --force --sign - <path>) or it gets Killed: 9. See DEBUG.md.
• Full usage: docs/reference/cli.md. Setup/troubleshooting: DEBUG.md.