feat(memory): add registerMemoryCommand for mosaic memory CLI surface

Adds mosaic memory CLI with four subcommands: search, stats,
insights list, and preferences list. Commands accept --db flag
(or MEMORY_DB_URL/DATABASE_URL env) to connect to pgvector or
keyword adapter. Smoke tests verify command wiring without DB.

Task: CU-05-04

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/plans/gateway-token-recovery.md

@@ -1,193 +0,0 @@
-# Gateway Admin Token Recovery — Implementation Plan
-
-**Mission:** `cli-unification-20260404`
-**Task:** `CU-03-01` (planning only — no runtime code changes)
-**Status:** Design locked (Session 1) — BetterAuth cookie-based recovery
-
----
-
-## 1. Problem Statement
-
-The gateway installer strands operators when the admin user exists but the admin
-API token is missing. Concrete trigger:
-
-- `~/.config/mosaic/gateway/meta.json` was deleted / regenerated.
-- The installer was re-run after a previous successful bootstrap.
-
-Flow today (`packages/mosaic/src/commands/gateway/install.ts:375-400`):
-
-1. `bootstrapFirstUser` hits `GET /api/bootstrap/status`.
-2. Server returns `needsSetup: false` because `users` count > 0.
-3. Installer logs `Admin user already exists — skipping setup. (No admin token on file — sign in via the web UI to manage tokens.)` and returns.
-4. The operator now has:
-   - No token in `meta.json`.
-   - No CLI path to mint a new one (`mosaic gateway <anything>` that needs the token fails).
-   - `POST /api/bootstrap/setup` locked out — it only runs when `users` count is zero (`apps/gateway/src/admin/bootstrap.controller.ts:34-37`).
-   - `POST /api/admin/tokens` gated by `AdminGuard` — requires either a bearer token (which they don't have) or a BetterAuth session (which they don't have in the CLI).
-
-Dead end. The web UI is the only escape hatch today, and for headless installs even that may be inaccessible.
-
-## 2. Design Summary
-
-The BetterAuth session cookie is the authority. The operator runs
-`mosaic gateway login` to sign in with email/password, which persists a session
-cookie via `saveSession` (reusing `packages/mosaic/src/auth.ts`). With a valid
-session, `mosaic gateway config recover-token` (stranded-operator entry point)
-and `mosaic gateway config rotate-token` call the existing authenticated admin
-endpoint `POST /api/admin/tokens` using the cookie, then persist the returned
-plaintext to `meta.json` via `writeMeta`. **No new server endpoints are
-required** — `AdminGuard` already accepts BetterAuth session cookies via its
-`validateSession` path (`apps/gateway/src/admin/admin.guard.ts:90-120`).
-
-## 3. Surface Contract
-
-### 3.1 Server — no changes required
-
-| Endpoint                       | Status          | Notes                                                                                                                    |
-| ------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `POST /api/admin/tokens`       | **Reuse as-is** | `admin-tokens.controller.ts:46-72`. Returns `{ id, label, scope, expiresAt, lastUsedAt, createdAt, plaintext }`.         |
-| `GET  /api/admin/tokens`       | **Reuse**       | Useful for `mosaic gateway config tokens list` follow-on (out of scope for CU-03-01, but trivial once auth path exists). |
-| `DELETE /api/admin/tokens/:id` | **Reuse**       | Used by rotate flow for optional old-token revocation.                                                                   |
-| `POST /api/bootstrap/setup`    | **Unchanged**   | Remains first-user-only; not part of recovery.                                                                           |
-
-`AdminGuard.validateSession` takes BetterAuth cookies from `request.raw.headers`
-via `fromNodeHeaders` and calls `auth.api.getSession({ headers })`. It also
-enforces `role === 'admin'`. This is exactly the path the CLI will hit with
-`Cookie: better-auth.session_token=...`.
-
-**Confirmed feasible** during CU-03-01 investigation.
-
-### 3.2 `mosaic gateway login`
-
-Thin wrapper over the existing top-level `mosaic login`
-(`packages/mosaic/src/cli.ts:42-76`) with gateway-specific defaults pulled from
-`readMeta()`.
-
-| Aspect              | Behavior                                                                                                                        |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Default gateway URL | `http://${meta.host}:${meta.port}` from `readMeta()`, fallback `http://localhost:14242`.                                        |
-| Flow                | Prompt email + password -> `signIn()` -> `saveSession()`.                                                                       |
-| Persistence         | `~/.mosaic/session.json` via existing `saveSession` (7-day expiry).                                                             |
-| Decision            | **Thin wrapper**, not alias. Rationale: defaults differ (reads `meta.json`), and discoverability under `mosaic gateway --help`. |
-| Implementation      | Share the sign-in logic by extracting a small `runLogin(gatewayUrl, email?, password?)` helper; both commands call it.          |
-
-### 3.3 `mosaic gateway config rotate-token`
-
-| Aspect       | Behavior                                                                                                                                                                                                                             |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Precondition | Valid session (via `loadSession` + `validateSession`). On failure, print: "Not signed in — run `mosaic gateway login`" and exit non-zero.                                                                                            |
-| Request      | `POST ${gatewayUrl}/api/admin/tokens` with header `Cookie: <session>`, body `{ label: "CLI token (rotated YYYY-MM-DD)" }`.                                                                                                           |
-| On success   | Read meta via `readMeta()`, set `meta.adminToken = plaintext`, `writeMeta(meta)`. Print the token banner (reuse `printAdminTokenBanner` shape).                                                                                      |
-| Old token    | **Optional `--revoke-old`** flag. When set and a previous `meta.adminToken` existed, call `DELETE /api/admin/tokens/:id` after rotation. Requires listing first to find the id; punt to CU-03-02 decision. Document as nice-to-have. |
-| Exit codes   | `0` success; `1` network error; `2` auth error; `3` server rejection.                                                                                                                                                                |
-
-### 3.4 `mosaic gateway config recover-token`
-
-Superset of `rotate-token` with an inline login nudge — the "stranded operator"
-entry point.
-
-| Step | Action                                                                                                                           |
-| ---- | -------------------------------------------------------------------------------------------------------------------------------- |
-| 1    | `readMeta()` — derive gateway URL. If meta is missing entirely, fall back to `--gateway` flag or default.                        |
-| 2    | `loadSession(gatewayUrl)` then `validateSession`. If either fails, prompt inline: email + password -> `signIn` -> `saveSession`. |
-| 3    | `POST /api/admin/tokens` with cookie, label `"Recovered via CLI YYYY-MM-DDTHH:mm"`.                                              |
-| 4    | Persist plaintext to `meta.json` via `writeMeta`.                                                                                |
-| 5    | Print the token banner and next-steps hints (e.g. `mosaic gateway status`).                                                      |
-| 6    | Exit `0`.                                                                                                                        |
-
-Key property: this command is **runnable with nothing but email+password in hand**.
-It assumes the gateway is up but assumes no prior CLI session state.
-
-### 3.5 File touch list (for CU-03-02..05 execution)
-
-| File                                                  | Change                                                                                     |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `packages/mosaic/src/commands/gateway.ts`             | Register `login`, `config recover-token`, `config rotate-token` subcommands under `gw`.    |
-| `packages/mosaic/src/commands/gateway/config.ts`      | Add `runRecoverToken`, `runRotateToken` handlers; export from module.                      |
-| `packages/mosaic/src/commands/gateway/login.ts` (new) | Thin wrapper calling shared `runLogin` helper with meta-derived default URL.               |
-| `packages/mosaic/src/auth.ts`                         | No change expected. Possibly export a `requireSession(gatewayUrl)` helper (reuse pattern). |
-| `packages/mosaic/src/commands/gateway/install.ts`     | `bootstrapFirstUser` branch: "user exists, no token" -> offer recovery (see Section 4).    |
-
-## 4. Installer Fix (CU-03-06 preview)
-
-Current stranding point is `install.ts:388-395`. The fix:
-
-```
-if (!status.needsSetup) {
-  if (meta.adminToken) {
-    // unchanged — happy path
-  } else {
-    // NEW: prompt "Admin exists but no token on file. Recover now? [Y/n]"
-    // If yes -> call runRecoverToken(gatewayUrl) inline (interactive):
-    //   - prompt email + password
-    //   - signIn -> saveSession
-    //   - POST /api/admin/tokens
-    //   - writeMeta(meta) with returned plaintext
-    //   - print banner
-    // If no -> print the current stranded message but include:
-    //   "Run `mosaic gateway config recover-token` when ready."
-  }
-}
-```
-
-Shape notes (actual code lands in CU-03-06):
-
-- Extract the recovery body so it can be called **both** from the standalone
-  command and from `bootstrapFirstUser` without duplicating prompts.
-- Reuse the same `rl` readline interface already open in `bootstrapFirstUser`
-  for the inline prompts.
-- Preserve non-interactive behavior: if `process.stdin.isTTY` is false, skip the
-  prompt and emit the "run recover-token" hint only.
-
-## 5. Test Strategy (CU-03-07 scope)
-
-### 5.1 Happy paths
-
-| Command                               | Scenario                                         | Expected                                                 |
-| ------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- |
-| `mosaic gateway login`                | Valid creds                                      | `session.json` written, 7-day expiry, exit 0             |
-| `mosaic gateway config rotate-token`  | Valid session, server reachable                  | `meta.json` updated, banner printed, new token usable    |
-| `mosaic gateway config recover-token` | No session, valid creds, server reachable        | Prompts for creds, writes session + meta, exit 0         |
-| Installer inline recovery             | Re-run after `meta.json` wipe, operator says yes | Meta restored, banner printed, no manual CLI step needed |
-
-### 5.2 Error paths (must all produce actionable messages and non-zero exit)
-
-| Failure                           | Expected handling                                                                 |
-| --------------------------------- | --------------------------------------------------------------------------------- |
-| Invalid email/password            | BetterAuth 401 surfaced as "Sign-in failed: <server message>", exit 2             |
-| Expired stored session            | Recover command silently re-prompts; rotate command exits 2 with "run login" hint |
-| Gateway down / connection refused | "Could not reach gateway at <url>" exit 1                                         |
-| Server rejects token creation     | Print status + body excerpt, exit 3                                               |
-| Meta file missing (recover)       | Fall back to `--gateway` flag or default; warn that meta will be created          |
-| Non-admin user                    | `AdminGuard` 403 surfaced as "User is not an admin", exit 2                       |
-
-### 5.3 Integration test (recommended)
-
-Spin up gateway in test harness, create admin user via `/api/bootstrap/setup`,
-wipe `meta.json`, invoke `mosaic gateway config recover-token` programmatically,
-assert new `meta.adminToken` works against `GET /api/admin/tokens`.
-
-## 6. Risks & Open Questions
-
-| #   | Item                                                                                                                                                                                    | Severity | Mitigation                                                                                                     |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
-| 1   | `AdminGuard.validateSession` calls `getSession` with `fromNodeHeaders(request.raw.headers)`. CLI sends `Cookie:` header only. Confirm BetterAuth reads from `Cookie`, not `Set-Cookie`. | Low      | Confirmed — `mosaic login` + `mosaic tui` already use this flow successfully (`cli.ts:137-181`).               |
-| 2   | Session cookie local expiry (7d) vs BetterAuth server-side expiry may drift.                                                                                                            | Low      | `validateSession` hits `get-session`; handle 401 by re-prompting.                                              |
-| 3   | Label collision / unbounded token growth if operators run `recover-token` repeatedly.                                                                                                   | Low      | Include ISO timestamp in label. Optional `--revoke-old` in CU-03-02. Add `tokens list/prune` later.            |
-| 4   | `mosaic login` exists at top level and `mosaic gateway login` is a wrapper — risk of confusion.                                                                                         | Low      | Document that `gateway login` is the preferred entry for gateway operators; top-level stays for compatibility. |
-| 5   | `meta.json` write is not atomic. Crash between token creation and `writeMeta` leaves an orphan token server-side with no plaintext on disk.                                             | Medium   | Accept for now — re-running `recover-token` mints a fresh token. Document as known limitation.                 |
-| 6   | Non-TTY installer runs (CI, headless provisioners) cannot prompt for creds interactively.                                                                                               | Medium   | Installer inline recovery must skip prompt when `!process.stdin.isTTY`; emit the recover-token hint.           |
-| 7   | If `BETTER_AUTH_SECRET` rotates between login and recover, the session cookie is invalid — user must re-login. Acceptable but surface a clear error.                                    | Low      | Error handler maps 401 on recover -> "Session invalid; re-run `mosaic gateway login`".                         |
-| 8   | No MFA today. When MFA lands, BetterAuth sign-in will return a challenge, not a cookie — recovery UX will need a second prompt step.                                                    | Future   | Out of scope for this mission. Flag for future CLI work.                                                       |
-
-## 7. Downstream Task Hooks
-
-| Task     | Scope                                                                      |
-| -------- | -------------------------------------------------------------------------- |
-| CU-03-02 | Implement `mosaic gateway login` wrapper + shared `runLogin` extraction.   |
-| CU-03-03 | Implement `mosaic gateway config rotate-token`.                            |
-| CU-03-04 | Implement `mosaic gateway config recover-token`.                           |
-| CU-03-05 | Wire commands into `gateway.ts` registration, update `--help` copy.        |
-| CU-03-06 | Installer inline recovery hook in `bootstrapFirstUser`.                    |
-| CU-03-07 | Tests per Section 5.                                                       |
-| CU-03-08 | Docs: update gateway install README + operator runbook with recovery flow. |

