@awareness-sdk/local 0.1.13 → 0.2.1

package/bin/awareness-local.mjs

@@ -433,6 +433,17 @@ async function cmdReindex(flags) {
   }
 }
 
+/**
+ * Run as a stdio MCP server (for IDE integrations like Claude Code).
+ */
+async function cmdMcp(flags) {
+  const projectDir = resolveProjectDir(flags);
+  const port = resolvePort(flags);
+
+  const { startStdioMcp } = await import('../src/mcp-stdio.mjs');
+  await startStdioMcp({ port, projectDir });
+}
+
 // ---------------------------------------------------------------------------
 // Help
 // ---------------------------------------------------------------------------
@@ -449,6 +460,7 @@ Commands:
   stop      Stop the daemon
   status    Show daemon status and stats
   reindex   Rebuild the search index
+  mcp       Run as stdio MCP server
 
 Options:
   --project <dir>   Project directory (default: current directory)
@@ -461,6 +473,7 @@ Examples:
   npx @awareness-sdk/local status
   npx @awareness-sdk/local stop
   npx @awareness-sdk/local reindex --project /path/to/project
+  npx @awareness-sdk/local mcp --project /path/to/project --port 37800
 `);
 }
 
@@ -489,6 +502,9 @@ async function main() {
     case 'reindex':
       await cmdReindex(flags);
       break;
+    case 'mcp':
+      await cmdMcp(flags);
+      break;
     default:
       console.error(`Unknown command: ${command}`);
       printHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awareness-sdk/local",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "description": "Local-first AI agent memory system. No account needed.",
   "license": "Apache-2.0",
   "type": "module",

package/src/core/cloud-sync.mjs

@@ -375,6 +375,10 @@ export class CloudSync {
       console.error(`${LOG_PREFIX} syncToCloud failed:`, err.message);
     }
 
+    if (synced > 0) {
+      this._recordSyncEvent('memories', { count: synced, direction: 'push' });
+    }
+
     return { synced, errors };
   }
 
@@ -426,6 +430,7 @@ export class CloudSync {
 
       if (pulled > 0) {
         console.log(`${LOG_PREFIX} Pulled ${pulled} memories from cloud`);
+        this._recordSyncEvent('memories', { count: pulled, direction: 'pull' });
       }
     } catch (err) {
       console.error(`${LOG_PREFIX} pullFromCloud failed:`, err.message);
@@ -496,6 +501,7 @@ export class CloudSync {
 
       if (synced > 0) {
         console.log(`${LOG_PREFIX} Pushed ${synced} knowledge cards to cloud` + (errors ? ` (${errors} errors)` : ''));
+        this._recordSyncEvent('insights', { count: synced, direction: 'push' });
       }
     } catch (err) {
       console.error(`${LOG_PREFIX} syncInsightsToCloud failed:`, err.message);
@@ -563,6 +569,7 @@ export class CloudSync {
 
       if (synced > 0) {
         console.log(`${LOG_PREFIX} Pushed ${synced} tasks to cloud` + (errors ? ` (${errors} errors)` : ''));
+        this._recordSyncEvent('tasks', { count: synced, direction: 'push' });
       }
     } catch (err) {
       console.error(`${LOG_PREFIX} syncTasksToCloud failed:`, err.message);
@@ -1171,6 +1178,51 @@ export class CloudSync {
     }
   }
 
+  // =========================================================================
+  // Public — sync history
+  // =========================================================================
+
+  /**
+   * Record a sync event to the sync_state table for history tracking.
+   * @param {string} type — "memories" | "insights" | "tasks"
+   * @param {object} details — { count, direction: "push"|"pull" }
+   */
+  _recordSyncEvent(type, details) {
+    try {
+      const timestamp = new Date().toISOString();
+      const key = `sync_log:${timestamp}`;
+      const value = JSON.stringify({ type, details, timestamp });
+      this._setSyncState(key, value);
+    } catch {
+      // Non-critical — don't crash on history logging failure
+    }
+  }
+
+  /**
+   * Get recent sync history events.
+   * @param {number} [limit=20] — Maximum number of events to return
+   * @returns {Array<{ type: string, details: object, timestamp: string }>}
+   */
+  getSyncHistory(limit = 20) {
+    try {
+      const rows = this.indexer.db
+        .prepare(
+          `SELECT value FROM sync_state WHERE key LIKE 'sync_log:%' ORDER BY key DESC LIMIT ?`
+        )
+        .all(limit);
+
+      return rows.map((row) => {
+        try {
+          return JSON.parse(row.value);
+        } catch {
+          return null;
+        }
+      }).filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
   // =========================================================================
   // Internal — utilities
   // =========================================================================

package/src/daemon.mjs

@@ -1072,6 +1072,8 @@ export class AwarenessLocalDaemon {
     const config = this._loadConfig();
     const cloud = config.cloud || {};
 
+    const history = this.cloudSync ? this.cloudSync.getSyncHistory() : [];
+
     return jsonResponse(res, {
       cloud_enabled: !!cloud.enabled,
       api_base: cloud.api_base || null,
@@ -1079,6 +1081,7 @@ export class AwarenessLocalDaemon {
       auto_sync: cloud.auto_sync ?? true,
       last_push_at: cloud.last_push_at || null,
       last_pull_at: cloud.last_pull_at || null,
+      history,
     });
   }
 

package/src/mcp-stdio.mjs

@@ -0,0 +1,398 @@
+/**
+ * mcp-stdio.mjs — Lightweight stdio MCP proxy for Awareness Local.
+ *
+ * Registers the same 5 tools as the HTTP daemon (awareness_init,
+ * awareness_recall, awareness_record, awareness_lookup,
+ * awareness_get_agent_prompt) but proxies every call to the local daemon
+ * via HTTP JSON-RPC at http://localhost:{port}/mcp.
+ *
+ * If the daemon is not running it is auto-started before the first call.
+ *
+ * stdout is reserved for the stdio MCP protocol — all logging goes to stderr.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import http from 'node:http';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Logging — always to stderr so stdout stays clean for stdio protocol
+// ---------------------------------------------------------------------------
+
+function log(...args) {
+  process.stderr.write(`[awareness-stdio] ${args.join(' ')}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Simple HTTP POST that returns parsed JSON.
+ * Uses only node:http to avoid external dependencies.
+ */
+function httpPost(url, body) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const data = JSON.stringify(body);
+    const req = http.request(
+      {
+        hostname: u.hostname,
+        port: u.port,
+        path: u.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(data),
+        },
+      },
+      (res) => {
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(Buffer.concat(chunks).toString()));
+          } catch (e) {
+            reject(new Error(`Failed to parse daemon response: ${e.message}`));
+          }
+        });
+      },
+    );
+    req.on('error', reject);
+    req.write(data);
+    req.end();
+  });
+}
+
+/**
+ * Quick health check — resolves true if daemon responds, false otherwise.
+ */
+function checkHealth(port) {
+  return new Promise((resolve) => {
+    const req = http.get(`http://127.0.0.1:${port}/healthz`, (res) => {
+      // Any response means daemon is up
+      res.resume();
+      resolve(true);
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(2000, () => {
+      req.destroy();
+      resolve(false);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Daemon lifecycle
+// ---------------------------------------------------------------------------
+
+/**
+ * Ensure the daemon is running. If not, spawn it and poll /healthz for up
+ * to 15 seconds.
+ */
+async function ensureDaemon(port) {
+  if (await checkHealth(port)) return;
+
+  log('Daemon not reachable — starting...');
+  const binPath = join(__dirname, '..', 'bin', 'awareness-local.mjs');
+  const child = spawn(process.execPath, [binPath, 'start'], {
+    stdio: 'ignore',
+    detached: true,
+    env: { ...process.env, PORT: String(port) },
+  });
+  child.unref();
+
+  // Poll healthz for up to 15 seconds
+  const deadline = Date.now() + 15_000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 500));
+    if (await checkHealth(port)) {
+      log('Daemon is ready.');
+      return;
+    }
+  }
+  throw new Error(
+    `Daemon did not become healthy within 15s (port ${port}). ` +
+    `Try running "npx awareness-local start" manually.`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC proxy
+// ---------------------------------------------------------------------------
+
+let _daemonChecked = false;
+
+/**
+ * Proxy a tool call to the daemon via JSON-RPC over HTTP.
+ *
+ * @param {number} port
+ * @param {string} toolName  — MCP tool name (e.g. "awareness_init")
+ * @param {object} args      — tool arguments
+ * @returns {object} parsed result from daemon
+ */
+async function proxyCall(port, toolName, args) {
+  // Lazy daemon startup — only check once per process
+  if (!_daemonChecked) {
+    await ensureDaemon(port);
+    _daemonChecked = true;
+  }
+
+  const rpcBody = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: { name: toolName, arguments: args },
+  };
+
+  let response;
+  try {
+    response = await httpPost(`http://127.0.0.1:${port}/mcp`, rpcBody);
+  } catch (err) {
+    // Daemon may have died — try to restart once
+    log(`Proxy error, retrying after daemon restart: ${err.message}`);
+    _daemonChecked = false;
+    await ensureDaemon(port);
+    _daemonChecked = true;
+    response = await httpPost(`http://127.0.0.1:${port}/mcp`, rpcBody);
+  }
+
+  // JSON-RPC error
+  if (response.error) {
+    throw new Error(
+      `Daemon RPC error ${response.error.code}: ${response.error.message}`,
+    );
+  }
+
+  // The daemon wraps results as:
+  //   result.content[0].text = JSON.stringify(payload)
+  const result = response.result;
+  if (result?.content?.[0]?.text) {
+    try {
+      return JSON.parse(result.content[0].text);
+    } catch {
+      // If it's not parseable JSON, return as-is
+      return result;
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a proxy result in the standard MCP content envelope.
+ */
+function mcpResult(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+}
+
+function mcpError(message) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+    isError: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Register tools — schemas match mcp-server.mjs exactly
+// ---------------------------------------------------------------------------
+
+function registerTools(server, port) {
+  // ======================== awareness_init ==================================
+
+  server.tool(
+    'awareness_init',
+    {
+      memory_id: z.string().optional().describe(
+        'Memory identifier (ignored in local mode, uses project dir)',
+      ),
+      source: z.string().optional().describe('Client source identifier'),
+      days: z.number().optional().default(7).describe(
+        'Days of history to load',
+      ),
+      max_cards: z.number().optional().default(5),
+      max_tasks: z.number().optional().default(5),
+    },
+    async (params) => {
+      try {
+        return mcpResult(await proxyCall(port, 'awareness_init', params));
+      } catch (err) {
+        return mcpError(`awareness_init failed: ${err.message}`);
+      }
+    },
+  );
+
+  // ======================== awareness_recall ================================
+
+  server.tool(
+    'awareness_recall',
+    {
+      semantic_query: z.string().optional().default('').describe(
+        'Natural language search query (required for search)',
+      ),
+      keyword_query: z.string().optional().default('').describe(
+        'Exact keyword match for BM25 full-text search',
+      ),
+      scope: z.enum(['all', 'timeline', 'knowledge', 'insights'])
+        .optional().default('all')
+        .describe('Search scope'),
+      recall_mode: z.enum(['precise', 'session', 'structured', 'hybrid', 'auto'])
+        .optional().default('hybrid')
+        .describe('Search mode (hybrid recommended)'),
+      limit: z.number().min(1).max(30).optional().default(10)
+        .describe('Max results'),
+      detail: z.enum(['summary', 'full']).optional().default('summary')
+        .describe(
+          'summary = lightweight index (~50-100 tokens each); ' +
+          'full = complete content for specified ids',
+        ),
+      ids: z.array(z.string()).optional().describe(
+        'Item IDs to expand when detail=full (from a prior detail=summary call)',
+      ),
+      agent_role: z.string().optional().default('').describe('Agent role filter'),
+    },
+    async (params) => {
+      try {
+        return mcpResult(await proxyCall(port, 'awareness_recall', params));
+      } catch (err) {
+        return mcpError(`awareness_recall failed: ${err.message}`);
+      }
+    },
+  );
+
+  // ======================== awareness_record ================================
+
+  server.tool(
+    'awareness_record',
+    {
+      action: z.enum([
+        'remember', 'remember_batch', 'update_task', 'submit_insights',
+      ]).describe('Record action type'),
+      content: z.string().optional().describe('Memory content (markdown)'),
+      title: z.string().optional().describe('Memory title'),
+      items: z.array(z.object({
+        content: z.string(),
+        title: z.string().optional(),
+        event_type: z.string().optional(),
+        tags: z.array(z.string()).optional(),
+        insights: z.any().optional(),
+      })).optional().describe('Batch items for remember_batch'),
+      insights: z.object({
+        knowledge_cards: z.array(z.any()).optional(),
+        action_items: z.array(z.any()).optional(),
+        risks: z.array(z.any()).optional(),
+      }).optional().describe('Pre-extracted knowledge cards, tasks, risks'),
+      session_id: z.string().optional(),
+      agent_role: z.string().optional(),
+      event_type: z.string().optional(),
+      tags: z.array(z.string()).optional(),
+      // Task update fields
+      task_id: z.string().optional(),
+      status: z.string().optional(),
+    },
+    async (params) => {
+      try {
+        return mcpResult(await proxyCall(port, 'awareness_record', params));
+      } catch (err) {
+        return mcpError(`awareness_record failed: ${err.message}`);
+      }
+    },
+  );
+
+  // ======================== awareness_lookup ================================
+
+  server.tool(
+    'awareness_lookup',
+    {
+      type: z.enum([
+        'context', 'tasks', 'knowledge', 'risks',
+        'session_history', 'timeline',
+      ]).describe(
+        'Data type to look up. ' +
+        'context = full dump, tasks = open tasks, knowledge = cards, ' +
+        'risks = risk items, session_history = past sessions, timeline = events',
+      ),
+      limit: z.number().optional().default(10).describe('Max items'),
+      status: z.string().optional().describe('Status filter'),
+      category: z.string().optional().describe('Category filter (knowledge cards)'),
+      priority: z.string().optional().describe('Priority filter (tasks/risks)'),
+      session_id: z.string().optional().describe('Session ID (for session_history)'),
+      agent_role: z.string().optional().describe('Agent role filter'),
+      query: z.string().optional().describe('Keyword filter'),
+    },
+    async (params) => {
+      try {
+        return mcpResult(await proxyCall(port, 'awareness_lookup', params));
+      } catch (err) {
+        return mcpError(`awareness_lookup failed: ${err.message}`);
+      }
+    },
+  );
+
+  // ======================== awareness_get_agent_prompt ======================
+
+  server.tool(
+    'awareness_get_agent_prompt',
+    {
+      role: z.string().optional().describe('Agent role to get prompt for'),
+    },
+    async (params) => {
+      try {
+        return mcpResult(await proxyCall(port, 'awareness_get_agent_prompt', params));
+      } catch (err) {
+        return mcpError(`awareness_get_agent_prompt failed: ${err.message}`);
+      }
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Start the stdio MCP proxy server.
+ *
+ * @param {object} opts
+ * @param {number} [opts.port=37800] — daemon HTTP port to proxy to
+ * @param {string} [opts.projectDir] — project directory (unused in proxy,
+ *   but accepted for API symmetry with direct-mode startup)
+ */
+export async function startStdioMcp({ port = 37800, projectDir } = {}) {
+  log(`Starting stdio MCP proxy (daemon port=${port})`);
+
+  const server = new McpServer({
+    name: 'awareness-local-stdio',
+    version: '1.0.0',
+  });
+
+  registerTools(server, port);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  log('stdio MCP proxy connected and ready.');
+  return server;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry — run directly with `node src/mcp-stdio.mjs`
+// ---------------------------------------------------------------------------
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const port = parseInt(process.env.AWARENESS_PORT || process.env.PORT || '37800', 10);
+  startStdioMcp({ port }).catch((err) => {
+    process.stderr.write(`[awareness-stdio] Fatal: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/src/web/index.html

@@ -215,6 +215,17 @@ body {
 .sync-history { margin-top: 20px; }
 .sync-history h4 { font-size: 0.9rem; font-weight: 600; margin-bottom: 12px; color: var(--text-secondary); }
 .sync-history-empty { font-size: 0.85rem; color: var(--text-muted); padding: 16px; text-align: center; }
+.sync-history-list { max-height: 300px; overflow-y: auto; }
+.sync-history-item {
+  display: flex; align-items: center; gap: 10px;
+  padding: 8px 12px; border-bottom: 1px solid var(--border);
+  font-size: 0.85rem;
+}
+.sync-history-item:last-child { border-bottom: none; }
+.sync-history-icon { font-size: 1rem; flex-shrink: 0; }
+.sync-history-type { font-weight: 500; min-width: 70px; }
+.sync-history-count { color: var(--text-secondary); }
+.sync-history-time { margin-left: auto; color: var(--text-muted); font-size: 0.8rem; white-space: nowrap; }
 
 /* ---- Settings ---- */
 .settings-section { margin-bottom: 28px; }
@@ -754,6 +765,31 @@ async function loadSync() {
     descEl.textContent = 'Memories are stored locally only. Connect to cloud for backup and cross-device sync.';
     btnEl.textContent = 'Connect to Cloud';
   }
+
+  // Render sync history
+  var historyEl = document.getElementById('sync-history');
+  if (data.history && data.history.length > 0) {
+    var html = '<h4>Sync History</h4><div class="sync-history-list">';
+    for (var i = 0; i < data.history.length; i++) {
+      var item = data.history[i];
+      var dir = (item.details && item.details.direction) || 'push';
+      var icon = dir === 'pull' ? '\u2B07\uFE0F' : '\u2B06\uFE0F';
+      var type = item.type || 'memories';
+      var count = (item.details && item.details.count) || 0;
+      var time = item.timestamp ? formatDate(item.timestamp) : '';
+      html += '<div class="sync-history-item">'
+        + '<span class="sync-history-icon">' + icon + '</span>'
+        + '<span class="sync-history-type">' + type + '</span>'
+        + '<span class="sync-history-count">' + count + ' ' + dir + '</span>'
+        + '<span class="sync-history-time">' + time + '</span>'
+        + '</div>';
+    }
+    html += '</div>';
+    historyEl.innerHTML = html;
+  } else {
+    historyEl.innerHTML = '<h4>Sync History</h4>'
+      + '<div class="sync-history-empty">No sync history yet. Connect to cloud to enable sync.</div>';
+  }
 }
 
 var _authApiKey = null;