waywiser

Your data never leaves your machine. Memories, preferences, boards, and scheduled jobs live in ~/.waywiser/ — a SQLite database you own, files you can edit by hand, and a whole home you can nuke in one rm -rf. No telemetry, no cloud sync. Your LLM runs on your hardware or behind your own API key.

A proactive personal AI agent built on pi. Waywiser doesn't wait to be spoken to — it monitors your boards, goals, deadlines, and calendar, alerts you when something needs attention, adapts to your communication style, and learns from corrections in real time. Extends pi with persistent memory, a proactive cognition engine, behavioral meta-skills, task delegation, project boards, Google Calendar integration, MCP integrations, scheduled jobs, notifications, and a permission engine — all as in-process TypeScript extensions. Nothing patches pi's core.

Architecture

waywiser/
├── extensions/                      ← Core agent extensions
│   ├── permissions.ts               ← Permission engine (9 risk classes, extensible classifiers, approval leases)
│   ├── soul.ts                      ← SOUL.md identity persistence (append-only)
│   ├── memory.ts                    ← Cross-session memory (FTS5, RecallProvider, deterministic gate)
│   ├── memrules.ts                  ← Memory rules (gate patterns, Jaccard, validation)
│   ├── mem-dream.ts                 ← Memory consolidation (dedup, merge, conflicts)
│   ├── proactive.ts                 ← Proactive cognition engine (OODA loop, signal gathering, calendar awareness)
│   ├── meta-skills.ts               ← Behavioral engines (EQ, discretion, adaptability, multi-tasking)
│   ├── brain/                       ← Persistent memory with procedural preferences (core — always loaded)
│   │   ├── index.ts                 ← Brain lifecycle (session, learning boundary, vault sync)
│   │   ├── store.ts                 ← BrainStore (SQLite, migrations, CRUD)
│   │   ├── recall.ts                ← Reciprocal rank fusion (lexical + scope + usage + confidence + recency + semantic)
│   │   ├── embeddings.ts            ← Embedding API (CPU-isolated, LRU cache, batch /api/embed)
│   │   ├── learner.ts               ← Two-pass learning (deterministic + LLM reflection)
│   │   ├── procedures.ts            ← Procedural preferences with evidence tracking
│   │   ├── evolve.ts                ← Auto-evolution pipeline (procedures → candidates → skills)
│   │   ├── cognition.ts             ← Cognition pool (pi RPC children for reflection)
│   │   ├── consolidate.ts           ← Dedup, merge, contradiction detection
│   │   ├── vault.ts                 ← Obsidian-native markdown sync (wikilinks, Properties, MOCs)
│   │   ├── trace.ts                 ← Experience trace (observations, outcomes)
│   │   ├── prompts.ts               ← Brain context rendering
│   │   ├── config.ts                ← Brain config loader
│   │   ├── policy.ts                ← Project-key detection, scoping
│   │   ├── eval.ts                  ← Competitive skill evaluation
│   │   ├── provenance.ts            ← Memory provenance tracking
│   │   ├── recovery.ts              ← Crash recovery
│   │   ├── skills.ts                ← Skill discovery, promotion, rollback
│   │   └── types.ts                 ← Brain type definitions
│   ├── kanban/                      ← Project boards (4 modules)
│   │   ├── index.ts                 ← Extension wiring, /kanban command, kanban tool
│   │   ├── ops.ts                   ← 25+ board/card CRUD operations
│   │   ├── worker.ts                ← Subagent card workers (spawnCard, waitCard)
│   │   └── shared.ts               ← Types, constants, DB helpers, nextCardId (UUID)
│   ├── kanban-server.ts             ← Localhost HTTP dashboard (token-authenticated, no CORS)
│   ├── kanban-html.ts               ← Board HTML/CSS generation (live + static snapshot)
│   ├── delegate.ts                  ← Task delegation via RPC subprocesses (warm pool, depth-2)
│   ├── execute-code.ts              ← Programmatic tool calling (vm.createContext sandbox + optional gondolin)
│   ├── cronjob.ts                   ← Scheduled jobs (cron parser, quiet hours, auto-pause on failure)
│   ├── notify.ts                    ← Desktop/Telegram/webhook notifications (spawn, no shell)
│   ├── mcp.ts                       ← MCP server loader (JSON-RPC 2.0 stdio, lazy connect, reconnect)
│   ├── web.ts                       ← Web search + extract (SSRF-guarded, HTML entity decoding)
│   ├── commands.ts                  ← Slash commands, goals (with budgets), /trace export, /journey
│   ├── skills-manage.ts             ← Playbook catalog (tier badges, auto-onboard trigger)
│   ├── todo-compat.ts               ← /todo → kanban compatibility shim
│   ├── clarify.ts                   ← User interaction tool
│   ├── index.ts                     ← Extension loader (fault-isolated, prompt assembly handler)
│   └── utils/
│       ├── state.ts                 ← Shared DB (SQLite WAL), registry, config, RecallProvider interface
│       ├── tool-policy.ts           ← Extensible tool risk classifiers (plugin registration)
│       ├── rpc.ts                   ← Pi RPC client + warm pool (lane-versioned, TTL-evicted)
│       ├── llmcall.ts               ← One-shot LLM child (queue-based semaphore, no deadlock)
│       ├── prompt-budget.ts         ← Priority-based prompt injection manager (cache telemetry)
│       ├── trace.ts                 ← Structured trace events (TraceEvent, logTrace, logLegacy)
│       └── url-guard.ts             ← SSRF protection (RFC1918, link-local, loopback, IPv6)
│
├── plugins/
│   ├── google-workspace/            ← Google Calendar integration via gog CLI
│   │   ├── shared/                  ← Shared infra (reusable for future Gmail, Drive, etc.)
│   │   │   ├── gog-runner.ts        ← GogRunner interface + ProductionGogRunner (shell:false, caps, abort)
│   │   │   ├── gog-contract.ts      ← Runtime capability probe (gog schema, contract cache)
│   │   │   ├── gog-errors.ts        ← Exit code → CalendarErrorCode semantic mapping
│   │   │   └── accounts.ts          ← Account routing (alias, default, multi-account)
│   │   ├── extensions/calendar/     ← Calendar semantic capability (loaded by bin/waywiser plugin discovery)
│   │   │   ├── index.ts             ← Plugin entry (risk classifier, projection, tool registration)
│   │   │   ├── tool.ts              ← Semantic `calendar` tool — 30+ actions dispatched
│   │   │   ├── operations.ts        ← Operation manifest — single source of truth (dispatch + permissions)
│   │   │   ├── types.ts             ← CalendarAction, CalendarEvent, CalendarStatus, OperationSpec
│   │   │   ├── invocation.ts        ← Safety flag assembly (--readonly, --exact, --wrap-untrusted)
│   │   │   ├── normalize.ts         ← Raw gog JSON → CalendarEvent normalization
│   │   │   ├── idempotency.ts       ← Operation journal + Google-compatible event ID generation
│   │   │   └── projection.ts        ← Materialized SQLite projection for proactive SENSE
│   │   ├── skills/google-workspace/
│   │   │   └── SKILL.md             ← PA skill (safety rules, operations catalog, patterns)
│   │   └── config/
│   │       └── google-workspace.example.json  ← Default config (accounts, timeouts, safety)
│   │
│   └── obsidian/                    ← Obsidian integration (optional add-on)
│       ├── src/                     ← Plugin source (dashboard, commands, graph, watcher)
│       ├── main.js                  ← Built plugin
│       ├── manifest.json
│       ├── styles.css
│       └── sql-wasm.wasm
│
├── skills/
│   ├── waywiser/SKILL.md            ← Core operating skill (always loaded)
│   ├── brain/SKILL.md               ← Brain operating skill (always loaded)
│   └── pa-*/SKILL.md               ← 19 PA playbooks (bootstrapped to ~/.waywiser/skills/)
│       ├── pa-time-manage/          ✅ verified
│       ├── pa-doc-writer/           ✅ verified
│       ├── pa-stakeholder-comm/     ✅ verified
│       ├── pa-research/             ✅ verified
│       ├── pa-lifestyle/            ✅ verified
│       ├── pa-onboard/              ✅ verified
│       ├── pa-project-coord/        ⚠️ experimental
│       ├── pa-event-manage/         ⚠️ experimental
│       ├── pa-finance/              ⚠️ experimental
│       ├── pa-travel/               ⚠️ experimental
│       ├── pa-procurement/          ⚠️ experimental
│       ├── pa-decision-support/     ⚠️ experimental
│       ├── pa-process-improve/      ⚠️ experimental
│       ├── pa-tech-ops/             ⚠️ experimental
│       ├── pa-records/              ⚠️ experimental
│       ├── pa-hr-support/           🔬 untested
│       ├── pa-compliance/           🔬 untested
│       ├── pa-governance/           🔬 untested
│       └── pa-protocol/             🔬 untested
│
├── bin/
│   └── waywiser                     ← Launcher (core extensions, plugin discovery for extras)
│
├── config/
│   ├── SOUL.md                      ← Default identity template
│   ├── mcp.example.json             ← MCP server config example
│   ├── notify.example.json          ← Notification channel config example
│   └── brain.example.json           ← Brain config example (recall, embeddings, vault, evolution)
│
├── test/
│   ├── waywiser.test.ts             ← Core unit tests (memory, gate, recall, goals, traces, meta-skills)
│   ├── smoke.test.ts                ← Extension registration smoke test
│   ├── permissions.test.ts          ← Permission engine tests (classifier, policy, budget, planning, plugins)
│   ├── prompt-budget.test.ts        ← Prompt budget manager tests (ordering, trimming, cache)
│   ├── brain/                       ← Brain unit tests (18 files, 332 tests)
│   ├── google-workspace/            ← Google Calendar plugin tests (8 files, 306 tests)
│   │   ├── gog-runner.test.ts            ← FakeGogRunner, shell injection safety
│   │   ├── gog-contract.test.ts          ← Capability probe, schema validation
│   │   ├── calendar-operations.test.ts   ← All 30 actions, risk mapping, manifest completeness
│   │   ├── calendar-safety.test.ts       ← Read path defense-in-depth (140 assertions)
│   │   ├── calendar-normalize.test.ts    ← Event normalization (timed, all-day, conference, recurring)
│   │   ├── calendar-errors.test.ts       ← Exit code → error code mapping
│   │   ├── calendar-idempotency.test.ts  ← Event ID generation, operation journal
│   │   └── calendar-projection.test.ts   ← Transactional snapshot, stale handling, isolation
│   ├── security/
│   │   ├── execute-code-sandbox.test.ts  ← vm.createContext sandbox escape prevention
│   │   ├── url-guard.test.ts             ← SSRF URL blocking
│   │   ├── kanban-auth.test.ts           ← Session token auth verification
│   │   └── notify-spawn.test.ts          ← Shell injection prevention
│   └── e2e/                              ← End-to-end evals (require WAYWISER_E2E_MODEL)
│       ├── helpers.ts                     ← Test home, model gate, paths
│       ├── memory-roundtrip.test.ts       ← Remember → recall preference
│       ├── kanban-lifecycle.test.ts       ← Card new → move → done
│       ├── delegation.test.ts             ← Spawn leaf → collect report
│       ├── cron-fire.test.ts              ← Schedule one-shot → verify fire
│       └── adversarial.test.ts            ← Injection, oversized write, escape
│
├── docs/
│   ├── specs/                       ← Design specs (01-07)
│   ├── audits/                      ← 4 audit reports + remediation plan
│   └── research/                    ← Proactive capabilities, Ollama contention, memory latency
│
├── package.json                     ← 1 production dep (typebox), Node ≥22.5
├── SPEC.md                          ← Original design spec
└── LICENSE                          ← MIT

