r2mcp 0.2.0

package/dist/tools/remember.d.ts

@@ -0,0 +1,26 @@
+export type Operation = 'ADD' | 'UPDATE' | 'ARCHIVE' | 'REJECTION' | 'NOOP';
+export type Tier = 'preferences' | 'project-context' | 'conversations';
+export type MemoryType = 'preference' | 'decision' | 'context' | 'relationship' | 'observation' | 'rejection';
+export interface MemoryMetadata {
+    type: MemoryType;
+    topics?: string[];
+    people?: string[];
+    section?: string;
+    date?: string;
+}
+export interface RememberInput {
+    operation: Operation;
+    tier: Tier;
+    content: string;
+    metadata: MemoryMetadata;
+    target_id?: string;
+}
+export interface RememberResult {
+    operation: Operation;
+    id?: string;
+    dedup?: boolean;
+    message: string;
+    /** Present only when the operation completed degraded (claw-8cjf.2). */
+    warnings?: string[];
+}
+export declare function remember(input: RememberInput, projectRoot?: string): Promise<RememberResult>;

package/dist/tools/remember.js

@@ -0,0 +1,140 @@
+import { getPool } from '../db.js';
+import { fingerprint } from '../fingerprint.js';
+import { embedText, embeddingWarning } from '../embeddings.js';
+import { triggerGraphRebuild } from '../graph-rebuild.js';
+import pgvector from 'pgvector';
+const { toSql } = pgvector;
+export async function remember(input, projectRoot) {
+    const { operation, tier, content, metadata, target_id } = input;
+    if (operation === 'NOOP') {
+        return { operation: 'NOOP', message: 'No action taken.' };
+    }
+    const pool = getPool();
+    if (operation === 'ADD' || operation === 'REJECTION') {
+        const fp = fingerprint(content);
+        const type = operation === 'REJECTION' ? 'rejection' : metadata.type;
+        // Check for dedup via fingerprint
+        const existing = await pool.query('SELECT id FROM memories WHERE fingerprint = $1', [fp]);
+        if (existing.rows.length > 0) {
+            // Dedup: just update timestamp
+            await pool.query('UPDATE memories SET updated_at = NOW() WHERE id = $1', [
+                existing.rows[0].id,
+            ]);
+            return {
+                operation,
+                id: existing.rows[0].id,
+                dedup: true,
+                message: `Duplicate detected. Updated timestamp for existing memory ${existing.rows[0].id}.`,
+            };
+        }
+        // Generate embedding (null-safe)
+        const embedding = await embedText(content);
+        const result = await pool.query(`INSERT INTO memories (content, tier, type, section, topics, people, date, fingerprint, embedding)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+       RETURNING id`, [
+            content,
+            tier,
+            type,
+            metadata.section || null,
+            metadata.topics || [],
+            metadata.people || [],
+            metadata.date || null,
+            fp,
+            embedding ? toSql(embedding) : null,
+        ]);
+        if (projectRoot) {
+            triggerGraphRebuild(projectRoot);
+        }
+        const warning = embeddingWarning(embedding);
+        return {
+            operation,
+            id: result.rows[0].id,
+            dedup: false,
+            message: `Memory stored with id ${result.rows[0].id}.`,
+            ...(warning ? { warnings: [warning] } : {}),
+        };
+    }
+    if (operation === 'UPDATE') {
+        if (!target_id) {
+            return { operation: 'UPDATE', message: 'UPDATE requires target_id.' };
+        }
+        const fp = fingerprint(content);
+        const embedding = await embedText(content);
+        const result = await pool.query(`UPDATE memories SET
+        content = $1,
+        tier = $2,
+        type = $3,
+        section = $4,
+        topics = $5,
+        people = $6,
+        date = $7,
+        fingerprint = $8,
+        embedding = $9,
+        updated_at = NOW()
+       WHERE id = $10
+       RETURNING id`, [
+            content,
+            tier,
+            metadata.type,
+            metadata.section || null,
+            metadata.topics || [],
+            metadata.people || [],
+            metadata.date || null,
+            fp,
+            embedding ? toSql(embedding) : null,
+            target_id,
+        ]);
+        if (result.rows.length === 0) {
+            return { operation: 'UPDATE', message: `No memory found with id ${target_id}.` };
+        }
+        if (projectRoot) {
+            triggerGraphRebuild(projectRoot);
+        }
+        const warning = embeddingWarning(embedding);
+        return {
+            operation: 'UPDATE',
+            id: result.rows[0].id,
+            message: `Memory ${target_id} updated.`,
+            ...(warning ? { warnings: [warning] } : {}),
+        };
+    }
+    if (operation === 'ARCHIVE') {
+        if (!target_id) {
+            return { operation: 'ARCHIVE', message: 'ARCHIVE requires target_id.' };
+        }
+        // Soft-archive: set type to 'archived' (preserves data for reversibility)
+        const archived = await pool.query("UPDATE memories SET type = 'archived', updated_at = NOW() WHERE id = $1 RETURNING id", [target_id]);
+        if (archived.rows.length === 0) {
+            return { operation: 'ARCHIVE', message: `No memory found with id ${target_id}.` };
+        }
+        // If replacement content is provided, insert it as a new memory
+        let replacementWarning = null;
+        if (content && content.trim().length > 0) {
+            const fp = fingerprint(content);
+            const embedding = await embedText(content);
+            replacementWarning = embeddingWarning(embedding);
+            await pool.query(`INSERT INTO memories (content, tier, type, section, topics, people, date, fingerprint, embedding)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`, [
+                content,
+                tier,
+                metadata.type,
+                metadata.section || null,
+                metadata.topics || [],
+                metadata.people || [],
+                metadata.date || null,
+                fp,
+                embedding ? toSql(embedding) : null,
+            ]);
+        }
+        if (projectRoot) {
+            triggerGraphRebuild(projectRoot);
+        }
+        return {
+            operation: 'ARCHIVE',
+            id: target_id,
+            message: `Memory ${target_id} archived.${content ? ' Replacement stored.' : ''}`,
+            ...(replacementWarning ? { warnings: [replacementWarning] } : {}),
+        };
+    }
+    return { operation, message: `Unknown operation: ${operation}` };
+}

