albenes/authorship-segovia

Purpose and entry points

Segovia is a local-first macOS home-agent runtime: CLI, loopback server/cockpit, and optional launchd daemon. It connects to LM Studio on localhost, maintains household data locally, and requires proposals/approval for critical actions. Main composition begins at src/index.ts, CLI dispatch at src/cli.ts, and server startup at src/server/index.ts.

Platform and module boundary

The platform defines a pluggable LifeModule architecture, central registry, module configuration mapping, enable/disable semantics, and sensitivity classification. Feature modules should expose their module port and be registered centrally rather than coupled directly to interfaces. Core paths: src/platform/module.ts, src/platform/registry.ts, src/platform/modules.ts.

Interaction and agent execution

Chat is the primary intent-to-action boundary. It assembles system context, calls configured local models, and invokes a registry of domain tools; tools mediate all operational capabilities instead of allowing arbitrary model execution. Relevant paths: src/chat.ts, src/tools/registry.ts, src/tools/run.ts.

Local models and runtime governance

The runtime manages model IDs/configuration, limited resident-model capacity, task budgets, pressure/degraded modes, circuit breaking, recovery, and correlated logging. LM Studio is the material external dependency and is expected on 127.0.0.1; model identifiers are configuration-controlled. Core paths: src/runtime/models.ts, src/runtime/governor.ts, src/provider.ts.

Domain data modules

Modules own their local stores and business rules. Major domains include durable memory with sensitivity-aware retrieval, a double-entry CFO ledger, household/health records, read-only mail, drop-folder inbox processing, and BM25 household knowledge search. Primary paths: src/memory/module.ts, src/life/cfo/ledger.ts, src/knowledge/search.ts. Additional module boundaries are represented by src/health/module.ts, src/household/module.ts, and src/mail/module.ts.

Events, proposals, and automation

Sensors/adapters and modules emit events into an event bus. Rules and conditions evaluate them into actions or approval-gated proposals, preserving the product boundary that critical changes are not executed autonomously. Automations and recurring work use this layer rather than direct cross-module mutation. Core paths: src/events/bus.ts, src/events/evaluator.ts, src/events/proposals.ts.

External integration and scheduling

macOS adapters provide Calendar, Mail, Reminders, JXA, notifications, and sync-facing interfaces. The rhythm scheduler queues and runs recurring jobs; the daemon wraps this for always-on or login-start operation through launchd. Core paths: src/adapters/mac/calendar.ts, src/rhythm/runner.ts, src/daemon/launchd.ts.

Security, persistence, and operations

Sensitive local state is protected through at-rest encryption, macOS Keychain secrets, audit/redaction, execution and workspace guards, quarantine, and integrity checks. SQL.js-backed storage supports local persistence; backup/restore and migrations provide lifecycle continuity. The HTTP server exposes loopback APIs and serves the static cockpit UI. Core paths: src/security/at-rest.ts, src/secrets/keychain.ts, src/storage/sqljs-db.ts; interfaces live in src/server/http.ts and src/cockpit/static/app.js.