total-agent-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vitalii Cherepanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# total-agent-memory
+
+> Persistent memory for Claude Code, Codex CLI, Cursor, Cline and any MCP client.
+> Local-first. Hits **#5 on LoCoMo** and **96.2% R@5 on LongMemEval**.
+
+```bash
+npx -y total-agent-memory
+```
+
+That's it. One command bootstraps a Python virtual env in `~/.claude-memory/`,
+installs the MCP server, and prints next-step instructions for wiring your IDE.
+
+## Quick start
+
+```bash
+# Onboard (install + show next steps)
+npx -y total-agent-memory
+
+# Or explicit
+npx -y total-agent-memory install
+npx -y total-agent-memory connect claude-code
+npx -y total-agent-memory connect cursor
+npx -y total-agent-memory connect codex
+npx -y total-agent-memory status
+```
+
+Alias: `tam` (same binary).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `install`         | Create venv, install Python server. 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` |
+| `demo`            | Health-check end-to-end. |
+| `status`          | Print install paths, DB size. |
+| `doctor`          | Diagnose Python/uv/git on PATH. |
+| `upgrade`         | Pull the latest server version. |
+| `uninstall`       | Remove `~/.claude-memory` (needs `--yes`). |
+
+## Options
+
+| Flag | Meaning |
+|---|---|
+| `--server-version 11.2.2` | Pin a specific server release. |
+| `--source pypi\|git`       | Force install source. Default: PyPI with GitHub fallback. |
+| `--memory-dir /path`      | Override install dir (default `~/.claude-memory`). |
+| `--yes`                   | Skip prompts (needed for `uninstall`). |
+| `--no-color`              | Disable ANSI. |
+| `--verbose`               | Print every shell command. |
+
+## Requirements
+
+- **Node ≥ 18** (you already have it if you're reading this).
+- **Python ≥ 3.10** on PATH. The wrapper will tell you how to install it if missing.
+- Optional: **[uv](https://docs.astral.sh/uv/)** — 10× faster installs, auto-detected.
+
+## What gets installed
+
+```
+~/.claude-memory/
+├── .venv/                   # isolated Python env
+│   └── bin/claude-total-memory   # MCP server entry-point
+└── memory.db                # SQLite — your memory lives here
+```
+
+Nothing global is touched. Uninstall with `tam uninstall --yes`.
+
+## Links
+
+- Site: <https://totalmemory.dev>
+- Server source: <https://github.com/vbcherepanov/total-agent-memory>
+- PyPI package: `claude-total-memory`
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// total-agent-memory CLI — Node wrapper around the Python MCP server.
+// Zero runtime dependencies, fast cold start, works on macOS / Linux / Windows.
+
+'use strict';
+
+const { parseArgs } = require('../lib/args');
+const { c, banner, dim, bold } = require('../lib/style');
+const cmds = require('../lib/commands');
+
+const VERSION = require('../package.json').version;
+
+const HELP = `${banner()}
+
+${bold('Usage:')}  total-agent-memory <command> [options]
+        ${dim('alias:')} tam <command> [options]
+
+${bold('Commands:')}
+  install            Install Python server into ~/.claude-memory (idempotent)
+  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')}
+  demo               Seed demo session + run a recall to prove it works
+  status             Health check + tool count + DB stats
+  doctor             Diagnose environment (python, uv, ports, configs)
+  upgrade            Upgrade to the latest server version
+  uninstall          Remove ~/.claude-memory and IDE wirings
+  version            Print version
+  help               Show this message
+
+${bold('Options:')}
+  --version, -v         Print npm wrapper version
+  --server-version <v>  Pin server version (default: latest)
+  --source <pypi|git>   Where to install from (default: auto)
+  --memory-dir <path>   Override install dir (default: ~/.claude-memory)
+  --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
+  npx -y total-agent-memory connect claude-code
+
+  ${c.dim('# All-in-one onboarding:')}
+  npx -y total-agent-memory
+
+  ${c.dim('# Pin a specific server version:')}
+  npx -y total-agent-memory install --server-version 11.2.2
+
+${bold('Docs:')}  https://totalmemory.dev
+${bold('Repo:')}  https://github.com/vbcherepanov/total-agent-memory
+`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgs(argv);
+
+  if (parsed.flags.version || parsed.flags.v) {
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+  if (parsed.command === 'version') {
+    process.stdout.write(`total-agent-memory v${VERSION}\n`);
+    return 0;
+  }
+  if (parsed.command === 'help' || parsed.flags.help || parsed.flags.h) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const ctx = {
+    flags: parsed.flags,
+    positional: parsed.positional,
+    wrapperVersion: VERSION,
+  };
+
+  const cmd = parsed.command || 'onboard';
+  const fn = cmds[cmd];
+  if (!fn) {
+    process.stderr.write(`${c.red('error')}: unknown command "${cmd}"\n`);
+    process.stderr.write(HELP);
+    return 2;
+  }
+  return await fn(ctx);
+}
+
+main()
+  .then((code) => process.exit(code || 0))
+  .catch((err) => {
+    process.stderr.write(`${c.red('fatal')}: ${err && err.message ? err.message : err}\n`);
+    if (process.env.TAM_DEBUG || process.argv.includes('--verbose')) {
+      process.stderr.write(`${err && err.stack ? err.stack : ''}\n`);
+    }
+    process.exit(1);
+  });

package/lib/args.js

@@ -0,0 +1,72 @@
+'use strict';
+
+// Minimal CLI parser. Supports:
+//   <command> <positional...>
+//   --flag, --flag=value, --flag value
+//   -shortflag, -shortflag value
+//   bare positionals collected in order.
+
+const FLAGS_WITH_VALUE = new Set([
+  '--server-version',
+  '--source',
+  '--memory-dir',
+  '--ide',
+  '--port',
+  '--log-level',
+]);
+
+function normalize(name) {
+  return name.replace(/^-+/, '');
+}
+
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  let command = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (!tok) continue;
+    if (tok === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (tok.startsWith('--')) {
+      const eq = tok.indexOf('=');
+      let key, val;
+      if (eq !== -1) {
+        key = tok.slice(0, eq);
+        val = tok.slice(eq + 1);
+      } else {
+        key = tok;
+        if (FLAGS_WITH_VALUE.has(key) && argv[i + 1] && !argv[i + 1].startsWith('-')) {
+          val = argv[++i];
+        } else {
+          val = true;
+        }
+      }
+      flags[normalize(key)] = val;
+      continue;
+    }
+    if (tok.startsWith('-') && tok.length > 1) {
+      // Short flag(s). We treat each separately and they take no value
+      // except the well-known -v/--version mapping.
+      const short = tok.slice(1);
+      flags[short] = true;
+      continue;
+    }
+    if (command === null) {
+      command = tok;
+    } else {
+      positional.push(tok);
+    }
+  }
+
+  // Normalize aliases.
+  if (flags.y) flags.yes = true;
+  if (flags.h) flags.help = true;
+
+  return { command, positional, flags };
+}
+
+module.exports = { parseArgs };

package/lib/commands.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+const { install, venvBin, pinned } = require('./install');
+const { connect, SUPPORTED } = require('./ide');
+const { diagnose, printReport, printRemediation } = require('./doctor');
+const { memoryDir, venvDir, exists, home } = require('./paths');
+const { run, runOrThrow } = require('./sh');
+const { c, bold, ok, fail, warn, info, banner, step } = require('./style');
+
+async function ensureInstalled(ctx) {
+  const bin = venvBin(ctx.flags, 'claude-total-memory');
+  if (exists(bin)) return bin;
+  process.stdout.write(`${info('Server not installed yet — installing now…')}\n`);
+  const code = await install(ctx);
+  if (code !== 0) throw new Error('install failed');
+  return bin;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+
+async function cmdInstall(ctx) {
+  process.stdout.write(banner());
+  return await install(ctx);
+}
+
+async function cmdStart(ctx) {
+  const bin = await ensureInstalled(ctx);
+  process.stdout.write(`${info(`Starting MCP server: ${c.dim(bin)}`)}\n`);
+  // Replace this Node process with the server (transparent pass-through).
+  const child = spawn(bin, [], {
+    stdio: 'inherit',
+    env: { ...process.env, MEMORY_MODE: process.env.MEMORY_MODE || 'fast' },
+  });
+  return await new Promise((resolve) => child.on('close', (code) => resolve(code || 0)));
+}
+
+async function cmdConnect(ctx) {
+  const ide = ctx.positional[0];
+  if (!ide) {
+    process.stderr.write(`${fail('connect requires an IDE name')}\n`);
+    process.stderr.write(`Supported: ${SUPPORTED.join(', ')}\n`);
+    return 2;
+  }
+  await ensureInstalled(ctx);
+  try {
+    const { file, manual } = connect(ide, ctx.flags);
+    if (manual) {
+      process.stdout.write(`${warn(`Manual wiring required for ${ide}: ${file}`)}\n`);
+      return 0;
+    }
+    process.stdout.write(banner());
+    process.stdout.write(`${ok(`Wired ${c.bold(ide)} → ${c.dim(file)}`)}\n`);
+    process.stdout.write(`${info('Restart your IDE for the change to take effect.')}\n`);
+    return 0;
+  } catch (e) {
+    process.stderr.write(`${fail(e.message)}\n`);
+    return 2;
+  }
+}
+
+async function cmdDemo(ctx) {
+  const bin = await ensureInstalled(ctx);
+  process.stdout.write(banner());
+  process.stdout.write(`${info('Demo: seed a session + recall it.')}\n`);
+  // We use the lookup-memory CLI shipped in the same venv to drive a
+  // round-trip without needing an MCP client.
+  const cli = path.join(path.dirname(bin), process.platform === 'win32' ? 'lookup-memory.exe' : 'lookup-memory');
+  if (!exists(cli)) {
+    process.stdout.write(`${warn('lookup-memory CLI not found in venv — open an MCP client to drive the server.')}\n`);
+    return 0;
+  }
+  process.stdout.write(`${c.dim('$ lookup-memory --help')}\n`);
+  await run(cli, ['--help']);
+  process.stdout.write(`\n${ok('Server is healthy. Connect your IDE next:')}\n`);
+  process.stdout.write(`  ${c.cyan('total-agent-memory connect claude-code')}\n`);
+  return 0;
+}
+
+async function cmdStatus(ctx) {
+  const env = await diagnose();
+  process.stdout.write(banner());
+  printReport(env);
+  const dir = memoryDir(ctx.flags);
+  const venv = venvDir(ctx.flags);
+  const bin = venvBin(ctx.flags, 'claude-total-memory');
+  const db = path.join(dir, 'memory.db');
+  process.stdout.write(`\n${bold('Install')}\n`);
+  process.stdout.write(`  ${exists(dir) ? ok(`memory dir : ${dir}`) : warn(`memory dir : ${dir} (missing)`)}\n`);
+  process.stdout.write(`  ${exists(venv) ? ok(`venv       : ${venv}`) : warn(`venv       : ${venv} (missing)`)}\n`);
+  process.stdout.write(`  ${exists(bin) ? ok(`server bin : ${bin}`) : warn(`server bin : ${bin} (missing)`)}\n`);
+  if (exists(db)) {
+    const sz = (fs.statSync(db).size / 1024 / 1024).toFixed(2);
+    process.stdout.write(`  ${ok(`memory.db  : ${sz} MB`)}\n`);
+  } else {
+    process.stdout.write(`  ${warn(`memory.db  : ${db} (will be created on first save)`)}\n`);
+  }
+  return 0;
+}
+
+async function cmdDoctor(ctx) {
+  const env = await diagnose();
+  process.stdout.write(banner());
+  printReport(env);
+  printRemediation(env);
+  return 0;
+}
+
+async function cmdUpgrade(ctx) {
+  process.stdout.write(banner());
+  process.stdout.write(`${info('Upgrading server to the latest version…')}\n`);
+  // Force install with --server-version=latest.
+  const upgradeCtx = { ...ctx, flags: { ...ctx.flags, 'server-version': 'latest' } };
+  return await install(upgradeCtx);
+}
+
+async function cmdUninstall(ctx) {
+  process.stdout.write(banner());
+  const dir = memoryDir(ctx.flags);
+  if (!exists(dir)) {
+    process.stdout.write(`${ok('Nothing to remove — directory does not exist.')}\n`);
+    return 0;
+  }
+  process.stdout.write(`${warn(`About to remove ${dir}.`)}\n`);
+  if (!ctx.flags.yes) {
+    process.stdout.write(`${info('Re-run with --yes to confirm.')}\n`);
+    return 0;
+  }
+  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;
+}
+
+// First-run onboarding: install + suggest a connect step.
+async function cmdOnboard(ctx) {
+  process.stdout.write(banner());
+  const env = await diagnose();
+  printReport(env);
+  if (!env.python3) {
+    printRemediation(env);
+    return 1;
+  }
+  process.stdout.write(`\n${bold('Quick setup')}\n`);
+  process.stdout.write(`  ${step(1, 2, 'install server')}\n`);
+  const code = await install(ctx);
+  if (code !== 0) return code;
+  process.stdout.write(`  ${step(2, 2, 'next: wire an IDE')}\n\n`);
+  process.stdout.write(`  ${c.cyan('total-agent-memory connect claude-code')}\n`);
+  process.stdout.write(`  ${c.cyan('total-agent-memory connect cursor')}\n`);
+  process.stdout.write(`  ${c.cyan('total-agent-memory connect codex')}\n`);
+  process.stdout.write(`\n${c.dim('Docs: https://totalmemory.dev')}\n`);
+  return 0;
+}
+
+module.exports = {
+  install: cmdInstall,
+  start: cmdStart,
+  connect: cmdConnect,
+  demo: cmdDemo,
+  status: cmdStatus,
+  doctor: cmdDoctor,
+  upgrade: cmdUpgrade,
+  uninstall: cmdUninstall,
+  onboard: cmdOnboard,
+};

package/lib/doctor.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { probe, which } = require('./sh');
+const { exists } = require('./paths');
+const { c, bold, ok, fail, warn, info } = require('./style');
+
+// Returns environment summary.
+async function diagnose() {
+  const env = {
+    platform: process.platform,
+    arch: process.arch,
+    node: process.version,
+    python: null,
+    python3: null,
+    uv: null,
+    pip: null,
+    pipx: null,
+    git: null,
+  };
+
+  for (const bin of ['python3', 'python', 'uv', 'pipx', 'git']) {
+    const r = probe(bin, ['--version']);
+    if (r.ok) {
+      env[bin] = { path: r.path, version: r.out };
+    }
+  }
+  if (env.python3 && env.python3.version) {
+    const m = env.python3.version.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (m) {
+      env.pythonMajor = +m[1];
+      env.pythonMinor = +m[2];
+      env.pythonPatch = +m[3];
+    }
+  }
+  return env;
+}
+
+function pickInstaller(env) {
+  // Prefer uv (fastest, most reliable). Fall back to venv+pip.
+  if (env.uv) return 'uv';
+  if (env.python3 && env.pythonMajor >= 3 && env.pythonMinor >= 10) return 'venv-pip';
+  return null;
+}
+
+function printReport(env) {
+  process.stdout.write(`\n${bold('Environment')}\n`);
+  process.stdout.write(`  ${info(`platform : ${env.platform}/${env.arch}`)}\n`);
+  process.stdout.write(`  ${info(`node     : ${env.node}`)}\n`);
+  if (env.python3) {
+    process.stdout.write(`  ${ok(`python3  : ${env.python3.version} ${c.dim('(' + env.python3.path + ')')}`)}\n`);
+  } else {
+    process.stdout.write(`  ${fail('python3  : not found')}\n`);
+  }
+  if (env.uv) {
+    process.stdout.write(`  ${ok(`uv       : ${env.uv.version} ${c.dim('(' + env.uv.path + ')')}`)}\n`);
+  } else {
+    process.stdout.write(`  ${warn('uv       : not found (optional but recommended — 10× faster installs)')}\n`);
+  }
+  if (env.git) {
+    process.stdout.write(`  ${ok(`git      : ${env.git.version}`)}\n`);
+  } else {
+    process.stdout.write(`  ${warn('git      : not found (needed only for --source git fallback)')}\n`);
+  }
+  return env;
+}
+
+function printRemediation(env) {
+  if (!env.python3) {
+    process.stdout.write(`\n${bold('Install Python 3.10+:')}\n`);
+    if (process.platform === 'darwin') {
+      process.stdout.write(`  ${c.cyan('brew install python@3.12')}\n`);
+    } else if (process.platform === 'linux') {
+      process.stdout.write(`  ${c.cyan('sudo apt install -y python3 python3-venv python3-pip')}    ${c.dim('# Debian/Ubuntu')}\n`);
+      process.stdout.write(`  ${c.cyan('sudo dnf install -y python3 python3-pip')}                 ${c.dim('# Fedora/RHEL')}\n`);
+    } else if (process.platform === 'win32') {
+      process.stdout.write(`  ${c.cyan('winget install Python.Python.3.12')}\n`);
+    }
+  }
+  if (env.python3 && !env.uv) {
+    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`);
+  }
+}
+
+module.exports = { diagnose, pickInstaller, printReport, printRemediation };