package/dist/tools/search.d.ts

@@ -0,0 +1,30 @@
+export interface SearchFilter {
+    type?: string;
+    tier?: string;
+    topics?: string[];
+    persons?: string[];
+    created_after?: string;
+    created_before?: string;
+}
+export interface SearchInput {
+    filter?: SearchFilter;
+    query?: string;
+    limit?: number;
+}
+export interface SearchResultEntry {
+    id: string;
+    content: string;
+    tier: string;
+    type: string;
+    topics: string[];
+    people: string[];
+    section: string | null;
+    date: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface SearchResult {
+    results: SearchResultEntry[];
+    count: number;
+}
+export declare function search(input: SearchInput): Promise<SearchResult>;

package/dist/tools/search.js

@@ -0,0 +1,69 @@
+import { getPool } from '../db.js';
+export async function search(input) {
+    const pool = getPool();
+    const { filter, query, limit = 20 } = input;
+    const conditions = ["type != 'rejection'"];
+    const params = [];
+    let paramIndex = 1;
+    if (filter) {
+        if (filter.type) {
+            conditions.push(`type = $${paramIndex}`);
+            params.push(filter.type);
+            paramIndex++;
+        }
+        if (filter.tier) {
+            conditions.push(`tier = $${paramIndex}`);
+            params.push(filter.tier);
+            paramIndex++;
+        }
+        if (filter.topics && filter.topics.length > 0) {
+            conditions.push(`topics && $${paramIndex}::text[]`);
+            params.push(filter.topics);
+            paramIndex++;
+        }
+        if (filter.persons && filter.persons.length > 0) {
+            conditions.push(`people && $${paramIndex}::text[]`);
+            params.push(filter.persons);
+            paramIndex++;
+        }
+        if (filter.created_after) {
+            conditions.push(`created_at >= $${paramIndex}::timestamptz`);
+            params.push(filter.created_after);
+            paramIndex++;
+        }
+        if (filter.created_before) {
+            conditions.push(`created_at <= $${paramIndex}::timestamptz`);
+            params.push(filter.created_before);
+            paramIndex++;
+        }
+    }
+    if (query) {
+        conditions.push(`tsv @@ plainto_tsquery('english', $${paramIndex})`);
+        params.push(query);
+        paramIndex++;
+    }
+    params.push(limit);
+    const sql = `
+    SELECT id, content, tier, type, topics, people, section, date, created_at, updated_at
+    FROM memories
+    WHERE ${conditions.join(' AND ')}
+    ORDER BY created_at DESC
+    LIMIT $${paramIndex}
+  `;
+    const result = await pool.query(sql, params);
+    return {
+        results: result.rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            tier: row.tier,
+            type: row.type,
+            topics: row.topics || [],
+            people: row.people || [],
+            section: row.section,
+            date: row.date ? row.date.toISOString().split('T')[0] : null,
+            created_at: row.created_at.toISOString(),
+            updated_at: row.updated_at.toISOString(),
+        })),
+        count: result.rows.length,
+    };
+}