packages/brain/package.json

@@ -22,8 +22,7 @@
   },
   "dependencies": {
     "@mosaicstack/db": "workspace:^",
-    "@mosaicstack/types": "workspace:*",
+    "@mosaicstack/types": "workspace:*"
-    "commander": "^13.0.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

packages/brain/src/cli.spec.ts

@@ -1,95 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { Command } from 'commander';
-import { registerBrainCommand } from './cli.js';
-
-/**
- * Smoke test: verifies the command tree is correctly registered.
- * No database connection is opened — we only inspect Commander metadata.
- */
-describe('registerBrainCommand', () => {
-  function buildProgram(): Command {
-    const program = new Command('mosaic');
-    // Prevent Commander from calling process.exit on parse errors during tests.
-    program.exitOverride();
-    registerBrainCommand(program);
-    return program;
-  }
-
-  it('registers a top-level "brain" command', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain');
-    expect(brainCmd).toBeDefined();
-  });
-
-  it('registers "brain projects" with "list" and "create" subcommands', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const projectsCmd = brainCmd.commands.find((c) => c.name() === 'projects');
-    expect(projectsCmd).toBeDefined();
-
-    const subNames = projectsCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('list');
-    expect(subNames).toContain('create');
-  });
-
-  it('registers "brain missions" with "list" subcommand', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const missionsCmd = brainCmd.commands.find((c) => c.name() === 'missions');
-    expect(missionsCmd).toBeDefined();
-
-    const subNames = missionsCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('list');
-  });
-
-  it('registers "brain tasks" with "list" subcommand', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const tasksCmd = brainCmd.commands.find((c) => c.name() === 'tasks');
-    expect(tasksCmd).toBeDefined();
-
-    const subNames = tasksCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('list');
-  });
-
-  it('registers "brain conversations" with "list" subcommand', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const conversationsCmd = brainCmd.commands.find((c) => c.name() === 'conversations');
-    expect(conversationsCmd).toBeDefined();
-
-    const subNames = conversationsCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('list');
-  });
-
-  it('"brain projects list" accepts --db and --limit options', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const projectsCmd = brainCmd.commands.find((c) => c.name() === 'projects')!;
-    const listCmd = projectsCmd.commands.find((c) => c.name() === 'list')!;
-
-    const optionNames = listCmd.options.map((o) => o.long);
-    expect(optionNames).toContain('--db');
-    expect(optionNames).toContain('--limit');
-  });
-
-  it('"brain missions list" accepts --project option', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const missionsCmd = brainCmd.commands.find((c) => c.name() === 'missions')!;
-    const listCmd = missionsCmd.commands.find((c) => c.name() === 'list')!;
-
-    const optionNames = listCmd.options.map((o) => o.long);
-    expect(optionNames).toContain('--project');
-  });
-
-  it('"brain tasks list" accepts --project option', () => {
-    const program = buildProgram();
-    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
-    const tasksCmd = brainCmd.commands.find((c) => c.name() === 'tasks')!;
-    const listCmd = tasksCmd.commands.find((c) => c.name() === 'list')!;
-
-    const optionNames = listCmd.options.map((o) => o.long);
-    expect(optionNames).toContain('--project');
-  });
-});