Install

Node >= 22.5, pi on PATH.

git clone git@github.com:yoda-digital/waywiser.git
cd waywiser
npm install
bin/waywiser

That's it. Brain (persistent memory with procedural preferences, RRF recall, auto-evolution, and vault sync) is a core component — it loads automatically on every launch. On first run, Waywiser walks you through setup: timezone, working hours, daily/weekly reviews, notification channels.

What you get out of the box:

Proactive intelligence:

• Proactive cognition engine — OODA loop ticks every 15 min, monitors boards/goals/deadlines/calendar, alerts without consuming GPU
• Calendar awareness — meeting-soon alerts, conflict detection, overloaded-day warnings from materialized projection (SQL-only, zero network in SENSE)
• Emotional intelligence — detects frustration from message patterns, adapts communication style in real time
• Discretion — suppresses low-value alerts during deep focus, caps notifications, respects quiet hours
• Adaptability — catches corrections instantly ("no, use X"), creates memories and adjusts same-session
• Multi-tasking — spawns background subagents for queued work during idle periods

Memory & learning:

• Cross-session memory (FTS5 + Brain's reciprocal rank fusion recall)
• Deterministic memory extraction per turn (CPU, ~1ms — no GPU contention)
• LLM-powered reflective learning at conversation boundaries
• Procedural preferences ("when X, prefer Y over Z") with evidence tracking
• Auto-evolution: mature procedures → candidate skills → competitive eval
• Embedding on CPU (num_gpu: 0), LRU cache, batch API — zero GPU contention with generation
• Memory export/import for data portability
• SOUL.md identity with consolidation

Tools & integrations:

• Google Calendar via gog — semantic calendar tool with 30+ operations (events, freebusy, conflicts, create, update, respond, focus-time, OOO, working-location), defense-in-depth read safety, write idempotency, materialized projection for proactive
• Task delegation (3 concurrent subagents, depth-capped at 2)
• Kanban boards (authenticated web dashboard + TUI + markdown)
• MCP integrations (Gmail, Drive, Notion, etc.)
• Scheduled jobs (cron + one-shot timers, auto-pause on repeated failures)
• Desktop/Telegram/webhook notifications
• 19 PA playbooks covering time management, writing, communication, research, finance, travel, procurement, governance, and more

Safety & observability:

• Permission engine (9 risk classes including unclassified fail-closed, extensible plugin classifiers, configurable policy, /permissions)
• Approval leases — scoped preauthorization for headless/proactive operations (tool + action + account + time window + max executions)
• Planning mode (/plan blocks writes, /plan approve re-enables; allows read_only + network + mcp_read)
• Session budgets (200 tool calls, 10 subagent spawns)
• Calendar read safety — exact command allowlist + readonly transport guard + untrusted content wrapping on every live read
• Sandboxed code execution (vm.createContext + optional Gondolin micro-VM)
• SSRF protection on web tools
• Structured trace events (/trace export)
• Goal budgets (/goal --max-steps --deadline --done)
• Prompt cache telemetry (/waywiser status)

Google Calendar

Requires gog (v0.37.0+, schema_version 1).

# Install gog, then authenticate
gog auth add

# Configure Waywiser
cat ~/.waywiser/google-workspace.json
# → Add your account(s) to "accounts" array:
#   { "email": "you@example.com", "alias": "personal", "default": true }

The calendar tool auto-discovers via plugin loading — no code changes needed. Capabilities are validated at runtime via gog schema, not pinned to a version string. The proactive engine picks up calendar signals (meeting-soon, conflicts, overloaded-day) automatically from the materialized SQLite projection.

Architecture:

Pi / LLM  →  calendar(action=events, ...)   (semantic tool, no CLI knowledge)
    ↓
Waywiser  →  permissions (risk classify → planning gate → approval)
    ↓
Plugin    →  operation manifest → invocation builder → safety flags
    ↓
GogRunner →  spawn("gog", argv, { shell: false })
    ↓
gog CLI   →  Google Calendar API

Optional: Obsidian Plugin

The Brain vault at ~/.waywiser/brain/ is already Obsidian-compatible (wikilinks, Properties, callouts, mermaid). For a richer experience — dashboard sidebar, command palette, graph coloring, confidence bars:

cd plugins/obsidian
npm install && npm run build
cp main.js manifest.json styles.css sql-wasm.wasm \
   /path/to/vault/.obsidian/plugins/waywiser-brain/

Enable in Obsidian → Settings → Community Plugins.

Proactive Engine

Waywiser runs a continuous OODA loop (Observe-Orient-Decide-Act) between user interactions. Every 15 minutes (30 during quiet hours), it:

1. Senses — SQL-only signal gathering (zero LLM cost): overdue kanban cards, goals past deadline, goals near budget, cron failures, evolution candidates, user absence, calendar meeting-soon, calendar conflicts, calendar overloaded-day (from materialized projection)
2. Orients — priority scores each signal (P0 interrupt → P3 background), deduplicates (1-hour window), applies discretion filter
3. Decides + Acts — P0 alerts via desktop/Telegram (no GPU); P1-P2 triggers agent turn via sendUserMessage followUp; P3 runs silently

The engine pauses during active conversation and re-arms when the agent settles. /proactive controls it (on/off/tick/signals/status). Config via ~/.waywiser/config.json:

{
  "proactive": {
    "enabled": true,
    "tickActiveMs": 900000,
    "tickQuietMs": 1800000
  }
}

Meta-Skills

Six cross-cutting meta-skills implemented as runtime behavioral engines:

Meta-Skill	Engine	How it works
Emotional Intelligence	meta-skills.ts	Analyzes message patterns at turn_end (short replies, corrections, caps); injects communication guidance into system prompt
Discretion	meta-skills.ts	Filters proactive notifications; max 3/hour; suppresses during deep conversations (>5 turns); never sends sensitive content externally
Anticipatory Thinking	proactive.ts	OODA loop scans boards, goals, calendar projection every 15 min; detects upcoming meetings, conflicts, overloaded days; prepares before deadlines hit
Adaptability	meta-skills.ts	Detects corrections instantly; creates memories and injects one-turn adjustment notes ("no, use X" → immediate memory + style shift)
Multi-tasking	meta-skills.ts	Spawns background subagents for kanban cards assigned to "subagent" during idle periods
Continuous Learning	Brain learner.ts	Two-pass learning at conversation boundaries: deterministic extraction (CPU, ~1ms) + LLM reflection (nuanced signals)

Manage via /meta-skills (status/emotional/discretion/corrections).

Playbooks (Personal Assistant)

19 domain-specific playbooks. Each embeds a professional methodology (GTD, Minto Pyramid, OODA Loop, DMAIC, etc.), few-shot examples, and tool integration. They load on-demand via skill_view (progressive disclosure).

Badge	Tier	Meaning
✅	verified	Tested with ≥60% accuracy. Few-shot examples tuned.
⚠️	experimental	Methodology-based but not yet empirically validated.
🔬	untested	Domain-expert playbook awaiting evaluation.

Tier	Playbooks
✅ Verified (6)	pa-time-manage pa-doc-writer pa-stakeholder-comm pa-research pa-lifestyle pa-onboard
⚠️ Experimental (9)	pa-project-coord pa-event-manage pa-finance pa-travel pa-procurement pa-decision-support pa-process-improve pa-tech-ops pa-records
🔬 Untested (4)	pa-hr-support pa-compliance pa-governance pa-protocol

On first run, the pa-onboard setup wizard triggers automatically — captures working hours, timezone, quiet hours, creates daily/weekly review crons, initializes the PA kanban board.

Security

• Permission engine — 9 risk classes (read_only, write_local, process_exec, communication, network, scheduling, mcp_read, mcp_write, unclassified). Policy per class: allow, block, ask_user, log_only. Unknown tools → unclassified → block (fail-closed). /permissions
• Extensible classifiers — plugins register per-tool risk classifiers via registerToolRiskClassifier(). Calendar plugin classifies each action (events → read_only, create → scheduling, respond → communication)
• Approval leases — scoped preauthorization for headless/proactive operations. Constrained by tool, action, account, calendar, time window, and max executions. No global allow calendar
• Planning mode — /plan blocks writes; /plan approve re-enables. Allows read_only + network + mcp_read. Allowlist never bypasses planning
• Session budgets — 200 tool calls, 10 spawns (configurable)
• Calendar read safety — every live read uses --readonly + --enable-commands-exact + --no-input + --wrap-untrusted + --json. Model cannot construct arbitrary gog argv
• Write idempotency — deterministic Google-compatible event IDs + operation journal prevents duplicate creation on retry
• Sandbox — vm.createContext(Object.create(null)) + 5s timeout; optional gondolin micro-VM
• SSRF guard — blocks RFC1918, link-local, loopback, IPv6 ULA in web_extract
• Kanban auth — per-session Bearer token, no CORS
• Notifications — spawn() with argument arrays (no shell)

Configuration

All config lives in ~/.waywiser/:

File	Purpose
waywiser.db	SQLite database (memory, boards, cron, goals, brain, calendar projection, approval leases)
brain.json	Brain config (recall, embeddings, vault, evolution)
google-workspace.json	Google Calendar config (accounts, timeouts, projection, safety flags)
config.json	Global config (prompt budget, execute_code backend, proactive engine)
permissions.json	Permission policy (risk class defaults, per-tool overrides, allowlist)
SOUL.md	Agent identity and preferences (append-only)
MEMORY.md	Append-only memory log (human-readable mirror)
USER.md	User profile
mcp.json	MCP server configuration
notify.json	Notification channel setup (desktop, Telegram, webhook)
mem.json	Memory subsystem tuning (auto, recall mode, gate timeout)
quiet.json	Quiet hours window (HH:MM-HH:MM)
brain/	Brain vault (Obsidian-compatible markdown)
boards/	Kanban board markdown exports
skills/	PA playbooks + evolved skills (active/candidates/retired)

Tests

# Everything — core + security + proactive + meta-skills + Brain + Calendar
npm test                                            # 760+ tests

# Google Calendar plugin only (8 suites, 306 tests)
node --test test/google-workspace/*.test.ts

# Brain only (76 suites)
npm run test:brain                                  # 332 tests

# End-to-end evals (requires a running LLM)
WAYWISER_E2E_MODEL=qwen3:latest npm run test:e2e    # 6 tests

License

MIT

---

Built on pi. MIT.