package/dist/tools/spawn-cli.d.ts

@@ -0,0 +1,14 @@
+export type CliScriptName = 'classify-edges' | 'compile-wiki' | 'dump-edges-json' | 'extract-entities';
+export interface ResolvedCli {
+    bin: string;
+    args: string[];
+}
+/**
+ * Convenience wrapper that uses the caller's import.meta.url. Most callers
+ * use this; resolveCliCommandForUrl is the testable seam.
+ */
+export declare function resolveCliCommand(scriptName: CliScriptName): ResolvedCli;
+/**
+ * Pure function — testable in isolation by passing a fake import.meta.url.
+ */
+export declare function resolveCliCommandForUrl(scriptName: CliScriptName, importMetaUrl: string): ResolvedCli;

package/dist/tools/spawn-cli.js

@@ -0,0 +1,41 @@
+/**
+ * SPEC-045: shared subprocess command resolver for r2mcp's CLI tools.
+ *
+ * Returns {bin, args} for spawning a script under both:
+ *   - dev mode: this file is .ts (via tsx) → spawn tsx <project>/src/cli/<name>.ts
+ *   - prod mode: this file is .js (compiled to dist/) → spawn node <project>/dist/cli/<name>.js
+ *
+ * Detection uses the file extension at import.meta.url. This is automatic,
+ * zero-config, and authoritative for tsx + tsc workflows. If r2mcp ever
+ * adopts esbuild single-file bundling (.ts and .js both look like .js),
+ * promote a different mitigation here (NODE_ENV check, or dist/ substring).
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+/**
+ * Convenience wrapper that uses the caller's import.meta.url. Most callers
+ * use this; resolveCliCommandForUrl is the testable seam.
+ */
+export function resolveCliCommand(scriptName) {
+    return resolveCliCommandForUrl(scriptName, import.meta.url);
+}
+/**
+ * Pure function — testable in isolation by passing a fake import.meta.url.
+ */
+export function resolveCliCommandForUrl(scriptName, importMetaUrl) {
+    const thisFile = fileURLToPath(importMetaUrl);
+    const isDev = thisFile.endsWith('.ts');
+    const dir = dirname(thisFile);
+    if (isDev) {
+        // dev: <root>/src/tools/spawn-cli.ts → <root>/src/cli/<name>.ts
+        return {
+            bin: 'tsx',
+            args: [resolve(dir, '..', 'cli', `${scriptName}.ts`)],
+        };
+    }
+    // prod: <root>/dist/tools/spawn-cli.js → <root>/dist/cli/<name>.js
+    return {
+        bin: 'node',
+        args: [resolve(dir, '..', 'cli', `${scriptName}.js`)],
+    };
+}

package/dist/tools/stats.d.ts

@@ -0,0 +1,31 @@
+export interface StatsResult {
+    total: number;
+    by_tier: {
+        preferences: number;
+        'project-context': number;
+        conversations: number;
+    };
+    by_type: {
+        preference: number;
+        decision: number;
+        context: number;
+        relationship: number;
+        observation: number;
+        rejection: number;
+    };
+    staleness: {
+        oldest_entry: string | null;
+        avg_age_days: number;
+    };
+    top_topics: Array<{
+        topic: string;
+        count: number;
+    }>;
+    index: {
+        entries_with_embeddings: number;
+        entries_without_embeddings: number;
+        model: 'openai/text-embedding-3-small';
+        last_write: string | null;
+    };
+}
+export declare function stats(): Promise<StatsResult>;

package/dist/tools/stats.js

