Happy slice of mcp pizzaMCP.pizza

waku-agent

MCP.Pizza Chef: ShenSeanChen

Waku sits on your computer as a personal assistant you can talk to in a terminal or a browser window, and it remembers things the way a human assistant would — recalling that you like morning meetings weeks later, without you repeating yourself. It works with Claude, ChatGPT, Gemini, and other AI models you already pay for, and it can search the web, check your calendar, and save notes about your preferences. Setup means running a few terminal commands and pasting in one account key, and everything it remembers stays in a single file on your machine.

Calendar
Notes
Web/Research

Use This MCP client To

Remember my preferences so I never repeat myself Book a meeting on my calendar from a chat Check what's already on my calendar today Search the web and add results straight to my calendar Save notes about people and things I care about Chat with my assistant from my computer or my phone See exactly what my assistant remembers, in plain text

README

waku-agent

Your own AI assistant. On your laptop. In code you can read in an afternoon.

Meet Waku — a local-first personal assistant that shows the four pillars behind every serious agent: Harness · Loop · Memory · Eval/LLM-Ops. No frameworks hiding the good parts. Built by seanchen.io.

  • Local-first. Your memory is one SQLite file. Open it. Read it. It's yours.
  • Memory is the hero. Semantic + episodic + procedural — with a gate that decides whether to remember, and a pass that decides what to keep.
  • The loop is ~95 lines of plain Python. Step through it.
  • Watch it think. A local dashboard lights up every message as it flows through the harness.
  • Eval built in. Deterministic tests and LLM-as-judge, side by side, with a release gate.

waku-agent architecture — the whiteboard

The system-design whiteboard from the series. Every box maps to a file — see the whiteboard maps to the code.

▶ Watch the 20-min code walkthrough — the loop, the memory pillars, the evals, the Telegram gateway and the "Waku Waku" wake word, live.

YouTube · X · LinkedIn · Instagram · TikTok · Discord · 哔哩哔哩 · 小红书 · 抖音

☕️ Buy me a coffee — it keeps this repo (and the videos) coming

Quickstart

Just want to run it:

pip install waku-agent
waku                                    # talk to your Waku in the terminal
waku dashboard                          # …or the browser cockpit → localhost:7777

It will tell you which key to set the first time. Want to read the code (the point of this repo) or contribute — clone it instead:

git clone https://github.com/ShenSeanChen/waku-agent && cd waku-agent
uv venv && uv pip install -e .          # create the env + install the `waku` command
cp .env.example .env                    # pick a provider, paste ONE key
uv run waku                             # talk to your Waku in the terminal
uv run waku dashboard                   # …or the browser cockpit → localhost:7777

waku-agent FAQ

Can I use this to keep track of things I tell my assistant, like scheduling preferences?
Yes — tell it once, for example "I prefer morning meetings," and it will remember and use that fact automatically in future conversations, since everything is saved to a single file on your computer.
Can I use this to search the web and put the results on my calendar?
Yes — you can ask it to look something up online and then create matching calendar events in the same conversation, one after another.
Do I need an account or a key to use this?
Yes. You need an account with an AI provider such as Claude, ChatGPT, or Gemini, and you'll paste in a key from that account when you set things up.
Which apps does this work with?
It runs on your own computer, either in a terminal window or in its own browser-based dashboard, and it can also connect to Telegram if you want to chat with it from your phone.
How hard is this to set up?
It takes some comfort with running commands in a terminal, so it suits someone willing to follow a short technical setup guide rather than a completely non-technical user.
Where is my information stored?
Everything your assistant remembers is saved locally on your own computer in a single file, rather than being sent to a company's servers for storage.
Can I switch which AI model it uses?
Yes — you can set it up with Claude, ChatGPT, Gemini, or several other AI providers, and switch between them by changing one setting.
Can I see what my assistant has remembered about me?
Yes — a browser dashboard shows every fact and note it has saved, and you can read or edit that file at any time.