KIWI
Autonomous local AI agent and community of voices living in The Grove with private memory.
The Problem
Autonomous AI agents often suffer from leaky memory isolation, unpredictable side-effects on host systems, and lack of human-in-the-loop governance for high-stakes file operations and external device actions.
My Role
Architected and implemented the cognitive engine ("The Grove"), fail-closed host action safety policies, immutable exact-action plan ledgers, multi-device agent companion protocol, and unified multi-channel gateways.
Highlights
- Community of six voices living in The Grove with local memory running on the user's machine
- Local cognitive core ("The Grove") separating owner memory from credentialed client sessions
- Fail-closed security policy requiring immutable exact plans with rollback for all destructive actions
- DPAPI-secured Windows companion agent with local execution receipts and anti-re-execution guarantees
- Multi-modal interaction surface: Next.js Web UI, Voice HUD (:4321), and Telegram bot gateway with inline approvals
- Deterministic audit ledger tracking every state mutation, file movement, and memory association
Stack
Constraints
- Host safety is non-negotiable: no autonomous file deletion or batch reorganization without human-confirmed exact plans.
- Offline-first engine: core cognitive loops and memory databases must run purely locally without cloud dependencies.
- Multi-tenant memory isolation: administrative sessions and API token holders must never access the owner private mind context.
System Architecture
Key Trade-offs
The decisions worth defending — what I chose, what I turned down, and why.
File management execution model
Chose
Immutable two-phase exact-action plans with hash verification and dry-run preview
Rejected
Direct agent tool execution with broad shell permissions
Agents making speculative shell or file modifications risk catastrophic data loss; two-phase plans guarantee human oversight and rollback capability.
Engine-to-web communication architecture
Chose
Dedicated loopback HTTP/SSE gateway with bearer token authentication
Rejected
Monolithic single-process Next.js application
Decoupling the AI engine process from the Next.js frontend ensures background monitoring, telegram polling, and long-running skills survive web redeployments.
Device pairing security model
Chose
Windows DPAPI machine-bound tokens with polling architecture
Rejected
Inbound SSH or remote socket servers on client machines
Inbound listening ports expose clients to local network scans; outbound HTTPS polling behind DPAPI keeps remote companion devices secure.
What I'd Do Differently
An honest retrospective — the stuff I'd change with more time, more users, or a second pass.
- 1Implement automated regression tests for memory graph decay sweeps earlier in the development lifecycle.
- 2Consolidate SQLite schema migrations between better-sqlite3 and pg-schema under a single unified migration runner.
- 3Add fine-grained telemetry dashboards to observe cognitive latency across multi-turn reasoning chains.
Interactive Autonomous Agent Shell
Test live KIWI autonomous agent supervisor routines (agent status, grove ping, mcp tools, help) in the emulated shell below.
Technical Deep-Dive
Architecture, specifications, and implementation details.
Isolated web and Windows pilot verification
Revision 9 build/browser evidence: npm run verify:web passed with 478 sources in .verify-work/web-NwBtZf/project; verification.json reports build exit 0 and no production database/restart. node scripts/verify-chat-http.mjs .verify-work/web-NwBtZf/project passed using the new scoped endpoint with a mock engine, real Edge/web HTTP/temporary SQLite. Artifacts: project/chat-probe/743dc227-e3ad-49d8-8ba3-ee9b914156a3/ within that snapshot. Two stream POSTs, zero JSON replay, two engine calls, two user rows and one assistant row. This does not test live providers or two PCs. Transient build network/TLS retries recovered; existing JOSE/Edge and scheduler-import warnings remain.
Revision 8, 2026-09-08. Use the project kiwi-test and kiwi-deploy skills. These checks do not deploy or certify two physical PCs.
#Chat probe — revision 8
After building: node scripts/verify-chat-http.mjs <snapshot-project-path>. The script accepts only a built snapshot under .verify-work/, starts its own loopback Next server and headless Edge, with separate SQLite, a synthetic admin and a mock HTTP engine. It sends no email or real-provider requests and stops its own processes. It checks success and engine failure in the UI, POST counts and persisted messages. Password login and the real owner engine are not tested.
Build passed: .verify-work/web-FI79by/project, 477 sources, exit 0. Probe chat-probe/a930c7aa-ed9a-418b-aa1c-f59f62a0aaf8/result.json reports passed:true: two stream POSTs, zero JSON replay, two engine calls, two user messages and one assistant. The error screenshot was inspected. Contract and limits. Device evidence below is the revision 6 baseline and was not rerun in this step.
#Build
Run npm run verify:web from the repository root. scripts/verify-web.mjs copies the current tracked/untracked build sources into .verify-work/web-*/project, including working-tree edits. It excludes real environment files, databases, ISO images and private PDF libraries. Installed node_modules are reused through directory links; dependencies are not a clean installation.
The snapshot uses the existing npm run build:web script and its own .next-prod, generated types and empty SQLite database. Synthetic auth configuration and an allowlisted environment replace production credentials; engine/LLM URLs point to a closed loopback port. No PM2 command runs. The verification folder must be on the source drive: a Windows cross-drive dependency junction produced invalid Webpack paths during the first attempt.
verification.json records the snapshot location, source-file count, exit code and actual build result. Keep failed artifacts for diagnosis. .verify-work/ is gitignored; review the exact retained directory before removing it. No automatic recursive cleanup is included.
The credential-free build exposed an eager new Resend(...) during route import. web/src/lib/email/index.ts now creates the client only when a send function is called. Sending still requires a configured key and fails explicitly if missing. Verification does not send mail or validate the live provider account.
#Browser and HTTP probe
After a successful build, compile the companion with npx tsc -p tsconfig.companion.json, then run:
npm run verify:devices -- <absolute-snapshot-project-path>
scripts/verify-device-http.mjs accepts only a built snapshot under .verify-work/. It starts its own Next production server on an available loopback port, uses synthetic account rows and signed test sessions, and launches installed Microsoft Edge through Playwright in headless mode. It never logs pairing codes, device tokens or cookies.
The probe exercises the real website's proposal/approval UI, HTTP middleware and device routes, two account/device identities, a real temporary file edit, denied foreign approval, denial, persisted results after restarting only the probe server, and device revocation. Synthetic accounts have initial onboarding completed, so the dashboard does not redirect away from Devices. Local APPLY is simulated, and the two workspaces are on the same PC. This does not validate browser login/password entry, two-PC networking, installer distribution, UAC or interactive terminal confirmation.
Artifacts are result.json, server.log and a screenshot of synthetic task data inside the snapshot's device-probe/ directory. Only a report with passed: true establishes probe success. Consult the checkpoint for the latest completed result and known warnings; the existence of these scripts is not acceptance evidence by itself.
Completed on 2026-09-08: build exit 0, snapshot .verify-work/web-jFs7GS/project (474 source files); probe device-probe/9f1216c3-2613-40ad-96e4-c098116335c1/result.json reports passed: true. The Edge screenshot was inspected. Build warnings about JOSE compression APIs in Edge remain; this browser/HTTP probe passed but does not cover every auth path. Import-time scheduler registration also appears during build workers against the isolated empty DB; removing that build side effect remains an operations improvement.