GitHub - Helmus101/weave

Local-first relationship & life intelligence engine for macOS. Weave quietly builds a private memory of what you see and do (screen OCR + Gmail/Calendar + contacts), then puts it to work: it watches your back with proactive nudges, answers questions from your own memory, and can act for you in the browser and in native macOS apps.

Everything is stored locally (SQLite via sql.js); cloud calls happen only for the LLM/search features you configure.

What it does

Track

• Home — a daily morning brief (to-do, what Weave did, notifications, world news, optional sports), proactive "Do-Now" cards, a relationship radar, and response debt.
• Memory graph — screen captures are OCR'd, reconstructed by layout (sidebar/main/panel are kept separate, not jumbled), summarized into one searchable sentence by a cheap model, and stored with the full OCR retained as the authoritative source for exact facts.
• Chat — ask questions against your own memory + the web. It can read your Google Calendar and Gmail to answer "what meetings tomorrow?" / "did Sarah email me?", and quotes exact dates/numbers verbatim from the full source.
• Explorer — browse the raw memory nodes.

Services

• Commitment tracker — promises you made/owe, extracted from OCR + Gmail.
• Response debt — email threads awaiting your reply.
• Routines / Playbooks — scheduled or on-demand briefings (e.g. a meeting brief ~15 min before a calendar event).
• Browser agent (Chrome extension) — give it a goal; it plans, works in a real Chrome tab, and over-delivers a compared, recommended deliverable. Auto-accepts cookie banners, recovers when stuck (incl. an optional vision fallback), and never clicks pay/submit/confirm.
• macOS control agent — drive native apps by voice/goal via the Accessibility API (open + play Spotify/Music, Maps directions, multi-step actions in Notes/Mail/etc.).
• Voice — a global shortcut pops a system-wide mic overlay; speech is transcribed and either controls an app, runs a browser task, or answers in the Responses tab.

Proactive intelligence runs on a graph-aware retrieval + memory-decay foundation, so suggestions and answers get sharper as the graph grows.

Run

npm install
npm run build:ocr        # build the native Apple Vision OCR helper (macOS)
npm run dev:electron     # full app: capture, sync, agents, voice, tray

npm run dev + http://127.0.0.1:5173 gives a renderer-only browser preview, but it has no native bridge — OCR, sync, agents, and account behavior require npm run dev:electron.

Configuration

Provide keys via the environment (legacy in-app values are migrated to the macOS Keychain):

Permissions (macOS):

• Screen Recording — required for OCR capture.
• Accessibility — required for the macOS control agent (keystrokes / clicking native UI).

Chrome extension (browser agent)

1. Run the app (it starts the localhost ingest server the extension polls).
2. chrome://extensions → enable Developer mode → Load unpacked → select the extension/ folder.
3. Trigger a browser task from a Do-Now item or by voice; the agent works in a dedicated tab and posts its deliverable back to Weave. If you change WEAVE_INGEST_PORT, match it in extension/background.js.

Google scopes

Gmail compose, Calendar events, and Drive scopes were added beyond the original read-only grant. Accounts connected earlier must disconnect and reconnect in Settings to re-consent.

MCP server

A local MCP server exposes Weave's memory graph to clients like Claude Desktop or ChatGPT.

npm run mcp        # stdio
npm run mcp:http   # local HTTP

Tools: status/health, memory search, ask-weave / chat, proactive suggestions, routines & runs, memory-node inspection, commitments, response debt, activity timeline.

Optional env: WEAVE_USER_DATA_DIR, WEAVE_MCP_PORT, WEAVE_MCP_HOST (default 0.0.0.0).

Remote HTTP mode is off unless Weave's Cloud & Remote Access setting is enabled; it uses Supabase session auth and serves only the matching signed-in account namespace. Put it behind your own HTTPS boundary before using it with web connectors.

Example Claude Desktop config:

{
  "mcpServers": {
    "weave": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/absolute/path/to/weave"
    }
  }
}

Remote requests must include Authorization: Bearer <supabase_access_token>.

Architecture

• src/main — Electron privileged services: SQLite persistence (db/), the capture watcher + ocrBridge/ocrLayout (layout-aware OCR), retrieval (vector + BM25 + graph), intelligence (chat synthesis), proactive, routines, morningBrief, commitments/responseDebt, browserAgent + localIngest (extension server), macAgent, google, deepseek, and IPC.
• src/preload — typed, renderer-safe API bridge (window.weave).
• src/renderer — React app: Home, Chat, Tasks, Routines, Responses, Explorer, Settings, the voice overlay, and the design-system stylesheet (light, editorial theme driven by :root tokens).
• extension/ — MV3 Chrome extension: the browser agent's background worker + CDP-driven DOM actions.
• native/ocr — Swift CLI that captures the screen and runs Apple Vision OCR (with per-line bounds).

Private beta checklist

• npm run typecheck, npm test, and npm run build pass on a clean machine (or npm run beta:check).
• Build native helpers before packaging: npm run build:ocr, npm run build:contacts.
• Verify on macOS: Screen Recording + Accessibility flows, Google connect/reconnect, Apple Contacts sync, the Chrome extension load + a browser task, account switching and current-account deletion.
• Beta users should understand: contact research is local-only until explicitly enabled; deleting data removes only the current account's local Weave data; the browser preview is not the runtime.

Packaging notes

Signing/notarization are manual. Before a beta build: tag a release candidate, package the Electron app with the native OCR + Apple Contacts binaries included, sign with the Apple Developer identity, notarize and staple, then validate the signed build on a separate macOS machine.

npm run dmg        # build:ocr + build:contacts + signed dmg (CSC identity required)

Notes

The database is a local SQLite file via sql.js (no native addon compilation). Vector search sits behind a local adapter with deterministic embeddings and file-backed persistence, so a real vector DB can be swapped in without touching the watcher or UI call sites.