package/lib/ide.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { home, memoryDir, venvBin, exists, readJSONSafe, writeJSON, ensureDir } = require('./paths');
+const { c, ok, info, warn } = require('./style');
+
+const SUPPORTED = [
+  'claude-code',
+  'codex',
+  'cursor',
+  'cline',
+  'continue',
+  'aider',
+  'windsurf',
+  'gemini-cli',
+  'opencode',
+];
+
+function mcpEntry(flags) {
+  const bin = venvBin(flags, 'claude-total-memory');
+  return {
+    command: bin,
+    args: [],
+    env: {
+      MEMORY_MODE: 'fast',
+    },
+  };
+}
+
+function claudeCodePath() {
+  return path.join(home(), '.claude.json');
+}
+
+function cursorPath() {
+  return path.join(home(), '.cursor', 'mcp.json');
+}
+
+function clinePath() {
+  // Cline reads VSCode global state, but for portability we use its public
+  // config file location when present.
+  return path.join(home(), '.cline', 'mcp.json');
+}
+
+function continuePath() {
+  return path.join(home(), '.continue', 'config.json');
+}
+
+function codexPath() {
+  return path.join(home(), '.codex', 'config.toml');
+}
+
+function geminiPath() {
+  return path.join(home(), '.gemini', 'settings.json');
+}
+
+function windsurfPath() {
+  return path.join(home(), '.codeium', 'windsurf', 'mcp_config.json');
+}
+
+function aiderPath() {
+  return path.join(home(), '.aider.conf.yml');
+}
+
+function opencodePath() {
+  return path.join(home(), '.config', 'opencode', 'config.json');
+}
+
+function mergeMcpServers(file, name, entry) {
+  const cfg = readJSONSafe(file) || {};
+  cfg.mcpServers = cfg.mcpServers || {};
+  cfg.mcpServers[name] = entry;
+  writeJSON(file, cfg);
+}
+
+function wireClaudeCode(flags) {
+  mergeMcpServers(claudeCodePath(), 'total-agent-memory', mcpEntry(flags));
+  return claudeCodePath();
+}
+function wireCursor(flags) {
+  ensureDir(path.dirname(cursorPath()));
+  mergeMcpServers(cursorPath(), 'total-agent-memory', mcpEntry(flags));
+  return cursorPath();
+}
+function wireCline(flags) {
+  ensureDir(path.dirname(clinePath()));
+  mergeMcpServers(clinePath(), 'total-agent-memory', mcpEntry(flags));
+  return clinePath();
+}
+function wireContinue(flags) {
+  ensureDir(path.dirname(continuePath()));
+  const cfg = readJSONSafe(continuePath()) || {};
+  cfg.mcpServers = cfg.mcpServers || [];
+  cfg.mcpServers = cfg.mcpServers.filter((s) => s.name !== 'total-agent-memory');
+  cfg.mcpServers.push({ name: 'total-agent-memory', ...mcpEntry(flags) });
+  writeJSON(continuePath(), cfg);
+  return continuePath();
+}
+function wireWindsurf(flags) {
+  ensureDir(path.dirname(windsurfPath()));
+  mergeMcpServers(windsurfPath(), 'total-agent-memory', mcpEntry(flags));
+  return windsurfPath();
+}
+function wireGeminiCLI(flags) {
+  ensureDir(path.dirname(geminiPath()));
+  mergeMcpServers(geminiPath(), 'total-agent-memory', mcpEntry(flags));
+  return geminiPath();
+}
+function wireOpenCode(flags) {
+  ensureDir(path.dirname(opencodePath()));
+  mergeMcpServers(opencodePath(), 'total-agent-memory', mcpEntry(flags));
+  return opencodePath();
+}
+function wireCodex(flags) {
+  ensureDir(path.dirname(codexPath()));
+  const bin = venvBin(flags, 'claude-total-memory');
+  const block = `
+
+[mcp_servers.total-agent-memory]
+command = ${JSON.stringify(bin)}
+args = []
+env = { MEMORY_MODE = "fast" }
+`;
+  let prev = '';
+  try { prev = fs.readFileSync(codexPath(), 'utf8'); } catch (_) { /* fresh */ }
+  if (prev.includes('[mcp_servers.total-agent-memory]')) {
+    return codexPath(); // already wired
+  }
+  fs.writeFileSync(codexPath(), prev + block);
+  return codexPath();
+}
+function wireAider() {
+  return aiderPath() + ' (manual: aider does not yet support MCP; use lookup-memory CLI instead)';
+}
+
+function connect(ide, flags) {
+  switch (ide) {
+    case 'claude-code': return { file: wireClaudeCode(flags) };
+    case 'codex': return { file: wireCodex(flags) };
+    case 'cursor': return { file: wireCursor(flags) };
+    case 'cline': return { file: wireCline(flags) };
+    case 'continue': return { file: wireContinue(flags) };
+    case 'windsurf': return { file: wireWindsurf(flags) };
+    case 'gemini-cli': return { file: wireGeminiCLI(flags) };
+    case 'opencode': return { file: wireOpenCode(flags) };
+    case 'aider': return { file: wireAider(flags), manual: true };
+    default: throw new Error(`unsupported IDE: ${ide}. Supported: ${SUPPORTED.join(', ')}`);
+  }
+}
+
+module.exports = { SUPPORTED, connect, mcpEntry };

