total-agent-memory 1.1.0 → 1.3.0

package/README.md

@@ -4,13 +4,20 @@
 > Local-first. Hits **#5 on LoCoMo** and **96.2% R@5 on LongMemEval**.
 
 ```bash
-npx -y total-agent-memory
+npx -y total-agent-memory connect claude-code
+# → server installed in ~/.tam, IDE wired, dashboard live at
+#   http://127.0.0.1:37737
 ```
 
-That's it. One command bootstraps a Python virtual env in `~/.tam/` (legacy
-`~/.claude-memory/` is migrated automatically with a symlink kept for
-backward-compat), installs the MCP server, and prints next-step instructions
-for wiring your IDE.
+One command bootstraps a Python virtual env in `~/.tam/`, installs the
+MCP server **and** registers two background services with your OS:
+
+- **Dashboard** — web UI on `http://127.0.0.1:37737` (LaunchAgent on macOS,
+  systemd-user unit on Linux, Scheduled Task on Windows). Survives reboot.
+- **Reflection** — file-watch drain of the reflection queues. Fires
+  whenever the server touches `~/.tam/.reflect-pending` (debounce 10s).
+
+Pass `--no-services` to skip the auto-service install.
 
 ## Quick start
 
@@ -32,22 +39,24 @@ Alias: `tam` (same binary).
 
 | Command | What it does |
 |---|---|
-| `install`         | Create venv, install Python server. Idempotent. |
+| `install`         | Create venv, install Python server, register dashboard + reflection services. Idempotent. |
 | `start`           | Run the MCP server (stdin/stdout). |
 | `connect <ide>`   | Wire an IDE config. `claude-code` `codex` `cursor` `cline` `continue` `windsurf` `gemini-cli` `opencode` `aider` |
+| `dashboard <sub>` | Manage background services: `install`, `uninstall`, `start`, `stop`, `restart`, `status`, `logs`, `open`. |
 | `demo`            | Health-check end-to-end. |
-| `status`          | Print install paths, DB size. |
+| `status`          | Print install paths, DB size, **service status, dashboard HTTP probe**. |
 | `doctor`          | Diagnose Python/uv/git on PATH. |
 | `upgrade`         | Pull the latest server version. |
-| `uninstall`       | Remove `~/.tam` (needs `--yes`). Also removes `~/.claude-memory` if it's a symlink to `~/.tam`. |
+| `uninstall`       | Remove `~/.tam` and unregister all services (needs `--yes`). |
 
 ## Options
 
 | Flag | Meaning |
 |---|---|
-| `--server-version 11.2.2` | Pin a specific server release. |
+| `--server-version 12.3.0` | Pin a specific server release. |
 | `--source pypi\|git`       | Force install source. Default: PyPI with GitHub fallback. |
 | `--memory-dir /path`      | Override install dir (default `~/.tam`). |
+| `--no-services`           | Skip dashboard / reflection auto-install. |
 | `--yes`                   | Skip prompts (needed for `uninstall`). |
 | `--no-color`              | Disable ANSI. |
 | `--verbose`               | Print every shell command. |
@@ -63,11 +72,32 @@ Alias: `tam` (same binary).
 ```
 ~/.tam/
 ├── .venv/                   # isolated Python env
-│   └── bin/total-agent-memory   # MCP server entry-point (legacy claude-total-memory also installed)
-└── memory.db                # SQLite — your memory lives here
+│   └── bin/total-agent-memory   # MCP server entry-point
+├── logs/
+│   ├── dashboard.log
+│   └── reflection.log
+├── memory.db                # SQLite — your memory lives here
+└── .reflect-pending         # touched on every save → triggers reflection
 ```
 
-Nothing global is touched. Uninstall with `tam uninstall --yes`.
+Background services registered with your OS:
+
+| OS      | Location                                                                 |
+|---------|--------------------------------------------------------------------------|
+| macOS   | `~/Library/LaunchAgents/com.total-agent-memory.{dashboard,reflection}.plist` |
+| Linux   | `~/.config/systemd/user/tam-{dashboard,reflection}.{service,path}`       |
+| Windows | Task Scheduler — `TotalAgentMemory-dashboard` (reflection: manual)       |
+
+Nothing system-wide. Uninstall with `tam uninstall --yes` (removes services first).
+
+### Verify
+
+```bash
+tam dashboard status
+# ● dashboard    running
+# ◉ reflection   watching
+# ✓ HTTP http://127.0.0.1:37737 → 200
+```
 
 ## Links
 

package/bin/cli.js

@@ -16,16 +16,19 @@ ${bold('Usage:')}  total-agent-memory <command> [options]
         ${dim('alias:')} tam <command> [options]
 
 ${bold('Commands:')}
-  install            Install Python server into ~/.tam (idempotent)
+  install            Install Python server + autostart dashboard/reflection
   start              Start the MCP server (default if no command)
   connect <ide>      Wire memory into an IDE config
                      ${dim('claude-code | codex | cursor | cline | continue')}
                      ${dim('aider | windsurf | gemini-cli | opencode')}
+  dashboard <sub>    Manage background services
+                     ${dim('install | uninstall | start | stop | restart')}
+                     ${dim('status  | logs       | open')}
   demo               Seed demo session + run a recall to prove it works
-  status             Health check + tool count + DB stats
+  status             Health check + tool count + DB stats + service status
   doctor             Diagnose environment (python, uv, ports, configs)
   upgrade            Upgrade to the latest server version
-  uninstall          Remove ~/.tam and IDE wirings
+  uninstall          Remove ~/.tam, services, and IDE wirings
   version            Print version
   help               Show this message
 
@@ -34,20 +37,25 @@ ${bold('Options:')}
   --server-version <v>  Pin server version (default: latest)
   --source <pypi|git>   Where to install from (default: auto)
   --memory-dir <path>   Override install dir (default: ~/.tam)
+  --no-services         Skip dashboard/reflection autostart during install
   --yes, -y             Skip prompts
   --no-color            Disable ANSI colors
   --verbose             Print every shell command
 
 ${bold('Examples:')}
