wa-memory

Local-native WhatsApp memory in your terminal or browser.

wa-memory is an npm CLI that links WhatsApp through wacli, stores messages in local SQLite, embeds chunks via OpenAI for semantic recall, and answers questions with OpenAI. Raw WhatsApp data stays on your machine — only the chunk text needed for embedding/synthesis ever leaves it.

Install

npm install -g wa-memory
wa-memory

The first wa-memory run starts an interactive setup wizard.

First-run flow

The CLI guides you through:

1. Connecting WhatsApp as a linked device (QR code or phone-code pairing).
2. Entering an OpenAI API key, chat model, and embedding model.
3. Running the initial sync.
4. Opening a terminal chat.

For WhatsApp linking, the wizard runs the QR flow by default:

wacli auth --idle-exit 2m --follow --qr-format terminal

Or skip QR with wa-memory setup --phone +<your-number> for phone-code pairing.

Requirements

• Node.js 22+
• wacli installed and paired by the setup wizard
• OpenAI API key (used for both text-embedding-3-small recall and chat synthesis)

Install wacli:

brew install steipete/tap/wacli

Commands

wa-memory                    # setup if needed, then open chat
wa-memory setup              # rerun setup wizard
wa-memory sync               # sync WhatsApp messages again now
wa-memory chats              # choose which conversations are synced/indexed
wa-memory chat               # open interactive terminal chat
wa-memory ask "question"      # ask one question and exit
wa-memory search "query"      # show retrieval evidence only
wa-memory status             # show local DB/sync status
wa-memory doctor             # check node, wacli, WhatsApp, OpenAI, embedding status
wa-memory serve              # start local web/API server on 127.0.0.1:8787

Most commands that are useful for scripts support --json:

wa-memory sync --json
wa-memory status --json
wa-memory doctor --json
wa-memory ask "what did Riya say about Goa?" --json

Chat mode

Start chat:

wa-memory chat

Inside chat:

/sync       sync WhatsApp messages again now
/status     show local database status
/help       show commands
/quit       exit

You can ask normal questions directly:

wa-memory> what did we decide about the Goa trip?

Question answering retrieves up to 50 vector matches, compresses them into a private summarized context, then answers from that summary. Normal chat output does not show vector hits, chunks, source counts, or retrieval details. Answers are formatted as terminal-friendly plain text instead of Markdown.

Manual sync

Run this any time you want to pull in new WhatsApp messages:

wa-memory sync

Or from inside chat:

/sync

Sync is incremental. wa-memory remembers the latest local message timestamp per conversation and only asks wacli for newer messages on later runs.

On the first interactive wa-memory sync, the CLI asks which conversations to sync. The top 25 conversations are preselected with checkboxes, and the Others option lets you add specific chat names case-insensitively. After that, the saved selection is reused. Use wa-memory chats any time to change it.

To limit sync/indexing to specific conversations:

wa-memory chats
wa-memory chats --add "Research group"
wa-memory chats --remove "Old group"
wa-memory chats --list

An empty chat allowlist keeps the CLI-compatible behavior of syncing all conversations. The browser UI always saves and sends an explicit conversation selection before starting sync.

Local browser UI

Run the local web/API server:

wa-memory serve

Then open:

http://127.0.0.1:8787

The browser UI talks to the same local Node server. There is no hosted proxy, tunnel, or remote message store.

When WhatsApp is connected, the browser shows the top 25 conversations as the initial sync set. You can tick or untick any of them, type a name under Others to add another conversation case-insensitively, and then sync only the selected conversations. While sync runs, the UI shows the current phase, chats processed, and new messages imported.

Architecture

                         USER
                          |
          +---------------+----------------+
          |                                |
   Terminal CLI                     Browser UI
   wa-memory ...                    http://127.0.0.1:8787
   src/cli/*                        src/web/*
          |                                |
          +---------------+----------------+
                          |
                Local Node Server
                src/local/server.ts
                - serves dist/web
                - handles /api/* aliases
                - exposes local JSON API
                          |
                          v
                Local Runtime
                src/local/runtime.ts
                          |
      +-------------------+-------------------+
      |                   |                   |
      v                   v                   v
 WacliClient        MemoryDatabase       OpenAI Clients
 src/local/wacli    local SQLite         embeddings + answers
      |             ~/.wa-memory/              |
      |             wa_memory.sqlite           |
      v                   |                    |
 wacli linked             |                    |
 WhatsApp store           |                    |
      |                   |                    |
      +------ sync ------>+<----- retrieval ---+
                          |
             messages, chats, chunks,
             FTS index, vectors, traces,
             chat turns all stay local

Configuration

The setup wizard stores user configuration at:

~/.config/wa-memory/config.json

The local SQLite database defaults to:

~/.wa-memory/wa_memory.sqlite

Environment variables and ~/.wa-memory/.env still work for advanced use. They override saved config:

WA_MEMORY_DATA_DIR=~/.wa-memory
WA_MEMORY_DB=~/.wa-memory/wa_memory.sqlite
WACLI_BIN=wacli
WACLI_STORE_DIR=~/.wacli
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5.2
OPENAI_ALLOWED_MODELS=gpt-5.2,gpt-5.2-mini,gpt-5.2-nano
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

Local-first behavior

• WhatsApp auth and message sync happen locally through wacli.
• Messages and chunks are stored in local SQLite, including text-embedding-3-small vectors as BLOBs.
• Recall is a cosine top-K over the local vector store; nothing leaves your machine for retrieval.
• OpenAI sees chunk text at sync time for embeddings, then at query time to summarize the top retrieved context and synthesize the final answer.
• Without an OpenAI key, wa-memory falls back to FTS keyword search and a local summary-style response.

Development

npm install
npm run dev:cli -- --help
npm run dev:local
npm run typecheck
npm test
npm run build

Build the package output:

npm run build
node dist/cli/index.js --help

For frontend iteration, run the local server and Vite dev server in separate terminals:

WA_MEMORY_ALLOW_DEV_ORIGIN=true npm run dev:local
npm run dev:web

The dev-origin flag is only needed for the Vite proxy on port 5173. The packaged local UI is served from the same local origin as the API.

Verification

Before publishing or pushing changes:

npm test
npm run build
npx deepsec init .deepsec . --id wa-memory
cd .deepsec
pnpm install
pnpm deepsec scan --project-id wa-memory
pnpm deepsec report --project-id wa-memory

DeepSec writes its workspace under .deepsec/, which is ignored because it contains local audit state.

Notes

• WhatsApp history backfill is best-effort because WhatsApp Web only returns the history available to the linked device.
• Node's built-in node:sqlite API is experimental in Node 22; the CLI suppresses that warning, but the underlying requirement remains Node 22+.