package/lib/index.js

@@ -0,0 +1,22 @@
+'use strict';
+
+// Library facade so users can `require('total-agent-memory')` and drive
+// the wrapper from JS as well. Useful for postinstall scripts and CI.
+
+const cmds = require('./commands');
+const { diagnose } = require('./doctor');
+const { mcpEntry, SUPPORTED } = require('./ide');
+const { memoryDir, venvDir, venvBin } = require('./paths');
+const { install, pinned } = require('./install');
+
+module.exports = {
+  ...cmds,
+  diagnose,
+  mcpEntry,
+  SUPPORTED_IDES: SUPPORTED,
+  memoryDir,
+  venvDir,
+  venvBin,
+  installServer: install,
+  pinnedVersion: pinned,
+};

package/lib/install.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const fs = require('fs');
+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 { c, bold, ok, fail, warn, info, step } = require('./style');
+
+const PYPI_PACKAGE = 'claude-total-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 = '11.2.2';
+const GIT_URL = 'https://github.com/vbcherepanov/total-agent-memory.git';
+
+function pinned(flags) {
+  return (
+    (flags && flags['server-version']) ||
+    process.env.TAM_SERVER_VERSION ||
+    DEFAULT_SERVER_VERSION
+  );
+}
+
+function specPyPI(flags) {
+  const v = pinned(flags);
+  return v && v !== 'latest' ? `${PYPI_PACKAGE}==${v}` : PYPI_PACKAGE;
+}
+
+function specGit(flags) {
+  const v = pinned(flags);
+  const tag = v && v !== 'latest' ? `@v${v}` : '';
+  return `git+${GIT_URL}${tag}`;
+}
+
+async function pypiHas(version) {
+  // We can't import https here cheaply — use built-in for HEAD.
+  return await new Promise((resolve) => {
+    const https = require('https');
+    const url = version
+      ? `https://pypi.org/pypi/${PYPI_PACKAGE}/${version}/json`
+      : `https://pypi.org/pypi/${PYPI_PACKAGE}/json`;
+    const req = https.get(url, (res) => {
+      // Drain.
+      res.on('data', () => {});
+      res.on('end', () => resolve(res.statusCode === 200));
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(4000, () => { req.destroy(); resolve(false); });
+  });
+}
+
+async function pickSource(flags) {
+  const explicit = flags && flags.source;
+  if (explicit === 'pypi' || explicit === 'git') return explicit;
+  // Auto: try PyPI first, fall back to git.
+  if (await pypiHas(pinned(flags))) return 'pypi';
+  return 'git';
+}
+
+async function createVenv(flags, env) {
+  const venv = venvDir(flags);
+  if (exists(path.join(venv, process.platform === 'win32' ? 'Scripts' : 'bin'))) {
+    return;
+  }
+  ensureDir(memoryDir(flags));
+
+  if (env.uv) {
+    await runOrThrow('uv', ['venv', venv, '--python', '3.12'], { silent: true });
+    return;
+  }
+  await runOrThrow('python3', ['-m', 'venv', venv], { silent: true });
+}
+
+async function pipInstall(flags, env, source) {
+  const spec = source === 'pypi' ? specPyPI(flags) : specGit(flags);
+  process.stdout.write(`${info(`Installing ${c.bold(spec)} (source: ${source})…`)}\n`);
+
+  // Dev-only: skip the actual pip step so CI / smoke tests can validate the
+  // wrapper end-to-end without downloading ~1.5GB of ML deps.
+  if (process.env.TAM_INSTALL_DRY === '1') {
+    process.stdout.write(`  ${warn('TAM_INSTALL_DRY=1 — skipping real pip install')}\n`);
+    // Drop a marker file so subsequent steps don't barf on missing bin.
+    const fs = require('fs');
+    const markerDir = path.dirname(venvBin(flags, 'claude-total-memory'));
+    fs.mkdirSync(markerDir, { recursive: true });
+    fs.writeFileSync(venvBin(flags, 'claude-total-memory'), '#!/bin/sh\necho "dry-run shim"\n');
+    fs.chmodSync(venvBin(flags, 'claude-total-memory'), 0o755);
+    return;
+  }
+
+  if (env.uv) {
+    // uv pip is dramatically faster.
+    const pyExe = venvBin(flags, 'python');
+    await runOrThrow('uv', ['pip', 'install', '--python', pyExe, '--upgrade', spec]);
+    return;
+  }
+  const pipExe = venvBin(flags, 'pip');
+  await runOrThrow(pipExe, ['install', '--upgrade', '--disable-pip-version-check', spec]);
+}
+
+async function install(ctx) {
+  const flags = ctx.flags;
+  const env = await diagnose();
+  printReport(env);
+
+  const picker = pickInstaller(env);
+  if (!picker) {
+    process.stderr.write(`\n${fail('cannot proceed: missing python3 ≥ 3.10')}\n`);
+    printRemediation(env);
+    return 1;
+  }
+
+  process.stdout.write(`\n${bold('Installing server…')}\n`);
+  process.stdout.write(`  ${step(1, 3, `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`);
+  const source = await pickSource(flags);
+
+  process.stdout.write(`  ${step(3, 3, 'pip install…')}\n`);
+  await pipInstall(flags, env, source);
+
+  // Verify entry-point present.
+  const bin = venvBin(flags, 'claude-total-memory');
+  if (!exists(bin)) {
+    process.stderr.write(`\n${fail(`entry-point ${bin} not found after install`)}\n`);
+    return 1;
+  }
+  process.stdout.write(`\n${ok(c.bold('Installation complete.'))}\n`);
+  process.stdout.write(`${info(`Binary: ${c.dim(bin)}`)}\n`);
+  return 0;
+}
+
+module.exports = { install, venvBin, pinned, DEFAULT_SERVER_VERSION, PYPI_PACKAGE };

package/lib/paths.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+function home() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+function memoryDir(flags) {
+  if (flags && typeof flags['memory-dir'] === 'string') return flags['memory-dir'];
+  if (process.env.CLAUDE_MEMORY_DIR) return process.env.CLAUDE_MEMORY_DIR;
+  return path.join(home(), '.claude-memory');
+}
+
+function venvDir(flags) {
+  return path.join(memoryDir(flags), '.venv');
+}
+
+function venvBin(flags, name) {
+  const sub = process.platform === 'win32' ? 'Scripts' : 'bin';
+  const ext = process.platform === 'win32' && !name.endsWith('.exe') ? '.exe' : '';
+  return path.join(venvDir(flags), sub, name + ext);
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
+}
+
+function exists(p) {
+  try { fs.accessSync(p); return true; } catch (_) { return false; }
+}
+
+function readJSONSafe(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch (_) { return null; }
+}
+
+function writeJSON(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(obj, null, 2));
+}
+
+module.exports = { home, memoryDir, venvDir, venvBin, ensureDir, exists, readJSONSafe, writeJSON };

package/lib/sh.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const { spawn, spawnSync } = require('child_process');
+const { c, dim } = require('./style');
+
+function isVerbose() {
+  return process.argv.includes('--verbose') || process.env.TAM_DEBUG === '1';
+}
+
+function which(bin) {
+  const cmd = process.platform === 'win32' ? 'where' : 'which';
+  const r = spawnSync(cmd, [bin], { encoding: 'utf8' });
+  if (r.status === 0) {
+    const path = (r.stdout || '').split(/\r?\n/).filter(Boolean)[0];
+    return path || null;
+  }
+  return null;
+}
+
+function probe(bin, args = ['--version']) {
+  const path = which(bin);
+  if (!path) return { ok: false };
+  const r = spawnSync(path, args, { encoding: 'utf8' });
+  return {
+    ok: r.status === 0,
+    path,
+    out: (r.stdout || '').trim() || (r.stderr || '').trim(),
+  };
+}
+
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    if (isVerbose()) {
+      process.stderr.write(
+        `${dim('$')} ${[cmd, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ')}\n`
+      );
+    }
+    const child = spawn(cmd, args, {
+      stdio: opts.silent ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      env: { ...process.env, ...(opts.env || {}) },
+      cwd: opts.cwd || process.cwd(),
+    });
+    let stdout = '';
+    let stderr = '';
+    if (opts.silent) {
+      child.stdout.on('data', (d) => (stdout += d.toString()));
+      child.stderr.on('data', (d) => (stderr += d.toString()));
+    }
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+    child.on('error', (err) => resolve({ code: 1, stdout, stderr: String(err) }));
+  });
+}
+
+async function runOrThrow(cmd, args, opts = {}) {
+  const r = await run(cmd, args, opts);
+  if (r.code !== 0) {
+    const err = new Error(`${cmd} ${args.join(' ')} exited with code ${r.code}`);
+    err.stdout = r.stdout;
+    err.stderr = r.stderr;
+    err.code = r.code;
+    throw err;
+  }
+  return r;
+}
+
+module.exports = { which, probe, run, runOrThrow, isVerbose };

package/lib/style.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const noColor =
+  process.argv.includes('--no-color') ||
+  process.env.NO_COLOR === '1' ||
+  process.env.TERM === 'dumb' ||
+  !process.stdout.isTTY;
+
+function wrap(open, close) {
+  return (s) => (noColor ? String(s) : `\x1b[${open}m${s}\x1b[${close}m`);
+}
+
+const c = {
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  blue: wrap(34, 39),
+  magenta: wrap(35, 39),
+  cyan: wrap(36, 39),
+  gray: wrap(90, 39),
+};
+
+function bold(s) { return c.bold(s); }
+function dim(s) { return c.dim(s); }
+
+function banner() {
+  const v = require('../package.json').version;
+  const line = c.cyan('total-agent-memory');
+  return `\n${c.bold(line)}  ${c.dim(`v${v}`)}  ${c.dim('— persistent memory for AI coding agents')}\n`;
+}
+
+function step(n, total, msg) {
+  return `${c.dim(`[${n}/${total}]`)} ${msg}`;
+}
+
+function ok(msg) { return `${c.green('✓')} ${msg}`; }
+function fail(msg) { return `${c.red('✗')} ${msg}`; }
+function warn(msg) { return `${c.yellow('!')} ${msg}`; }
+function info(msg) { return `${c.cyan('›')} ${msg}`; }
+
+module.exports = { c, bold, dim, banner, step, ok, fail, warn, info };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "total-agent-memory",
+  "version": "0.1.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",
+    "memory",
+    "claude",
+    "claude-code",
+    "codex",
+    "cursor",
+    "cline",
+    "agent",
+    "ai",
+    "llm",
+    "knowledge-graph",
+    "rag",
+    "persistent-memory",
+    "local-first"
+  ],
+  "homepage": "https://totalmemory.dev",
+  "bugs": {
+    "url": "https://git.infra.vbcherepanov.com/vbcherepanov/total-memory-npm/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.infra.vbcherepanov.com/vbcherepanov/total-memory-npm.git"
+  },
+  "license": "MIT",
+  "author": "Vitalii Cherepanov <vbcherepanov@gmail.com> (https://vbcherepanov.com)",
+  "type": "commonjs",
+  "bin": {
+    "total-agent-memory": "bin/cli.js",
+    "tam": "bin/cli.js"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node tests/smoke.test.js",
+    "lint": "node --check bin/cli.js && node --check lib/*.js"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}