packages/brain/src/cli.ts

@@ -1,142 +0,0 @@
-import type { Command } from 'commander';
-import { createDb, type DbHandle } from '@mosaicstack/db';
-import { createBrain } from './brain.js';
-
-/**
- * Build and attach the `brain` subcommand tree onto an existing Commander program.
- * Uses the caller's Command instance to avoid cross-package Commander version mismatches.
- */
-export function registerBrainCommand(parent: Command): void {
-  const brain = parent.command('brain').description('Inspect and manage brain data stores');
-
-  // ─── shared DB option helper ─────────────────────────────────────────────
-
-  function addDbOption(cmd: Command): Command {
-    return cmd.option(
-      '--db <connection-string>',
-      'PostgreSQL connection string (overrides MOSAIC_DB_URL)',
-    );
-  }
-
-  function resolveDb(opts: { db?: string }): ReturnType<typeof createBrain> {
-    const connectionString = opts.db ?? process.env['MOSAIC_DB_URL'];
-    if (!connectionString) {
-      console.error('No DB connection string provided. Pass --db <url> or set MOSAIC_DB_URL.');
-      process.exit(1);
-    }
-    const handle: DbHandle = createDb(connectionString);
-    return createBrain(handle.db);
-  }
-
-  // ─── projects ────────────────────────────────────────────────────────────
-
-  const projects = brain.command('projects').description('Manage projects');
-
-  addDbOption(
-    projects
-      .command('list')
-      .description('List all projects')
-      .option('--limit <n>', 'Maximum number of results', '50'),
-  ).action(async (opts: { db?: string; limit: string }) => {
-    const b = resolveDb(opts);
-    const limit = parseInt(opts.limit, 10);
-    const rows = await b.projects.findAll();
-    const sliced = rows.slice(0, limit);
-    if (sliced.length === 0) {
-      console.log('No projects found.');
-      return;
-    }
-    for (const p of sliced) {
-      console.log(`${p.id}  ${p.name}`);
-    }
-  });
-
-  addDbOption(
-    projects
-      .command('create <name>')
-      .description('Create a new project')
-      .requiredOption('--owner-id <id>', 'Owner user ID'),
-  ).action(async (name: string, opts: { db?: string; ownerId: string }) => {
-    const b = resolveDb(opts);
-    const created = await b.projects.create({
-      name,
-      ownerId: opts.ownerId,
-      ownerType: 'user',
-    });
-    console.log(`Created project: ${created.id}  ${created.name}`);
-  });
-
-  // ─── missions ────────────────────────────────────────────────────────────
-
-  const missions = brain.command('missions').description('Manage missions');
-
-  addDbOption(
-    missions
-      .command('list')
-      .description('List all missions')
-      .option('--limit <n>', 'Maximum number of results', '50')
-      .option('--project <id>', 'Filter by project ID'),
-  ).action(async (opts: { db?: string; limit: string; project?: string }) => {
-    const b = resolveDb(opts);
-    const limit = parseInt(opts.limit, 10);
-    const rows = opts.project
-      ? await b.missions.findByProject(opts.project)
-      : await b.missions.findAll();
-    const sliced = rows.slice(0, limit);
-    if (sliced.length === 0) {
-      console.log('No missions found.');
-      return;
-    }
-    for (const m of sliced) {
-      console.log(`${m.id}  ${m.name}`);
-    }
-  });
-
-  // ─── tasks ────────────────────────────────────────────────────────────────
-
-  const tasks = brain.command('tasks').description('Manage generic tasks');
-
-  addDbOption(
-    tasks
-      .command('list')
-      .description('List all tasks')
-      .option('--limit <n>', 'Maximum number of results', '50')
-      .option('--project <id>', 'Filter by project ID'),
-  ).action(async (opts: { db?: string; limit: string; project?: string }) => {
-    const b = resolveDb(opts);
-    const limit = parseInt(opts.limit, 10);
-    const rows = opts.project ? await b.tasks.findByProject(opts.project) : await b.tasks.findAll();
-    const sliced = rows.slice(0, limit);
-    if (sliced.length === 0) {
-      console.log('No tasks found.');
-      return;
-    }
-    for (const t of sliced) {
-      console.log(`${t.id}  ${t.title}  [${t.status}]`);
-    }
-  });
-
-  // ─── conversations ────────────────────────────────────────────────────────
-
-  const conversations = brain.command('conversations').description('Manage conversations');
-
-  addDbOption(
-    conversations
-      .command('list')
-      .description('List conversations for a user')
-      .option('--limit <n>', 'Maximum number of results', '50')
-      .requiredOption('--user-id <id>', 'User ID to scope the query'),
-  ).action(async (opts: { db?: string; limit: string; userId: string }) => {
-    const b = resolveDb(opts);
-    const limit = parseInt(opts.limit, 10);
-    const rows = await b.conversations.findAll(opts.userId);
-    const sliced = rows.slice(0, limit);
-    if (sliced.length === 0) {
-      console.log('No conversations found.');
-      return;
-    }
-    for (const c of sliced) {
-      console.log(`${c.id}  ${c.title ?? '(untitled)'}`);
-    }
-  });
-}