-  ${c.dim('# Install and start, then wire Claude Code:')}
-  npx -y total-agent-memory install
+  ${c.dim('# One-shot: install everything (server + dashboard + reflection)')}
+  ${c.dim('# and wire Claude Code:')}
   npx -y total-agent-memory connect claude-code
+  ${c.dim('# → open http://127.0.0.1:37737 for the dashboard')}
 
-  ${c.dim('# All-in-one onboarding:')}
-  npx -y total-agent-memory
+  ${c.dim('# Check that all services are running:')}
+  npx total-agent-memory dashboard status
+
+  ${c.dim('# Install server only, skip auto-services:')}
+  npx -y total-agent-memory install --no-services
 
   ${c.dim('# Pin a specific server version:')}
-  npx -y total-agent-memory install --server-version 11.2.2
+  npx -y total-agent-memory install --server-version 12.3.0
 
 ${bold('Docs:')}  https://totalmemory.dev
 ${bold('Repo:')}  https://github.com/vbcherepanov/total-agent-memory

package/lib/commands.js

@@ -8,6 +8,14 @@ const { connect, SUPPORTED } = require('./ide');
 const { diagnose, printReport, printRemediation } = require('./doctor');
 const { memoryDir, venvDir, exists, home } = require('./paths');
 const { run, runOrThrow } = require('./sh');
+const {
+  installServices,
+  uninstallServices,
+  serviceStatus,
+  controlService,
+  logsPath,
+  probeDashboardHealth,
+} = require('./services');
 const { c, bold, ok, fail, warn, info, banner, step } = require('./style');
 
 async function ensureInstalled(ctx) {
@@ -97,6 +105,20 @@ async function cmdStatus(ctx) {
   } else {
     process.stdout.write(`  ${warn(`memory.db  : ${db} (will be created on first save)`)}\n`);
   }
+  // Background services + dashboard health
+  process.stdout.write(`\n${bold('Services')}\n`);
+  const rows = await serviceStatus(ctx.flags);
+  for (const row of rows) {
+    const mode = row.mode || (row.running ? 'running' : row.installed ? 'idle' : 'absent');
+    const mark = mode === 'running' ? c.green('●')
+               : mode === 'watching' ? c.cyan('◉')
+               : mode === 'idle' ? c.yellow('○')
+               : c.red('✗');
+    process.stdout.write(`  ${mark} ${row.name.padEnd(12)} ${c.dim(mode)}\n`);
+  }
+  const dashUrl = `http://127.0.0.1:${process.env.DASHBOARD_PORT || '37737'}`;
+  const healthy = await probeDashboardHealth(ctx.flags);
+  process.stdout.write(`  ${healthy ? ok(`HTTP ${dashUrl} → 200`) : warn(`HTTP ${dashUrl} → no response`)}\n`);
   return 0;
 }
 
@@ -128,12 +150,91 @@ async function cmdUninstall(ctx) {
     process.stdout.write(`${info('Re-run with --yes to confirm.')}\n`);
     return 0;
   }
+  // Remove background services first — otherwise LaunchAgents/units keep
+  // respawning against a freshly-deleted venv and litter logs with 5xx.
+  try { await uninstallServices(ctx.flags); } catch (_) {}
   fs.rmSync(dir, { recursive: true, force: true });
   process.stdout.write(`${ok('Removed.')}\n`);
   process.stdout.write(`${info('IDE configs were left intact. Edit ~/.claude.json / ~/.cursor/mcp.json / etc. manually to drop the MCP entry.')}\n`);
   return 0;
 }
 
