@geravant/sinain 1.23.7 → 1.24.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +236 -141
  2. package/onboard.js +31 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,189 +1,284 @@
1
- # @geravant/sinain
1
+ # Sinain <img src="https://raw.githubusercontent.com/anthillnet/sinain-hud/main/media/screen-recording-2026-03-26.gif" alt="Sinain HUD" width="120" align="right">
2
2
 
3
- This package serves two roles:
3
+ [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/anthillnet/sinain-hud/blob/main/LICENSE)
4
+ [![CI](https://github.com/anthillnet/sinain-hud/actions/workflows/ci.yml/badge.svg)](https://github.com/anthillnet/sinain-hud/actions/workflows/ci.yml)
5
+ [![npm](https://img.shields.io/npm/v/@geravant/sinain)](https://www.npmjs.com/package/@geravant/sinain)
6
+ [![macOS 12.3+](https://img.shields.io/badge/macOS-12.3%2B-black?logo=apple)](https://support.apple.com/macos)
7
+ [![LongMemEval IPR 82.8%](https://img.shields.io/badge/LongMemEval%20IPR-82.8%25-success)](https://github.com/anthillnet/sinain-hud/blob/main/docs/LONGMEMEVAL-AUDIT.md)
4
8
 
5
- 1. **Standalone launcher** — run `npx @geravant/sinain start` to launch the full sinain stack (core, sense, overlay, agent) on your Mac. See the [main README](../README.md#quick-start) for usage.
6
- 2. **OpenClaw plugin** — when installed on an OpenClaw gateway server (`npx @geravant/sinain install`), it manages the sinain-hud agent lifecycle.
9
+ **Context OS** — ambient intelligence for builders. Captures what you see and hear, distills it into a private knowledge graph, accessible from MCP, a web UI, and a screen-recording-invisible HUD overlay.
7
10
 
8
- ---
11
+ <p align="center">
12
+ <img src="https://raw.githubusercontent.com/anthillnet/sinain-hud/main/media/sinain-demo-full.gif" alt="Sinain demo" width="720">
13
+ </p>
9
14
 
10
- ## OpenClaw Plugin
15
+ **[Quick Start](#quick-start)** · **[Docs](https://github.com/anthillnet/sinain-hud/tree/main/docs)** · **[Privacy](https://github.com/anthillnet/sinain-hud/blob/main/docs/privacy-protection-design.md)** · **[Configuration](https://github.com/anthillnet/sinain-hud/blob/main/docs/CONFIGURATION.md)** · **[Contributing](https://github.com/anthillnet/sinain-hud/blob/main/CONTRIBUTING.md)**
11
16
 
12
- Plugin for the [anthillnet fork of OpenClaw](https://github.com/anthillnet/openclaw) that manages the sinain-hud agent lifecycle on the server.
17
+ ---
13
18
 
14
- ## What It Does
19
+ ### You, Augmented
15
20
 
16
- Five lifecycle hooks, one tool, four commands, and a background service:
21
+ Sinain captures your screen and audio continuously, distills the stream into a **structured live knowledge graph** of facts, entities, and decisions, and exposes that graph through every interface where you might need it.
17
22
 
18
- ### Hooks
23
+ - **Capture** — screen frames + system audio, with `<private>` tag stripping and auto-redaction of credentials and tokens *before* anything leaves your machine.
24
+ - **Distill** — facts (atomic claims), entities (people / projects / topics), decisions (what was chosen and why) — extracted by an LLM, integrated by deterministic graph operations (no LLM in the integration step → **[82.8% Information Preservation Rate](https://github.com/anthillnet/sinain-hud/blob/main/docs/LONGMEMEVAL-AUDIT.md)** on the [LongMemEval benchmark](https://github.com/xiaowu0162/LongMemEval) (ICLR 2025, 500 questions), measured against full-context oracle).
25
+ - **Access from anywhere** — **MCP server** for agents (Claude Code, Codex, Goose, OpenClaude, Junie), **web UI** at `localhost:9500/knowledge/ui/` for browsing, and a **HUD overlay** for in-the-moment recall.
19
26
 
20
- | Hook | Purpose |
21
- |---|---|
22
- | `session_start` | Initializes per-session tool usage and compliance tracking |
23
- | `before_agent_start` | Syncs HEARTBEAT.md, SKILL.md, sinain-memory/ (recursively, including eval/), and modules/ from `sinain-sources/` to workspace; generates effective playbook; creates memory directories |
24
- | `tool_result_persist` | Strips `<private>` tags from tool results; tracks `sinain_heartbeat_tick` calls for compliance validation |
25
- | `agent_end` | Writes structured session summary; validates heartbeat compliance (warns on skip, escalates after 3 consecutive skips) |
26
- | `session_end` | Cleans up orphaned session state |
27
+ The HUD overlay is invisible to screen capture — never appears in screenshots, recordings, or screen shares.
27
28
 
28
- ### Tool
29
+ ### Agent-Agnostic
29
30
 
30
- | Tool | Purpose |
31
- |---|---|
32
- | `sinain_heartbeat_tick` | Executes all heartbeat mechanical work (signal analysis, insight synthesis, log writing). Returns structured JSON with results, recommended actions, and Telegram output. |
31
+ Sinain feeds the same screen and audio context to any MCP-compatible agent. Switch agents on the fly — no restart, no context loss.
33
32
 
34
- The heartbeat tool accepts `{ sessionSummary: string, idle: boolean }` and runs:
35
- 1. `uv run python3 sinain-memory/signal_analyzer.py` (60s timeout)
36
- 2. `uv run python3 sinain-memory/insight_synthesizer.py` (60s timeout)
37
- 3. Writes log entry to `memory/playbook-logs/YYYY-MM-DD.jsonl`
33
+ - Tested with Claude Code, OpenClaude, Codex, Goose, and Junie. Any MCP-compatible agent works.
34
+ - Pick agents in the overlay's flash-icon selector — spawn tasks can route to any profile in your roster.
35
+ - Add custom profiles (personal Claude config, alternate models) by editing [`agents.json`](https://github.com/anthillnet/sinain-hud/blob/main/docs/AGENT-ROSTER.md). The roster is the source of truth.
36
+ - Knowledge modules travel with you — export from one machine, import on another.
38
37
 
39
- ### Commands
38
+ ### Privacy Controls
40
39
 
41
- | Command | Purpose |
42
- |---|---|
43
- | `/sinain_status` | Shows persistent session data from `sessions.json` (update time, tokens, compactions, transcript size) and resilience metrics |
44
- | `/sinain_modules` | Shows active knowledge module stack, suspended and disabled modules |
45
- | `/sinain_eval` | Shows latest evaluation report and recent tick evaluation metrics |
46
- | `/sinain_eval_level` | Sets evaluation level: `mechanical`, `sampled`, or `full` |
47
-
48
- ### Service
49
-
50
- **Curation pipeline** — runs every 30 minutes in the background:
51
- 1. Feedback analysis (`feedback_analyzer.py`) → extracts `curateDirective` + effectiveness metrics
52
- 2. Memory mining (`memory_miner.py`) → reads unread daily memory files
53
- 3. Playbook curation (`playbook_curator.py`) → archives, applies changes
54
- 4. Effectiveness footer update → writes metrics into playbook
55
- 5. Effective playbook regeneration → merges base playbook + active module patterns
56
- 6. Tick evaluation (`tick_evaluator.py`) → runs mechanical + sampled judges (120s timeout)
57
- 7. Daily eval report (`eval_reporter.py`) → generates report once per day after 03:00 UTC
40
+ By default, sinain uses cloud APIs (OpenRouter) for transcription and analysis. When you need tighter control, switch privacy modes — no code changes, one env var.
58
41
 
59
- ## Configuration
42
+ - `off` → `standard` → `strict` → `paranoid` — four modes in `~/.sinain/.env`.
43
+ - `paranoid` mode: Ollama + whisper.cpp. **Zero network calls at runtime** — the embedding model is pre-cached during the setup wizard (`sinain setup-embedding`), so subsequent runs are fully offline.
44
+ - HUD overlay is invisible to screen capture (`NSWindow.sharingType = .none` — see [`overlay/macos/Runner/AppDelegate.swift:70`](https://github.com/anthillnet/sinain-hud/blob/main/overlay/macos/Runner/AppDelegate.swift#L70)). Verifiable via split-screen recording with QuickTime + OBS + Loom — the HUD is absent from all three.
60
45
 
61
- Configured in `openclaw.json` under `plugins.entries.sinain-hud`:
62
-
63
- ```json
64
- {
65
- "plugins": {
66
- "entries": {
67
- "sinain-hud": {
68
- "enabled": true,
69
- "config": {
70
- "heartbeatPath": "/home/node/.openclaw/sinain-sources/HEARTBEAT.md",
71
- "skillPath": "/home/node/.openclaw/sinain-sources/SKILL.md",
72
- "memoryPath": "/home/node/.openclaw/sinain-sources/sinain-memory",
73
- "modulesPath": "/home/node/.openclaw/sinain-sources/modules",
74
- "sessionKey": "agent:main:sinain"
75
- }
76
- }
77
- }
78
- }
79
- }
46
+ ## Quick Start
47
+
48
+ ```bash
49
+ npx @geravant/sinain@latest start
80
50
  ```
81
51
 
82
- | Field | Type | Description |
83
- |---|---|---|
84
- | `heartbeatPath` | string | Path to HEARTBEAT.md source (resolved relative to state dir) |
85
- | `skillPath` | string | Path to SKILL.md source |
86
- | `memoryPath` | string | Path to sinain-memory/ scripts directory |
87
- | `modulesPath` | string | Path to modules/ directory for knowledge module system |
88
- | `sessionKey` | string | Session key for the sinain agent |
52
+ That's it. On first run, sinain will:
53
+ 1. Run an **interactive setup wizard** — transcription backend, API key, agent, privacy mode
54
+ 2. **Auto-download** the overlay app (~17MB), sck-capture binary (~5MB), embedding model (~90MB), and Python dependencies
55
+ 3. **Start all services** — sinain-core, sense_client, overlay, and agent
56
+
57
+ All assets are cached locally after the first install. In `paranoid` mode, subsequent runs are fully offline — no network calls at runtime.
58
+
59
+ > **Pin `@latest`** on every invocation. `npx @geravant/sinain` (without `@latest`) caches *forever* against the unversioned spec — you'd silently keep running an old version for months. Sinain self-updates automatically when stale, but pinning `@latest` makes it explicit and saves a redundant relaunch.
60
+
61
+ > **Re-run the wizard** anytime: `npx @geravant/sinain@latest start --setup`
62
+
63
+ ### Prerequisites
64
+
65
+ - **macOS 12.3+** — Sinain uses ScreenCaptureKit (introduced in 12.3). Earlier versions are not supported in this release. Apple Silicon and Intel both work.
66
+ - **Node.js 18+** — [nodejs.org](https://nodejs.org/) (LTS recommended)
67
+ - **Python 3.10+** — `brew install python3` (macOS) or [python.org](https://www.python.org/downloads/)
68
+ - **OpenRouter API key** (optional for local-only mode) — [openrouter.ai](https://openrouter.ai)
69
+ - **Network access during first install** — the wizard downloads ~112MB total (overlay app, sck-capture binary, sentence-transformer embedding model). All cached locally; subsequent runs need network only for cloud LLM API calls (or zero network in `paranoid` mode).
70
+
71
+ > **Fully local?** No API key needed. Ollama + whisper-cli = zero cloud at runtime. See [Running Fully Local](#running-fully-local).
72
+
73
+ > **First install reproducibility?** See [docs/cold-install-verification.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/cold-install-verification.md) for a step-by-step verified-on-fresh-user-account guide, including the timing measurement and the failure modes the audit caught + fixed.
89
74
 
90
- ## File Auto-Deploy
75
+ ### macOS Permissions
91
76
 
92
- The `before_agent_start` hook copies files from the persistent source directory to the agent workspace:
77
+ 1. **System Settings → Privacy & Security → Screen Recording** — add your Terminal, then **quit and reopen Terminal** (macOS TCC entitlements only apply to processes started after the grant)
78
+ 2. **System Settings → Privacy & Security → Microphone** — same: add Terminal, then restart Terminal
79
+
80
+ > Sinain detects when these permissions are missing and surfaces a clear restart-instruction banner; you'll never get a silent degraded mode.
81
+
82
+ ### Managing sinain
83
+
84
+ ```bash
85
+ npx @geravant/sinain@latest stop # stop all services
86
+ npx @geravant/sinain@latest status # check what's running
87
+ npx @geravant/sinain@latest start --setup # re-run setup wizard
88
+ npx @geravant/sinain@latest start --no-sense # skip screen capture
89
+ npx @geravant/sinain@latest start --no-overlay # headless mode
90
+ ```
91
+
92
+ > Always pin `@latest` — see the note in [Quick Start](#quick-start) above.
93
+
94
+ ## Architecture
93
95
 
94
96
  ```
95
- /mnt/openclaw-state/sinain-sources/ → /home/node/.openclaw/workspace/
96
- HEARTBEAT.md HEARTBEAT.md
97
- SKILL.md SKILL.md
98
- sinain-memory/ sinain-memory/
99
- *.json, *.sh, *.txt (always overwritten)
100
- *.py (deploy-once — skip if exists)
101
- modules/ modules/
102
- manifest.json (always overwritten)
103
- module-registry.json (deploy-once)
104
- */patterns.md (deploy-once)
105
- sinain-memory/eval/ sinain-memory/eval/ (recursive)
106
- *.py (deploy-once)
107
- *.json, *.jsonl (always overwritten)
97
+ ┌─── Your Device ─────────────────────────────────────────────────────┐
98
+ │ │
99
+ │ sck-capture (Swift) │
100
+ │ ├─ system audio (PCM) ──► sinain-core :9500 │
101
+ │ └─ screen frames (JPEG) ──► sense_client ─── POST /sense ──► │
102
+ │ │ │
103
+ │ ┌────────────────────────┘ │
104
+ │ │ │
105
+ │ sinain-core │
106
+ │ ├─ audio pipeline → transcription │
107
+ │ ├─ agent loop → digest + HUD text │
108
+ │ ├─ knowledge graph (private, on-device) │
109
+ │ └─ WebSocket feed │
110
+ │ │ │
111
+ │ ▼ │
112
+ │ overlay (Flutter) │
113
+ │ private, invisible to screen capture │
114
+ │ │
115
+ └─────────────────────────────────────────────────────────────────────┘
108
116
  ```
109
117
 
110
- Only writes if content has actually changed (avoids unnecessary git diffs).
118
+ ## Components
119
+
120
+ | Component | Language | What it does | Docs |
121
+ |---|---|---|---|
122
+ | **sinain-core** | TypeScript | Central hub: audio pipeline, agent loop, knowledge graph, WS feed | [README](https://github.com/anthillnet/sinain-hud/blob/main/sinain-core/README.md) |
123
+ | **overlay** | Dart / Swift | Private HUD (macOS), display modes, hotkeys | [Hotkeys](https://github.com/anthillnet/sinain-hud/blob/main/docs/HOTKEYS.md) |
124
+ | **sense_client** | Python | Screen capture, SSIM diff, OCR, privacy filter | [sense_client/](https://github.com/anthillnet/sinain-hud/tree/main/sense_client) |
125
+ | **sck-capture** | Swift | ScreenCaptureKit: system audio + screen frames | [tools/sck-capture/](https://github.com/anthillnet/sinain-hud/tree/main/tools/sck-capture) |
126
+ | **sinain-agent** | Bash | Shell harness that connects any agent to sinain-core | [sinain-agent/](https://github.com/anthillnet/sinain-hud/tree/main/sinain-agent) |
127
+ | **sinain-knowledge** | TypeScript | Curation, playbook, eval, portable knowledge modules | [Knowledge System](https://github.com/anthillnet/sinain-hud/blob/main/docs/knowledge-system.md) |
128
+ | **sinain-mcp-server** | TypeScript | MCP server exposing sinain tools to agents | [sinain-mcp-server/](https://github.com/anthillnet/sinain-hud/tree/main/sinain-mcp-server) |
129
+
130
+ ## Configuration
131
+
132
+ Sinain splits config across two files in `~/.sinain/`:
133
+
134
+ - **`.env`** — secrets (API keys) and infrastructure (ports, audio device, privacy mode, analyzer LLM).
135
+ - **`agents.json`** — agent roster (default agent, allowed-tools whitelists, analyzer pacing).
136
+
137
+ Both are created by the setup wizard. To re-run: `npx @geravant/sinain start --setup`.
138
+
139
+ ### Agents & profiles → `agents.json`
140
+
141
+ The agent roster lives in `~/.sinain/agents.json`. Each entry is a profile mapping a name to a binary + behavior type + optional env, settings, and model overrides. The overlay's flash-icon selector lets you pick which profile handles spawn tasks at runtime. Custom profiles like `pclaude` (personal claude with its own config dir) are first-class — the dispatch decision keys off `profile.type`, not the profile name.
142
+
143
+ See **[Agent Roster & Profiles](https://github.com/anthillnet/sinain-hud/blob/main/docs/AGENT-ROSTER.md)** for the complete schema, recipes, and routing model.
111
144
 
112
- Also ensures these directories exist:
113
- - `memory/`, `memory/playbook-archive/`, `memory/playbook-logs/`
114
- - `memory/eval-logs/`, `memory/eval-reports/`
145
+ ### Context Analysis (HUD summarizer) → `.env`
115
146
 
116
- After syncing modules, the plugin generates `memory/sinain-playbook-effective.md` — a merged view of active module patterns (sorted by priority) plus the base playbook.
147
+ The context analysis loop runs every 3–30 seconds, sending recent audio/screen context to an LLM. It produces the short HUD text shown on the overlay plus a richer digest stored in the feed buffer for the knowledge graph.
117
148
 
118
- ## Heartbeat Compliance Validation
149
+ | Variable | Default | Description |
150
+ |---|---|---|
151
+ | `ANALYSIS_PROVIDER` | `openrouter` | `openrouter` (cloud) or `ollama` (local, free) |
152
+ | `ANALYSIS_MODEL` | `google/gemini-2.5-flash-lite` | Primary model for text analysis |
153
+ | `ANALYSIS_VISION_MODEL` | `google/gemini-2.5-flash` | Auto-selected when screen images are present |
154
+ | `ANALYSIS_ENDPOINT` | *(auto per provider)* | Override for custom OpenAI-compatible endpoints |
155
+ | `ANALYSIS_API_KEY` | *(from OPENROUTER_API_KEY)* | API key; not needed for ollama |
156
+ | `ANALYSIS_FALLBACK_MODELS` | `gemini-2.5-flash,...` | Comma-separated fallback chain |
157
+
158
+ ### Other Key Settings → `.env`
159
+
160
+ | Variable | Default | Description |
161
+ |---|---|---|
162
+ | `OPENROUTER_API_KEY` | — | Required (unless `ANALYSIS_PROVIDER=ollama` + local transcription) |
163
+ | `PRIVACY_MODE` | `off` | `off` / `standard` / `strict` / `paranoid` |
164
+
165
+ See [docs/CONFIGURATION.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/CONFIGURATION.md) for the full reference.
166
+
167
+ ## Privacy Modes
168
+
169
+ | Mode | What it does |
170
+ |---|---|
171
+ | `off` | All data flows freely — maximum insight quality |
172
+ | `standard` | Auto-redacts credentials before cloud APIs (wizard default) |
173
+ | `strict` | Only summaries leave your machine — no raw text sent to cloud |
174
+ | `paranoid` | Fully local: Ollama + whisper.cpp. Zero network calls at runtime (embedding model pre-cached at install). |
119
175
 
120
- The plugin enforces that the agent actually calls `sinain_heartbeat_tick` during heartbeat runs:
176
+ See [Privacy Threat Model](https://github.com/anthillnet/sinain-hud/blob/main/docs/privacy-protection-design.md) for the full design.
121
177
 
122
- 1. `tool_result_persist` sets `heartbeatToolCalled = true` when `sinain_heartbeat_tick` is invoked
123
- 2. `agent_end` checks if the run was a heartbeat (`messageProvider === "heartbeat"`)
124
- 3. If tool wasn't called: logs warning, increments `consecutiveHeartbeatSkips` counter
125
- 4. After 3 consecutive skips: logs ESCALATION warning
126
- 5. A successful tool call resets the counter to 0
178
+ ## Hotkeys
127
179
 
128
- ## Privacy Tag Stripping
180
+ Global hotkeys use **Cmd+Shift**:
129
181
 
130
- The `tool_result_persist` hook intercepts tool results before they're saved to session history. Any `<private>...</private>` blocks are removed from:
131
- - String content (simple tool results)
132
- - Text blocks in array content (structured tool results)
182
+ | Shortcut | Action |
183
+ |---|---|
184
+ | `Cmd+Shift+Space` | Toggle overlay visibility |
185
+ | `Cmd+Shift+M` | Cycle display mode |
186
+ | `Cmd+Shift+/` | Open command input |
187
+ | `Cmd+Shift+H` | Quit overlay |
188
+
189
+ See [docs/HOTKEYS.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/HOTKEYS.md) for all 15 shortcuts.
133
190
 
134
- This is the server-side complement to sense_client's client-side `apply_privacy()` filter.
191
+ ## Running Fully Local
135
192
 
136
- ## Session Summaries
193
+ No cloud APIs needed. Local models handle everything:
194
+
195
+ ```bash
196
+ # 1. Install local transcription
197
+ ./setup-local-stt.sh
137
198
 
138
- On `agent_end`, the plugin appends a JSON line to `memory/session-summaries.jsonl`:
199
+ # 2. Install Ollama + vision model
200
+ brew install ollama && ollama pull llava
139
201
 
140
- ```json
141
- {
142
- "ts": "2026-02-18T12:00:00.000Z",
143
- "sessionKey": "agent:main:sinain",
144
- "agentId": "...",
145
- "durationMs": 45000,
146
- "success": true,
147
- "error": null,
148
- "toolCallCount": 12,
149
- "toolBreakdown": { "sessions_history": 3, "sinain_heartbeat_tick": 1, "Write": 5 },
150
- "messageCount": 8
151
- }
202
+ # 3. Start in local mode
203
+ ./start-local.sh
152
204
  ```
153
205
 
154
- ## Context Overflow Watchdog
206
+ | Model | Size | Speed | Best for |
207
+ |---|---|---|---|
208
+ | `llava` | 4.7 GB | ~2s/frame | General use (recommended) |
209
+ | `llama3.2-vision` | 7.9 GB | ~4s/frame | Best accuracy |
210
+ | `moondream` | 1.7 GB | ~1s/frame | Fastest, lower quality |
211
+
212
+ ## Setup Guides
213
+
214
+ | Setup | Guide |
215
+ |---|---|
216
+ | **Agent Roster & Profiles** | [docs/AGENT-ROSTER.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/AGENT-ROSTER.md) — pick agents, add custom profiles |
217
+ | **Bare Agent** | [docs/INSTALL-BARE-AGENT.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/INSTALL-BARE-AGENT.md) — the default install path |
218
+ | From Source | `git clone`, `cp .env.example ~/.sinain/.env`, `./start.sh` |
219
+
220
+ ## Knowledge System
155
221
 
156
- Automatically recovers from runaway context growth that causes repeated agent failures.
222
+ Sinain builds a persistent knowledge graph from everything it captures — audio transcriptions, screen OCR, and agent interactions. Facts are distilled incrementally (on buffer full and session end), stored in an EAV triplestore with graph relationships, and retrieved via hybrid search (FTS5 + tag-based + entity graph backrefs with RRF fusion).
157
223
 
158
- - **Detection:** Tracks consecutive errors matching `/overloaded|context.*too.*long|token.*limit/i` on `cfg.sessionKey`
159
- - **Trigger:** 5 consecutive errors + transcript ≥ 1 MB
160
- - **Action:** Archives transcript via `copyFileSync`, truncates to empty, resets `contextTokens` in `sessions.json`
161
- - **Resets:** Counter clears on any successful session completion and on `gateway_start`
224
+ The integration step is fully deterministic — no LLM decides what to store. Every extracted fact is preserved.
162
225
 
163
- The 1 MB minimum guard prevents resets from transient API outages when the transcript is small.
226
+ ```bash
227
+ npx @geravant/sinain export-knowledge # export playbook, modules, graph
228
+ npx @geravant/sinain import-knowledge ~/sinain-knowledge-export.tar.gz
229
+ ```
230
+
231
+ See [Knowledge System docs](https://github.com/anthillnet/sinain-hud/blob/main/docs/knowledge-system.md) for architecture details.
232
+
233
+ ### Querying knowledge from any MCP agent
164
234
 
165
- ## Deployment
235
+ Sinain's knowledge graph is exposed to any MCP-aware agent via the bundled MCP server. See **[Connect Your Coding Agent (MCP)](#connect-your-coding-agent-mcp)** below for setup.
166
236
 
167
- **IMPORTANT:** Use `docker-compose.openclaw.yml` — the default compose file uses unset env vars and will fail.
237
+ ## Connect Your Coding Agent (MCP)
238
+
239
+ Sinain ships an MCP server that exposes 15 `sinain_*` tools — including `sinain_knowledge_query`, `sinain_get_knowledge`, `sinain_distill_session`, `sinain_get_context`, and `sinain_respond` — to any MCP-aware agent. Register it once and the agent can read your knowledge graph and surface text on the HUD from any project.
168
240
 
169
241
  ```bash
170
- # Upload plugin files to the server
171
- scp -i ~/.ssh/<your-key> \
172
- sinain-hud-plugin/index.ts sinain-hud-plugin/openclaw.plugin.json \
173
- root@<your-server-ip>:/mnt/openclaw-state/extensions/sinain-hud/
174
-
175
- # Restart gateway to load updated plugin
176
- ssh -i ~/.ssh/<your-key> root@<your-server-ip> \
177
- 'cd /opt/openclaw && docker compose -f docker-compose.openclaw.yml restart'
178
-
179
- # Verify plugin loaded
180
- ssh -i ~/.ssh/<your-key> root@<your-server-ip> \
181
- 'cd /opt/openclaw && docker compose -f docker-compose.openclaw.yml logs --tail=30 openclaw-gateway 2>&1 | grep sinain'
242
+ npx @geravant/sinain@latest mcp install
182
243
  ```
183
244
 
184
- ## Files
245
+ The wizard detects which MCP agents you have installed and registers sinain for the ones you select. Re-runnable any time; idempotent.
246
+
247
+ | Agent | Setup | Config it touches |
248
+ |---|---|---|
249
+ | **Claude Code** | `mcp install` (auto via wizard) | `~/.claude.json` (`claude mcp add`) |
250
+ | **Claude Desktop** | `mcp install` (auto via wizard) | `~/Library/Application Support/Claude/claude_desktop_config.json` (mac) |
251
+ | **Cursor** | `mcp install` (auto via wizard) | `~/.cursor/mcp.json` |
252
+ | **Codex** | `mcp install` (auto via wizard) | `~/.codex/config.toml` (`codex mcp add`) |
253
+ | **Goose** | `mcp install` (auto via wizard) | `~/.config/goose/config.yaml` |
254
+ | **Junie** | `mcp install` (auto via wizard) | `~/.junie/mcp/mcp.json` |
255
+
256
+ > **Already in `sinain onboard`** — step 6 of the advanced flow runs the same registration. Quickstart asks once if any MCP agent is detected.
185
257
 
186
- | File | Purpose |
258
+ - See [docs/MCP-INTEGRATION.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/MCP-INTEGRATION.md) for setup details, troubleshooting, and the manual `pclaude` / alternate `CLAUDE_CONFIG_DIR` recipe.
259
+ - See [docs/MCP-CAPABILITIES.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/MCP-CAPABILITIES.md) for what each tool enables, with example prompts and end-to-end recipes.
260
+
261
+ ## Deep Dives
262
+
263
+ | Topic | Doc |
187
264
  |---|---|
188
- | `index.ts` | Plugin implementation (hooks, tool, commands, curation service) |
189
- | `openclaw.plugin.json` | Plugin manifest (metadata, config schema, UI hints) |
265
+ | Knowledge System | [docs/knowledge-system.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/knowledge-system.md) |
266
+ | Knowledge API (HTTP) | [docs/KNOWLEDGE-API.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/KNOWLEDGE-API.md) |
267
+ | MCP Integration (setup) | [docs/MCP-INTEGRATION.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/MCP-INTEGRATION.md) |
268
+ | MCP Capabilities (tools + recipes) | [docs/MCP-CAPABILITIES.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/MCP-CAPABILITIES.md) |
269
+ | LongMemEval Audit | [docs/LONGMEMEVAL-AUDIT.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/LONGMEMEVAL-AUDIT.md) |
270
+ | Privacy Threat Model | [docs/privacy-protection-design.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/privacy-protection-design.md) |
271
+ | Full Configuration | [docs/CONFIGURATION.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/CONFIGURATION.md) |
272
+ | All Hotkeys | [docs/HOTKEYS.md](https://github.com/anthillnet/sinain-hud/blob/main/docs/HOTKEYS.md) |
273
+
274
+ ## Source
275
+
276
+ Full source, issues, and contributing guide: **[github.com/anthillnet/sinain-hud](https://github.com/anthillnet/sinain-hud)**
277
+
278
+ ## Contributing
279
+
280
+ See [CONTRIBUTING.md](https://github.com/anthillnet/sinain-hud/blob/main/CONTRIBUTING.md).
281
+
282
+ ## License
283
+
284
+ MIT
package/onboard.js CHANGED
@@ -267,6 +267,37 @@ export async function runOnboard(args = {}) {
267
267
  }
268
268
  }
269
269
 
270
+ // If Ollama is installed, offer to pull a local LLM for paranoid-mode
271
+ // analysis. Mirrors the whisper download pattern — auto-acquire optional,
272
+ // user can `ollama pull <model>` manually later if they skip here.
273
+ let ollamaInstalled = false;
274
+ try {
275
+ execFileSync("ollama", ["--version"], { stdio: "ignore" });
276
+ ollamaInstalled = true;
277
+ } catch { /* ollama not on PATH */ }
278
+
279
+ if (ollamaInstalled) {
280
+ const pullOllama = guard(await p.confirm({
281
+ message: "Pull an Ollama model for paranoid-mode analysis (~4.7 GB for llava)?",
282
+ initialValue: true,
283
+ }));
284
+ if (pullOllama) {
285
+ const modelName = guard(await p.text({
286
+ message: "Ollama model to pull",
287
+ placeholder: "llava",
288
+ defaultValue: "llava",
289
+ }));
290
+ const s = p.spinner();
291
+ s.start(`Pulling ${modelName} via Ollama (this can take several minutes)...`);
292
+ try {
293
+ execFileSync("ollama", ["pull", modelName], { stdio: "inherit" });
294
+ s.stop(c.green(`Pulled ${modelName}.`));
295
+ } catch {
296
+ s.stop(c.yellow(`Pull failed. Run \`ollama pull ${modelName}\` manually later.`));
297
+ }
298
+ }
299
+ }
300
+
270
301
  // OpenClaw gateway is opt-in: most users run sinain in standalone mode
271
302
  // and never need a gateway. Default the prompt to "No" on fresh installs
272
303
  // (when no openclaw profile already exists) so accepting all wizard
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@geravant/sinain",
3
- "version": "1.23.7",
3
+ "version": "1.24.1",
4
4
  "description": "Context OS — ambient intelligence for builders. Captures screen + audio, distills into a private knowledge graph, accessible from MCP, web UI, and HUD overlay.",
5
5
  "type": "module",
6
6
  "bin": {