packages/brain/src/index.ts

@@ -1,5 +1,4 @@
 export { createBrain, type Brain } from './brain.js';
-export { registerBrainCommand } from './cli.js';
 export {
   createProjectsRepo,
   type ProjectsRepo,

packages/memory/package.json

@@ -25,6 +25,7 @@
     "@mosaicstack/db": "workspace:*",
     "@mosaicstack/storage": "workspace:*",
     "@mosaicstack/types": "workspace:*",
+    "commander": "^13.0.0",
     "drizzle-orm": "^0.45.1"
   },
   "devDependencies": {

packages/memory/src/cli.spec.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { registerMemoryCommand } from './cli.js';
+
+/**
+ * Smoke test — only verifies command wiring.
+ * Does NOT open a database connection.
+ */
+describe('registerMemoryCommand', () => {
+  function buildProgram(): Command {
+    const program = new Command('mosaic');
+    program.exitOverride(); // prevent process.exit during tests
+    registerMemoryCommand(program);
+    return program;
+  }
+
+  it('registers a "memory" subcommand', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory');
+    expect(memory).toBeDefined();
+  });
+
+  it('registers "memory search"', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const search = memory.commands.find((c) => c.name() === 'search');
+    expect(search).toBeDefined();
+  });
+
+  it('registers "memory stats"', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const stats = memory.commands.find((c) => c.name() === 'stats');
+    expect(stats).toBeDefined();
+  });
+
+  it('registers "memory insights list"', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const insights = memory.commands.find((c) => c.name() === 'insights');
+    expect(insights).toBeDefined();
+    const list = insights!.commands.find((c) => c.name() === 'list');
+    expect(list).toBeDefined();
+  });
+
+  it('registers "memory preferences list"', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const preferences = memory.commands.find((c) => c.name() === 'preferences');
+    expect(preferences).toBeDefined();
+    const list = preferences!.commands.find((c) => c.name() === 'list');
+    expect(list).toBeDefined();
+  });
+
+  it('"memory search" has --limit and --agent options', () => {
+    const program = buildProgram();
+    const memory = program.commands.find((c) => c.name() === 'memory')!;
+    const search = memory.commands.find((c) => c.name() === 'search')!;
+    const optNames = search.options.map((o) => o.long);
+    expect(optNames).toContain('--limit');
+    expect(optNames).toContain('--agent');
+  });
+});

packages/memory/src/cli.ts

