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 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
/sources    show evidence from the previous answer
/help       show commands
/quit       exit

You can ask normal questions directly:

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

Manual sync

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

wa-memory sync

Or from inside chat:

/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.

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 twice: once at sync time to embed it, and once at query time to synthesize an answer from the retrieved evidence.
• Without an OpenAI key, wa-memory falls back to FTS keyword search and evidence-only answers.

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:

npm run dev:local
npm run dev:web

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+.