lucid-mem 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentMemoryRepo
+
+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,46 @@
+# lucid-mem
+
+Autonomous, git-backed memory for AI coding agents. `amr` keeps what your agents learn across sessions and across repositories: it injects memory at session start, lets agents save durable facts while they work, syncs through git, and maintains itself with scheduled dreaming — no manual invocation.
+
+Implements the [Agent Memory Repo spec](https://github.com/AgentMemoryRepo/agentmemoryrepo). Full docs and per-host details live in the [project repo](https://github.com/tonythethompson/lucid-mem).
+
+## Install
+
+```sh
+npm i -g lucid-mem        # gives you `amr` (and `lucid` as an alias)
+amr ensure                # create the memory repo (default ~/agent-memory, $AMR_HOME to override)
+amr install               # wire rules + hooks + MCP into detected agent hosts
+amr doctor                # verify everything
+```
+
+Then start a session in a wired host — Cursor, Claude Code, Windsurf, Devin, Copilot, Codex, Cline, Muse, Claude Desktop, Antigravity, OpenCode, CommandCode, or Freebuff — and memory is already in context.
+
+## Daily use
+
+Mostly you don't touch it; agents do. Useful by hand:
+
+```sh
+amr context               # what a session here would see
+amr add "I prefer concise summaries"          # global memory
+amr add "uses Kokoro-82M for TTS" --project   # this repo's memory
+amr search "tts"
+amr link other-repo       # auto-attach another repo's memory to sessions here
+amr discover              # which hot repos still lack memory
+amr dream --fix --compact # dedupe + archive overflow
+```
+
+Memory lives in `~/agent-memory` — a real git repo you can read, diff, and point at a private remote (`amr remote set <url>`) for sync and backup.
+
+## Multi-repo memory
+
+One memory repo serves every project. `projects/<name>-<hash>.md` files key off the repo's origin remote, so clones share memory and same-named repos don't collide. `amr link` attaches related projects (transitively); `private` policy keeps a project out of transitive auto-attach; `noglobal` skips global memory for a repo.
+
+## MCP
+
+`amr serve` is a stdio MCP server (`memory_context`, `memory_add`, `memory_search`, `memory_update`) — `amr install` registers it with hosts that support MCP.
+
+## Links
+
+- Repo: https://github.com/tonythethompson/lucid-mem
+- Spec: https://github.com/AgentMemoryRepo/agentmemoryrepo
+- License: MIT

package/lib/cli.mjs

@@ -1,3 +1,6 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   cmdAdd,
   cmdContext,
@@ -14,7 +17,7 @@ import {
 import { cmdDiscover } from './discover.mjs';
 import { cmdDream } from './dream.mjs';
 import { cmdHarvest } from './harvest.mjs';
-import { cmdDoctor, cmdInstall } from './install.mjs';
+import { cmdDoctor, cmdInstall, cmdUninstall } from './install.mjs';
 import { cmdServe } from './serve.mjs';
 
 const USAGE = `amr: agent memory CLI (lucid-mem)
@@ -37,6 +40,7 @@ usage: amr <command> [args] [flags]
   harvest [--days N] [--json] [--extract] [--max N] [--min C]   list transcripts; --extract streams normalized user messages
   discover [--days N] [--min N] [--json]   rank repos by transcript mentions; shows memory coverage + suggested links
   install [--host a,b|all]      wire hooks + rules + MCP into detected agent hosts
+  uninstall [--host a,b|all]    remove amr hooks + rules + MCP entries
   serve                         stdio MCP server (memory_context/add/search/update)
 
 flags:
@@ -125,10 +129,19 @@ export function main(argv) {
         return cmdDiscover(flags);
       case 'install':
         return cmdInstall(flags);
+      case 'uninstall':
+        return cmdUninstall(flags);
       case 'version':
       case '--version':
-      case '-v':
-        return process.stdout.write('amr 0.1.0\n');
+      case '-v': {
+        const pkg = JSON.parse(
+          fs.readFileSync(
+            path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'),
+            'utf8'
+          )
+        );
+        return process.stdout.write(`amr ${pkg.version}\n`);
+      }
       case 'help':
       case '--help':
       case '-h':

package/lib/install.mjs

@@ -540,6 +540,165 @@ export function cmdInstall(flags) {
   out('verify with: amr doctor');
 }
 
+// ---------- uninstall ----------
+
+const isAmrCmd = (c) => typeof c === 'string' && c.includes('amr.mjs');
+
+function unmergeHooksJson(file) {
+  if (!fs.existsSync(file)) return false;
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return false;
+  }
+  if (!cfg.hooks) return false;
+  let changed = false;
+  for (const [ev, list] of Object.entries(cfg.hooks)) {
+    const kept = list.filter((e) => !isAmrCmd(e?.command));
+    if (kept.length !== list.length) changed = true;
+    if (kept.length) cfg.hooks[ev] = kept;
+    else delete cfg.hooks[ev];
+  }
+  if (!Object.keys(cfg.hooks).length) delete cfg.hooks;
+  if (changed) {
+    backup(file);
+    fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+  }
+  return changed;
+}
+
+function unmergeClaudeSettings(file) {
+  if (!fs.existsSync(file)) return false;
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return false;
+  }
+  if (!cfg.hooks) return false;
+  let changed = false;
+  for (const [ev, list] of Object.entries(cfg.hooks)) {
+    const kept = list
+      .map((e) => ({
+        ...e,
+        hooks: (e?.hooks || []).filter((h) => !isAmrCmd(h?.command)),
+      }))
+      .filter((e) => (e.hooks || []).length || !Array.isArray(e?.hooks));
+    if (JSON.stringify(kept) !== JSON.stringify(list)) changed = true;
+    if (kept.length) cfg.hooks[ev] = kept;
+    else delete cfg.hooks[ev];
+  }
+  if (!Object.keys(cfg.hooks).length) delete cfg.hooks;
+  if (changed) {
+    backup(file);
+    fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+  }
+  return changed;
+}
+
+function unmergeMcpJson(file) {
+  if (!fs.existsSync(file)) return false;
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return false;
+  }
+  if (!cfg.mcpServers?.['agent-memory']) return false;
+  delete cfg.mcpServers['agent-memory'];
+  if (!Object.keys(cfg.mcpServers).length) delete cfg.mcpServers;
+  backup(file);
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+  return true;
+}
+
+function unmergeMcpToml(file) {
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, 'utf8');
+  const next = text.replace(
+    /\n*\[mcp_servers\.agent-memory\]\n(?:[^[]*)?/,
+    '\n'
+  );
+  if (next === text) return false;
+  backup(file);
+  fs.writeFileSync(file, next);
+  return true;
+}
+
+function unmergeMcpOpencode(file) {
+  if (!fs.existsSync(file)) return false;
+  const text = fs.readFileSync(file, 'utf8');
+  let cfg;
+  try {
+    cfg = JSON.parse(text);
+  } catch {
+    return false; // .jsonc we never managed to write anyway
+  }
+  if (!cfg.mcp?.['agent-memory']) return false;
+  delete cfg.mcp['agent-memory'];
+  if (!Object.keys(cfg.mcp).length) delete cfg.mcp;
+  backup(file);
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+  return true;
+}
+
+function unstampRules(file) {
+  if (!fs.existsSync(file)) return 'absent';
+  const text = fs.readFileSync(file, 'utf8');
+  if (!text.includes(MARK_BEGIN)) return 'absent';
+  const re = new RegExp(`\\n*${MARK_BEGIN}[\\s\\S]*?${MARK_END}\\n?`, 'm');
+  const next = text.replace(re, '\n').replace(/\n{3,}/g, '\n\n');
+  // If only whitespace or a lone yaml frontmatter husk remains (e.g.
+  // a wrapper file we created), the file was entirely ours — delete it.
+  if (!next.replace(/^---\s*\n[\s\S]*?\n---/, '').trim()) {
+    fs.rmSync(file);
+    return 'removed (file deleted)';
+  }
+  backup(file);
+  fs.writeFileSync(file, next);
+  return 'removed';
+}
+
+export function cmdUninstall(flags) {
+  const requested = flags.host
+    ? String(flags.host).split(',').map((s) => s.trim())
+    : null;
+  const names = Object.keys(HOSTS).filter((n) =>
+    requested ? requested.includes('all') || requested.includes(n) : HOSTS[n].detect()
+  );
+  if (!names.length) {
+    out('no known agent hosts detected; nothing to remove');
+    return;
+  }
+  for (const name of names) {
+    const h = HOSTS[name];
+    const did = [];
+    try {
+      if (h.hooksJson && unmergeHooksJson(h.hooksJson()))
+        did.push(`hooks removed from ${h.hooksJson()}`);
+      if (h.settingsJson && unmergeClaudeSettings(h.settingsJson()))
+        did.push(`hooks removed from ${h.settingsJson()}`);
+      if (h.rules) {
+        for (const r of h.rules()) {
+          const res = unstampRules(r.path);
+          if (res !== 'absent') did.push(`rules ${res}: ${r.path}`);
+        }
+      }
+      if (h.mcpJson && unmergeMcpJson(h.mcpJson()))
+        did.push(`mcp entry removed from ${h.mcpJson()}`);
+      if (h.mcpToml && unmergeMcpToml(h.mcpToml()))
+        did.push(`mcp entry removed from ${h.mcpToml()}`);
+      if (h.mcpOpencode && unmergeMcpOpencode(h.mcpOpencode()))
+        did.push(`mcp entry removed from ${h.mcpOpencode()}`);
+    } catch (e) {
+      err(`${name}: ${e.message}`);
+      continue;
+    }
+    out(`${name}: ${did.length ? did.join('; ') : 'nothing wired'}`);
+  }
+}
+
 function hostWired(name) {
   const h = HOSTS[name];
   if (!h.detect()) return 'not installed';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lucid-mem",
-  "version": "0.2.0",
-  "description": "lucid-mem (amr) — autonomous git-backed agent memory (Agent Memory Repo spec)",
+  "version": "0.3.0",
+  "description": "lucid-mem (amr) - autonomous git-backed agent memory (Agent Memory Repo spec)",
   "type": "module",
   "bin": {
     "amr": "./amr.mjs",
@@ -18,5 +18,8 @@
     "agent",
     "memory",
     "cli"
-  ]
+  ],
+  "scripts": {
+    "test": "node --test"
+  }
 }

package/test/context.test.mjs

@@ -0,0 +1,97 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { run, tmpdir, initRepo, read } from './helpers.mjs';
+
+function seed(home, repo, text) {
+  const r = run(['add', text, '--project'], { amrHome: home, cwd: repo });
+  assert.equal(r.status, 0, r.stderr);
+}
+
+test('context in a non-git dir shows global memory only', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  run(['add', 'prefers tabs'], { amrHome: home });
+  const r = run(['context'], { amrHome: home, cwd: tmpdir() });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /prefers tabs/);
+});
+
+test('context in a repo shows its project memory', () => {
+  const home = tmpdir();
+  const repo = initRepo(path.join(tmpdir(), 'app'), 'https://github.com/acme/app.git');
+  run(['ensure'], { amrHome: home });
+  seed(home, repo, 'app uses redis cache');
+  const r = run(['context'], { amrHome: home, cwd: repo });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /app uses redis cache/);
+});
+
+test('link attaches a sibling project transitively; private blocks transitive only', () => {
+  const home = tmpdir();
+  const base = tmpdir();
+  const repoA = initRepo(path.join(base, 'a'), 'https://github.com/acme/a.git');
+  const repoB = initRepo(path.join(base, 'b'), 'https://github.com/acme/b.git');
+  const repoC = initRepo(path.join(base, 'c'), 'https://github.com/acme/c.git');
+  run(['ensure'], { amrHome: home });
+  seed(home, repoA, 'a uses sqlite');
+  seed(home, repoB, 'b uses kafka');
+  seed(home, repoC, 'c is a leaf');
+
+  // b links to a
+  const link = run(['link', 'a'], { amrHome: home, cwd: repoB });
+  assert.equal(link.status, 0);
+  const inB = run(['context'], { amrHome: home, cwd: repoB });
+  assert.match(inB.stdout, /a uses sqlite/);
+
+  // c links to b; a is private -> transitive refusal in c
+  run(['link', 'b'], { amrHome: home, cwd: repoC });
+  run(['policy', 'a', 'private', 'true'], { amrHome: home, cwd: repoA });
+  const inC = run(['context'], { amrHome: home, cwd: repoC });
+  assert.match(inC.stdout, /b uses kafka/);
+  assert.match(inC.stdout, /omitted by private policy/);
+  assert.ok(!inC.stdout.includes('a uses sqlite'));
+
+  // explicit --also still attaches the private project
+  const explicit = run(['context', '--also', 'a'], { amrHome: home, cwd: repoC });
+  assert.match(explicit.stdout, /a uses sqlite/);
+});
+
+test('unresolved link names surface a marker', () => {
+  const home = tmpdir();
+  const repo = initRepo(path.join(tmpdir(), 'solo'), 'https://github.com/acme/solo.git');
+  run(['ensure'], { amrHome: home });
+  seed(home, repo, 'solo entry');
+  run(['link', 'ghost-project'], { amrHome: home, cwd: repo });
+  const r = run(['context'], { amrHome: home, cwd: repo });
+  assert.match(r.stdout, /unresolved \(no memory file\): ghost-project/);
+});
+
+test('unlink removes the auto-attach', () => {
+  const home = tmpdir();
+  const base = tmpdir();
+  const repoA = initRepo(path.join(base, 'x1'), 'https://github.com/acme/x1.git');
+  const repoB = initRepo(path.join(base, 'y1'), 'https://github.com/acme/y1.git');
+  run(['ensure'], { amrHome: home });
+  seed(home, repoA, 'x1 fact');
+  seed(home, repoB, 'y1 fact');
+  run(['link', 'x1'], { amrHome: home, cwd: repoB });
+  assert.match(run(['context'], { amrHome: home, cwd: repoB }).stdout, /x1 fact/);
+  run(['unlink', 'x1'], { amrHome: home, cwd: repoB });
+  assert.ok(!run(['context'], { amrHome: home, cwd: repoB }).stdout.includes('x1 fact'));
+});
+
+test('noglobal policy suppresses global memory for that repo', () => {
+  const home = tmpdir();
+  const repo = initRepo(path.join(tmpdir(), 'iso'), 'https://github.com/acme/iso.git');
+  run(['ensure'], { amrHome: home });
+  run(['add', 'global pref'], { amrHome: home });
+  seed(home, repo, 'iso fact');
+  const before = run(['context'], { amrHome: home, cwd: repo });
+  assert.match(before.stdout, /global pref/);
+  run(['policy', 'iso', 'noglobal', 'true'], { amrHome: home, cwd: repo });
+  const after = run(['context'], { amrHome: home, cwd: repo });
+  assert.match(after.stdout, /iso fact/);
+  assert.ok(!after.stdout.includes('global pref'));
+});

package/test/core.test.mjs

@@ -0,0 +1,117 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { run, tmpdir, initRepo, read, entries } from './helpers.mjs';
+
+test('ensure creates repo, MEMORY.md with index, idempotent', () => {
+  const home = tmpdir();
+  const r1 = run(['ensure'], { amrHome: home });
+  assert.equal(r1.status, 0, r1.stderr);
+  const mem = read(path.join(home, 'MEMORY.md'));
+  assert.match(mem, /# Memory/);
+  assert.match(mem, /## Index/);
+  assert.ok(fs.existsSync(path.join(home, '.git')));
+  const r2 = run(['ensure'], { amrHome: home });
+  assert.equal(r2.status, 0);
+});
+
+test('ensure refuses a non-empty non-repo dir', () => {
+  const home = tmpdir();
+  fs.writeFileSync(path.join(home, 'junk.txt'), 'x');
+  const r = run(['ensure'], { amrHome: home });
+  assert.notEqual(r.status, 0);
+});
+
+test('add appends a dated bullet to MEMORY.md', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  const r = run(['add', 'prefers bullet points'], { amrHome: home });
+  assert.equal(r.status, 0, r.stderr);
+  const lines = entries(path.join(home, 'MEMORY.md'));
+  assert.ok(lines.some((l) => l.includes('prefers bullet points')));
+  assert.match(lines[lines.length - 1], /\[added: \d{4}-\d{2}-\d{2}/);
+});
+
+test('add refuses secret-shaped text; --allow-secret overrides', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  const r = run(['add', 'api key is ghp_abcdefghijklmnop1234567890'], { amrHome: home });
+  assert.notEqual(r.status, 0);
+  assert.ok(!(read(path.join(home, 'MEMORY.md')) || '').includes('ghp_'));
+  const r2 = run(['add', 'api key is ghp_abcdefghijklmnop1234567890', '--allow-secret'], {
+    amrHome: home,
+  });
+  assert.equal(r2.status, 0);
+});
+
+test('add skips near-duplicates', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  run(['add', 'uses dark mode'], { amrHome: home });
+  const r = run(['add', 'uses dark mode'], { amrHome: home });
+  assert.equal(r.status, 0);
+  assert.equal(
+    entries(path.join(home, 'MEMORY.md')).filter((l) => l.includes('dark mode')).length,
+    1
+  );
+});
+
+test('add --file writes a topic file and indexes it', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  const r = run(['add', 'prefers pnpm', '--file', 'tooling'], { amrHome: home });
+  assert.equal(r.status, 0);
+  assert.ok(read(path.join(home, 'tooling.md')).includes('prefers pnpm'));
+  assert.match(read(path.join(home, 'MEMORY.md')), /\[\[tooling\]\]/);
+});
+
+test('update replaces an entry and keeps metadata', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  run(['add', 'port is 3000'], { amrHome: home });
+  const r = run(['update', 'port is', 'port is 8080'], { amrHome: home });
+  assert.equal(r.status, 0, r.stderr);
+  const mem = read(path.join(home, 'MEMORY.md'));
+  assert.match(mem, /port is 8080/);
+  assert.match(mem, /updated: \d{4}-\d{2}-\d{2}/);
+  assert.ok(!mem.includes('port is 3000'));
+});
+
+test('update errors on zero and multiple matches', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  run(['add', 'alpha entry'], { amrHome: home });
+  run(['add', 'alpha two'], { amrHome: home });
+  const none = run(['update', 'no-such-text', 'x'], { amrHome: home });
+  assert.notEqual(none.status, 0);
+  const many = run(['update', 'alpha', 'x'], { amrHome: home });
+  assert.notEqual(many.status, 0);
+});
+
+test('search finds entries; index rebuilds', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  run(['add', 'kokoro for tts'], { amrHome: home });
+  const r = run(['search', 'kokoro'], { amrHome: home });
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /kokoro/);
+  const ri = run(['index'], { amrHome: home });
+  assert.equal(ri.status, 0);
+});
+
+test('add --project routes to projects/<slug>.md', () => {
+  const home = tmpdir();
+  const repo = initRepo(path.join(tmpdir(), 'myproj'), 'https://github.com/acme/myproj.git');
+  run(['ensure'], { amrHome: home });
+  const r = run(['add', 'uses pnpm workspaces', '--project'], {
+    amrHome: home,
+    cwd: repo,
+  });
+  assert.equal(r.status, 0, r.stderr);
+  const projDir = path.join(home, 'projects');
+  const files = fs.readdirSync(projDir);
+  assert.equal(files.length, 1);
+  assert.match(files[0], /^myproj-[0-9a-f]{6}\.md$/);
+  assert.ok(read(path.join(projDir, files[0])).includes('pnpm workspaces'));
+});

package/test/dream.test.mjs

@@ -0,0 +1,55 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { run, tmpdir, read, entries } from './helpers.mjs';
+
+function seeded() {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  return home;
+}
+
+test('dream --json returns a health report', () => {
+  const home = seeded();
+  run(['add', 'one fact'], { amrHome: home });
+  const r = run(['dream', '--json'], { amrHome: home });
+  assert.equal(r.status, 0, r.stderr);
+  const j = JSON.parse(r.stdout);
+  assert.equal(typeof j.stats.entries, 'number');
+  assert.ok(Array.isArray(j.exactDups));
+});
+
+test('dream --fix dedupes repeated entries', () => {
+  const home = seeded();
+  const mem = path.join(home, 'MEMORY.md');
+  // bypass near-dup skip by writing raw duplicates
+  fs.appendFileSync(mem, '- duplicate line [added: 2026-01-01]\n');
+  fs.appendFileSync(mem, '- duplicate line [added: 2026-01-02]\n');
+  const r = run(['dream', '--fix'], { amrHome: home });
+  assert.equal(r.status, 0, r.stderr);
+  const count = entries(mem).filter((l) => l.includes('duplicate line')).length;
+  assert.equal(count, 1);
+});
+
+test('dream --compact --keep archives overflow entries', () => {
+  const home = seeded();
+  for (let i = 0; i < 5; i++) run(['add', `entry number ${i}`], { amrHome: home });
+  const r = run(['dream', '--fix', '--compact', '--keep', '2'], { amrHome: home });
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(entries(path.join(home, 'MEMORY.md')).length <= 2 + 1); // +index tolerance
+  const arch = fs.readdirSync(path.join(home, 'archive'));
+  assert.ok(arch.length > 0);
+});
+
+test('dream --if-stale no-ops right after a dream', () => {
+  const home = seeded();
+  run(['add', 'stale check'], { amrHome: home });
+  run(['dream', '--fix'], { amrHome: home });
+  const r = run(['dream', '--if-stale', '30', '--json'], { amrHome: home });
+  assert.equal(r.status, 0, r.stderr);
+  // second run should not rewrite the tree
+  const mem1 = read(path.join(home, 'MEMORY.md'));
+  run(['dream', '--if-stale', '30', '--fix'], { amrHome: home });
+  assert.equal(read(path.join(home, 'MEMORY.md')), mem1);
+});

package/test/harvest-install.test.mjs

@@ -0,0 +1,86 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { run, tmpdir, read } from './helpers.mjs';
+
+test('harvest --extract pulls user messages from transcript fixtures', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  const fakeHome = tmpdir();
+  const sessDir = path.join(fakeHome, '.claude', 'projects', 'myrepo');
+  fs.mkdirSync(sessDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(sessDir, 'session-1.jsonl'),
+    [
+      JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: 'harvest this durable sentence please' }] } }),
+      JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: '<system-reminder>injected noise</system-reminder>' }] } }),
+      JSON.stringify({ role: 'assistant', content: [{ type: 'text', text: 'assistant reply not user' }] }),
+    ].join('\n')
+  );
+  const r = run(['harvest', '--days', '7', '--extract'], { amrHome: home, fakeHome });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /harvest this durable sentence/);
+  assert.ok(!r.stdout.includes('injected noise'));
+  assert.ok(!r.stdout.includes('assistant reply'));
+});
+
+test('install --host bogus errors and lists valid hosts', () => {
+  const home = tmpdir();
+  const r = run(['install', '--host', 'bogus'], { amrHome: home, fakeHome: tmpdir() });
+  assert.notEqual(r.status, 0);
+  assert.match(r.stdout + r.stderr, /bogus/);
+});
+
+test('uninstall removes only amr wiring and preserves user config', () => {
+  const home = tmpdir();
+  const fakeHome = tmpdir();
+  run(['ensure'], { amrHome: home });
+  // codex with pre-existing user config
+  const codexDir = path.join(fakeHome, '.codex');
+  fs.mkdirSync(codexDir, { recursive: true });
+  fs.writeFileSync(path.join(codexDir, 'config.toml'), 'model = "o4-mini"\n');
+  // cursor with a foreign hook that must survive
+  const cursorDir = path.join(fakeHome, '.cursor');
+  fs.mkdirSync(cursorDir, { recursive: true });
+  const cursorHooks = path.join(cursorDir, 'hooks.json');
+  fs.writeFileSync(
+    cursorHooks,
+    JSON.stringify({
+      version: 1,
+      hooks: { sessionStart: [{ command: 'echo user-hook' }] },
+    })
+  );
+
+  run(['install', '--host', 'codex,cursor'], { amrHome: home, fakeHome });
+  assert.match(read(path.join(codexDir, 'config.toml')), /mcp_servers\.agent-memory/);
+  assert.match(read(cursorHooks), /amr\.mjs/);
+
+  const r = run(['uninstall', '--host', 'codex,cursor'], { amrHome: home, fakeHome });
+  assert.equal(r.status, 0, r.stderr);
+
+  // ours removed
+  assert.ok(!fs.existsSync(path.join(codexDir, 'AGENTS.md'))); // file was entirely ours
+  const toml = read(path.join(codexDir, 'config.toml'));
+  assert.ok(!toml.includes('mcp_servers.agent-memory'));
+  const hooks = JSON.parse(read(cursorHooks));
+  // theirs preserved
+  assert.ok(toml.includes('o4-mini'));
+  assert.ok(hooks.hooks.sessionStart.some((h) => h.command === 'echo user-hook'));
+  assert.ok(!JSON.stringify(hooks).includes('amr.mjs'));
+});
+
+test('install --host codex writes rules + mcp into a fake home, idempotent', () => {
+  const home = tmpdir();
+  const fakeHome = tmpdir();
+  run(['ensure'], { amrHome: home });
+  const r1 = run(['install', '--host', 'codex'], { amrHome: home, fakeHome });
+  assert.equal(r1.status, 0, r1.stderr);
+  const agents = read(path.join(fakeHome, '.codex', 'AGENTS.md')) || '';
+  assert.match(agents, /agent-memory/);
+  const toml = read(path.join(fakeHome, '.codex', 'config.toml')) || '';
+  assert.match(toml, /mcp_servers\.agent-memory/);
+  const r2 = run(['install', '--host', 'codex'], { amrHome: home, fakeHome });
+  assert.equal(r2.status, 0);
+  assert.match(r2.stdout + r2.stderr, /unchanged|already/);
+});

package/test/helpers.mjs

@@ -0,0 +1,74 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const CLI = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'amr.mjs'
+);
+
+export function tmpdir(prefix = 'amrtest-') {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+// Run the real CLI as a subprocess. Every test gets an isolated
+// AMR_HOME; fakeHome additionally redirects HOME/USERPROFILE for
+// adapters and harvest sources that resolve paths off the home dir.
+export function run(args, { cwd, amrHome, fakeHome, env } = {}) {
+  const e = {
+    ...process.env,
+    AMR_HOME: amrHome,
+    // Redirect every home-ish env var so harvest/adapters can't touch
+    // the real user profile during tests (APPDATA leaks otherwise).
+    ...(fakeHome
+      ? {
+          HOME: fakeHome,
+          USERPROFILE: fakeHome,
+          APPDATA: path.join(fakeHome, 'AppData', 'Roaming'),
+          LOCALAPPDATA: path.join(fakeHome, 'AppData', 'Local'),
+          HOMEDRIVE: path.parse(fakeHome).root.replace(/[\\/]+$/, ''),
+          HOMEPATH: fakeHome.slice(path.parse(fakeHome).root.length),
+          XDG_CONFIG_HOME: path.join(fakeHome, '.config'),
+        }
+      : {}),
+    ...env,
+  };
+  const r = spawnSync(process.execPath, [CLI, ...args], {
+    encoding: 'utf8',
+    cwd,
+    env: e,
+    timeout: 30_000,
+  });
+  return { status: r.status ?? 1, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+export function git(dir, args) {
+  const r = spawnSync('git', args, { cwd: dir, encoding: 'utf8' });
+  if (r.status !== 0)
+    throw new Error(`git ${args[0]} failed: ${r.stderr || r.stdout}`);
+  return r.stdout.trim();
+}
+
+export function initRepo(dir, remoteUrl) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(dir, ['init', '-b', 'main']);
+  if (remoteUrl) git(dir, ['remote', 'add', 'origin', remoteUrl]);
+  git(dir, [
+    '-c', 'user.email=test@lucid-mem.dev',
+    '-c', 'user.name=amr-test',
+    'commit', '--allow-empty', '-m', 'init',
+  ]);
+  return dir;
+}
+
+export function read(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
+export function entries(file) {
+  const t = read(file) || '';
+  return t.split('\n').filter((l) => l.startsWith('- '));
+}

package/test/serve.test.mjs

@@ -0,0 +1,41 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { tmpdir, run, CLI } from './helpers.mjs';
+
+// serve is a stdio JSON-RPC server: newline-delimited requests.
+function rpc(home, messages, cwd) {
+  const input = messages.map((m) => JSON.stringify(m)).join('\n') + '\n';
+  const r = spawnSync(process.execPath, [CLI, 'serve'],
+    { input, encoding: 'utf8', env: { ...process.env, AMR_HOME: home }, cwd, timeout: 15_000 }
+  );
+  return (r.stdout || '')
+    .split('\n')
+    .filter(Boolean)
+    .map((l) => {
+      try { return JSON.parse(l); } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+test('serve answers tools/list with the memory tools', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  const out = rpc(home, [{ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }]);
+  const resp = out.find((m) => m.id === 1);
+  assert.ok(resp, 'no response to tools/list');
+  const names = resp.result.tools.map((t) => t.name);
+  for (const t of ['memory_context', 'memory_add', 'memory_search', 'memory_update'])
+    assert.ok(names.includes(t), `missing tool ${t}`);
+});
+
+test('serve memory_context returns the digest as content text', () => {
+  const home = tmpdir();
+  run(['ensure'], { amrHome: home });
+  run(['add', 'mcp round-trip fact'], { amrHome: home });
+  const out = rpc(home, [
+    { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'memory_context', arguments: {} } },
+  ]);
+  const resp = out.find((m) => m.id === 2);
+  assert.ok(resp?.result?.content?.[0]?.text?.includes('mcp round-trip fact'));
+});