@@ -0,0 +1,179 @@
+import type { Command } from 'commander';
+
+import type { MemoryAdapter } from './types.js';
+
+/**
+ * Build and return a connected MemoryAdapter from a connection string or
+ * the MEMORY_DB_URL / DATABASE_URL environment variable.
+ *
+ * For pgvector (postgres://...) the connection string is injected into
+ * DATABASE_URL so that PgVectorAdapter's internal createDb() picks it up.
+ *
+ * Throws with a human-readable message if no connection info is available.
+ */
+async function resolveAdapter(dbOption: string | undefined): Promise<MemoryAdapter> {
+  const connStr = dbOption ?? process.env['MEMORY_DB_URL'] ?? process.env['DATABASE_URL'];
+  if (!connStr) {
+    throw new Error(
+      'No database connection string provided. ' +
+        'Pass --db <connection-string> or set MEMORY_DB_URL / DATABASE_URL.',
+    );
+  }
+
+  // Lazy imports so the module loads cleanly without a live DB during smoke tests.
+  const { createMemoryAdapter, registerMemoryAdapter } = await import('./factory.js');
+
+  if (connStr.startsWith('postgres') || connStr.startsWith('pg')) {
+    // PgVectorAdapter reads DATABASE_URL via createDb() — inject it here.
+    process.env['DATABASE_URL'] = connStr;
+
+    const { PgVectorAdapter } = await import('./adapters/pgvector.js');
+    registerMemoryAdapter('pgvector', (cfg) => new PgVectorAdapter(cfg as never));
+    return createMemoryAdapter({ type: 'pgvector' });
+  }
+
+  // Keyword adapter backed by pglite storage; treat connStr as a data directory.
+  const { KeywordAdapter } = await import('./adapters/keyword.js');
+  const { createStorageAdapter, registerStorageAdapter } = await import('@mosaicstack/storage');
+  const { PgliteAdapter } = await import('@mosaicstack/storage');
+
+  registerStorageAdapter('pglite', (cfg) => new PgliteAdapter(cfg as never));
+
+  const storage = createStorageAdapter({ type: 'pglite', dataDir: connStr });
+
+  registerMemoryAdapter('keyword', (cfg) => new KeywordAdapter(cfg as never));
+  return createMemoryAdapter({ type: 'keyword', storage });
+}
+
+/**
+ * Register `memory` subcommands on an existing Commander program.
+ * Follows the registerQualityRails pattern from @mosaicstack/quality-rails.
+ */
+export function registerMemoryCommand(parent: Command): void {
+  const memory = parent.command('memory').description('Inspect and query the Mosaic memory layer');
+
+  // ── memory search <query> ──────────────────────────────────────────────
+  memory
+    .command('search <query>')
+    .description('Semantic search over insights')
+    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
+    .option('--limit <n>', 'Maximum number of results', '10')
+    .option('--agent <id>', 'Filter by agent / user ID')
+    .action(async (query: string, opts: { db?: string; limit: string; agent?: string }) => {
+      let adapter: MemoryAdapter | undefined;
+      try {
+        adapter = await resolveAdapter(opts.db);
+        const limit = parseInt(opts.limit, 10);
+        const userId = opts.agent ?? 'system';
+        const results = await adapter.searchInsights(userId, query, { limit });
+
+        if (results.length === 0) {
+          console.log('No insights found.');
+        } else {
+          for (const r of results) {
+            console.log(`[${r.id}] (score=${r.score.toFixed(3)}) ${r.content}`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+      } finally {
+        await adapter?.close();
+      }
+    });
+
+  // ── memory stats ──────────────────────────────────────────────────────
+  memory
+    .command('stats')
+    .description('Print memory tier info: adapter type, insight count, preference count')
+    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
+    .option('--agent <id>', 'User / agent ID scope for counts', 'system')
+    .action(async (opts: { db?: string; agent: string }) => {
+      let adapter: MemoryAdapter | undefined;
+      try {
+        adapter = await resolveAdapter(opts.db);
+
+        const adapterType = adapter.name;
+
+        const insightCount = await adapter
+          .searchInsights(opts.agent, '', { limit: 100000 })
+          .then((r) => r.length)
+          .catch(() => -1);
+
+        const prefCount = await adapter
+          .listPreferences(opts.agent)
+          .then((r) => r.length)
+          .catch(() => -1);
+
+        console.log(`adapter:     ${adapterType}`);
+        console.log(`insights:    ${insightCount === -1 ? 'unavailable' : String(insightCount)}`);
+        console.log(`preferences: ${prefCount === -1 ? 'unavailable' : String(prefCount)}`);
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+      } finally {
+        await adapter?.close();
+      }
+    });
+
+  // ── memory insights ───────────────────────────────────────────────────
+  const insightsCmd = memory.command('insights').description('Manage insights');
+
+  insightsCmd
+    .command('list')
+    .description('List recent insights')
+    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
+    .option('--limit <n>', 'Maximum number of results', '20')
+    .option('--agent <id>', 'User / agent ID scope', 'system')
+    .action(async (opts: { db?: string; limit: string; agent: string }) => {
+      let adapter: MemoryAdapter | undefined;
+      try {
+        adapter = await resolveAdapter(opts.db);
+        const limit = parseInt(opts.limit, 10);
+        const results = await adapter.searchInsights(opts.agent, '', { limit });
+
+        if (results.length === 0) {
+          console.log('No insights found.');
+        } else {
+          for (const r of results) {
+            console.log(`[${r.id}] ${r.content}`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+      } finally {
+        await adapter?.close();
+      }
+    });
+
+  // ── memory preferences ────────────────────────────────────────────────
+  const prefsCmd = memory.command('preferences').description('Manage stored preferences');
+
+  prefsCmd
+    .command('list')
+    .description('List stored preferences')
+    .option('--db <connection-string>', 'Database connection string (or set MEMORY_DB_URL)')
+    .option('--agent <id>', 'User / agent ID scope', 'system')
+    .option('--category <cat>', 'Filter by category')
+    .action(async (opts: { db?: string; agent: string; category?: string }) => {
+      let adapter: MemoryAdapter | undefined;
+      try {
+        adapter = await resolveAdapter(opts.db);
+        const prefs = await adapter.listPreferences(opts.agent, opts.category);
+
+        if (prefs.length === 0) {
+          console.log('No preferences found.');
+        } else {
+          for (const p of prefs) {
+            console.log(`[${p.category}] ${p.key} = ${JSON.stringify(p.value)}`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+      } finally {
+        await adapter?.close();
+      }
+    });
+}

packages/memory/src/index.ts

@@ -1,4 +1,5 @@
 export { createMemory, type Memory } from './memory.js';
+export { registerMemoryCommand } from './cli.js';
 export {
   createPreferencesRepo,
   type PreferencesRepo,

packages/mosaic/package.json

@@ -27,10 +27,10 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@mosaicstack/brain": "workspace:*",
     "@mosaicstack/config": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
     "@mosaicstack/macp": "workspace:*",
+    "@mosaicstack/memory": "workspace:*",
     "@mosaicstack/prdy": "workspace:*",
     "@mosaicstack/quality-rails": "workspace:*",
     "@mosaicstack/types": "workspace:*",

packages/mosaic/src/cli.ts

@@ -2,10 +2,9 @@
 
 import { createRequire } from 'module';
 import { Command } from 'commander';
-import { registerBrainCommand } from '@mosaicstack/brain';
 import { registerQualityRails } from '@mosaicstack/quality-rails';
+import { registerMemoryCommand } from '@mosaicstack/memory';
 import { registerAgentCommand } from './commands/agent.js';
-import { registerConfigCommand } from './commands/config.js';
 import { registerMissionCommand } from './commands/mission.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
@@ -35,23 +34,7 @@ try {
 
 const program = new Command();
 
-program
+program.name('mosaic').description('Mosaic Stack CLI').version(CLI_VERSION);
-  .name('mosaic')
-  .description('Mosaic Stack CLI')
-  .version(CLI_VERSION)
-  .configureHelp({ sortSubcommands: true })
-  .addHelpText(
-    'after',
-    `
-Command Groups:
-
-  Runtime:    tui, login, sessions
-  Gateway:    gateway
-  Framework:  agent, bootstrap, coord, doctor, init, launch, mission, prdy, seq, sync, upgrade, wizard, yolo
-  Platform:   update
-  Runtimes:   claude, codex, opencode, pi
-`,
-  );
 
 // ─── runtime launchers + framework commands ────────────────────────────
 
@@ -232,10 +215,7 @@ program
 
 // ─── sessions ───────────────────────────────────────────────────────────
 
-const sessionsCmd = program
+const sessionsCmd = program.command('sessions').description('Manage active agent sessions');
-  .command('sessions')
-  .description('Manage active agent sessions')
-  .configureHelp({ sortSubcommands: true });
 
 sessionsCmd
   .command('list')
@@ -331,22 +311,18 @@ registerGatewayCommand(program);
 
 registerAgentCommand(program);
 
-// ─── config ────────────────────────────────────────────────────────────
-
-registerConfigCommand(program);
-
 // ─── mission ───────────────────────────────────────────────────────────
 
 registerMissionCommand(program);
 
-// ─── brain ──────────────────────────────────────────────────────────────
-
-registerBrainCommand(program);
-
 // ─── quality-rails ──────────────────────────────────────────────────────
 
 registerQualityRails(program);
 
+// ─── memory ──────────────────────────────────────────────────────────────
+
+registerMemoryCommand(program);
+
 // ─── update ─────────────────────────────────────────────────────────────
 
 program

packages/mosaic/src/commands/config.spec.ts

@@ -1,289 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { Command } from 'commander';
-import { registerConfigCommand } from './config.js';
-
-// ── helpers ──────────────────────────────────────────────────────────────────
-
-/** Build a fresh Command tree with the config command registered. */
-function buildProgram(): Command {
-  const program = new Command();
-  program.exitOverride(); // prevent process.exit during tests
-  registerConfigCommand(program);
-  return program;
-}
-
-/** Locate the 'config' command registered on the root program. */
-function getConfigCmd(program: Command): Command {
-  const found = program.commands.find((c) => c.name() === 'config');
-  if (!found) throw new Error('config command not found');
-  return found;
-}
-
-// ── subcommand registration ───────────────────────────────────────────────────
-
-describe('registerConfigCommand', () => {
-  it('registers a "config" command on the program', () => {
-    const program = buildProgram();
-    const names = program.commands.map((c) => c.name());
-    expect(names).toContain('config');
-  });
-
-  it('registers exactly the five required subcommands', () => {
-    const program = buildProgram();
-    const config = getConfigCmd(program);
-    const subs = config.commands.map((c) => c.name()).sort();
-    expect(subs).toEqual(['edit', 'get', 'path', 'set', 'show']);
-  });
-});
-
-// ── mock config service ───────────────────────────────────────────────────────
-
-const mockSoul = {
-  agentName: 'TestBot',
-  roleDescription: 'test role',
-  communicationStyle: 'direct' as const,
-};
-const mockUser = { userName: 'Tester', pronouns: 'they/them', timezone: 'UTC' };
-const mockTools = { credentialsLocation: '/dev/null' };
-
-const mockSvc = {
-  readSoul: vi.fn().mockResolvedValue(mockSoul),
-  readUser: vi.fn().mockResolvedValue(mockUser),
-  readTools: vi.fn().mockResolvedValue(mockTools),
-  writeSoul: vi.fn().mockResolvedValue(undefined),
-  writeUser: vi.fn().mockResolvedValue(undefined),
-  writeTools: vi.fn().mockResolvedValue(undefined),
-  syncFramework: vi.fn().mockResolvedValue(undefined),
-  readAll: vi.fn().mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools }),
-  getValue: vi.fn().mockResolvedValue('TestBot'),
-  setValue: vi.fn().mockResolvedValue('OldBot'),
-  getConfigPath: vi
-    .fn()
-    .mockImplementation((section?: string) =>
-      section
-        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
-        : '/home/user/.config/mosaic',
-    ),
-  isInitialized: vi.fn().mockReturnValue(true),
-};
-
-// Mock the config-service module so commands use our mock.
-vi.mock('../config/config-service.js', () => ({
-  createConfigService: vi.fn(() => mockSvc),
-}));
-
-// Also mock child_process for the edit command.
-vi.mock('node:child_process', () => ({
-  spawnSync: vi.fn().mockReturnValue({ status: 0, error: undefined }),
-}));
-
-// ── config show ───────────────────────────────────────────────────────────────
-
-describe('config show', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(true);
-    mockSvc.readAll.mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools });
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('calls readAll() and prints a table by default', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'show']);
-    expect(mockSvc.readAll).toHaveBeenCalledOnce();
-    // Should have printed something
-    expect(consoleSpy).toHaveBeenCalled();
-  });
-
-  it('prints JSON when --format json is passed', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'show', '--format', 'json']);
-    expect(mockSvc.readAll).toHaveBeenCalledOnce();
-    // Verify JSON was logged
-    const allOutput = consoleSpy.mock.calls.map((c) => c[0] as string).join('\n');
-    expect(allOutput).toContain('"agentName"');
-  });
-});
-
-// ── config get ────────────────────────────────────────────────────────────────
-
-describe('config get', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(true);
-    mockSvc.getValue.mockResolvedValue('TestBot');
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('delegates to getValue() with the provided key', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'get', 'soul.agentName']);
-    expect(mockSvc.getValue).toHaveBeenCalledWith('soul.agentName');
-  });
-
-  it('prints the returned value', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'get', 'soul.agentName']);
-    expect(consoleSpy).toHaveBeenCalledWith('TestBot');
-  });
-});
-
-// ── config set ────────────────────────────────────────────────────────────────
-
-describe('config set', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(true);
-    mockSvc.setValue.mockResolvedValue('OldBot');
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('delegates to setValue() with key and value', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'set', 'soul.agentName', 'NewBot']);
-    expect(mockSvc.setValue).toHaveBeenCalledWith('soul.agentName', 'NewBot');
-  });
-
-  it('prints old and new values', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'set', 'soul.agentName', 'NewBot']);
-    const output = consoleSpy.mock.calls.map((c) => c[0] as string).join('\n');
-    expect(output).toContain('OldBot');
-    expect(output).toContain('NewBot');
-  });
-});
-
-// ── config path ───────────────────────────────────────────────────────────────
-
-describe('config path', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.getConfigPath.mockImplementation((section?: string) =>
-      section
-        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
-        : '/home/user/.config/mosaic',
-    );
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('prints the mosaicHome directory when no section is specified', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'path']);
-    expect(mockSvc.getConfigPath).toHaveBeenCalledWith();
-    expect(consoleSpy).toHaveBeenCalledWith('/home/user/.config/mosaic');
-  });
-
-  it('prints the section file path when --section is given', async () => {
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'path', '--section', 'soul']);
-    expect(mockSvc.getConfigPath).toHaveBeenCalledWith('soul');
-    expect(consoleSpy).toHaveBeenCalledWith('/home/user/.config/mosaic/SOUL.md');
-  });
-});
-
-// ── config edit ───────────────────────────────────────────────────────────────
-
-describe('config edit', () => {
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-  let spawnSyncMock: ReturnType<typeof vi.fn>;
-
-  beforeEach(async () => {
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(true);
-    mockSvc.readAll.mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools });
-    mockSvc.getConfigPath.mockImplementation((section?: string) =>
-      section
-        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
-        : '/home/user/.config/mosaic',
-    );
-
-    // Re-import to get the mock reference
-    const cp = await import('node:child_process');
-    spawnSyncMock = cp.spawnSync as ReturnType<typeof vi.fn>;
-    spawnSyncMock.mockReturnValue({ status: 0, error: undefined });
-  });
-
-  afterEach(() => {
-    consoleSpy.mockRestore();
-  });
-
-  it('calls spawnSync with the editor binary and config path', async () => {
-    process.env['EDITOR'] = 'nano';
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'edit']);
-    expect(spawnSyncMock).toHaveBeenCalledWith(
-      'nano',
-      ['/home/user/.config/mosaic'],
-      expect.objectContaining({ stdio: 'inherit' }),
-    );
-    delete process.env['EDITOR'];
-  });
-
-  it('falls back to "vi" when EDITOR is not set', async () => {
-    delete process.env['EDITOR'];
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'edit']);
-    expect(spawnSyncMock).toHaveBeenCalledWith('vi', expect.any(Array), expect.any(Object));
-  });
-
-  it('opens the section-specific file when --section is provided', async () => {
-    process.env['EDITOR'] = 'code';
-    const program = buildProgram();
-    await program.parseAsync(['node', 'mosaic', 'config', 'edit', '--section', 'soul']);
-    expect(spawnSyncMock).toHaveBeenCalledWith(
-      'code',
-      ['/home/user/.config/mosaic/SOUL.md'],
-      expect.any(Object),
-    );
-    delete process.env['EDITOR'];
-  });
-});
-
-// ── not-initialized guard ────────────────────────────────────────────────────
-
-describe('not-initialized guard', () => {
-  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
-    vi.clearAllMocks();
-    mockSvc.isInitialized.mockReturnValue(false);
-  });
-
-  afterEach(() => {
-    consoleErrorSpy.mockRestore();
-    mockSvc.isInitialized.mockReturnValue(true);
-  });
-
-  it('prints a helpful message when config is missing (show)', async () => {
-    const program = buildProgram();
-    // process.exit is intercepted; catch the resulting error from exitOverride
-    await expect(program.parseAsync(['node', 'mosaic', 'config', 'show'])).rejects.toThrow();
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('mosaic wizard'));
-  });
-});

packages/mosaic/src/commands/config.ts

@@ -1,206 +0,0 @@
-import { spawnSync } from 'node:child_process';
-import type { Command } from 'commander';
-import { createConfigService } from '../config/config-service.js';
-import { DEFAULT_MOSAIC_HOME } from '../constants.js';
-
-/**
- * Resolve mosaicHome from the MOSAIC_HOME env var or the default constant.
- */
-function getMosaicHome(): string {
-  return process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME;
-}
-
-/**
- * Guard: print an error and exit(1) if config has not been initialised.
- */
-function assertInitialized(svc: ReturnType<typeof createConfigService>): void {
-  if (!svc.isInitialized()) {
-    console.error('No config found — run `mosaic wizard` first.');
-    process.exit(1);
-  }
-}
-
-/**
- * Flatten a nested object into dotted-key rows for table display.
- */
-function flattenConfig(obj: Record<string, unknown>, prefix = ''): Array<[string, string]> {
-  const rows: Array<[string, string]> = [];
-  for (const [k, v] of Object.entries(obj)) {
-    const key = prefix ? `${prefix}.${k}` : k;
-    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
-      rows.push(...flattenConfig(v as Record<string, unknown>, key));
-    } else {
-      rows.push([key, v === undefined || v === null ? '' : String(v)]);
-    }
-  }
-  return rows;
-}
-
-/**
- * Print rows as a padded ASCII table.
- */
-function printTable(rows: Array<[string, string]>): void {
-  if (rows.length === 0) {
-    console.log('(no config values)');
-    return;
-  }
-  const maxKey = Math.max(...rows.map(([k]) => k.length));
-  const header = `${'Key'.padEnd(maxKey)}  Value`;
-  const divider = '-'.repeat(header.length);
-  console.log(header);
-  console.log(divider);
-  for (const [k, v] of rows) {
-    console.log(`${k.padEnd(maxKey)}  ${v}`);
-  }
-}
-
-export function registerConfigCommand(program: Command): void {
-  const cmd = program
-    .command('config')
-    .description('Manage Mosaic framework configuration')
-    .configureHelp({ sortSubcommands: true });
-
-  // ── config show ─────────────────────────────────────────────────────────
-
-  cmd
-    .command('show')
-    .description('Print the current resolved config')
-    .option('-f, --format <format>', 'Output format: table or json', 'table')
-    .action(async (opts: { format: string }) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-      assertInitialized(svc);
-
-      const config = await svc.readAll();
-
-      if (opts.format === 'json') {
-        console.log(JSON.stringify(config, null, 2));
-        return;
-      }
-
-      // Default: table
-      const rows = flattenConfig(config as unknown as Record<string, unknown>);
-      printTable(rows);
-    });
-
-  // ── config get <key> ────────────────────────────────────────────────────
-
-  cmd
-    .command('get <key>')
-    .description('Print a single config value (supports dotted keys, e.g. soul.agentName)')
-    .action(async (key: string) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-      assertInitialized(svc);
-
-      const value = await svc.getValue(key);
-      if (value === undefined) {
-        console.error(`Key "${key}" not found.`);
-        process.exit(1);
-      }
-      if (typeof value === 'object') {
-        console.log(JSON.stringify(value, null, 2));
-      } else {
-        console.log(String(value));
-      }
-    });
-
-  // ── config set <key> <value> ────────────────────────────────────────────
-
-  cmd
-    .command('set <key> <value>')
-    .description(
-      'Set a config value and persist (supports dotted keys, e.g. soul.agentName "Jarvis")',
-    )
-    .action(async (key: string, value: string) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-      assertInitialized(svc);
-
-      let previous: unknown;
-      try {
-        previous = await svc.setValue(key, value);
-      } catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-
-      const prevStr = previous === undefined ? '(unset)' : String(previous);
-      console.log(`${key}`);
-      console.log(`  old: ${prevStr}`);
-      console.log(`  new: ${value}`);
-    });
-
-  // ── config edit ─────────────────────────────────────────────────────────
-
-  cmd
-    .command('edit')
-    .description('Open the config directory in $EDITOR (or vi)')
-    .option('-s, --section <section>', 'Open a specific section file: soul | user | tools')
-    .action(async (opts: { section?: string }) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-      assertInitialized(svc);
-
-      const editor = process.env['EDITOR'] ?? 'vi';
-
-      let targetPath: string;
-      if (opts.section) {
-        const validSections = ['soul', 'user', 'tools'] as const;
-        if (!validSections.includes(opts.section as (typeof validSections)[number])) {
-          console.error(`Invalid section "${opts.section}". Choose: soul, user, tools`);
-          process.exit(1);
-        }
-        targetPath = svc.getConfigPath(opts.section as 'soul' | 'user' | 'tools');
-      } else {
-        targetPath = svc.getConfigPath();
-      }
-
-      const result = spawnSync(editor, [targetPath], { stdio: 'inherit' });
-
-      if (result.error) {
-        console.error(`Failed to open editor: ${result.error.message}`);
-        process.exit(1);
-      }
-
-      if (result.status !== 0) {
-        console.error(`Editor exited with code ${String(result.status ?? 1)}`);
-        process.exit(result.status ?? 1);
-      }
-
-      // Re-read after edit and report any issues
-      try {
-        await svc.readAll();
-        console.log('Config looks valid.');
-      } catch (err) {
-        console.error('Warning: config may have validation issues:');
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-      }
-    });
-
-  // ── config path ─────────────────────────────────────────────────────────
-
-  cmd
-    .command('path')
-    .description('Print the active config directory path (for scripting)')
-    .option(
-      '-s, --section <section>',
-      'Print path for a specific section file: soul | user | tools',
-    )
-    .action(async (opts: { section?: string }) => {
-      const mosaicHome = getMosaicHome();
-      const svc = createConfigService(mosaicHome, mosaicHome);
-
-      if (opts.section) {
-        const validSections = ['soul', 'user', 'tools'] as const;
-        if (!validSections.includes(opts.section as (typeof validSections)[number])) {
-          console.error(`Invalid section "${opts.section}". Choose: soul, user, tools`);
-          process.exit(1);
-        }
-        console.log(svc.getConfigPath(opts.section as 'soul' | 'user' | 'tools'));
-      } else {
-        console.log(svc.getConfigPath());
-      }
-    });
-}

