r2mcp 0.2.0

package/dist/compiler/clustering.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function clusterByTopic(memories) {
+    const buckets = new Map();
+    for (const m of memories) {
+        const topic = pickPrimaryTopic(m);
+        const bucket = buckets.get(topic) ?? [];
+        bucket.push(m);
+        buckets.set(topic, bucket);
+    }
+    const clusters = [];
+    for (const [topic, mems] of buckets) {
+        clusters.push({
+            topic,
+            topic_slug: topicToSlug(topic),
+            memories: [...mems].sort((a, b) => a.id.localeCompare(b.id)),
+        });
+    }
+    return clusters.sort((a, b) => a.topic.localeCompare(b.topic));
+}
+/**
+ * For topic-mode compile: filter to memories tagged with `topic`, sort by
+ * `created_at` ascending (so Timeline section flows naturally), tiebreak by id.
+ */
+export function memoriesForTopic(memories, topic) {
+    return memories
+        .filter((m) => m.topics.includes(topic))
+        .sort((a, b) => {
+        if (a.created_at !== b.created_at)
+            return a.created_at.localeCompare(b.created_at);
+        return a.id.localeCompare(b.id);
+    });
+}
+function pickPrimaryTopic(m) {
+    if (!m.topics || m.topics.length === 0)
+        return 'uncategorized';
+    // Pick the lexicographically smallest topic so the bucket is stable
+    // even if topic order in the array changes.
+    return [...m.topics].sort()[0];
+}
+export function topicToSlug(topic) {
+    return topic
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+export function topicTitle(topic) {
+    return topic
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}

package/dist/compiler/frontmatter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * YAML frontmatter generation + body comparison helpers for compile output
+ * (SPEC-044 B.R3, B.R5).
+ *
+ * Kept dependency-free: a compact YAML emitter is enough for our schema.
+ * We only emit strings, numbers, nulls, and arrays of strings — no nested
+ * objects — so a hand-rolled emitter sidesteps the js-yaml dependency.
+ */
+import type { CompileFrontmatter } from './types.js';
+export declare function emitFrontmatter(data: CompileFrontmatter): string;
+/**
+ * Parse the leading `---\n...\n---\n` frontmatter block from a markdown file.
+ * Returns the parsed fields (only the ones we emit) and the body that follows.
+ * Throws if the file does not start with frontmatter.
+ */
+export declare function parseFrontmatter(text: string): {
+    frontmatter: Partial<CompileFrontmatter>;
+    body: string;
+};
+/**
+ * Extract `## H2` and `### H3` headers from a markdown body. Used by B.R5/B.AC3
+ * stability check: header set across two runs must be identical.
+ */
+export declare function extractHeaders(body: string): string[];
+/**
+ * Strip frontmatter, headers, and inline citation tags (`<m:abc-123>`,
+ * `[m:abc-123]`) so the remaining body text can be Levenshtein-compared
+ * for prose-level variance (B.R5/B.AC3 third clause).
+ */
+export declare function stripForBodyComparison(text: string): string;
+/**
+ * Levenshtein distance ratio (1.0 = identical, 0.0 = totally different).
+ * Used by B.R5/B.AC3 to bound prose-level variance.
+ */
+export declare function levenshteinRatio(a: string, b: string): number;

package/dist/compiler/frontmatter.js

@@ -0,0 +1,168 @@
+/**
+ * YAML frontmatter generation + body comparison helpers for compile output
+ * (SPEC-044 B.R3, B.R5).
+ *
+ * Kept dependency-free: a compact YAML emitter is enough for our schema.
+ * We only emit strings, numbers, nulls, and arrays of strings — no nested
+ * objects — so a hand-rolled emitter sidesteps the js-yaml dependency.
+ */
+const FRONTMATTER_DELIM = '---';
+export function emitFrontmatter(data) {
+    const lines = [FRONTMATTER_DELIM];
+    lines.push(`generated_at: ${quote(data.generated_at)}`);
+    lines.push(`compile_run_id: ${quote(data.compile_run_id)}`);
+    lines.push(`source_count: ${data.source_count}`);
+    lines.push(`provider: ${quote(data.provider)}`);
+    if (data.source_git_sha === null) {
+        lines.push('source_git_sha: null');
+    }
+    else {
+        lines.push(`source_git_sha: ${quote(data.source_git_sha)}`);
+    }
+    if (data.tier)
+        lines.push(`tier: ${quote(data.tier)}`);
+    if (data.topic)
+        lines.push(`topic: ${quote(data.topic)}`);
+    lines.push('source_memory_ids:');
+    for (const id of data.source_memory_ids) {
+        lines.push(`  - ${quote(id)}`);
+    }
+    lines.push(FRONTMATTER_DELIM);
+    return lines.join('\n') + '\n';
+}
+/**
+ * Parse the leading `---\n...\n---\n` frontmatter block from a markdown file.
+ * Returns the parsed fields (only the ones we emit) and the body that follows.
+ * Throws if the file does not start with frontmatter.
+ */
+export function parseFrontmatter(text) {
+    if (!text.startsWith(FRONTMATTER_DELIM + '\n')) {
+        throw new Error('File does not start with YAML frontmatter');
+    }
+    const rest = text.slice(FRONTMATTER_DELIM.length + 1);
+    const endIdx = rest.indexOf('\n' + FRONTMATTER_DELIM + '\n');
+    if (endIdx === -1) {
+        throw new Error('Frontmatter block is not closed');
+    }
+    const yaml = rest.slice(0, endIdx);
+    const body = rest.slice(endIdx + ('\n' + FRONTMATTER_DELIM + '\n').length);
+    const fm = {};
+    const ids = [];
+    let inIds = false;
+    for (const rawLine of yaml.split('\n')) {
+        if (rawLine === '')
+            continue;
+        if (rawLine.startsWith('  - ')) {
+            if (inIds)
+                ids.push(unquote(rawLine.slice(4)));
+            continue;
+        }
+        inIds = false;
+        const colonIdx = rawLine.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = rawLine.slice(0, colonIdx).trim();
+        const value = rawLine.slice(colonIdx + 1).trim();
+        if (key === 'source_memory_ids') {
+            inIds = true;
+            continue;
+        }
+        if (key === 'source_count') {
+            fm.source_count = Number(value);
+        }
+        else if (key === 'source_git_sha') {
+            fm.source_git_sha = value === 'null' ? null : unquote(value);
+        }
+        else if (key === 'generated_at')
+            fm.generated_at = unquote(value);
+        else if (key === 'compile_run_id')
+            fm.compile_run_id = unquote(value);
+        else if (key === 'provider')
+            fm.provider = unquote(value);
+        else if (key === 'tier')
+            fm.tier = unquote(value);
+        else if (key === 'topic')
+            fm.topic = unquote(value);
+    }
+    fm.source_memory_ids = ids;
+    return { frontmatter: fm, body };
+}
+function quote(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+function unquote(s) {
+    if (s.startsWith('"') && s.endsWith('"')) {
+        return s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    }
+    return s;
+}
+/**
+ * Extract `## H2` and `### H3` headers from a markdown body. Used by B.R5/B.AC3
+ * stability check: header set across two runs must be identical.
+ */
+export function extractHeaders(body) {
+    const out = [];
+    for (const line of body.split('\n')) {
+        const m = line.match(/^(##|###)\s+(.+?)\s*$/);
+        if (m)
+            out.push(`${m[1]} ${m[2].trim()}`);
+    }
+    return out;
+}
+/**
+ * Strip frontmatter, headers, and inline citation tags (`<m:abc-123>`,
+ * `[m:abc-123]`) so the remaining body text can be Levenshtein-compared
+ * for prose-level variance (B.R5/B.AC3 third clause).
+ */
+export function stripForBodyComparison(text) {
+    // Remove frontmatter if present
+    let body = text;
+    if (body.startsWith(FRONTMATTER_DELIM + '\n')) {
+        const rest = body.slice(FRONTMATTER_DELIM.length + 1);
+        const endIdx = rest.indexOf('\n' + FRONTMATTER_DELIM + '\n');
+        if (endIdx !== -1)
+            body = rest.slice(endIdx + ('\n' + FRONTMATTER_DELIM + '\n').length);
+    }
+    // Remove markdown header lines
+    body = body
+        .split('\n')
+        .filter((l) => !l.match(/^#{1,6}\s/))
+        .join('\n');
+    // Remove citation tags
+    body = body.replace(/<m:[a-zA-Z0-9-]+>/g, '');
+    body = body.replace(/\[m:[a-zA-Z0-9-]+\]/g, '');
+    // Collapse whitespace
+    return body.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Levenshtein distance ratio (1.0 = identical, 0.0 = totally different).
+ * Used by B.R5/B.AC3 to bound prose-level variance.
+ */
+export function levenshteinRatio(a, b) {
+    if (a === b)
+        return 1.0;
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1.0;
+    return 1 - levenshtein(a, b) / maxLen;
+}
+function levenshtein(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // Two-row DP for memory efficiency
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}

package/dist/compiler/manifest.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compile manifest — written each run. Stale-cleanup logic uses it to delete
+ * compiled files that are no longer covered by the latest manifest (B.R8).
+ *
+ * Per-tier and per-topic invocations only update their own scoped entries.
+ * A full `compile({all: true})` rewrites everything in scope.
+ */
+import type { CompileManifest, Tier } from './types.js';
+export declare function manifestPath(compiledDir: string): string;
+export declare function readManifest(compiledDir: string): Promise<CompileManifest | null>;
+export declare function writeManifest(compiledDir: string, manifest: CompileManifest): Promise<string>;
+/**
+ * Compute the set of files in `prev` that are NOT in `next` and should be
+ * deleted (B.AC8). Honors per-tier / per-topic scope: if `next` only updates
+ * the `preferences` tier and the `wiki-mode` topic, don't delete entries
+ * for other tiers or topics.
+ *
+ * `scope` lists what was updated this run:
+ *   - `tiers`: which tier paths were rewritten
+ *   - `topics`: which topic slugs were rewritten
+ *   - `allTiers`: true if this was a full compile and ALL tiers should be
+ *     considered in scope (so dropped tiers also get cleaned up — but in
+ *     practice the three tier names are fixed)
+ *   - `allTopics`: true if topic-set was rewritten as a whole; tiers/topics
+ *     not in `next` and present in `prev` get deleted
+ */
+export declare function computeStaleFiles(prev: CompileManifest | null, next: CompileManifest, scope: {
+    tiers: Tier[];
+    topics: string[];
+    allTopics: boolean;
+}): string[];
+export declare function deleteStaleFiles(compiledDir: string, paths: string[]): Promise<void>;

package/dist/compiler/manifest.js

@@ -0,0 +1,82 @@
+/**
+ * Compile manifest — written each run. Stale-cleanup logic uses it to delete
+ * compiled files that are no longer covered by the latest manifest (B.R8).
+ *
+ * Per-tier and per-topic invocations only update their own scoped entries.
+ * A full `compile({all: true})` rewrites everything in scope.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+const MANIFEST_FILENAME = 'manifest.json';
+export function manifestPath(compiledDir) {
+    return join(compiledDir, MANIFEST_FILENAME);
+}
+export async function readManifest(compiledDir) {
+    const p = manifestPath(compiledDir);
+    if (!existsSync(p))
+        return null;
+    try {
+        const raw = await readFile(p, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeManifest(compiledDir, manifest) {
+    const p = manifestPath(compiledDir);
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, JSON.stringify(manifest, null, 2), 'utf-8');
+    return p;
+}
+/**
+ * Compute the set of files in `prev` that are NOT in `next` and should be
+ * deleted (B.AC8). Honors per-tier / per-topic scope: if `next` only updates
+ * the `preferences` tier and the `wiki-mode` topic, don't delete entries
+ * for other tiers or topics.
+ *
+ * `scope` lists what was updated this run:
+ *   - `tiers`: which tier paths were rewritten
+ *   - `topics`: which topic slugs were rewritten
+ *   - `allTiers`: true if this was a full compile and ALL tiers should be
+ *     considered in scope (so dropped tiers also get cleaned up — but in
+ *     practice the three tier names are fixed)
+ *   - `allTopics`: true if topic-set was rewritten as a whole; tiers/topics
+ *     not in `next` and present in `prev` get deleted
+ */
+export function computeStaleFiles(prev, next, scope) {
+    if (!prev)
+        return [];
+    const stale = new Set();
+    const nextTierPaths = new Set(next.tiers.map((t) => t.path));
+    const nextTopicPaths = new Set(next.topics.map((t) => t.path));
+    // Tier files: only candidates within our scope.
+    for (const t of prev.tiers) {
+        if (!scope.tiers.includes(t.tier))
+            continue;
+        if (!nextTierPaths.has(t.path))
+            stale.add(t.path);
+    }
+    // Topic files: if allTopics, every prev topic that's not in next is stale.
+    // Otherwise, only the topics named in scope.topics.
+    for (const t of prev.topics) {
+        if (scope.allTopics) {
+            if (!nextTopicPaths.has(t.path))
+                stale.add(t.path);
+        }
+        else if (scope.topics.includes(t.topic)) {
+            if (!nextTopicPaths.has(t.path))
+                stale.add(t.path);
+        }
+    }
+    return [...stale];
+}
+export async function deleteStaleFiles(compiledDir, paths) {
+    for (const rel of paths) {
+        const abs = resolve(compiledDir, rel);
+        if (existsSync(abs)) {
+            await rm(abs, { force: true });
+        }
+    }
+}

package/dist/compiler/prompts.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Synthesis prompts for tier and topic compile. Kept in their own module so
+ * tests can snapshot them and developers can iterate on prompt language
+ * without scrolling through synthesis logic.
+ *
+ * Design contract (B.R5 stability):
+ *   - The compiler controls structure (headers, citation placeholders).
+ *   - The LLM produces only the prose paragraphs.
+ *   - Citation tags are inserted by the compiler, not the LLM, so the set
+ *     of cited memory IDs is identical across runs.
+ */
+import type { MemoryForCompile, Tier } from './types.js';
+export declare function tierSystemPrompt(tier: Tier): string;
+export declare function topicSystemPrompt(): string;
+export declare function memoryListPromptFragment(memories: MemoryForCompile[]): string;
+export declare function tierClusterUserPrompt(topic: string, memories: MemoryForCompile[]): string;
+export declare function topicSectionUserPrompt(topic: string, section: 'Summary' | 'Key Decisions' | 'Open Questions', memories: MemoryForCompile[]): string;

package/dist/compiler/prompts.js

@@ -0,0 +1,82 @@
+/**
+ * Synthesis prompts for tier and topic compile. Kept in their own module so
+ * tests can snapshot them and developers can iterate on prompt language
+ * without scrolling through synthesis logic.
+ *
+ * Design contract (B.R5 stability):
+ *   - The compiler controls structure (headers, citation placeholders).
+ *   - The LLM produces only the prose paragraphs.
+ *   - Citation tags are inserted by the compiler, not the LLM, so the set
+ *     of cited memory IDs is identical across runs.
+ */
+const TIER_INTENT = {
+    preferences: 'a browsable summary of preferences and decisions',
+    'project-context': 'a browsable summary of architecture and project state',
+    conversations: 'a browsable summary of relationship continuity and recurring threads',
+};
+export function tierSystemPrompt(tier) {
+    return `You produce ${TIER_INTENT[tier]} for a personal AI memory store.
+
+Write a single concise paragraph (2-4 sentences) per cluster. Do NOT add headers, lists, or citation tags — those are inserted by the compiler around your output. Speak in present tense. Stay grounded in the cluster content; do not invent decisions or context.
+
+Reply with ONLY the paragraph text — no preamble, no closing remarks.`;
+}
+export function topicSystemPrompt() {
+    return `You write a single section of an LLM wiki page about a topic. The section name and the source memories are given. Write a concise paragraph (2-5 sentences) capturing the section's content.
+
+Do NOT add headers, lists, or citation tags — the compiler inserts those. Stay grounded; do not speculate beyond the source memories. If the section is empty (no relevant content), reply with the literal string: NONE`;
+}
+export function memoryListPromptFragment(memories) {
+    return memories.map((m) => `- (id=${m.id}, type=${m.type}) ${m.content}`).join('\n');
+}
+export function tierClusterUserPrompt(topic, memories) {
+    const edgeNote = describeEdges(memories);
+    return [
+        `Cluster topic: ${topic}`,
+        'Source memories:',
+        memoryListPromptFragment(memories),
+        edgeNote ? `\nKnown structural relationships:\n${edgeNote}` : '',
+        '\nWrite the paragraph.',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+export function topicSectionUserPrompt(topic, section, memories) {
+    const edgeNote = describeEdges(memories);
+    return [
+        `Topic: ${topic}`,
+        `Section: ${section}`,
+        'Source memories:',
+        memoryListPromptFragment(memories),
+        edgeNote ? `\nKnown structural relationships:\n${edgeNote}` : '',
+        '\nWrite the section paragraph (or NONE if no content fits this section).',
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+/**
+ * Surface superseded / contradicted relationships so the LLM frames history
+ * accurately (B.AC7). Only mentions relations that affect prose framing.
+ */
+function describeEdges(memories) {
+    const lines = [];
+    const ids = new Set(memories.map((m) => m.id));
+    for (const m of memories) {
+        if (!m.edges)
+            continue;
+        for (const e of m.edges) {
+            if (!ids.has(e.from_memory_id) || !ids.has(e.to_memory_id))
+                continue;
+            if (e.relation === 'supersedes') {
+                lines.push(`- ${e.from_memory_id} supersedes ${e.to_memory_id} — ${e.rationale}`);
+            }
+            else if (e.relation === 'contradicts') {
+                lines.push(`- ${e.from_memory_id} contradicts ${e.to_memory_id} — ${e.rationale}`);
+            }
+            else if (e.relation === 'evolved_into') {
+                lines.push(`- ${e.from_memory_id} evolved into ${e.to_memory_id} — ${e.rationale}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}

package/dist/compiler/run.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Compile orchestrator — composes tier and topic synthesis, writes files,
+ * cleans stale outputs, and produces the run summary.
+ *
+ * `runCompile()` is dependency-injected so tests can run it without a DB:
+ * pass in the memory list and a mocked LLMProvider, get back the summary
+ * plus an in-memory file map for assertions.
+ */
+import type { CompileManifest, CompileSummary, MemoryForCompile, Tier } from './types.js';
+import type { LLMProvider } from '../providers/types.js';
+export interface RunCompileOptions {
+    /** Compile a single tier. Mutually exclusive with `all` and `topic`. */
+    tier?: Tier;
+    /** Compile all three tiers. */
+    all?: boolean;
+    /** Compile a single topic page. Mutually exclusive with `tier` and `all`. */
+    topic?: string;
+    /** When true, emit preview to stdout and write no files. */
+    dryRun?: boolean;
+    /** Maximum total cost across all sections in the run. */
+    maxCostUsd: number;
+    runId: string;
+    startedAt: string;
+    /** git rev-parse HEAD of the host repo, or null. */
+    sourceGitSha: string | null;
+    /** Compiled output directory. Default: `<projectRoot>/memory/compiled/`. */
+    compiledDir: string;
+}
+export interface RunCompileDeps {
+    /**
+     * Returns the memories visible to compile. CLI implementations pass a DB
+     * query; tests inject synthetic data.
+     */
+    loadMemories: () => Promise<MemoryForCompile[]>;
+    provider: LLMProvider;
+    /**
+     * Test seam — replaces `writeFile`/`rm` calls with in-memory recording.
+     * Default: real filesystem.
+     */
+    fs?: CompileFs;
+    /** Test seam for stdout (dry-run preview). Default: process.stdout.write. */
+    stdout?: (chunk: string) => void;
+}
+export interface CompileFs {
+    ensureDir: (path: string) => Promise<void>;
+    writeFile: (path: string, content: string) => Promise<void>;
+    deleteFile: (path: string) => Promise<void>;
+    readManifest: (compiledDir: string) => Promise<CompileManifest | null>;
+    writeManifest: (compiledDir: string, manifest: CompileManifest) => Promise<string>;
+    exists: (path: string) => boolean;
+}
+export declare function runCompile(opts: RunCompileOptions, deps: RunCompileDeps): Promise<CompileSummary>;