Repolode
Submit
ShenSeanChen

ShenSeanChen/waku-agent

A local-first personal AI assistant in readable Python, with its own agent loop, SQLite-based memory, and built-in evals.

Open-source alternative to:ChatGPT

View on GitHubWebsite
Stars
2,082
Forks
410
Open issues
57
Last commit
11 days ago

What is it?

waku-agent is a personal AI assistant that runs on your own machine. It is built around four parts: a harness that connects gateways such as a terminal, a browser dashboard, Telegram, and Discord to one agent loop; a loop of about 95 lines of Python that reasons, acts, and repeats; a memory system covering semantic, episodic, and procedural (skill) memory; and an eval layer that combines deterministic tests with LLM-as-judge scoring.

Memory is stored in a single SQLite file, and a gate decides whether each message is worth remembering while a consolidation pass decides what to keep. The project supports several model providers, including Anthropic, OpenAI, Gemini, DeepSeek, and OpenRouter, selected through an environment variable and an API key. An optional integration connects the agent to the hosted Waku Memory service so the same memory can be shared with other agents.

The code is intended to be read and modified rather than used as a black box. It is MIT licensed, except for the hosted/ directory, which uses Elastic License 2.0.

Key features

  • 01Agent loop of about 95 lines of plain Python with reasoning, action, and repetition
  • 02Semantic, episodic, and procedural memory stored in a local SQLite file
  • 03Terminal, browser dashboard, Telegram, Discord, and voice gateways
  • 04Deterministic tests and LLM-as-judge evals with a release gate
  • 05Support for multiple model providers including Anthropic, OpenAI, Gemini, and OpenRouter

Use cases

  • Running a personal assistant on your laptop that keeps its memory locally
  • Studying how an agent loop, memory retrieval, and evals fit together in a small codebase
  • Forking the harness to add a new messaging gateway or tool
  • Sharing one memory across Claude Code, Codex, and other agents via Waku Memory

Quick start

  1. 1

    Install the package from PyPI

    pip install waku-agent
  2. 2

    Talk to your Waku in the terminal (it will ask for an API key the first time)

    waku
  3. 3

    Or open the browser dashboard at localhost:7777

    waku dashboard

Things to know

  • Needs an API key from a model provider (e.g. Anthropic, OpenAI) to run.

Topics

#ai-agent#local-first#llm#memory#evals#personal-assistant#python#sqlite#agent-framework#ai-assistant

FAQ

What is waku-agent?
A local-first personal AI assistant in readable Python, with its own agent loop, SQLite-based memory, and built-in evals. waku-agent is a personal AI assistant that runs on your own machine. It is built around four parts: a harness that connects gateways such as a terminal, a browser dashboard, Telegram, and Discord to one agent loop; a loop of about 95 lines of Python that reasons, acts, and repeats; a memory system covering semantic, episodic, and procedural (skill) memory; and an eval layer that combines deterministic tests with LLM-as-judge scoring.
Is waku-agent free to use? What license does it have?
waku-agent is open source under the MIT license. Check the license terms before using it in commercial products.
Is waku-agent still maintained?
Actively maintained. The last commit to waku-agent was on Oct 11, 2026.
What can I use waku-agent for?
Running a personal assistant on your laptop that keeps its memory locally Studying how an agent loop, memory retrieval, and evals fit together in a small codebase Forking the harness to add a new messaging gateway or tool Sharing one memory across Claude Code, Codex, and other agents via Waku Memory
How do I install waku-agent?
Install the package from PyPI: pip install waku-agent Talk to your Waku in the terminal (it will ask for an API key the first time): waku Or open the browser dashboard at localhost:7777: waku dashboard
Where can I get waku-agent?
The source code and installation instructions are on GitHub: https://github.com/ShenSeanChen/waku-agent

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects