r2mcp 0.2.0

package/dist/cli/extract-entities.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env tsx
+// OTel instrumentation MUST be imported first — before any other module —
+// so OTEL_TRACEPARENT propagation has an SDK to attach the parent context to
+// (claw-1ejd). Without this import, propagation.extract() is a no-op.
+import '../instrumentation.js';
+/**
+ * SPEC-046 entity extractor CLI.
+ *
+ * Usage:
+ *   npm run entities:extract -- [--since-days=N | --full] [--max-cost=USD]
+ *                               [--provider=<name>] [--resume=<run_id>]
+ *                               [--data-dir=PATH] [--context-top-n=N]
+ *
+ * Provider selection precedence (mirrors SPEC-043):
+ *   1. --provider=claude-code|anthropic|openrouter
+ *   2. R2MCP_CLASSIFIER_PROVIDER env var
+ *   3. Auto-fallback (claude-code → anthropic → openrouter)
+ *
+ * Examples:
+ *   npm run entities:extract -- --since-days=1 --max-cost=0.05
+ *   npm run entities:extract -- --full --max-cost=1.00
+ *   npm run entities:extract -- --resume=abc123
+ *
+ * Exit codes:
+ *   0 — completed normally (including cap-reached and provider errors that
+ *       finalize via run summary)
+ *   1 — fatal error (DB unreachable, no provider configured, parse error in args, etc.)
+ *   2 — invalid CLI argument combination
+ */
+import { resolve } from 'node:path';
+import { context, propagation } from '@opentelemetry/api';
+import { initDb, getPool, closeDb } from '../db.js';
+import { runExtractor } from '../entities/extractor.js';
+import { selectProvider, isProviderName, ProviderUnavailableError, } from '../providers/index.js';
+import { loadEnvFile } from '../env.js';
+// Load .env from project root — launchd-spawned subprocesses don't inherit
+// shell env, so OTEL_ENABLED + DB URL + provider keys must be loaded here
+// (claw-1ejd; mirrors src/index.ts).
+loadEnvFile(resolve(process.env.PROJECT_ROOT || process.cwd(), '.env'));
+/**
+ * claw-2jbo finding 6: if the MCP wrapper passed an OTEL_TRACEPARENT env
+ * var (W3C traceparent format), reconstruct the parent OTel context so any
+ * spans/auto-instrumentation in this subprocess chain under the wrapper's
+ * `memory.extract_entities` span. No-op when the env var is absent or no
+ * propagator is registered (OTel SDK not initialized).
+ */
+function parentContextFromEnv() {
+    const traceparent = process.env.OTEL_TRACEPARENT;
+    if (!traceparent)
+        return undefined;
+    // Standard W3C TextMap carrier: lowercase `traceparent` (and optional
+    // `tracestate`) keys. propagation.extract is a no-op without a propagator,
+    // which is fine — the env var is still set, future SDK init will see it.
+    const carrier = { traceparent };
+    if (process.env.OTEL_TRACESTATE)
+        carrier.tracestate = process.env.OTEL_TRACESTATE;
+    return propagation.extract(context.active(), carrier);
+}
+// SPEC-046 R6: argv-parse errors must produce a non-zero exit with a clear
+// message naming the offending flag(s). UsageError carries the exit code so
+// main() can preserve the historical exit-2 contract while parseArgs stays
+// pure & unit-testable.
+export class UsageError extends Error {
+    exitCode;
+    constructor(message, exitCode = 2) {
+        super(message);
+        this.name = 'UsageError';
+        this.exitCode = exitCode;
+    }
+}
+export function parseArgs(argv) {
+    const args = {
+        maxCostUsd: Number(process.env.R2MCP_ENTITY_MAX_USD ?? '1.00'),
+        dataDir: process.env.R2MCP_ENTITY_DATA_DIR ?? 'data',
+        contextTopN: Number(process.env.R2MCP_ENTITY_CONTEXT_TOP_N ?? '100'),
+        full: false,
+    };
+    for (const a of argv) {
+        if (a === '--full') {
+            args.full = true;
+        }
+        else if (a.startsWith('--since-days=')) {
+            args.sinceDays = Number(a.split('=')[1]);
+        }
+        else if (a.startsWith('--max-cost=')) {
+            args.maxCostUsd = Number(a.split('=')[1]);
+        }
+        else if (a.startsWith('--provider=')) {
+            const raw = a.split('=')[1];
+            if (!isProviderName(raw)) {
+                throw new UsageError(`--provider must be one of claude-code|anthropic|openrouter, got ${raw}`);
+            }
+            args.providerFlag = raw;
+        }
+        else if (a.startsWith('--resume=')) {
+            args.resume = a.split('=')[1];
+        }
+        else if (a.startsWith('--data-dir=')) {
+            args.dataDir = a.split('=')[1];
+        }
+        else if (a.startsWith('--context-top-n=')) {
+            args.contextTopN = Number(a.split('=')[1]);
+        }
+    }
+    if (args.full && args.sinceDays !== undefined) {
+        throw new UsageError('Error: --full and --since-days are mutually exclusive');
+    }
+    return args;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    await initDb();
+    const pool = getPool();
+    const provider = await selectProvider({ flag: args.providerFlag });
+    try {
+        const summary = await runExtractor({
+            client: pool,
+            provider,
+            dataDir: args.dataDir,
+            maxCostUsd: args.maxCostUsd,
+            contextTopN: args.contextTopN,
+            sinceDays: args.sinceDays,
+            full: args.full,
+            resumeFrom: args.resume,
+        });
+        process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
+    }
+    finally {
+        await closeDb();
+    }
+}
+// Only run main() when invoked as the script entry point. Importing parseArgs
+// (e.g. from tests) must not boot the extractor.
+const isDirectInvocation = (() => {
+    if (!process.argv[1])
+        return false;
+    try {
+        return import.meta.url === new URL(`file://${process.argv[1]}`).href;
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectInvocation) {
+    // Wrap main() in the extracted parent context so any future OTel spans
+    // in this process chain under the MCP wrapper's parent span (claw-2jbo
+    // finding 6). When parentCtx is undefined we just run main() directly.
+    const parentCtx = parentContextFromEnv();
+    const runner = () => main().catch((err) => {
+        if (err instanceof UsageError) {
+            process.stderr.write(`${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        if (err instanceof ProviderUnavailableError) {
+            process.stderr.write(`${err.message}\n`);
+        }
+        else {
+            process.stderr.write(`ERROR: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        process.exit(1);
+    });
+    if (parentCtx)
+        context.with(parentCtx, runner);
+    else
+        runner();
+}

package/dist/cli/lint-memory.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env tsx
+/**
+ * SPEC-044 Section C — lint CLI driver.
+ *
+ * Usage:
+ *   npm run lint -- [--check=<name>] [--since=Nd] [--limit=N] [--fix]
+ *
+ * Output: human-readable terminal report grouped by check type, with a
+ * trailing JSON summary line for programmatic consumption (mirrors the
+ * pattern of classify-edges and compile-wiki).
+ *
+ * Exit codes:
+ *   0 — completed normally (regardless of finding count)
+ *   1 — fatal error (DB unreachable, malformed input)
+ */
+export {};

package/dist/cli/lint-memory.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env tsx
+/**
+ * SPEC-044 Section C — lint CLI driver.
+ *
+ * Usage:
+ *   npm run lint -- [--check=<name>] [--since=Nd] [--limit=N] [--fix]
+ *
+ * Output: human-readable terminal report grouped by check type, with a
+ * trailing JSON summary line for programmatic consumption (mirrors the
+ * pattern of classify-edges and compile-wiki).
+ *
+ * Exit codes:
+ *   0 — completed normally (regardless of finding count)
+ *   1 — fatal error (DB unreachable, malformed input)
+ */
+import { resolve } from 'node:path';
+import { initDb, getPool, closeDb } from '../db.js';
+import { loadEnvFile } from '../env.js';
+import { runLint } from '../lint/run.js';
+import { ALL_CHECKS } from '../lint/types.js';
+// Load .env from project root — mirrors src/index.ts (claw-8cjf.2; this CLI
+// previously loaded no environment at all and silently hit the default URL).
+loadEnvFile(resolve(process.env.PROJECT_ROOT || process.cwd(), '.env'));
+function isCheck(s) {
+    return ALL_CHECKS.includes(s);
+}
+function parseArgs(argv) {
+    const out = {};
+    for (const arg of argv) {
+        if (arg === '--fix')
+            out.fix = true;
+        else if (arg.startsWith('--check=')) {
+            const c = arg.split('=')[1];
+            if (!isCheck(c))
+                throw new Error(`--check must be one of ${ALL_CHECKS.join('|')}, got ${c}`);
+            out.check = c;
+        }
+        else if (arg.startsWith('--since=')) {
+            const raw = arg.split('=')[1];
+            const m = raw.match(/^(\d+)d$/);
+            if (!m)
+                throw new Error(`--since must be Nd (e.g. 30d), got ${raw}`);
+            out.since_days = Number(m[1]);
+        }
+        else if (arg.startsWith('--limit=')) {
+            out.limit = Number(arg.split('=')[1]);
+        }
+    }
+    return out;
+}
+function renderReport(result) {
+    const lines = [];
+    lines.push('Lint Report');
+    lines.push('===========');
+    lines.push(`Total findings: ${result.summary.total_findings}`);
+    for (const [check, count] of Object.entries(result.summary.by_check)) {
+        lines.push(`  ${check}: ${count}`);
+    }
+    // Per-check sections (C.AC3)
+    for (const checkName of ALL_CHECKS) {
+        const subset = result.findings.filter((f) => f.check === checkName);
+        if (subset.length === 0)
+            continue;
+        lines.push('');
+        lines.push(`## ${checkName}`);
+        for (const f of subset) {
+            lines.push(`  - ${f.memory_id}${f.related_memory_id ? ` ↔ ${f.related_memory_id}` : ''}`);
+            lines.push(`      action: ${f.suggested_action} (confidence ${f.confidence.toFixed(2)})`);
+            lines.push(`      ${f.rationale}`);
+        }
+    }
+    if (result.fixes_applied && result.fixes_applied.length > 0) {
+        lines.push('');
+        lines.push(`Fixes applied (${result.fixes_applied.length}):`);
+        for (const fx of result.fixes_applied) {
+            lines.push(`  - ${fx.memory_id}: ${fx.action}`);
+        }
+    }
+    return lines.join('\n');
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    await initDb();
+    const result = await runLint(args, getPool());
+    process.stdout.write(renderReport(result) + '\n');
+    process.stdout.write('---\n');
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    await closeDb();
+    process.exit(0);
+}
+main().catch((err) => {
+    process.stderr.write(`ERROR: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/cli/migrate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Migration script: imports tiered markdown memory files into PostgreSQL.
+ *
+ * Usage:
+ *   R2MCP_DATABASE_URL=postgresql://localhost:5432/r2mcp npx tsx scripts/migrate.ts <memory-dir>
+ *
+ * Where <memory-dir> contains preferences.md, project-context.md, conversations.md
+ *
+ * Idempotent — re-running produces zero new rows thanks to SHA-256 fingerprint dedup.
+ */
+import type { Tier, MemoryType, MemoryMetadata } from '../tools/remember.js';
+export interface ParsedEntry {
+    content: string;
+    tier: Tier;
+    metadata: MemoryMetadata;
+}
+export declare function parseMarkdownEntries(content: string, tier: Tier, defaultType: MemoryType): ParsedEntry[];

package/dist/cli/migrate.js

@@ -0,0 +1,146 @@
+/**
+ * Migration script: imports tiered markdown memory files into PostgreSQL.
+ *
+ * Usage:
+ *   R2MCP_DATABASE_URL=postgresql://localhost:5432/r2mcp npx tsx scripts/migrate.ts <memory-dir>
+ *
+ * Where <memory-dir> contains preferences.md, project-context.md, conversations.md
+ *
+ * Idempotent — re-running produces zero new rows thanks to SHA-256 fingerprint dedup.
+ */
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { initDb, closeDb } from '../db.js';
+import { loadEnvFile } from '../env.js';
+import { remember } from '../tools/remember.js';
+const TIER_FILES = [
+    { file: 'preferences.md', tier: 'preferences', defaultType: 'preference' },
+    { file: 'project-context.md', tier: 'project-context', defaultType: 'context' },
+    { file: 'conversations.md', tier: 'conversations', defaultType: 'relationship' },
+];
+function parseInlineMetadata(text) {
+    const meta = {};
+    const commentRegex = /<!--\s*(.*?)\s*-->/gs;
+    let match;
+    while ((match = commentRegex.exec(text)) !== null) {
+        const body = match[1];
+        const typeMatch = body.match(/type:(\S+)/);
+        if (typeMatch)
+            meta.type = typeMatch[1];
+        const topicsMatch = body.match(/topics:(\S+)/);
+        if (topicsMatch)
+            meta.topics = topicsMatch[1].split(',').filter(Boolean);
+        const peopleMatch = body.match(/people:(\S+)/);
+        if (peopleMatch)
+            meta.people = peopleMatch[1].split(',').filter(Boolean);
+    }
+    return meta;
+}
+export function parseMarkdownEntries(content, tier, defaultType) {
+    const lines = content.split('\n');
+    const entries = [];
+    let currentSection;
+    let currentEntry = null;
+    function flushEntry() {
+        if (!currentEntry || currentEntry.length === 0)
+            return;
+        const raw = currentEntry.join('\n').trim();
+        if (!raw)
+            return;
+        const inlineMeta = parseInlineMetadata(raw);
+        entries.push({
+            content: raw,
+            tier,
+            metadata: {
+                type: inlineMeta.type || defaultType,
+                section: currentSection,
+                ...(inlineMeta.topics && { topics: inlineMeta.topics }),
+                ...(inlineMeta.people && { people: inlineMeta.people }),
+            },
+        });
+    }
+    for (const line of lines) {
+        if (/^# /.test(line))
+            continue;
+        if (/^## /.test(line)) {
+            flushEntry();
+            currentEntry = null;
+            currentSection = line.replace(/^##\s*/, '').trim();
+            continue;
+        }
+        if (/^- /.test(line)) {
+            flushEntry();
+            currentEntry = [line.slice(2)];
+            continue;
+        }
+        if (currentEntry !== null && /^\s+/.test(line)) {
+            currentEntry.push(line);
+            continue;
+        }
+        if (line.trim() === '')
+            continue;
+    }
+    flushEntry();
+    return entries;
+}
+async function migrate(memoryDir) {
+    await initDb();
+    let totalAdded = 0, totalDedup = 0, totalErrors = 0;
+    for (const { file, tier, defaultType } of TIER_FILES) {
+        const filePath = join(memoryDir, file);
+        let raw;
+        try {
+            raw = readFileSync(filePath, 'utf-8');
+        }
+        catch (err) {
+            console.error(`  ⚠️  Could not read ${filePath}: ${err.message}`);
+            totalErrors++;
+            continue;
+        }
+        const entries = parseMarkdownEntries(raw, tier, defaultType);
+        console.log(`Migrating ${file} → tier: ${tier} (${entries.length} entries)`);
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            const preview = entry.content.slice(0, 60).replace(/\n/g, ' ');
+            try {
+                const result = await remember({
+                    operation: 'ADD',
+                    tier: entry.tier,
+                    content: entry.content,
+                    metadata: entry.metadata,
+                });
+                if (result.dedup) {
+                    console.log(`  [${i + 1}/${entries.length}] Dedup: "${preview}..."`);
+                    totalDedup++;
+                }
+                else {
+                    console.log(`  [${i + 1}/${entries.length}] Added: "${preview}..."`);
+                    totalAdded++;
+                }
+            }
+            catch (err) {
+                console.error(`  [${i + 1}/${entries.length}] Error: "${preview}..." — ${err.message}`);
+                totalErrors++;
+            }
+        }
+    }
+    console.log(`\nMigration complete: ${totalAdded} added, ${totalDedup} deduplicated, ${totalErrors} errors`);
+    await closeDb();
+}
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.dirname || '.', 'migrate.ts');
+if (isMain) {
+    // Load .env only on the CLI path — tests import this module, and a
+    // module-level load would leak the consumer's R2MCP_DATABASE_URL into the
+    // test process (the test-isolation guard caught exactly that, claw-8cjf.2).
+    loadEnvFile(resolve(process.env.PROJECT_ROOT || process.cwd(), '.env'));
+    const memoryDir = process.argv[2] ? resolve(process.argv[2]) : null;
+    if (!memoryDir) {
+        console.error('Usage: tsx scripts/migrate.ts <memory-dir>');
+        console.error('  <memory-dir> must contain preferences.md, project-context.md, conversations.md');
+        process.exit(1);
+    }
+    migrate(memoryDir).catch((err) => {
+        console.error('Migration failed:', err);
+        process.exit(1);
+    });
+}

package/dist/cli/setup-helpers.d.ts

@@ -0,0 +1,7 @@
+export declare function redactDatabaseUrl(url: string): string;
+export declare function validateDatabaseUrl(url: string): void;
+export type SetupErrorClassification = {
+    cause: string;
+    fix: string;
+};
+export declare function classifySetupError(err: Error, redactedUrl: string): SetupErrorClassification;

package/dist/cli/setup-helpers.js

@@ -0,0 +1,72 @@
+export function redactDatabaseUrl(url) {
+    return url.replace(/:[^:/@]+@/, ':***@');
+}
+export function validateDatabaseUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return;
+    }
+    if (parsed.port === '6543') {
+        throw new Error(`Transaction-pooler URL detected (port 6543).\n` +
+            `Schema setup needs a session-capable connection — the transaction pooler does not\n` +
+            `support prepared statements or DDL. Use the Session pooler (port 5432) instead:\n` +
+            `\n` +
+            `  Supabase Dashboard → Connect (top of page) → Session pooler\n` +
+            `\n` +
+            `It looks like: postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres\n` +
+            `(A Direct connection also works if your network has IPv6 or the IPv4 add-on.)`);
+    }
+}
+export function classifySetupError(err, redactedUrl) {
+    const msg = err.message.toLowerCase();
+    const code = err.code;
+    if (code === 'ECONNREFUSED' ||
+        msg.includes('connect econnrefused') ||
+        msg.includes('connection refused')) {
+        return {
+            cause: `Connection refused — could not reach ${redactedUrl}`,
+            fix: 'Check that PostgreSQL is running (Docker: docker compose up -d) and that the host/port in DATABASE_URL are correct',
+        };
+    }
+    if (msg.includes('password authentication failed') ||
+        msg.includes('authentication failed') ||
+        (msg.includes('role') && msg.includes('does not exist'))) {
+        return {
+            cause: `Authentication failed for ${redactedUrl}`,
+            fix: 'Verify R2MCP_DATABASE_URL credentials in .env — username, password, and database name must match your PostgreSQL instance',
+        };
+    }
+    if (msg.includes('extension "vector" is not available') ||
+        msg.includes('could not open extension control file') ||
+        msg.includes('pgvector')) {
+        return {
+            cause: `pgvector extension not available at ${redactedUrl}`,
+            fix: 'Enable pgvector: Supabase Dashboard → Database → Extensions → search "vector" → Enable. For Docker, use pgvector/pgvector:pg17 image.',
+        };
+    }
+    if (code === 'ENETUNREACH' || msg.includes('enetunreach')) {
+        return {
+            cause: `Network unreachable (IPv6) — could not reach ${redactedUrl}`,
+            fix: 'The Supabase Direct connection resolves to an IPv6 address, and this network appears to be IPv4-only ' +
+                '(IPv4 for direct connections is a paid add-on). Use the Session pooler instead: in the Supabase dashboard ' +
+                'click "Connect" and copy the Session pooler string (port 5432, host like aws-0-<region>.pooler.supabase.com, ' +
+                'username postgres.<project-ref>). It is IPv4-compatible on every tier and supports schema setup.',
+        };
+    }
+    if (code === 'ETIMEDOUT' ||
+        code === 'ENOTFOUND' ||
+        msg.includes('connect etimedout') ||
+        msg.includes('getaddrinfo')) {
+        return {
+            cause: `Could not reach ${redactedUrl}`,
+            fix: 'Check that the host in DATABASE_URL is correct. For Supabase: verify your IP is allowed under Project Settings → Networking, and that the project ref in the URL matches your project.',
+        };
+    }
+    return {
+        cause: `Setup failed: ${err.message}`,
+        fix: 'Check R2MCP_DATABASE_URL in .env and ensure the database is accessible',
+    };
+}

package/dist/cli/setup.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * r2mcp setup script — idempotent schema provisioner.
+ *
+ * Usage: npm run setup
+ *
+ * What it does:
+ * 1. Connects to R2MCP_DATABASE_URL
+ * 2. Enables the pgvector extension
+ * 3. Runs schema.sql (CREATE TABLE IF NOT EXISTS + CREATE INDEX IF NOT EXISTS)
+ * 4. Verifies the schema by running a quick sanity query
+ *
+ * Safe to re-run: all DDL uses IF NOT EXISTS / IF EXISTS. No data is modified.
+ */
+export {};

package/dist/cli/setup.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * r2mcp setup script — idempotent schema provisioner.
+ *
+ * Usage: npm run setup
+ *
+ * What it does:
+ * 1. Connects to R2MCP_DATABASE_URL
+ * 2. Enables the pgvector extension
+ * 3. Runs schema.sql (CREATE TABLE IF NOT EXISTS + CREATE INDEX IF NOT EXISTS)
+ * 4. Verifies the schema by running a quick sanity query
+ *
+ * Safe to re-run: all DDL uses IF NOT EXISTS / IF EXISTS. No data is modified.
+ */
+import pg from 'pg';
+import pgvector from 'pgvector/pg';
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateDatabaseUrl, classifySetupError, redactDatabaseUrl } from './setup-helpers.js';
+import { loadEnvFile } from '../env.js';
+import { MISSING_DATABASE_URL_MESSAGE } from '../db.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Load .env from project root
+loadEnvFile(resolve(__dirname, '..', '..', '.env'));
+// claw-8cjf.2: fail fast instead of defaulting to a credential-less localhost
+// URL that matches neither the Docker compose setup nor any hosted option.
+if (!process.env.R2MCP_DATABASE_URL) {
+    console.error(`\n❌ ${MISSING_DATABASE_URL_MESSAGE}`);
+    process.exit(1);
+}
+const R2MCP_DATABASE_URL = process.env.R2MCP_DATABASE_URL;
+async function setup() {
+    const redactedUrl = redactDatabaseUrl(R2MCP_DATABASE_URL);
+    try {
+        validateDatabaseUrl(R2MCP_DATABASE_URL);
+    }
+    catch (validationErr) {
+        console.error(`\n❌ Invalid database URL: ${redactedUrl}`);
+        console.error(validationErr.message);
+        process.exit(1);
+    }
+    console.log('r2mcp setup — provisioning database schema...');
+    console.log(`Connecting to: ${redactedUrl}`);
+    const pool = new pg.Pool({ connectionString: R2MCP_DATABASE_URL });
+    const client = await pool.connect();
+    try {
+        // 1. Enable pgvector
+        console.log('→ Enabling pgvector extension...');
+        await client.query('CREATE EXTENSION IF NOT EXISTS vector');
+        console.log('  ✓ pgvector enabled');
+        // 2. Register pgvector types
+        await pgvector.registerTypes(client);
+        // 3. Run schema.sql
+        const schemaPath = resolve(__dirname, '..', 'schema.sql');
+        const schema = readFileSync(schemaPath, 'utf-8');
+        console.log('→ Applying schema.sql...');
+        await client.query(schema);
+        console.log('  ✓ Schema applied (idempotent)');
+        // 4. Sanity check
+        const result = await client.query(`
+      SELECT
+        (SELECT COUNT(*) FROM information_schema.tables WHERE table_name = 'memories')::int AS table_exists,
+        (SELECT COUNT(*) FROM pg_indexes WHERE tablename = 'memories')::int AS index_count
+    `);
+        const { table_exists, index_count } = result.rows[0];
+        if (table_exists !== 1) {
+            throw new Error('memories table was not created — schema.sql may have failed silently');
+        }
+        console.log(`  ✓ memories table present, ${index_count} indexes`);
+        console.log('\n✅ r2mcp setup complete!');
+        console.log('\nNext steps:');
+        console.log('  1. Add to .mcp.json:');
+        console.log('     "memory": {');
+        console.log('       "command": "node",');
+        console.log('       "args": ["<path-to-r2mcp>/dist/index.js"],');
+        console.log('       "env": { "R2MCP_DATABASE_URL": "<your-url>", "R2MCP_OPENROUTER_API_KEY": "<your-key>" }');
+        console.log('     }');
+        console.log('  2. Build: npm run build');
+        console.log('  3. Restart Claude Code to pick up the new MCP server');
+    }
+    finally {
+        client.release();
+        await pool.end();
+    }
+}
+setup().catch((err) => {
+    const redactedUrl = redactDatabaseUrl(R2MCP_DATABASE_URL);
+    // pg library always throws Error instances; cast is safe
+    const { cause, fix } = classifySetupError(err, redactedUrl);
+    console.error('\n❌ Setup failed');
+    console.error(`\nCause: ${cause}`);
+    console.error(`Fix:   ${fix}`);
+    process.exit(1);
+});

package/dist/compiler/clustering.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Deterministic memory grouping — used by both tier and topic compile to
+ * keep section structure stable across runs (B.R5 / B.AC3).
+ *
+ * Clustering is computed from input only — the LLM never sees an
+ * unsorted/unstable list, so its outputs cite the same memory IDs and
+ * surface the same headers run-to-run.
+ */
+import type { MemoryForCompile } from './types.js';
+export interface MemoryCluster {
+    topic: string;
+    topic_slug: string;
+    memories: MemoryForCompile[];
+}
+/**
+ * Group memories by their first-listed topic, then sort:
+ *   - clusters by topic name (alphabetical)
+ *   - memories within each cluster by `id` (alphabetical, stable)
+ *
+ * Memories with no topics are grouped under "uncategorized".
+ */
+export declare function clusterByTopic(memories: MemoryForCompile[]): MemoryCluster[];
+/**
+ * For topic-mode compile: filter to memories tagged with `topic`, sort by
+ * `created_at` ascending (so Timeline section flows naturally), tiebreak by id.
+ */
+export declare function memoriesForTopic(memories: MemoryForCompile[], topic: string): MemoryForCompile[];
+export declare function topicToSlug(topic: string): string;
+export declare function topicTitle(topic: string): string;