+// ────────────────────────────────────────────────────────────────────────
+// dashboard — manage the background dashboard + reflection services
+// ────────────────────────────────────────────────────────────────────────
+
+async function cmdDashboard(ctx) {
+  const sub = (ctx.positional[0] || 'status').toLowerCase();
+  const dashUrl = `http://127.0.0.1:${process.env.DASHBOARD_PORT || '37737'}`;
+  process.stdout.write(banner());
+
+  if (sub === 'install') {
+    await ensureInstalled(ctx);
+    const okFlag = await installServices(ctx.flags);
+    if (okFlag) process.stdout.write(`\n${ok(`Open ${c.cyan(dashUrl)} to view the dashboard.`)}\n`);
+    return okFlag ? 0 : 1;
+  }
+  if (sub === 'uninstall' || sub === 'remove') {
+    await uninstallServices(ctx.flags);
+    return 0;
+  }
+  if (sub === 'start' || sub === 'stop' || sub === 'restart') {
+    const target = ctx.positional[1] || 'dashboard';
+    process.stdout.write(`${info(`${sub} ${target}…`)}\n`);
+    try {
+      await controlService(sub, target, ctx.flags);
+      process.stdout.write(`${ok('done')}\n`);
+      return 0;
+    } catch (e) {
+      process.stderr.write(`${fail(e.message)}\n`);
+      return 1;
+    }
+  }
+  if (sub === 'logs') {
+    const target = ctx.positional[1] || 'dashboard';
+    const stream = ctx.flags.err ? 'stderr' : 'stdout';
+    const lp = logsPath(target, ctx.flags, stream);
+    if (!lp || !exists(lp)) {
+      process.stdout.write(`${warn(`no log file yet: ${lp || target}`)}\n`);
+      return 0;
+    }
+    const data = fs.readFileSync(lp, 'utf8');
+    const tail = data.split('\n').slice(-50).join('\n');
+    process.stdout.write(`${c.dim(`--- ${lp} (last 50 lines) ---`)}\n${tail}\n`);
+    return 0;
+  }
+  if (sub === 'open') {
+    const opener = process.platform === 'darwin' ? 'open'
+                 : process.platform === 'win32' ? 'start'
+                 : 'xdg-open';
+    await run(opener, [dashUrl], { silent: true });
+    process.stdout.write(`${ok(`Opened ${c.cyan(dashUrl)}`)}\n`);
+    return 0;
+  }
+  if (sub === 'status' || sub === '') {
+    const rows = await serviceStatus(ctx.flags);
+    process.stdout.write(`${bold('Services')}\n`);
+    for (const row of rows) {
+      const mode = row.mode || (row.running ? 'running' : row.installed ? 'idle' : 'absent');
+      const mark = mode === 'running' ? c.green('●')
+                 : mode === 'watching' ? c.cyan('◉')
+                 : mode === 'scheduled' ? c.magenta('◷')
+                 : mode === 'idle' ? c.yellow('○')
+                 : c.red('✗');
+      process.stdout.write(`  ${mark} ${row.name.padEnd(12)} ${c.dim(mode)}${row.note ? c.dim(' — ' + row.note) : ''}\n`);
+    }
+    const healthy = await probeDashboardHealth(ctx.flags);
+    process.stdout.write(`\n  ${healthy ? ok(`HTTP ${dashUrl} → 200`) : warn(`HTTP ${dashUrl} → no response`)}\n`);
+    if (!healthy && !rows.find((r) => r.name === 'dashboard' && r.installed)) {
+      process.stdout.write(`\n  ${info(`Run: ${c.cyan('npx total-agent-memory dashboard install')}`)}\n`);
+    }
+    return 0;
+  }
+  process.stderr.write(`${fail(`unknown dashboard subcommand: ${sub}`)}\n`);
+  process.stderr.write(`Try: install | uninstall | start | stop | restart | status | logs | open\n`);
+  return 2;
+}
+
 // First-run onboarding: install + suggest a connect step.
 async function cmdOnboard(ctx) {
   process.stdout.write(banner());
@@ -165,4 +266,5 @@ module.exports = {
   upgrade: cmdUpgrade,
   uninstall: cmdUninstall,
   onboard: cmdOnboard,
+  dashboard: cmdDashboard,
 };

package/lib/doctor.js

@@ -16,9 +16,10 @@ async function diagnose() {
     pip: null,
     pipx: null,
     git: null,
+    ollama: null,
   };
 
-  for (const bin of ['python3', 'python', 'uv', 'pipx', 'git']) {
+  for (const bin of ['python3', 'python', 'uv', 'pipx', 'git', 'ollama']) {
     const r = probe(bin, ['--version']);
     if (r.ok) {
       env[bin] = { path: r.path, version: r.out };
@@ -32,9 +33,42 @@ async function diagnose() {
       env.pythonPatch = +m[3];
     }
   }
+  // Probe Ollama HTTP — works whether installed via brew, the .app, or
+  // running in Docker. We hit /api/tags (cheap, always-available).
+  env.ollamaHttp = await probeOllamaHttp();
   return env;
 }
 
+async function probeOllamaHttp(timeoutMs = 1500) {
+  const host = process.env.OLLAMA_HOST || 'http://127.0.0.1:11434';
+  const url = host.endsWith('/') ? host + 'api/tags' : host + '/api/tags';
+  return await new Promise((resolve) => {
+    try {
+      const http = url.startsWith('https') ? require('https') : require('http');
+      const req = http.get(url, (res) => {
+        let body = '';
+        res.on('data', (d) => { body += d.toString(); });
+        res.on('end', () => {
+          if (res.statusCode !== 200) {
+            resolve({ ok: false, status: res.statusCode, host });
+            return;
+          }
+          let models = [];
+          try {
+            const j = JSON.parse(body);
+            models = (j.models || []).map((m) => m.name);
+          } catch (_) {}
+          resolve({ ok: true, host, models, modelCount: models.length });
+        });
+      });
+      req.on('error', () => resolve({ ok: false, host, error: 'unreachable' }));
+      req.setTimeout(timeoutMs, () => { req.destroy(); resolve({ ok: false, host, error: 'timeout' }); });
+    } catch (e) {
+      resolve({ ok: false, host, error: String(e) });
+    }
+  });
+}
+
 function pickInstaller(env) {
   // Prefer uv (fastest, most reliable). Fall back to venv+pip.
   if (env.uv) return 'uv';
@@ -61,6 +95,18 @@ function printReport(env) {
   } else {
     process.stdout.write(`  ${warn('git      : not found (needed only for --source git fallback)')}\n`);
   }
+  // Ollama — optional but unlocks LLM-powered enrichment (deep entity
+  // extraction, summarisation, contradiction detection). Without it the
+  // server still works in degraded mode: FTS5 + embeddings, no LLM stages.
+  if (env.ollamaHttp && env.ollamaHttp.ok) {
+    const models = env.ollamaHttp.modelCount;
+    process.stdout.write(`  ${ok(`ollama   : reachable at ${env.ollamaHttp.host} (${models} model${models === 1 ? '' : 's'})`)}\n`);
+  } else if (env.ollama) {
+    process.stdout.write(`  ${warn(`ollama   : binary present but daemon not reachable at ${env.ollamaHttp ? env.ollamaHttp.host : 'http://127.0.0.1:11434'}`)}\n`);
+    process.stdout.write(`             ${c.dim('start with: ollama serve')}\n`);
+  } else {
+    process.stdout.write(`  ${warn(`ollama   : not found (optional — needed for LLM enrichment)`)}\n`);
+  }
   return env;
 }
 
@@ -80,6 +126,21 @@ function printRemediation(env) {
     process.stdout.write(`\n${bold('Optional — install uv for 10× faster installs:')}\n`);
     process.stdout.write(`  ${c.cyan('curl -LsSf https://astral.sh/uv/install.sh | sh')}\n`);
   }
+  // Suggest Ollama install only if it's missing entirely. If the binary
+  // is present but the daemon is down, the printReport message already
+  // tells the user to `ollama serve`.
+  if (!env.ollama && (!env.ollamaHttp || !env.ollamaHttp.ok)) {
+    process.stdout.write(`\n${bold('Optional — install Ollama for local LLM enrichment:')}\n`);
+    if (process.platform === 'darwin') {
+      process.stdout.write(`  ${c.cyan('brew install ollama && brew services start ollama')}\n`);
+    } else if (process.platform === 'linux') {
+      process.stdout.write(`  ${c.cyan('curl -fsSL https://ollama.com/install.sh | sh')}\n`);
+    } else if (process.platform === 'win32') {
+      process.stdout.write(`  ${c.cyan('winget install Ollama.Ollama')}\n`);
+    }
+    process.stdout.write(`  ${c.cyan('ollama pull qwen2.5-coder:7b && ollama pull nomic-embed-text')}    ${c.dim('# default models')}\n`);
+    process.stdout.write(`  ${c.dim('(server still works without Ollama — runs in FTS+embedding mode)')}\n`);
+  }
 }
 
 module.exports = { diagnose, pickInstaller, printReport, printRemediation };

package/lib/index.js

@@ -8,6 +8,13 @@ const { diagnose } = require('./doctor');
 const { mcpEntry, SUPPORTED } = require('./ide');
 const { memoryDir, venvDir, venvBin } = require('./paths');
 const { install, pinned } = require('./install');
+const {
+  installServices,
+  uninstallServices,
+  serviceStatus,
+  controlService,
+  probeDashboardHealth,
+} = require('./services');
 
 module.exports = {
   ...cmds,
@@ -19,4 +26,9 @@ module.exports = {
   venvBin,
   installServer: install,
   pinnedVersion: pinned,
+  installServices,
+  uninstallServices,
+  serviceStatus,
+  controlService,
+  probeDashboardHealth,
 };

package/lib/install.js

@@ -5,12 +5,13 @@ const path = require('path');
 const { runOrThrow, run, which } = require('./sh');
 const { memoryDir, venvDir, venvBin, ensureDir, exists } = require('./paths');
 const { diagnose, pickInstaller, printReport, printRemediation } = require('./doctor');
+const { installServices } = require('./services');
 const { c, bold, ok, fail, warn, info, step } = require('./style');
 
 const PYPI_PACKAGE = 'total-agent-memory';
 // Pinned to the latest stable release at the time of the wrapper release.
 // Override via `--server-version` or env TAM_SERVER_VERSION.
-const DEFAULT_SERVER_VERSION = '12.2.0';
+const DEFAULT_SERVER_VERSION = '12.4.0';
 const GIT_URL = 'https://github.com/vbcherepanov/total-agent-memory.git';
 
 function pinned(flags) {
@@ -110,15 +111,16 @@ async function install(ctx) {
     return 1;
   }
 
+  const totalSteps = flags['no-services'] ? 3 : 4;
   process.stdout.write(`\n${bold('Installing server…')}\n`);
-  process.stdout.write(`  ${step(1, 3, `venv  → ${c.dim(venvDir(flags))}`)}\n`);
+  process.stdout.write(`  ${step(1, totalSteps, `venv  → ${c.dim(venvDir(flags))}`)}\n`);
   await createVenv(flags, env);
   process.stdout.write(`  ${ok('venv ready')}\n`);
 
-  process.stdout.write(`  ${step(2, 3, 'resolving source (PyPI → GitHub fallback)…')}\n`);
+  process.stdout.write(`  ${step(2, totalSteps, 'resolving source (PyPI → GitHub fallback)…')}\n`);
   const source = await pickSource(flags);
 
-  process.stdout.write(`  ${step(3, 3, 'pip install…')}\n`);
+  process.stdout.write(`  ${step(3, totalSteps, 'pip install…')}\n`);
   await pipInstall(flags, env, source);
 
   // Verify entry-point present.
@@ -127,8 +129,27 @@ async function install(ctx) {
     process.stderr.write(`\n${fail(`entry-point ${bin} not found after install`)}\n`);
     return 1;
   }
+
+  // Step 4 — register background services (dashboard + reflection) unless
+  // explicitly opted out. Failure here is non-fatal: the server itself is
+  // installed, the user can re-run `npx total-agent-memory dashboard install`.
+  if (!flags['no-services']) {
+    process.stdout.write(`  ${step(4, totalSteps, 'background services (dashboard + reflection)…')}\n`);
+    try {
+      await installServices(flags, { dryRun: process.env.TAM_INSTALL_DRY === '1' });
+    } catch (e) {
+      process.stdout.write(`  ${warn(`services install failed: ${e.message}`)}\n`);
+      process.stdout.write(`  ${info(`Retry later with: ${c.cyan('npx total-agent-memory dashboard install')}`)}\n`);
+    }
+  } else {
+    process.stdout.write(`  ${info('--no-services set — skipping dashboard/reflection autostart')}\n`);
+  }
+
   process.stdout.write(`\n${ok(c.bold('Installation complete.'))}\n`);
-  process.stdout.write(`${info(`Binary: ${c.dim(bin)}`)}\n`);
+  process.stdout.write(`${info(`Binary:    ${c.dim(bin)}`)}\n`);
+  if (!flags['no-services']) {
+    process.stdout.write(`${info(`Dashboard: ${c.cyan('http://127.0.0.1:37737')}`)}\n`);
+  }
   return 0;
 }
 

package/lib/services.js

@@ -0,0 +1,621 @@
+'use strict';
+
+// Manage background services (dashboard + reflection) per OS.
+//
+// macOS  → ~/Library/LaunchAgents/com.total-agent-memory.<name>.plist
+// Linux  → ~/.config/systemd/user/tam-<name>.service (+ .path for reflection)
+// Windows → schtasks /Create (best-effort) or printed instructions
+//
+// All services point at the existing entry points inside the installed
+// venv (no new server code needed):
+//   dashboard  → python -m src.dashboard
+//   reflection → python -m src.tools.run_reflection
+//
+// Why not bundle a supervisor? Each OS has a battle-tested supervisor
+// already (launchd / systemd). Re-implementing one inside the venv would
+// be a downgrade on restart-on-crash, log rotation, and boot-order.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { run, runOrThrow, which, probe } = require('./sh');
+const { memoryDir, venvBin, ensureDir, exists, home } = require('./paths');
+const { c, ok, fail, warn, info } = require('./style');
+
+// ────────────────────────────────────────────────────────────────────────
+// Service definitions (OS-independent shape)
+// ────────────────────────────────────────────────────────────────────────
+
+function serviceDefs(flags) {
+  const md = memoryDir(flags);
+  const logDir = path.join(md, 'logs');
+  return [
+    {
+      name: 'dashboard',
+      title: 'Web dashboard',
+      module: 'src.dashboard',
+      env: {
+        DASHBOARD_PORT: process.env.DASHBOARD_PORT || '37737',
+        DASHBOARD_BIND: process.env.DASHBOARD_BIND || '127.0.0.1',
+        TAM_MEMORY_DIR: md,
+      },
+      port: parseInt(process.env.DASHBOARD_PORT || '37737', 10),
+      healthcheck: '/api/stats',
+      keepAlive: true, // long-running HTTP server
+      logFile: path.join(logDir, 'dashboard.log'),
+      errFile: path.join(logDir, 'dashboard.err'),
+    },
+    {
+      name: 'reflection',
+      title: 'Reflection drain (file-watch)',
+      module: 'src.tools.run_reflection',
+      env: {
+        REFLECT_DEBOUNCE_SEC: process.env.REFLECT_DEBOUNCE_SEC || '10',
+        TAM_MEMORY_DIR: md,
+      },
+      // File-watch trigger: server touches this on every save.
+      watchPath: path.join(md, '.reflect-pending'),
+      keepAlive: false, // re-spawned by file-watch, exits when drain done
+      throttleSec: 5,
+      // Safety net periodic run every hour even if no trigger fires.
+      startIntervalSec: 3600,
+      logFile: path.join(logDir, 'reflection.log'),
+      errFile: path.join(logDir, 'reflection.err'),
+    },
+    {
+      // Cron-style: backfill orphan graph edges 4× per day. Keeps the
+      // knowledge graph fresh as new saves accumulate.
+      name: 'orphan-backfill',
+      title: 'Orphan-edge backfill (4×/day)',
+      module: 'src.tools.backfill_orphan_edges',
+      moduleArgs: ['--min-mentions=1', '--limit=500', '--trigger-now'],
+      env: { TAM_MEMORY_DIR: md },
+      keepAlive: false,
+      // launchd StartCalendarInterval — fires at 00, 06, 12, 18 daily.
+      calendarHours: [0, 6, 12, 18],
+      // systemd timer OnCalendar equivalent.
+      systemdOnCalendar: '00,06,12,18:00:00',
+      logFile: path.join(logDir, 'orphan-backfill.log'),
+      errFile: path.join(logDir, 'orphan-backfill.err'),
+    },
+    {
+      // Weekly check for new releases — non-critical, informational.
+      name: 'check-updates',
+      title: 'Check for new releases (weekly)',
+      module: 'src.tools.check_updates',
+      env: { TAM_MEMORY_DIR: md },
+      keepAlive: false,
+      // launchd StartCalendarInterval — Sunday 03:00.
+      calendarWeekly: { Weekday: 0, Hour: 3, Minute: 0 },
+      // systemd timer — Sun *-*-* 03:00:00.
+      systemdOnCalendar: 'Sun *-*-* 03:00:00',
+      logFile: path.join(logDir, 'check-updates.log'),
+      errFile: path.join(logDir, 'check-updates.err'),
+    },
+  ];
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// macOS — LaunchAgent
+// ────────────────────────────────────────────────────────────────────────
+
+function plistLabel(name) {
+  return `com.total-agent-memory.${name}`;
+}
+
+function plistPath(name) {
+  return path.join(home(), 'Library', 'LaunchAgents', `${plistLabel(name)}.plist`);
+}
+
+function renderPlist(svc, pyPath) {
+  const envEntries = Object.entries(svc.env)
+    .map(([k, v]) => `    <key>${escapeXml(k)}</key><string>${escapeXml(String(v))}</string>`)
+    .join('\n');
+  const cmdArgs = ['-m', svc.module, ...(svc.moduleArgs || [])];
+  const args = cmdArgs
+    .map((a) => `    <string>${escapeXml(a)}</string>`)
+    .join('\n');
+  const watchBlock = svc.watchPath
+    ? `  <key>WatchPaths</key>\n  <array>\n    <string>${escapeXml(svc.watchPath)}</string>\n  </array>\n`
+    : '';
+  const throttleBlock = svc.throttleSec
+    ? `  <key>ThrottleInterval</key><integer>${svc.throttleSec}</integer>\n`
+    : '';
+  const intervalBlock = svc.startIntervalSec
+    ? `  <key>StartInterval</key><integer>${svc.startIntervalSec}</integer>\n`
+    : '';
+  // StartCalendarInterval — for cron-style daily/weekly jobs.
+  let calendarBlock = '';
+  if (Array.isArray(svc.calendarHours) && svc.calendarHours.length) {
+    const dicts = svc.calendarHours
+      .map((h) => `    <dict><key>Hour</key><integer>${h}</integer><key>Minute</key><integer>0</integer></dict>`)
+      .join('\n');
+    calendarBlock = `  <key>StartCalendarInterval</key>\n  <array>\n${dicts}\n  </array>\n`;
+  } else if (svc.calendarWeekly) {
+    const w = svc.calendarWeekly;
+    const keys = ['Weekday', 'Hour', 'Minute']
+      .filter((k) => k in w)
+      .map((k) => `    <key>${k}</key><integer>${w[k]}</integer>`)
+      .join('\n');
+    calendarBlock = `  <key>StartCalendarInterval</key>\n  <dict>\n${keys}\n  </dict>\n`;
+  }
+  // keepAlive=true → HTTP server (always running). false → triggered by
+  // file-watch or calendar.
+  const runAtLoad = svc.keepAlive ? '<true/>' : '<false/>';
+  const keepAlive = svc.keepAlive ? '<true/>' : '<false/>';
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${plistLabel(svc.name)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(pyPath)}</string>
+${args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envEntries}
+  </dict>
+  <key>RunAtLoad</key>${runAtLoad}
+  <key>KeepAlive</key>${keepAlive}
+${watchBlock}${throttleBlock}${intervalBlock}${calendarBlock}  <key>StandardOutPath</key><string>${escapeXml(svc.logFile)}</string>
+  <key>StandardErrorPath</key><string>${escapeXml(svc.errFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+async function macInstall(svcs, pyPath, opts) {
+  ensureDir(path.dirname(plistPath('x')));
+  for (const svc of svcs) {
+    ensureDir(path.dirname(svc.logFile));
+    if (svc.watchPath) ensureDir(path.dirname(svc.watchPath));
+    const p = plistPath(svc.name);
+    fs.writeFileSync(p, renderPlist(svc, pyPath));
+    if (opts.dryRun) continue;
+    const label = plistLabel(svc.name);
+    const target = `gui/${process.getuid()}/${label}`;
+    // Bootout previous version (if any). launchd is async — give it a
+    // beat before bootstrapping the replacement, otherwise we hit
+    // "Input/output error" on rapid replace.
+    await run('launchctl', ['bootout', target], { silent: true });
+    await _sleep(150);
+    const r = await run('launchctl', ['bootstrap', `gui/${process.getuid()}`, p], { silent: true });
+    if (r.code !== 0) {
+      // Retry once after a longer pause (launchd was likely still
+      // tearing down the old job).
+      await _sleep(500);
+      const r2 = await run('launchctl', ['bootstrap', `gui/${process.getuid()}`, p], { silent: true });
+      if (r2.code !== 0) {
+        // Fall back to legacy load (older macOS / sandbox issues).
+        await run('launchctl', ['load', '-w', p], { silent: true });
+      }
+    }
+    if (svc.keepAlive) {
+      // Kickstart so the long-running service runs *now*.
+      await run('launchctl', ['kickstart', '-k', target], { silent: true });
+    }
+  }
+}
+
+function _sleep(ms) {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+async function macUninstall(svcs, opts) {
+  for (const svc of svcs) {
+    const p = plistPath(svc.name);
+    if (!opts.dryRun) {
+      await run('launchctl', ['bootout', `gui/${process.getuid()}/${plistLabel(svc.name)}`], { silent: true });
+      await run('launchctl', ['unload', '-w', p], { silent: true });
+    }
+    if (exists(p)) fs.unlinkSync(p);
+  }
+}
+
+async function macStatus(svcs) {
+  const out = [];
+  for (const svc of svcs) {
+    const r = await run('launchctl', ['print', `gui/${process.getuid()}/${plistLabel(svc.name)}`], { silent: true });
+    const installed = exists(plistPath(svc.name));
+    const loaded = r.code === 0;
+    const running = loaded && /state\s*=\s*running/i.test(r.stdout);
+    // Cron-style services with calendar/interval triggers are healthy
+    // when loaded — they just sit until their next fire. File-watch
+    // services likewise: "watching" means ready, not stopped.
+    let mode;
+    if (running) mode = 'running';
+    else if (loaded && (svc.calendarHours || svc.calendarWeekly)) mode = 'scheduled';
+    else if (loaded && svc.watchPath) mode = 'watching';
+    else if (installed) mode = 'idle';
+    else mode = 'absent';
+    out.push({ name: svc.name, installed, running, mode });
+  }
+  return out;
+}
+
+async function macControl(action, name) {
+  const target = `gui/${process.getuid()}/${plistLabel(name)}`;
+  if (action === 'start') {
+    return await run('launchctl', ['kickstart', '-k', target], { silent: true });
+  }
+  if (action === 'stop') {
+    return await run('launchctl', ['kill', 'SIGTERM', target], { silent: true });
+  }
+  if (action === 'restart') {
+    return await run('launchctl', ['kickstart', '-k', target], { silent: true });
+  }
+  throw new Error(`unknown action: ${action}`);
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Linux — systemd --user
+// ────────────────────────────────────────────────────────────────────────
+
+function systemdDir() {
+  return path.join(home(), '.config', 'systemd', 'user');
+}
+
+function systemdUnitName(name, type = 'service') {
+  return `tam-${name}.${type}`;
+}
+
+function renderSystemdService(svc, pyPath) {
+  const envLines = Object.entries(svc.env)
+    .map(([k, v]) => `Environment=${k}=${v}`)
+    .join('\n');
+  // `Type=exec` lets systemd consider the unit started as soon as the
+  // binary is exec'd (good for short jobs).
+  const type = svc.keepAlive ? 'simple' : 'exec';
+  const restart = svc.keepAlive ? 'always' : 'no';
+  const restartSec = svc.keepAlive ? 'RestartSec=5\n' : '';
+  const moduleArgs = (svc.moduleArgs || []).join(' ');
+  const execStart = `${pyPath} -m ${svc.module}${moduleArgs ? ' ' + moduleArgs : ''}`;
+  return `[Unit]
+Description=Total Agent Memory — ${svc.title}
+After=default.target
+
+[Service]
+Type=${type}
+ExecStart=${execStart}
+Restart=${restart}
+${restartSec}${envLines}
+StandardOutput=append:${svc.logFile}
+StandardError=append:${svc.errFile}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function renderSystemdCalendarTimer(svc) {
+  if (!svc.systemdOnCalendar) return null;
+  return `[Unit]
+Description=Total Agent Memory — schedule for ${svc.title}
+
+[Timer]
+OnCalendar=${svc.systemdOnCalendar}
+Persistent=true
+Unit=${systemdUnitName(svc.name, 'service')}
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+function renderSystemdPath(svc) {
+  return `[Unit]
+Description=Total Agent Memory — watch ${path.basename(svc.watchPath)}
+
+[Path]
+PathChanged=${svc.watchPath}
+Unit=${systemdUnitName(svc.name, 'service')}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function renderSystemdTimer(svc) {
+  return `[Unit]
+Description=Total Agent Memory — periodic safety run for ${svc.title}
+
+[Timer]
+OnUnitActiveSec=${svc.startIntervalSec}s
+OnBootSec=60s
+Unit=${systemdUnitName(svc.name, 'service')}
+
+[Install]
+WantedBy=timers.target
+`;
+}
+
+function systemctlAvailable() {
+  if (!which('systemctl')) return false;
+  // `systemctl --user show-environment` returns 0 only when the user bus
+  // is reachable (i.e. lingering enabled, or interactive login session).
+  const r = probe('systemctl', ['--user', 'show-environment']);
+  return r.ok;
+}
+
+async function linuxInstall(svcs, pyPath, opts) {
+  ensureDir(systemdDir());
+  for (const svc of svcs) {
+    ensureDir(path.dirname(svc.logFile));
+    if (svc.watchPath) ensureDir(path.dirname(svc.watchPath));
+    const svcFile = path.join(systemdDir(), systemdUnitName(svc.name, 'service'));
+    fs.writeFileSync(svcFile, renderSystemdService(svc, pyPath));
+    if (svc.watchPath) {
+      const pathFile = path.join(systemdDir(), systemdUnitName(svc.name, 'path'));
+      fs.writeFileSync(pathFile, renderSystemdPath(svc));
+    }
+    if (svc.startIntervalSec && !svc.keepAlive) {
+      const timerFile = path.join(systemdDir(), systemdUnitName(svc.name, 'timer'));
+      fs.writeFileSync(timerFile, renderSystemdTimer(svc));
+    }
+    if (svc.systemdOnCalendar) {
+      const timerFile = path.join(systemdDir(), systemdUnitName(svc.name, 'timer'));
+      fs.writeFileSync(timerFile, renderSystemdCalendarTimer(svc));
+    }
+  }
+  if (opts.dryRun) return;
+  if (!systemctlAvailable()) {
+    process.stdout.write(`  ${warn('systemctl --user bus not reachable — unit files written. Enable later with:')}\n`);
+    process.stdout.write(`    ${c.cyan('systemctl --user daemon-reload')}\n`);
+    for (const svc of svcs) {
+      const unit = primaryUnitFor(svc);
+      process.stdout.write(`    ${c.cyan(`systemctl --user enable --now ${unit}`)}\n`);
+    }
+    return;
+  }
+  await run('systemctl', ['--user', 'daemon-reload'], { silent: true });
+  for (const svc of svcs) {
+    // For file-watch services we enable the `.path` unit which triggers
+    // the `.service` unit on change. For calendar/interval jobs we
+    // enable the `.timer`. For HTTP servers, enable the `.service`.
+    const unit = primaryUnitFor(svc);
+    await run('systemctl', ['--user', 'enable', '--now', unit], { silent: true });
+  }
+}
+
+function primaryUnitFor(svc) {
+  if (svc.watchPath) return systemdUnitName(svc.name, 'path');
+  if (svc.systemdOnCalendar || svc.startIntervalSec) return systemdUnitName(svc.name, 'timer');
+  return systemdUnitName(svc.name, 'service');
+}
+
+async function linuxUninstall(svcs, opts) {
+  for (const svc of svcs) {
+    const units = [
+      systemdUnitName(svc.name, 'service'),
+      svc.watchPath ? systemdUnitName(svc.name, 'path') : null,
+      (svc.startIntervalSec && !svc.keepAlive) || svc.systemdOnCalendar
+        ? systemdUnitName(svc.name, 'timer') : null,
+    ].filter(Boolean);
+    if (!opts.dryRun && systemctlAvailable()) {
+      for (const unit of units) {
+        await run('systemctl', ['--user', 'disable', '--now', unit], { silent: true });
+      }
+    }
+    for (const unit of units) {
+      const f = path.join(systemdDir(), unit);
+      if (exists(f)) fs.unlinkSync(f);
+    }
+  }
+  if (!opts.dryRun && systemctlAvailable()) {
+    await run('systemctl', ['--user', 'daemon-reload'], { silent: true });
+  }
+}
+
+async function linuxStatus(svcs) {
+  const out = [];
+  for (const svc of svcs) {
+    const unit = systemdUnitName(svc.name, 'service');
+    const pathUnit = svc.watchPath ? systemdUnitName(svc.name, 'path') : null;
+    const timerUnit = (svc.systemdOnCalendar || svc.startIntervalSec) ? systemdUnitName(svc.name, 'timer') : null;
+    const installed = exists(path.join(systemdDir(), unit));
+    let running = false, watching = false, scheduled = false;
+    if (systemctlAvailable()) {
+      const r = await run('systemctl', ['--user', 'is-active', unit], { silent: true });
+      running = r.code === 0 && r.stdout.trim() === 'active';
+      if (pathUnit) {
+        const r2 = await run('systemctl', ['--user', 'is-active', pathUnit], { silent: true });
+        watching = r2.code === 0 && r2.stdout.trim() === 'active';
+      }
+      if (timerUnit) {
+        const r3 = await run('systemctl', ['--user', 'is-active', timerUnit], { silent: true });
+        scheduled = r3.code === 0 && r3.stdout.trim() === 'active';
+      }
+    }
+    let mode;
+    if (running) mode = 'running';
+    else if (scheduled) mode = 'scheduled';
+    else if (watching) mode = 'watching';
+    else if (installed) mode = 'idle';
+    else mode = 'absent';
+    out.push({ name: svc.name, installed, running, mode });
+  }
+  return out;
+}
+
+async function linuxControl(action, name) {
+  const unit = systemdUnitName(name, 'service');
+  if (!systemctlAvailable()) {
+    throw new Error('systemctl --user bus not reachable');
+  }
+  if (action === 'start') return await run('systemctl', ['--user', 'start', unit], { silent: true });
+  if (action === 'stop') return await run('systemctl', ['--user', 'stop', unit], { silent: true });
+  if (action === 'restart') return await run('systemctl', ['--user', 'restart', unit], { silent: true });
+  throw new Error(`unknown action: ${action}`);
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Windows — schtasks (best-effort) or printed instructions
+// ────────────────────────────────────────────────────────────────────────
+
+async function winInstall(svcs, pyPath, opts) {
+  if (opts.dryRun) {
+    process.stdout.write(`  ${info('Windows service install is a dry-run only in v1.2.0. Use Task Scheduler manually.')}\n`);
+    return;
+  }
+  // Best-effort: create onLogon scheduled task for the dashboard.
+  // Reflection (file-watch) is not supported via schtasks; instruct user.
+  process.stdout.write(`  ${warn('Windows auto-service install is limited in v1.2.0:')}\n`);
+  process.stdout.write(`    ${info('Dashboard: registering schtasks onLogon trigger…')}\n`);
+  for (const svc of svcs) {
+    if (svc.name !== 'dashboard') {
+      process.stdout.write(`    ${warn(`${svc.name}: not auto-installed on Windows. Run manually when needed:`)}\n`);
+      process.stdout.write(`      ${c.cyan(`"${pyPath}" -m ${svc.module}`)}\n`);
+      continue;
+    }
+    const taskName = `TotalAgentMemory-${svc.name}`;
+    const cmd = `"${pyPath}" -m ${svc.module}`;
+    await run('schtasks', [
+      '/Create', '/F',
+      '/SC', 'ONLOGON',
+      '/TN', taskName,
+      '/TR', cmd,
+      '/RL', 'LIMITED',
+    ], { silent: true });
+    // And run it once now.
+    await run('schtasks', ['/Run', '/TN', taskName], { silent: true });
+  }
+}
+
+async function winUninstall(svcs, opts) {
+  for (const svc of svcs) {
+    if (svc.name !== 'dashboard') continue;
+    const taskName = `TotalAgentMemory-${svc.name}`;
+    if (!opts.dryRun) await run('schtasks', ['/Delete', '/F', '/TN', taskName], { silent: true });
+  }
+}
+
+async function winStatus(svcs) {
+  const out = [];
+  for (const svc of svcs) {
+    if (svc.name !== 'dashboard') {
+      out.push({ name: svc.name, installed: false, running: false, mode: 'absent', note: 'manual on Windows' });
+      continue;
+    }
+    const taskName = `TotalAgentMemory-${svc.name}`;
+    const r = await run('schtasks', ['/Query', '/TN', taskName, '/FO', 'CSV', '/NH'], { silent: true });
+    const installed = r.code === 0;
+    const running = installed && /Running/i.test(r.stdout);
+    const mode = running ? 'running' : (installed ? 'idle' : 'absent');
+    out.push({ name: svc.name, installed, running, mode });
+  }
+  return out;
+}
+
+async function winControl(action, name) {
+  const taskName = `TotalAgentMemory-${name}`;
+  if (action === 'start') return await run('schtasks', ['/Run', '/TN', taskName], { silent: true });
+  if (action === 'stop') return await run('schtasks', ['/End', '/TN', taskName], { silent: true });
+  if (action === 'restart') {
+    await run('schtasks', ['/End', '/TN', taskName], { silent: true });
+    return await run('schtasks', ['/Run', '/TN', taskName], { silent: true });
+  }
+  throw new Error(`unknown action: ${action}`);
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Public API (OS dispatch)
+// ────────────────────────────────────────────────────────────────────────
+
+function osDispatch() {
+  if (process.platform === 'darwin') return { install: macInstall, uninstall: macUninstall, status: macStatus, control: macControl, name: 'macOS' };
+  if (process.platform === 'linux') return { install: linuxInstall, uninstall: linuxUninstall, status: linuxStatus, control: linuxControl, name: 'Linux' };
+  if (process.platform === 'win32') return { install: winInstall, uninstall: winUninstall, status: winStatus, control: winControl, name: 'Windows' };
+  return null;
+}
+
+async function installServices(flags, opts = {}) {
+  const d = osDispatch();
+  if (!d) {
+    process.stdout.write(`  ${warn(`OS ${process.platform} not supported for auto-service install`)}\n`);
+    return false;
+  }
+  const py = venvBin(flags, 'python');
+  if (!exists(py)) {
+    process.stdout.write(`  ${fail(`venv python not found: ${py}`)}\n`);
+    return false;
+  }
+  const svcs = serviceDefs(flags);
+  process.stdout.write(`  ${info(`Installing ${svcs.length} background services (${d.name})…`)}\n`);
+  await d.install(svcs, py, opts);
+  // Print quick verification hint.
+  process.stdout.write(`  ${ok(`Services installed. Dashboard: ${c.cyan('http://127.0.0.1:37737')}`)}\n`);
+  return true;
+}
+
+async function uninstallServices(flags, opts = {}) {
+  const d = osDispatch();
+  if (!d) return false;
+  const svcs = serviceDefs(flags);
+  process.stdout.write(`  ${info(`Removing background services (${d.name})…`)}\n`);
+  await d.uninstall(svcs, opts);
+  process.stdout.write(`  ${ok('Services removed.')}\n`);
+  return true;
+}
+
+async function serviceStatus(flags) {
+  const d = osDispatch();
+  if (!d) return [];
+  return await d.status(serviceDefs(flags));
+}
+
+async function controlService(action, name, flags) {
+  const d = osDispatch();
+  if (!d) throw new Error(`OS ${process.platform} not supported`);
+  return await d.control(action, name);
+}
+
+function logsPath(name, flags, which = 'stdout') {
+  const svc = serviceDefs(flags).find((s) => s.name === name);
+  if (!svc) return null;
+  return which === 'stderr' ? svc.errFile : svc.logFile;
+}
+
+// Probe dashboard HTTP endpoint. Returns true if /api/stats answers 200.
+async function probeDashboardHealth(flags, timeoutMs = 2000) {
+  const port = process.env.DASHBOARD_PORT || '37737';
+  return await new Promise((resolve) => {
+    const http = require('http');
+    const req = http.get(`http://127.0.0.1:${port}/api/stats`, (res) => {
+      res.on('data', () => {});
+      res.on('end', () => resolve(res.statusCode === 200));
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(timeoutMs, () => { req.destroy(); resolve(false); });
+  });
+}
+
+module.exports = {
+  serviceDefs,
+  installServices,
+  uninstallServices,
+  serviceStatus,
+  controlService,
+  logsPath,
+  probeDashboardHealth,
+  // Exposed for tests:
+  renderPlist,
+  renderSystemdService,
+  renderSystemdPath,
+  renderSystemdTimer,
+  renderSystemdCalendarTimer,
+  plistPath,
+  plistLabel,
+  systemdDir,
+  systemdUnitName,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-agent-memory",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Persistent memory for Claude Code, Codex CLI, Cursor and any MCP client. Local-first, hits #5 on LoCoMo. One command to install.",
   "keywords": [
     "mcp",