@geravant/sinain 1.1.0 → 1.2.1

package/index.ts

@@ -560,8 +560,10 @@ export default function sinainHudPlugin(api: OpenClawPluginApi): void {
           `sinain-hud: session summary written (${toolCount} tools, ${Math.round(durationMs / 1000)}s)`,
         );
 
-        // Fire-and-forget: ingest session summary into triple store
-        if (state.workspaceDir) {
+        // Fire-and-forget: ingest session summary into knowledge graph
+        // NOTE: Main knowledge integration happens in heartbeat tick (session_distiller + knowledge_integrator).
+        // This is a lightweight best-effort path for when agent_end fires (won't fire on kill).
+        if (false && state.workspaceDir) {
           api.runtime.system.runCommandWithTimeout(
             ["uv", "run", "--with", "requests", "python3",
              "sinain-memory/triple_ingest.py",

package/install.js

@@ -3,6 +3,7 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import { execSync } from "child_process";
+import { randomBytes } from "crypto";
 
 const HOME        = os.homedir();
 const PLUGIN_DIR  = path.join(HOME, ".openclaw/extensions/sinain-hud");
@@ -18,7 +19,9 @@ const SKILL      = path.join(PKG_DIR, "SKILL.md");
 
 console.log("\nInstalling sinain plugin...");
 
-// 1. Stage plugin files to local ~/.openclaw (used by both paths)
+// 1. Copy plugin files (remove stale extensions/sinain dir if present from old installs)
+const stalePluginDir = path.join(HOME, ".openclaw/extensions/sinain");
+if (fs.existsSync(stalePluginDir)) fs.rmSync(stalePluginDir, { recursive: true, force: true });
 fs.mkdirSync(PLUGIN_DIR, { recursive: true });
 fs.copyFileSync(path.join(PKG_DIR, "index.ts"),             path.join(PLUGIN_DIR, "index.ts"));
 fs.copyFileSync(path.join(PKG_DIR, "openclaw.plugin.json"), path.join(PLUGIN_DIR, "openclaw.plugin.json"));
@@ -115,6 +118,8 @@ async function installNemoClaw({ sandboxName }) {
       sessionKey:    "agent:main:sinain"
     }
   };
+  // Remove stale "sinain" entry if present from a previous install
+  delete cfg.plugins.entries["sinain"];
   if (!cfg.plugins.allow.includes("sinain-hud")) cfg.plugins.allow.push("sinain-hud");
   cfg.agents                                         ??= {};
   cfg.agents.defaults                                ??= {};
@@ -145,6 +150,19 @@ async function installNemoClaw({ sandboxName }) {
     }
   }
 
+  // Knowledge snapshot repo (optional) — inside sandbox
+  const snapshotUrl = process.env.SINAIN_SNAPSHOT_REPO;
+  if (snapshotUrl) {
+    try {
+      await checkRepoPrivacy(snapshotUrl);
+      run(`ssh -T openshell-${sandboxName} 'mkdir -p ~/.sinain/knowledge-snapshots && cd ~/.sinain/knowledge-snapshots && ([ -d .git ] || (git init && git config user.name sinain-knowledge && git config user.email sinain@local)) && (git remote get-url origin >/dev/null 2>&1 && git remote set-url origin "${snapshotUrl}" || git remote add origin "${snapshotUrl}") && (git fetch origin && git checkout -B main origin/main) 2>/dev/null || true'`);
+      console.log("  ✓ Snapshot repo configured in sandbox");
+    } catch (e) {
+      console.error("\n  ✗ Snapshot repo setup aborted:", e.message, "\n");
+      process.exit(1);
+    }
+  }
+
   // Restart openclaw gateway inside sandbox (kill existing PID + start fresh)
   try {
     // Find the gateway PID, kill it, then start a new instance detached
@@ -201,6 +219,10 @@ async function installLocal() {
       sessionKey:    "agent:main:sinain"
     }
   };
+  // Remove stale "sinain" entry if present from a previous install
+  delete cfg.plugins.entries["sinain"];
+  cfg.plugins.allow ??= [];
+  if (!cfg.plugins.allow.includes("sinain-hud")) cfg.plugins.allow.push("sinain-hud");
   cfg.agents                                         ??= {};
   cfg.agents.defaults                                ??= {};
   cfg.agents.defaults.sandbox                        ??= {};
@@ -241,25 +263,70 @@ async function installLocal() {
     }
   }
 
-  // Reload gateway
+  // Knowledge snapshot repo (optional)
+  await setupSnapshotRepo();
+
+  // Start / restart gateway
   try {
-    execSync("openclaw reload", { stdio: "pipe" });
-    console.log("  ✓ Gateway reloaded");
+    execSync("openclaw gateway restart --background", { stdio: "pipe" });
+    console.log("  ✓ Gateway restarted");
   } catch {
     try {
-      execSync("openclaw stop && sleep 1 && openclaw start --background", { stdio: "pipe" });
-      console.log("  ✓ Gateway restarted");
+      execSync("openclaw gateway start --background", { stdio: "pipe" });
+      console.log("  ✓ Gateway started");
     } catch {
       console.warn("  ⚠ Could not start gateway — run: openclaw gateway");
     }
   }
 
-  console.log(`
-✓ sinain installed successfully.
-  Plugin config: ~/.openclaw/openclaw.json
-  Auth token:    check your Brev dashboard → 'Gateway Token'
-  Then run ./setup-nemoclaw.sh on your Mac.
-`);
+  const token = cfg?.gateway?.auth?.token ?? "(see openclaw.json)";
+  console.log("\n✓ sinain installed successfully.");
+  console.log("  Plugin config: ~/.openclaw/openclaw.json");
+  console.log(`  Auth token:    ${token}`);
+  console.log("  Next: run 'openclaw gateway' if not running, or restart to pick up changes.\n");
+}
+
+// ── Knowledge snapshot repo setup (shared) ──────────────────────────────────
+
+const SNAPSHOT_DIR = path.join(HOME, ".sinain", "knowledge-snapshots");
+
+async function setupSnapshotRepo() {
+  const snapshotUrl = process.env.SINAIN_SNAPSHOT_REPO;
+  if (!snapshotUrl) return;
+
+  try {
+    await checkRepoPrivacy(snapshotUrl);
+    fs.mkdirSync(SNAPSHOT_DIR, { recursive: true });
+
+    if (!fs.existsSync(path.join(SNAPSHOT_DIR, ".git"))) {
+      execSync(`git init "${SNAPSHOT_DIR}"`, { stdio: "pipe" });
+      execSync(`git -C "${SNAPSHOT_DIR}" config user.name "sinain-knowledge"`, { stdio: "pipe" });
+      execSync(`git -C "${SNAPSHOT_DIR}" config user.email "sinain@local"`, { stdio: "pipe" });
+    }
+
+    // Set remote (add or update)
+    try {
+      run_capture(`git -C "${SNAPSHOT_DIR}" remote get-url origin`);
+      execSync(`git -C "${SNAPSHOT_DIR}" remote set-url origin "${snapshotUrl}"`, { stdio: "pipe" });
+    } catch {
+      execSync(`git -C "${SNAPSHOT_DIR}" remote add origin "${snapshotUrl}"`, { stdio: "pipe" });
+    }
+
+    // Pull existing snapshots if remote has content
+    try {
+      execSync(`git -C "${SNAPSHOT_DIR}" fetch origin`, { stdio: "pipe", timeout: 15_000 });
+      execSync(`git -C "${SNAPSHOT_DIR}" checkout -B main origin/main`, { stdio: "pipe" });
+      console.log("  ✓ Snapshot repo restored from", snapshotUrl);
+    } catch {
+      console.log("  ✓ Snapshot repo configured (empty remote)");
+    }
+  } catch (e) {
+    if (e.message?.startsWith("SECURITY") || e.message?.startsWith("Refusing")) {
+      console.error("\n  ✗ Snapshot repo setup aborted:", e.message, "\n");
+      process.exit(1);
+    }
+    console.warn("  ⚠ Snapshot repo setup failed:", e.message);
+  }
 }
 
 // ── Detection ────────────────────────────────────────────────────────────────

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@geravant/sinain",
-  "version": "1.1.0",
-  "description": "sinain — AI overlay system for macOS (npx @geravant/sinain start)",
+  "version": "1.2.1",
+  "description": "Ambient AI overlay invisible to screen capture — real-time insights from audio + screen context",
   "type": "module",
   "bin": {
     "sinain": "./cli.js",

package/sinain-agent/CLAUDE.md

@@ -12,8 +12,10 @@ You have MCP tools from `sinain-mcp-server`:
 - `sinain_get_feedback` — get feedback signals from recent escalations
 - `sinain_post_feed` — push an arbitrary message to the HUD
 - `sinain_health` — check system health
-- `sinain_knowledge_query` — query the knowledge graph for relevant context
-- `sinain_heartbeat_tick` — run the full curation pipeline (git backup, signals, insights, playbook)
+- `sinain_get_knowledge` — get the portable knowledge document (playbook + long-term facts + sessions)
+- `sinain_knowledge_query` — query the knowledge graph for facts about specific entities/domains
+- `sinain_distill_session` — explicitly distill the current session into knowledge updates
+- `sinain_heartbeat_tick` — run the heartbeat pipeline (git backup, signals, distillation, insights)
 - `sinain_module_guidance` — get active module guidance
 
 ## Main Loop
@@ -23,7 +25,7 @@ Your primary job is an escalation response loop:
 1. Call `sinain_get_escalation` to check for pending escalations
 2. If an escalation is present:
    a. Read the escalation message carefully — it contains screen OCR, audio transcripts, app context, and the local agent's digest
-   b. Optionally call `sinain_knowledge_query` with key context from the escalation to enrich your response
+   b. Optionally call `sinain_get_knowledge` to read the knowledge document, or `sinain_knowledge_query` with specific entities to enrich your response
    c. Optionally call `sinain_module_guidance` to get active module instructions
    d. Craft a response and call `sinain_respond` with the escalation ID and your response
 3. If no escalation is pending, wait a few seconds and poll again
@@ -47,10 +49,12 @@ When responding to escalations:
 2. The tool runs the full pipeline automatically:
    - Git backup of memory directory
    - Signal analysis (detects opportunities from session patterns)
+   - **Session distillation** — fetches new feed items from sinain-core, distills patterns/learnings
+   - **Knowledge integration** — updates playbook (working memory) and knowledge graph (long-term memory)
    - Insight synthesis (generates suggestions from accumulated patterns)
-   - Playbook curation (updates effective playbook based on feedback)
 3. If the result contains a suggestion or insight, post it to the HUD via `sinain_post_feed`
-4. Optionally call `sinain_get_feedback` to review recent escalation scores
+4. Optionally call `sinain_get_knowledge` to review the portable knowledge document
+5. Optionally call `sinain_get_feedback` to review recent escalation scores
 
 ## Spawning Background Tasks
 
@@ -69,8 +73,11 @@ Rules:
 ## Files You Manage
 
 Your working memory lives at `~/.openclaw/workspace/memory/`:
-- `playbook.md` — your effective playbook (updated by curation pipeline)
-- `triplestore.db` — knowledge graph (SQLite, managed by Python scripts)
+- `sinain-playbook.md` — your effective playbook (working memory, updated by knowledge integrator)
+- `knowledge-graph.db` — long-term knowledge graph (SQLite, curated facts with confidence tracking)
+- `sinain-knowledge.md` — portable knowledge document (<8KB, playbook + top graph facts + recent sessions)
+- `session-digests.jsonl` — session distillation history
+- `distill-state.json` — watermark for what's been distilled
 - `playbook-logs/YYYY-MM-DD.jsonl` — decision logs
 
 ## Privacy

package/sinain-core/.env.example

@@ -14,7 +14,6 @@ AUDIO_VAD_ENABLED=true
 AUDIO_VAD_THRESHOLD=0.003
 AUDIO_AUTO_START=true
 AUDIO_GAIN_DB=20
-# AUDIO_ALT_DEVICE=                # alternate device for switch_device command
 
 # ── Microphone (opt-in for privacy) ──
 MIC_ENABLED=false                  # set true to capture user's microphone

package/sinain-core/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sinain-core",
   "version": "1.0.0",
-  "description": "Unified HUD-sense-audio-bridge-relay — replaces relay + bridge with a single process",
+  "description": "SinainHUD core — audio transcription, agent analysis loop, escalation orchestration, WebSocket feed",
   "type": "module",
   "main": "dist/index.js",
   "scripts": {

package/sinain-core/src/config.ts

@@ -228,7 +228,6 @@ export function loadConfig(): CoreConfig {
   return {
     port: intEnv("PORT", 9500),
     audioConfig,
-    audioAltDevice: env("AUDIO_ALT_DEVICE", "BlackHole 2ch"),
     micConfig,
     micEnabled,
     transcriptionConfig,

package/sinain-core/src/escalation/escalator.ts

@@ -1,4 +1,4 @@
-import type { AgentEntry, ContextWindow, EscalationConfig, OpenClawConfig, FeedItem, SpawnTaskMessage, SpawnTaskStatus } from "../types.js";
+import type { AgentEntry, ContextWindow, EscalationConfig, OpenClawConfig, FeedItem, SpawnTaskMessage, SpawnTaskStatus, UserCommand } from "../types.js";
 import type { FeedBuffer } from "../buffers/feed-buffer.js";
 import type { WsHandler } from "../overlay/ws-handler.js";
 import type { Profiler } from "../profiler.js";
@@ -9,7 +9,7 @@ import { OpenClawWsClient } from "./openclaw-ws.js";
 import { EscalationSlot } from "./escalation-slot.js";
 import type { SlotEntry, QueueFeedbackCtx } from "./escalation-slot.js";
 import { shouldEscalate, calculateEscalationScore } from "./scorer.js";
-import { isCodingContext, buildEscalationMessage } from "./message-builder.js";
+import { isCodingContext, buildEscalationMessage, fetchKnowledgeFacts } from "./message-builder.js";
 import { loadPendingTasks, savePendingTasks, type PendingTaskEntry } from "../util/task-store.js";
 import { log, warn, error } from "../log.js";
 
@@ -32,6 +32,7 @@ export interface EscalatorDeps {
   profiler?: Profiler;
   feedbackStore?: FeedbackStore;
   signalCollector?: SignalCollector;
+  queryKnowledgeFacts?: (entities: string[], maxFacts: number) => Promise<string>;
 }
 
 /**
@@ -73,6 +74,10 @@ export class Escalator {
   // Store context from last escalation for response handling
   private lastEscalationContext: ContextWindow | null = null;
 
+  // User command to inject into the next escalation
+  private pendingUserCommand: UserCommand | null = null;
+  private static readonly USER_COMMAND_EXPIRY_MS = 120_000; // 2 minutes
+
   private stats = {
     totalEscalations: 0,
     totalResponses: 0,
@@ -122,6 +127,15 @@ export class Escalator {
     this.deps.signalCollector = sc;
   }
 
+  /** Queue a user command to inject into the next escalation. */
+  setUserCommand(text: string, source: "text" | "voice" = "text"): void {
+    this.pendingUserCommand = { text, ts: Date.now(), source };
+    const preview = text.length > 60 ? text.slice(0, 60) + "…" : text;
+    this.deps.feedBuffer.push(`⌘ Command queued: ${preview}`, "normal", "system", "stream");
+    this.deps.wsHandler.broadcast(`⌘ Command queued: ${preview}`, "normal");
+    log(TAG, `user command set: "${preview}"`);
+  }
+
   /** Start the WS connection to OpenClaw (skipped when transport=http). */
   start(): void {
     if (this.deps.escalationConfig.mode !== "off" && this.deps.escalationConfig.transport !== "http") {
@@ -159,7 +173,15 @@ export class Escalator {
    * Called after every agent analysis tick.
    * Decides whether to escalate and enqueues the message for delivery.
    */
-  onAgentAnalysis(entry: AgentEntry, contextWindow: ContextWindow): void {
+  async onAgentAnalysis(entry: AgentEntry, contextWindow: ContextWindow): Promise<void> {
+    // Expire stale user commands (safety net — 120s is generous)
+    if (this.pendingUserCommand && Date.now() - this.pendingUserCommand.ts > Escalator.USER_COMMAND_EXPIRY_MS) {
+      warn(TAG, `user command expired after ${Escalator.USER_COMMAND_EXPIRY_MS / 1000}s — no escalation occurred`);
+      this.deps.feedBuffer.push("⚠ Command expired — no escalation occurred", "normal", "system", "stream");
+      this.deps.wsHandler.broadcast("⚠ Command expired — no escalation occurred", "normal");
+      this.pendingUserCommand = null;
+    }
+
     // Skip WS escalations when circuit is open (HTTP transport bypasses this)
     const transport = this.deps.escalationConfig.transport;
     if (this.wsClient.isCircuitOpen && transport !== "http") {
@@ -167,6 +189,9 @@ export class Escalator {
       return;
     }
 
+    // If user command is pending, force escalation (bypass score + cooldown)
+    const hasUserCommand = this.pendingUserCommand !== null;
+
     const { escalate, score, stale } = shouldEscalate(
       entry.digest,
       entry.hud,
@@ -178,7 +203,7 @@ export class Escalator {
       this.deps.escalationConfig.staleMs,
     );
 
-    if (!escalate) {
+    if (!escalate && !hasUserCommand) {
       log(TAG, `tick #${entry.id}: not escalating (mode=${this.deps.escalationConfig.mode}, score=${score.total}, hud="${entry.hud.slice(0, 40)}")`);
       return;
     }
@@ -191,21 +216,44 @@ export class Escalator {
     this.lastEscalatedDigest = entry.digest;
 
     const staleTag = stale ? ", STALE" : "";
+    const cmdTag = hasUserCommand ? ", USER_CMD" : "";
     const wsState = this.wsClient.isConnected ? "ws=connected" : "ws=disconnected";
-    log(TAG, `escalating tick #${entry.id} (score=${score.total}, reasons=[${score.reasons.join(",")}]${staleTag}, ${wsState})`);
+    log(TAG, `escalating tick #${entry.id} (score=${score.total}, reasons=[${score.reasons.join(",")}]${staleTag}${cmdTag}, ${wsState})`);
 
     // Store context for response handling (used in pushResponse for coding-context max-length)
     this.lastEscalationContext = contextWindow;
 
-    const escalationReason = score.reasons.join(", ");
-    const message = buildEscalationMessage(
+    const escalationReason = hasUserCommand
+      ? `user_command: ${this.pendingUserCommand!.text.slice(0, 80)}`
+      : score.reasons.join(", ");
+    let message = buildEscalationMessage(
       entry.digest,
       contextWindow,
       entry,
       this.deps.escalationConfig.mode,
       escalationReason,
+      undefined,
+      this.pendingUserCommand ?? undefined,
     );
 
+    // Clear user command after building the message (consumed once)
+    this.pendingUserCommand = null;
+
+    // Enrich with long-term knowledge facts (best-effort, 5s max)
+    if (this.deps.queryKnowledgeFacts) {
+      try {
+        const knowledgeSection = await fetchKnowledgeFacts(
+          contextWindow, entry.digest, this.deps.queryKnowledgeFacts,
+        );
+        if (knowledgeSection) {
+          message = message + "\n\n" + knowledgeSection;
+          log(TAG, `knowledge enrichment injected (${knowledgeSection.length} chars)`);
+        }
+      } catch (err) {
+        log(TAG, `knowledge enrichment failed: ${String(err)}`);
+      }
+    }
+
     const slotId = createHash("sha256").update(this.deps.openclawConfig.sessionKey + entry.ts).digest("hex").slice(0, 16);
     const slotEntry: SlotEntry = {
       id: slotId,
@@ -373,6 +421,7 @@ ${recentLines.join("\n")}`;
       cooldownMs: this.deps.escalationConfig.cooldownMs,
       staleMs: this.deps.escalationConfig.staleMs,
       pendingSpawnTasks: this.pendingSpawnTasks.size,
+      pendingUserCommand: this.pendingUserCommand ? this.pendingUserCommand.text.slice(0, 80) : null,
       ...this.stats,
     };
   }

package/sinain-core/src/escalation/message-builder.ts

@@ -1,4 +1,4 @@
-import type { ContextWindow, AgentEntry, EscalationMode, FeedbackRecord } from "../types.js";
+import type { ContextWindow, AgentEntry, EscalationMode, FeedbackRecord, UserCommand } from "../types.js";
 import { normalizeAppName } from "../agent/context-window.js";
 import { levelFor, applyLevel } from "../privacy/index.js";
 
@@ -142,12 +142,18 @@ export function buildEscalationMessage(
   mode: EscalationMode,
   escalationReason?: string,
   recentFeedback?: FeedbackRecord[],
+  userCommand?: UserCommand,
 ): string {
   const sections: string[] = [];
 
   // Header with tick metadata
   sections.push(`[sinain-hud live context — tick #${entry.id}]`);
 
+  // User command — placed at the top so the agent sees it first
+  if (userCommand) {
+    sections.push(`## User Command\n> ${userCommand.text}\n\nThe user has explicitly asked you to address the above command. Prioritize it in your response.`);
+  }
+
   // Digest (always full)
   sections.push(`## Digest\n${digest}`);
 
@@ -292,6 +298,53 @@ the local analyzer reported idle/no-change. Provide a PROACTIVE response:
   return sections.join("\n\n");
 }
 
+/**
+ * Fetch relevant long-term knowledge facts for the current escalation context.
+ * Extracts entities from the context and queries the knowledge graph.
+ * Returns a formatted section or empty string if no relevant facts found.
+ */
+export async function fetchKnowledgeFacts(
+  context: ContextWindow,
+  digest: string,
+  queryFn?: (entities: string[], maxFacts: number) => Promise<string>,
+): Promise<string> {
+  if (!queryFn) return "";
+
+  // Extract entities from context: current app + error types + domain keywords
+  const entities: string[] = [];
+  const app = normalizeAppName(context.currentApp).toLowerCase().replace(/\s+/g, "-");
+  if (app && app.length > 2) entities.push(app);
+
+  // Extract error type keywords from digest
+  const errorPatterns = digest.matchAll(
+    /(?:Error|Exception|TypeError|SyntaxError|ReferenceError|HTTP\s*\d{3}|ENOENT|EACCES)/gi,
+  );
+  for (const m of errorPatterns) {
+    entities.push(m[0].toLowerCase());
+  }
+
+  // Extract technology keywords
+  const techKeywords = [
+    "react-native", "react", "flutter", "swift", "kotlin", "python",
+    "typescript", "node", "docker", "metro", "gradle", "cocoapods",
+    "intellij", "vscode", "xcode", "sinain",
+  ];
+  const lowerDigest = digest.toLowerCase();
+  for (const kw of techKeywords) {
+    if (lowerDigest.includes(kw)) entities.push(kw);
+  }
+
+  if (entities.length === 0) return "";
+
+  try {
+    const factsText = await queryFn(entities.slice(0, 5), 5);
+    if (factsText && factsText.trim().length > 20) {
+      return `## Past Experience\nBased on long-term knowledge relevant to this context:\n${factsText.trim()}`;
+    }
+  } catch {}
+  return "";
+}
+
 /**
  * Format a compact inline feedback section for escalation messages.
  * Shows recent performance so the agent can calibrate its response style.

package/sinain-core/src/index.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { loadConfig } from "./config.js";
 import { FeedBuffer } from "./buffers/feed-buffer.js";
 import { SenseBuffer } from "./buffers/sense-buffer.js";
@@ -78,6 +79,17 @@ async function main() {
     openclawConfig: config.openclawConfig,
     profiler,
     feedbackStore: feedbackStore ?? undefined,
+    queryKnowledgeFacts: async (entities: string[], maxFacts: number) => {
+      const workspace = process.env.SINAIN_WORKSPACE || `${process.env.HOME}/.openclaw/workspace`;
+      const dbPath = `${workspace}/memory/knowledge-graph.db`;
+      const scriptPath = `${workspace}/sinain-memory/graph_query.py`;
+      try {
+        const { execFileSync } = await import("node:child_process");
+        const args = [scriptPath, "--db", dbPath, "--max-facts", String(maxFacts), "--format", "text"];
+        if (entities.length > 0) args.push("--entities", JSON.stringify(entities));
+        return execFileSync("python3", args, { timeout: 5000, encoding: "utf-8" });
+      } catch { return ""; }
+    },
   });
 
   // ── Initialize agent loop (event-driven) ──
@@ -379,9 +391,31 @@ async function main() {
     getTraces: (after, limit) => tracer ? tracer.getTraces(after, limit) : [],
     reconnectGateway: () => escalator.reconnectGateway(),
 
+    // User command injection (bare agent / HTTP)
+    setUserCommand: (text: string) => escalator.setUserCommand(text),
+
     // Bare agent HTTP escalation bridge
     getEscalationPending: () => escalator.getPendingHttp(),
     respondEscalation: (id: string, response: string) => escalator.respondHttp(id, response),
+
+    // Knowledge graph integration
+    getKnowledgeDocPath: () => {
+      const workspace = process.env.SINAIN_WORKSPACE || `${process.env.HOME}/.openclaw/workspace`;
+      const p = `${workspace}/memory/sinain-knowledge.md`;
+      try { if (existsSync(p)) return p; } catch {}
+      return null;
+    },
+    queryKnowledgeFacts: async (entities: string[], maxFacts: number) => {
+      const workspace = process.env.SINAIN_WORKSPACE || `${process.env.HOME}/.openclaw/workspace`;
+      const dbPath = `${workspace}/memory/knowledge-graph.db`;
+      const scriptPath = `${workspace}/sinain-memory/graph_query.py`;
+      try {
+        const { execFileSync } = await import("node:child_process");
+        const args = [scriptPath, "--db", dbPath, "--max-facts", String(maxFacts), "--format", "text"];
+        if (entities.length > 0) args.push("--entities", JSON.stringify(entities));
+        return execFileSync("python3", args, { timeout: 5000, encoding: "utf-8" });
+      } catch { return ""; }
+    },
   });
 
   // ── Wire overlay profiling ──
@@ -398,6 +432,9 @@ async function main() {
     onUserMessage: async (text) => {
       await escalator.sendDirect(text);
     },
+    onUserCommand: (text) => {
+      escalator.setUserCommand(text);
+    },
     onToggleScreen: () => {
       screenActive = !screenActive;
       if (!screenActive) {

package/sinain-core/src/overlay/commands.ts

@@ -13,6 +13,8 @@ export interface CommandDeps {
   micPipeline: AudioPipeline | null;
   config: CoreConfig;
   onUserMessage: (text: string) => Promise<void>;
+  /** Queue a user command to augment the next escalation */
+  onUserCommand: (text: string) => void;
   /** Toggle screen capture — returns new state */
   onToggleScreen: () => boolean;
   /** Toggle trait voices — returns new enabled state */
@@ -37,6 +39,11 @@ export function setupCommands(deps: CommandDeps): void {
         }
         break;
       }
+      case "user_command": {
+        log(TAG, `user command received: "${msg.text.slice(0, 60)}"`);
+        deps.onUserCommand(msg.text);
+        break;
+      }
       case "command": {
         handleCommand(msg.action, deps);
         log(TAG, `command processed: ${msg.action}`);
@@ -47,7 +54,7 @@ export function setupCommands(deps: CommandDeps): void {
 }
 
 function handleCommand(action: string, deps: CommandDeps): void {
-  const { wsHandler, systemAudioPipeline, micPipeline, config } = deps;
+  const { wsHandler, systemAudioPipeline, micPipeline } = deps;
 
   switch (action) {
     case "toggle_audio": {
@@ -100,15 +107,6 @@ function handleCommand(action: string, deps: CommandDeps): void {
       log(TAG, `screen toggled ${nowActive ? "ON" : "OFF"}`);
       break;
     }
-    case "switch_device": {
-      const current = systemAudioPipeline.getDevice();
-      const alt = config.audioAltDevice;
-      const next = current === config.audioConfig.device ? alt : config.audioConfig.device;
-      systemAudioPipeline.switchDevice(next);
-      wsHandler.broadcast(`Audio device \u2192 ${next}`, "normal");
-      log(TAG, `audio device switched: ${current} \u2192 ${next}`);
-      break;
-    }
     case "toggle_traits": {
       if (!deps.onToggleTraits) {
         wsHandler.broadcast("Trait voices not configured", "normal");

package/sinain-core/src/overlay/ws-handler.ts

@@ -194,6 +194,9 @@ export class WsHandler {
       case "command":
         log(TAG, `\u2190 command: ${msg.action}`);
         break;
+      case "user_command":
+        log(TAG, `\u2190 user command: ${msg.text.slice(0, 100)}`);
+        break;
       case "profiling":
         if (this.onProfilingCb) this.onProfilingCb(msg);
         return;

package/sinain-core/src/server.ts

@@ -34,8 +34,11 @@ export interface ServerDeps {
   getTraces: (after: number, limit: number) => unknown[];
   reconnectGateway: () => void;
   feedbackStore?: FeedbackStore;
+  setUserCommand?: (text: string) => void;
   getEscalationPending?: () => any;
   respondEscalation?: (id: string, response: string) => any;
+  getKnowledgeDocPath?: () => string | null;
+  queryKnowledgeFacts?: (entities: string[], maxFacts: number) => Promise<string>;
 }
 
 function readBody(req: IncomingMessage, maxBytes: number): Promise<string> {
@@ -207,6 +210,43 @@ export function createAppServer(deps: ServerDeps) {
         return;
       }
 
+      // ── /knowledge ──
+      if (req.method === "GET" && url.pathname === "/knowledge") {
+        // Return portable knowledge document
+        const knowledgePath = deps.getKnowledgeDocPath?.();
+        if (knowledgePath) {
+          try {
+            const { readFileSync } = await import("node:fs");
+            const content = readFileSync(knowledgePath, "utf-8");
+            res.end(JSON.stringify({ ok: true, content }));
+          } catch {
+            res.end(JSON.stringify({ ok: true, content: "" }));
+          }
+        } else {
+          res.end(JSON.stringify({ ok: true, content: "" }));
+        }
+        return;
+      }
+
+      if (req.method === "GET" && url.pathname === "/knowledge/facts") {
+        // Query knowledge graph for entity-matched facts
+        const entitiesParam = url.searchParams.get("entities") || "";
+        const maxFacts = Math.min(parseInt(url.searchParams.get("max") || "5"), 20);
+        const entities = entitiesParam.split(",").map(e => e.trim()).filter(Boolean);
+
+        if (deps.queryKnowledgeFacts) {
+          try {
+            const facts = await deps.queryKnowledgeFacts(entities, maxFacts);
+            res.end(JSON.stringify({ ok: true, facts }));
+          } catch (err) {
+            res.end(JSON.stringify({ ok: true, facts: [], error: String(err) }));
+          }
+        } else {
+          res.end(JSON.stringify({ ok: true, facts: [] }));
+        }
+        return;
+      }
+
       // ── /traces ──
       if (req.method === "GET" && url.pathname === "/traces") {
         const after = parseInt(url.searchParams.get("after") || "0");
@@ -266,6 +306,20 @@ export function createAppServer(deps: ServerDeps) {
         return;
       }
 
+      // ── /user/command ──
+      if (req.method === "POST" && url.pathname === "/user/command") {
+        const body = await readBody(req, 4096);
+        const { text } = JSON.parse(body);
+        if (!text) {
+          res.writeHead(400);
+          res.end(JSON.stringify({ ok: false, error: "missing text" }));
+          return;
+        }
+        deps.setUserCommand?.(text);
+        res.end(JSON.stringify({ ok: true, message: "Command queued for next escalation" }));
+        return;
+      }
+
       // ── /escalation/pending ──
       if (req.method === "GET" && url.pathname === "/escalation/pending") {
         const pending = deps.getEscalationPending?.();