waku agent - Moses Yebei

The Problem

Building a personal AI agent typically means either fighting heavyweight frameworks that obscure the core loop, or gluing together scattered scripts with no memory, no evals, and no way to verify changes. You end up with a black box you cannot debug or trust.

What This Does

waku-agent is a local-first personal assistant built on four explicit pillars: Harness · Loop · Memory · Eval. The core agent loop lives in about 95 lines of plain Python in waku/loop/. Memory is a single SQLite file (.waku/state.db) with semantic, episodic, and procedural stores, gated by a retrieval pass in waku/memory/retrieval_gate.py. A local dashboard in waku/ops/dashboard.py (1,211 lines) visualizes every message as it flows through the system. Evals live in evals/, with both deterministic tests (evals/deterministic/) and an LLM-as-judge setup in evals/judge/.

How It Is Wired

Execution starts at main in waku/__main__.py, which reaches 82 functions. The CLI routes into respond in waku/app.py, the central turn handler called from 20 places. From there, the loop calls waku/loop/models.py for inference, which routes through load_settings (called from 28 places) and make_waku (called from 27 places) — the two highest-blast-radius functions.

The memory path is concrete: handle in waku/gateway/telegram.py → respond → export_markdown, which writes to MEMORY.md and executes a SQL SELECT against the SQLite DB. The dashboard's chat function in waku/ops/dashboard.py manages sessions and calls _get_agent, which touches the database, filesystem, external commands, and the network.

waku/config.py is the module hub — 21 modules depend on it, none of which it imports. It is stable but any churn there ripples widely. The import graph shows zero circular dependencies across 85 modules, which is clean for a codebase this size.

How To Use It

git clone https://github.com/moses-y/waku-agent && cd waku-agent
uv venv && uv pip install -e .
cp .env.example .env
uv run waku

Configuration lives in .env — pick one provider key (Anthropic, OpenAI, Gemini, DeepSeek). Run uv run waku dashboard for the browser UI at localhost:7777, or set TELEGRAM_BOT_TOKEN to enable the Telegram gateway.

Real-World Use

A personal research assistant that remembers context across sessions. Say: "Remember that Alex prefers morning meetings." Quit, restart, then: "Book a catch-up with Alex on Friday." It retrieves the preference from the SQLite memory store and books the slot via the calendar tool in waku/tools/calendar.py, which syncs to Apple Calendar.

Code Health & Issues

Static analysis found 46 issues (14 high, 32 medium) across 7 kinds. The notable ones:

High - cognitive load - waku/ops/dashboard.py at 1,211 lines with max indentation depth of 9; waku/app.py and waku/loop/models.py have deep nesting. Flatten with guard clauses.
Medium - broad exception handling - waku/ops/dashboard.py, waku/gateway/voice.py, waku/loop/agent.py catch Exception indiscriminately.
Medium - hub module - waku/config.py has 21 dependents; keep it stable and small.
Medium - empty catch blocks - three JS files (compare.js, main.js, render.js) silently discard errors.
Medium - file handle leak - waku/memory/retrieval_gate.py uses open() without a context manager.

SDLC gaps: no lockfile (pyproject.toml declares openai >=1.50 and rich >=13.0, both 2 majors behind), no Dependabot, no dependency vulnerability scan in CI, and validate-skills.yml does not declare least-privilege GITHUB_TOKEN permissions. Tests and CI are present; no committed secrets found.

The Bottom Line

A genuinely readable agent architecture — the loop, memory pillars, and eval harness are all inspectable in an afternoon. The dashboard is overgrown and the dependency hygiene needs attention before production use. Ideal for engineers learning agent internals or building a local-first assistant they can trust and modify.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

123 files

Python76
Markdown16
JavaScript9
JSON2
YAML2
HTML2

Flask

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["waku<br/>54 modules"] g1["evals<br/>27 modules"] g2["scripts<br/>3 modules"] g1 -->|34| g0 g2 -->|12| g0

Module dependencies

The 10 most depended-upon modules of 85, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_waku_config["config"] n1_waku_loop_models["models"] n2_waku_tools_registry["registry"] n3_evals_helpers["helpers"] n4_waku_ops___init__["__init__"] n5_waku_ops_dashboard["dashboard"] n6_waku_app["app"] n7_aku_memory_procedural_loader["loader"] n8_waku_tools___init__["__init__"] n9_waku_memory_semantic_store["store"] n3_evals_helpers --> n0_waku_config n3_evals_helpers --> n1_waku_loop_models n3_evals_helpers --> n6_waku_app n6_waku_app --> n0_waku_config n6_waku_app --> n1_waku_loop_models n6_waku_app --> n8_waku_tools___init__ n1_waku_loop_models --> n0_waku_config n5_waku_ops_dashboard --> n0_waku_config n5_waku_ops_dashboard --> n4_waku_ops___init__ n5_waku_ops_dashboard --> n6_waku_app n5_waku_ops_dashboard --> n7_aku_memory_procedural_loader n5_waku_ops_dashboard --> n8_waku_tools___init__ n5_waku_ops_dashboard --> n9_waku_memory_semantic_store n5_waku_ops_dashboard --> n1_waku_loop_models n8_waku_tools___init__ --> n0_waku_config n8_waku_tools___init__ --> n2_waku_tools_registry

Dependencies

2 of 4 declared dependencies are a major version behind. Resolved 4 of 4 against the registry.

Package	Declared	Latest	Behind
`openai`	>=1.50	3.1.0	2 major
`rich`	>=13.0	15.0.0	2 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium4

low1

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/validate-skills.yml

1 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/validate-skills.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/validate-skills.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.