packages/mosaic/src/commands/gateway.ts

@@ -30,7 +30,6 @@ export function registerGatewayCommand(program: Command): void {
     .option('-h, --host <host>', 'Gateway host', 'localhost')
     .option('-p, --port <port>', 'Gateway port', '14242')
     .option('-t, --token <token>', 'Admin API token')
-    .configureHelp({ sortSubcommands: true })
     .action(() => {
       gw.outputHelp();
     });

packages/mosaic/src/commands/mission.ts

@@ -47,7 +47,6 @@ export function registerMissionCommand(program: Command) {
     .option('--update <idOrName>', 'Update a mission')
     .option('--project <idOrName>', 'Scope to project')
     .argument('[id]', 'Show mission detail by ID')
-    .configureHelp({ sortSubcommands: true })
     .action(
       async (
         id: string | undefined,

packages/mosaic/src/config/config-service.ts

@@ -1,16 +1,6 @@
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { FileConfigAdapter } from './file-adapter.js';
 
-/** Supported top-level config sections for dotted-key access. */
-export type ConfigSection = 'soul' | 'user' | 'tools';
-
-/** A resolved view of all config sections, keyed by section name. */
-export interface ResolvedConfig {
-  soul: SoulConfig;
-  user: UserConfig;
-  tools: ToolsConfig;
-}
-
 /**
  * ConfigService interface — abstracts config read/write operations.
  * Currently backed by FileConfigAdapter (writes .md files from templates).
@@ -26,35 +16,6 @@ export interface ConfigService {
   writeTools(config: ToolsConfig): Promise<void>;
 
   syncFramework(action: InstallAction): Promise<void>;
-
-  /**
-   * Return the resolved (merged) config across all sections.
-   */
-  readAll(): Promise<ResolvedConfig>;
-
-  /**
-   * Read a single value by dotted key (e.g. "soul.agentName").
-   * Returns undefined if the key doesn't exist.
-   */
-  getValue(dottedKey: string): Promise<unknown>;
-
-  /**
-   * Set a single value by dotted key (e.g. "soul.agentName") and persist.
-   * Returns the previous value (or undefined).
-   */
-  setValue(dottedKey: string, value: string): Promise<unknown>;
-
-  /**
-   * Return the filesystem path for a given config section file.
-   * When no section is provided, returns the mosaicHome directory.
-   */
-  getConfigPath(section?: ConfigSection): string;
-
-  /**
-   * Returns true if the mosaicHome directory exists and at least one
-   * config file (SOUL.md, USER.md, TOOLS.md) is present.
-   */
-  isInitialized(): boolean;
 }
 
 export function createConfigService(mosaicHome: string, sourceDir: string): ConfigService {

packages/mosaic/src/config/file-adapter.ts

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { ConfigService, ConfigSection, ResolvedConfig } from './config-service.js';
+import type { ConfigService } from './config-service.js';
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { soulSchema, userSchema, toolsSchema } from './schemas.js';
 import { renderTemplate } from '../template/engine.js';
@@ -159,73 +159,6 @@ export class FileConfigAdapter implements ConfigService {
     }
   }
 
-  async readAll(): Promise<ResolvedConfig> {
-    const [soul, user, tools] = await Promise.all([
-      this.readSoul(),
-      this.readUser(),
-      this.readTools(),
-    ]);
-    return { soul, user, tools };
-  }
-
-  async getValue(dottedKey: string): Promise<unknown> {
-    const parts = dottedKey.split('.');
-    const section = parts[0] ?? '';
-    const field = parts.slice(1).join('.');
-    const config = await this.readAll();
-    if (!this.isValidSection(section)) return undefined;
-    const sectionData = config[section as ConfigSection] as Record<string, unknown>;
-    return field ? sectionData[field] : sectionData;
-  }
-
-  async setValue(dottedKey: string, value: string): Promise<unknown> {
-    const parts = dottedKey.split('.');
-    const section = parts[0] ?? '';
-    const field = parts.slice(1).join('.');
-    if (!this.isValidSection(section) || !field) {
-      throw new Error(
-        `Invalid key "${dottedKey}". Use format <section>.<field> (e.g. soul.agentName).`,
-      );
-    }
-
-    const previous = await this.getValue(dottedKey);
-
-    if (section === 'soul') {
-      const current = await this.readSoul();
-      await this.writeSoul({ ...current, [field]: value });
-    } else if (section === 'user') {
-      const current = await this.readUser();
-      await this.writeUser({ ...current, [field]: value });
-    } else {
-      const current = await this.readTools();
-      await this.writeTools({ ...current, [field]: value });
-    }
-
-    return previous;
-  }
-
-  getConfigPath(section?: ConfigSection): string {
-    if (!section) return this.mosaicHome;
-    const fileMap: Record<ConfigSection, string> = {
-      soul: join(this.mosaicHome, 'SOUL.md'),
-      user: join(this.mosaicHome, 'USER.md'),
-      tools: join(this.mosaicHome, 'TOOLS.md'),
-    };
-    return fileMap[section];
-  }
-
-  isInitialized(): boolean {
-    return (
-      existsSync(join(this.mosaicHome, 'SOUL.md')) ||
-      existsSync(join(this.mosaicHome, 'USER.md')) ||
-      existsSync(join(this.mosaicHome, 'TOOLS.md'))
-    );
-  }
-
-  private isValidSection(s: string): s is ConfigSection {
-    return s === 'soul' || s === 'user' || s === 'tools';
-  }
-
   /**
    * Look for template in source dir first, then mosaic home.
    */

pnpm-lock.yaml

@@ -294,9 +294,6 @@ importers:
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
-      commander:
-        specifier: ^13.0.0
-        version: 13.1.0
     devDependencies:
       typescript:
         specifier: ^5.8.0
@@ -441,6 +438,9 @@ importers:
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
+      commander:
+        specifier: ^13.0.0
+        version: 13.1.0
       drizzle-orm:
         specifier: ^0.45.1
         version: 0.45.1(@electric-sql/pglite@0.2.17)(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.15.6)(better-sqlite3@12.8.0)(kysely@0.28.11)(postgres@3.4.8)
@@ -457,9 +457,6 @@ importers:
       '@clack/prompts':
         specifier: ^0.9.1
         version: 0.9.1
-      '@mosaicstack/brain':
-        specifier: workspace:*
-        version: link:../brain
       '@mosaicstack/config':
         specifier: workspace:*
         version: link:../config
@@ -469,6 +466,9 @@ importers:
       '@mosaicstack/macp':
         specifier: workspace:*
         version: link:../macp
+      '@mosaicstack/memory':
+        specifier: workspace:*
+        version: link:../memory
       '@mosaicstack/prdy':
         specifier: workspace:*
         version: link:../prdy