@@ -0,0 +1,88 @@
+import { getPool } from '../db.js';
+export async function stats() {
+    const pool = getPool();
+    // Run all queries in parallel
+    const [totalResult, tierResult, typeResult, stalenessResult, topicsResult, embeddingResult, lastWriteResult,] = await Promise.all([
+        // Total count
+        pool.query('SELECT COUNT(*)::int AS total FROM memories'),
+        // By tier
+        pool.query(`
+      SELECT tier, COUNT(*)::int AS count
+      FROM memories
+      GROUP BY tier
+    `),
+        // By type
+        pool.query(`
+      SELECT type, COUNT(*)::int AS count
+      FROM memories
+      GROUP BY type
+    `),
+        // Staleness
+        pool.query(`
+      SELECT
+        MIN(created_at) AS oldest_entry,
+        COALESCE(EXTRACT(EPOCH FROM AVG(NOW() - created_at)) / 86400, 0) AS avg_age_days
+      FROM memories
+    `),
+        // Top topics (unnest topics array and count)
+        pool.query(`
+      SELECT topic, COUNT(*)::int AS count
+      FROM memories, unnest(topics) AS topic
+      GROUP BY topic
+      ORDER BY count DESC
+      LIMIT 10
+    `),
+        // Embedding counts
+        pool.query(`
+      SELECT
+        COUNT(*) FILTER (WHERE embedding IS NOT NULL)::int AS with_embeddings,
+        COUNT(*) FILTER (WHERE embedding IS NULL)::int AS without_embeddings
+      FROM memories
+    `),
+        // Last write
+        pool.query('SELECT MAX(updated_at) AS last_write FROM memories'),
+    ]);
+    // Build tier map
+    const tierMap = {};
+    for (const row of tierResult.rows) {
+        tierMap[row.tier] = row.count;
+    }
+    // Build type map
+    const typeMap = {};
+    for (const row of typeResult.rows) {
+        typeMap[row.type] = row.count;
+    }
+    const stalenessRow = stalenessResult.rows[0];
+    const embeddingRow = embeddingResult.rows[0];
+    const lastWriteRow = lastWriteResult.rows[0];
+    return {
+        total: totalResult.rows[0].total,
+        by_tier: {
+            preferences: tierMap['preferences'] || 0,
+            'project-context': tierMap['project-context'] || 0,
+            conversations: tierMap['conversations'] || 0,
+        },
+        by_type: {
+            preference: typeMap['preference'] || 0,
+            decision: typeMap['decision'] || 0,
+            context: typeMap['context'] || 0,
+            relationship: typeMap['relationship'] || 0,
+            observation: typeMap['observation'] || 0,
+            rejection: typeMap['rejection'] || 0,
+        },
+        staleness: {
+            oldest_entry: stalenessRow.oldest_entry ? stalenessRow.oldest_entry.toISOString() : null,
+            avg_age_days: Math.round(parseFloat(stalenessRow.avg_age_days) * 100) / 100,
+        },
+        top_topics: topicsResult.rows.map((row) => ({
+            topic: row.topic,
+            count: row.count,
+        })),
+        index: {
+            entries_with_embeddings: embeddingRow.with_embeddings,
+            entries_without_embeddings: embeddingRow.without_embeddings,
+            model: 'openai/text-embedding-3-small',
+            last_write: lastWriteRow.last_write ? lastWriteRow.last_write.toISOString() : null,
+        },
+    };
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "r2mcp",
+  "version": "0.2.0",
+  "description": "Persistent semantic memory layer for Claude Code — PostgreSQL + pgvector + OpenRouter embeddings",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist/",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc && cp src/schema.sql dist/",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "setup": "tsx src/cli/setup.ts",
+    "edges:classify": "tsx src/cli/classify-edges.ts",
+    "entities:extract": "tsx src/cli/extract-entities.ts",
+    "compile-wiki": "tsx src/cli/compile-wiki.ts",
+    "lint:memory": "tsx src/cli/lint-memory.ts",
+    "migrate": "tsx src/cli/migrate.ts",
+    "gauntlet": "vitest run tests/gauntlet.test.ts",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.92.0",
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.213.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.213.0",
+    "@opentelemetry/instrumentation-http": "^0.213.0",
+    "@opentelemetry/instrumentation-pg": "^0.65.0",
+    "@opentelemetry/resources": "^2.6.0",
+    "@opentelemetry/sdk-metrics": "^2.6.0",
+    "@opentelemetry/sdk-node": "^0.213.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0",
+    "pg": "^8.20.0",
+    "pgvector": "^0.2.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/pg": "^8.11.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^10.4.0",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.8.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "types": "dist/index.d.ts",
+  "bin": {
+    "r2mcp": "dist/index.js",
+    "r2mcp-setup": "dist/cli/setup.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DMokong/r2mcp.git"
+  },
+  "homepage": "https://github.com/DMokong/r2mcp#readme",
+  "bugs": {
+    "url": "https://github.com/DMokong/r2mcp/issues"
+  },
+  "author": "Dustin Cheng",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "memory",
+    "pgvector",
+    "semantic-search",
+    "model-context-protocol"
+  ]
+}