@vishnuvmx/recall-memory 0.0.0-stage → 0.1.0

package/dist/core/checkpoint.js

@@ -0,0 +1,233 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from './config.js';
+import { repoChanges } from './git.js';
+import { atomicWrite, resolveInside, today } from '../utils/fs.js';
+export function getCurrentTimestamp() {
+    const d = new Date();
+    return d.toISOString().replace('T', ' ').substring(0, 19);
+}
+export function parseSessionLogEntries(logContent) {
+    const entries = [];
+    const lines = logContent.split('\n');
+    let currentHeader = null;
+    let currentLines = [];
+    let summary = '';
+    let nextSteps;
+    let modifiedFiles;
+    const flush = () => {
+        if (currentHeader) {
+            entries.push({
+                timestamp: currentHeader.timestamp,
+                date: currentHeader.date,
+                summary: summary || 'Task checkpoint',
+                nextSteps,
+                modifiedFiles,
+                rawText: currentLines.join('\n').trim(),
+            });
+        }
+        currentHeader = null;
+        currentLines = [];
+        summary = '';
+        nextSteps = undefined;
+        modifiedFiles = undefined;
+    };
+    for (const line of lines) {
+        const match = line.match(/^###\s*\[(\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2})\]\s*Checkpoint/i);
+        if (match) {
+            flush();
+            const ts = match[1];
+            const parsedDate = new Date(ts.replace(' ', 'T') + 'Z');
+            currentHeader = {
+                timestamp: ts,
+                date: isNaN(parsedDate.getTime()) ? new Date() : parsedDate,
+            };
+            currentLines.push(line);
+            continue;
+        }
+        if (currentHeader) {
+            currentLines.push(line);
+            const summaryMatch = line.match(/^-\s*\*\*Summary\*\*:\s*(.*)$/i);
+            if (summaryMatch) {
+                summary = summaryMatch[1].trim();
+            }
+            const nextMatch = line.match(/^-\s*\*\*Next\*\*:\s*(.*)$/i);
+            if (nextMatch) {
+                nextSteps = nextMatch[1].trim();
+            }
+            const modMatch = line.match(/^-\s*\*\*Modified\*\*:\s*(.*)$/i);
+            if (modMatch) {
+                modifiedFiles = modMatch[1].split(',').map((f) => f.trim()).filter(Boolean);
+            }
+        }
+    }
+    flush();
+    return entries;
+}
+export function pruneSessionLog(logContent, opts = {}) {
+    const retentionDays = opts.retentionDays ?? 14;
+    const maxEntries = opts.maxEntries ?? 50;
+    const now = opts.now ?? new Date();
+    const cutoffTime = now.getTime() - retentionDays * 24 * 60 * 60 * 1000;
+    const entries = parseSessionLogEntries(logContent);
+    if (entries.length === 0) {
+        return {
+            content: logContent.trim() ? logContent.trim() : '# Session Log',
+            retained: [],
+            removedCount: 0,
+        };
+    }
+    // Filter out entries older than retention cutoff (e.g. 14 days)
+    let retained = entries.filter((e) => e.date.getTime() >= cutoffTime);
+    // If total entries still exceed maxEntries, keep only the newest ones
+    if (retained.length > maxEntries) {
+        retained = retained.slice(-maxEntries);
+    }
+    const removedCount = entries.length - retained.length;
+    const header = '# Session Log';
+    const body = retained.map((e) => e.rawText).join('\n\n');
+    const content = body ? `${header}\n\n${body}\n` : `${header}\n`;
+    return {
+        content,
+        retained,
+        removedCount,
+    };
+}
+export function pruneSessions(recallDir, opts = {}) {
+    const logFile = path.join(recallDir, 'sessions', 'session-log.md');
+    if (!fs.existsSync(logFile)) {
+        return { removedCount: 0, remainingCount: 0 };
+    }
+    let retentionDays = 14;
+    let maxEntries = 50;
+    try {
+        const cfg = loadConfig(recallDir);
+        if (cfg.retentionDays)
+            retentionDays = cfg.retentionDays;
+        if (cfg.maxLogEntries)
+            maxEntries = cfg.maxLogEntries;
+    }
+    catch {
+        // Non-fatal fallback to defaults
+    }
+    if (opts.retentionDays !== undefined)
+        retentionDays = opts.retentionDays;
+    if (opts.maxEntries !== undefined)
+        maxEntries = opts.maxEntries;
+    const raw = fs.readFileSync(logFile, 'utf8');
+    const res = pruneSessionLog(raw, { retentionDays, maxEntries, now: opts.now });
+    atomicWrite(logFile, res.content);
+    return { removedCount: res.removedCount, remainingCount: res.retained.length };
+}
+export function buildCurrentStateMarkdown(result) {
+    const lines = [
+        '# Previous Iteration State (Historical Context Only)',
+        '',
+        `> **Last Updated**: ${result.timestamp}`,
+        '> **AI AGENTS**: This records what happened in the PREVIOUS session. DO NOT execute these files or next steps unless the user explicitly asks to continue that specific work. Always prioritize the user\'s current prompt.',
+        '',
+        '## Previous Progress',
+        result.summary,
+        '',
+    ];
+    if (result.nextSteps) {
+        lines.push('## Previous Task Next Steps (Conditional on User Request)', result.nextSteps, '');
+    }
+    lines.push('## Files Modified in Previous Task');
+    if (result.modifiedFiles.length === 0) {
+        lines.push('_Working directory clean or no uncommitted changes._');
+    }
+    else {
+        for (const file of result.modifiedFiles) {
+            lines.push(`- \`${file}\``);
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+export function recordCheckpoint(root, recallDir, summary, opts = {}) {
+    const rawChanges = repoChanges(root) ?? [];
+    const modifiedFiles = opts.clear ? [] : rawChanges.slice(0, 20); // Top 20 active files
+    let cleanSummary = summary?.trim();
+    if (opts.clear) {
+        cleanSummary = 'Previous task completed. Ready for new instructions.';
+    }
+    else if (!cleanSummary || cleanSummary === 'Task checkpoint' || opts.auto) {
+        if (modifiedFiles.length > 0) {
+            const sample = modifiedFiles.slice(0, 3).join(', ');
+            const extra = modifiedFiles.length > 3 ? ` (+${modifiedFiles.length - 3} more)` : '';
+            cleanSummary = `Session update: modified ${sample}${extra}`;
+        }
+        else {
+            cleanSummary = 'Session chat iteration completed (working directory clean)';
+        }
+    }
+    const timestamp = getCurrentTimestamp();
+    const sessionLogDir = path.join(recallDir, 'sessions');
+    const logFile = path.join(sessionLogDir, 'session-log.md');
+    const existingRaw = fs.existsSync(logFile) ? fs.readFileSync(logFile, 'utf8') : '';
+    // The Stop hook fires after every agent turn; don't log a new entry when nothing changed.
+    if (opts.auto && !opts.clear) {
+        const last = parseSessionLogEntries(existingRaw).at(-1);
+        const lastFiles = last?.modifiedFiles ?? [];
+        const same = lastFiles.length === modifiedFiles.length && lastFiles.every((f, i) => f === modifiedFiles[i]);
+        if (last && same && last.summary.startsWith('Session ')) {
+            return { timestamp: last.timestamp, summary: last.summary, modifiedFiles, skipped: true };
+        }
+    }
+    const result = {
+        timestamp,
+        summary: cleanSummary,
+        nextSteps: opts.clear ? undefined : opts.nextSteps?.trim(),
+        modifiedFiles,
+    };
+    const currentStateFile = resolveInside(recallDir, 'CURRENT_STATE.md');
+    atomicWrite(currentStateFile, buildCurrentStateMarkdown(result));
+    fs.mkdirSync(sessionLogDir, { recursive: true });
+    const entryLines = [
+        `### [${timestamp}] Checkpoint`,
+        `- **Summary**: ${cleanSummary}`,
+    ];
+    if (result.nextSteps) {
+        entryLines.push(`- **Next**: ${result.nextSteps}`);
+    }
+    if (modifiedFiles.length > 0) {
+        entryLines.push(`- **Modified**: ${modifiedFiles.join(', ')}`);
+    }
+    const logEntry = `${entryLines.join('\n')}\n\n`;
+    let retentionDays = 14;
+    let maxEntries = 50;
+    try {
+        const cfg = loadConfig(recallDir);
+        if (cfg.retentionDays)
+            retentionDays = cfg.retentionDays;
+        if (cfg.maxLogEntries)
+            maxEntries = cfg.maxLogEntries;
+    }
+    catch {
+        // Non-fatal if config missing or uninitialized
+    }
+    if (opts.retentionDays !== undefined)
+        retentionDays = opts.retentionDays;
+    if (opts.maxEntries !== undefined)
+        maxEntries = opts.maxEntries;
+    const existingLog = existingRaw ? existingRaw.trimEnd() : '# Session Log';
+    const combinedLog = `${existingLog}\n\n${logEntry}`;
+    const pruned = pruneSessionLog(combinedLog, { retentionDays, maxEntries });
+    atomicWrite(logFile, pruned.content);
+    // Deliberately no agent-file or project-map rewrites here: checkpoints run from a hook after every
+    // session, and mutating always-on agent instructions would invalidate provider prompt caches.
+    return result;
+}
+export function initialCurrentStateMarkdown() {
+    return [
+        '# Project State (Ready)',
+        '',
+        `> **Initialized**: ${today()}`,
+        '> **AI AGENTS**: Project initialized. Always prioritize the user\'s immediate prompt.',
+        '',
+        '## Status',
+        'Ready for tasks. No previous work in progress.',
+        '',
+    ].join('\n');
+}

package/dist/core/config.d.ts

@@ -0,0 +1,5 @@
+import { type RecallConfig } from '../schemas/index.js';
+export declare function configPath(recallDir: string): string;
+export declare function defaultConfig(): RecallConfig;
+export declare function loadConfig(recallDir: string): RecallConfig;
+export declare function writeConfig(recallDir: string, cfg: RecallConfig): void;

package/dist/core/config.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { configSchema } from '../schemas/index.js';
+import { RecallError, atomicWrite } from '../utils/fs.js';
+export function configPath(recallDir) {
+    return path.join(recallDir, 'config.json');
+}
+export function defaultConfig() {
+    return { version: 1, agentFile: 'AGENTS.md', profile: 'standard', retentionDays: 14, maxLogEntries: 50, writes: 'auto' };
+}
+export function loadConfig(recallDir) {
+    const file = configPath(recallDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        throw new RecallError(`Cannot read ${file}: ${err.message}`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        throw new RecallError(`${file} is not valid JSON.`, 'Fix the syntax or restore it from Git (`git checkout -- .recall/config.json`).');
+    }
+    const parsed = configSchema.safeParse(json);
+    if (!parsed.success) {
+        const msg = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+        throw new RecallError(`Invalid config: ${msg}`, 'Fix .recall/config.json or restore it from Git.');
+    }
+    return parsed.data;
+}
+export function writeConfig(recallDir, cfg) {
+    atomicWrite(configPath(recallDir), `${JSON.stringify(cfg, null, 2)}\n`);
+}

package/dist/core/cost.d.ts

@@ -0,0 +1,19 @@
+/** Rough estimate (~4 chars/token for English/code). Labelled as an estimate everywhere it is shown. */
+export declare const estimateTokens: (text: string) => number;
+export interface CostLine {
+    source: string;
+    tokens: number;
+    note?: string;
+}
+export interface CostReport {
+    /** Sent on every agent turn. */
+    alwaysOn: CostLine[];
+    alwaysOnTotal: number;
+    /** Only sent if the MCP server is configured. */
+    mcp: CostLine;
+    /** Only paid when the agent explicitly reads/calls it. */
+    onDemand: CostLine[];
+    /** Problems that make Recall cost more than it should (fixed by re-running `recall init`). */
+    warnings: string[];
+}
+export declare function costReport(start: string): CostReport;

package/dist/core/cost.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { HOOK_COMMAND, HOOK_NAME } from './agent.js';
+import { loadConfig } from './config.js';
+import { requireInitialized } from './project.js';
+import { TOOLS } from '../mcp/server.js';
+import { extractManagedBlock } from '../utils/managed.js';
+/** Rough estimate (~4 chars/token for English/code). Labelled as an estimate everywhere it is shown. */
+export const estimateTokens = (text) => Math.ceil(text.length / 4);
+function read(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function costReport(start) {
+    const p = requireInitialized(start);
+    let agentFile = 'AGENTS.md';
+    try {
+        agentFile = loadConfig(p.recallDir).agentFile;
+    }
+    catch {
+        /* surfaced by `recall doctor` */
+    }
+    const alwaysOn = [];
+    const warnings = [];
+    const agentText = read(path.join(p.root, agentFile));
+    const agentBlock = agentText ? extractManagedBlock(agentText) : null;
+    alwaysOn.push({ source: `${agentFile} (Recall block only)`, tokens: agentBlock ? estimateTokens(agentBlock) : 0, note: agentBlock ? undefined : 'not installed' });
+    const ruleText = read(path.join(p.root, '.agents', 'rules', 'recall.md'));
+    const ruleBlock = ruleText ? extractManagedBlock(ruleText) : null;
+    if (ruleBlock) {
+        alwaysOn.push({ source: '.agents/rules/recall.md (Recall block)', tokens: estimateTokens(ruleBlock) });
+        if (agentFile === 'AGENTS.md' || agentFile === 'GEMINI.md') {
+            warnings.push('.agents/rules/recall.md duplicates the AGENTS.md instructions (legacy). Run `recall init` to remove it.');
+        }
+        if (/Current Working State|Previous Progress/.test(ruleBlock)) {
+            warnings.push('Always-on rule embeds session state, which changes every session and defeats prompt caching. Run `recall init`.');
+        }
+    }
+    const skillText = read(path.join(p.root, '.agents', 'skills', 'recall', 'SKILL.md'));
+    const skillDesc = skillText ? /description:\s*(.*)/.exec(skillText)?.[1] ?? '' : '';
+    if (skillText)
+        alwaysOn.push({ source: 'skill name + description', tokens: estimateTokens(`recall ${skillDesc}`) });
+    const hooksText = read(path.join(p.root, '.agents', 'hooks.json'));
+    if (hooksText) {
+        try {
+            const hooks = JSON.parse(hooksText);
+            const cmd = hooks[HOOK_NAME]?.Stop?.[0]?.command;
+            if (cmd && cmd !== HOOK_COMMAND) {
+                warnings.push(`Checkpoint hook uses an outdated command (\`${cmd}\`) that does not run outside the Recall repo. Run \`recall init\`.`);
+            }
+        }
+        catch {
+            warnings.push('.agents/hooks.json is not valid JSON.');
+        }
+    }
+    const onDemand = [];
+    const addFile = (rel, note) => {
+        const t = read(path.join(p.recallDir, rel));
+        if (t !== null)
+            onDemand.push({ source: `.recall/${rel}`, tokens: estimateTokens(t), note });
+    };
+    if (skillText)
+        onDemand.push({ source: 'skill body', tokens: estimateTokens(skillText) - estimateTokens(skillDesc), note: 'loaded when the agent picks the skill' });
+    onDemand.push({ source: '`recall context` response', tokens: 400, note: 'hard cap' });
+    addFile('CURRENT_STATE.md', 'read only for continue/resume');
+    addFile('PROJECT_MAP.md', 'for humans; agents use `recall where`');
+    return {
+        alwaysOn,
+        alwaysOnTotal: alwaysOn.reduce((s, l) => s + l.tokens, 0),
+        mcp: { source: `MCP tool schemas (${TOOLS.length} tools)`, tokens: estimateTokens(JSON.stringify(TOOLS)), note: 'only if `recall serve` is configured' },
+        onDemand,
+        warnings,
+    };
+}

package/dist/core/doctor.d.ts

@@ -0,0 +1,7 @@
+export interface Check {
+    name: string;
+    ok: boolean;
+    detail: string;
+    fix?: string;
+}
+export declare function runDoctor(start: string): Check[];

package/dist/core/doctor.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { agentState } from './agent.js';
+import { loadConfig } from './config.js';
+import { gitInfo, recallChanges } from './git.js';
+import { brokenIndexLinks, indexState } from './index-builder.js';
+import { loadAll } from './memory.js';
+import { findProject } from './project.js';
+const REQUIRED = ['rules', 'decisions', 'lessons', 'tasks', 'sessions', 'logs'];
+export function runDoctor(start) {
+    const p = findProject(start);
+    const checks = [];
+    const add = (name, ok, detail, fix) => {
+        checks.push({ name, ok, detail, ...(fix ? { fix } : {}) });
+    };
+    add('project root', true, `${p.root} (found via ${p.source})`);
+    if (!p.initialized) {
+        add('initialized', false, 'No .recall/config.json found.', 'Run `recall init`.');
+        return checks;
+    }
+    let agentFile = 'AGENTS.md';
+    try {
+        agentFile = loadConfig(p.recallDir).agentFile;
+        add('config', true, '.recall/config.json is valid');
+    }
+    catch (err) {
+        add('config', false, err.message, 'Fix .recall/config.json or `git checkout -- .recall/config.json`.');
+    }
+    for (const d of REQUIRED) {
+        const ok = fs.existsSync(path.join(p.recallDir, d));
+        if (!ok)
+            add(`directory ${d}/`, false, 'missing', `Run \`recall init\` (safe to repeat) or mkdir .recall/${d}`);
+    }
+    for (const f of ['MEMORY.md', 'INDEX.md', 'PROJECT_MAP.md', 'CURRENT_STATE.md']) {
+        const ok = fs.existsSync(path.join(p.recallDir, f));
+        if (!ok) {
+            let fix = 'Run `recall init`.';
+            if (f === 'INDEX.md')
+                fix = 'Run `recall rebuild`.';
+            if (f === 'PROJECT_MAP.md')
+                fix = 'Run `recall map`.';
+            add(f, false, 'missing', fix);
+        }
+    }
+    const loaded = loadAll(p.recallDir);
+    if (loaded.problems.length === 0)
+        add('memory files', true, `${loaded.memories.length} valid memories`);
+    for (const pr of loaded.problems)
+        add(`memory ${pr.file}`, false, pr.error, 'Edit the file to fix its frontmatter. Recall will not delete it.');
+    const state = indexState(p.recallDir);
+    add('index', state === 'up_to_date', state, state === 'up_to_date' ? undefined : 'Run `recall rebuild`.');
+    const broken = brokenIndexLinks(p.recallDir);
+    if (broken.length > 0)
+        add('index links', false, `broken: ${broken.join(', ')}`, 'Run `recall rebuild` or fix hand-written links.');
+    try {
+        const a = agentState(p.root, agentFile);
+        add('agent instructions', a === 'installed', `${agentFile}: ${a}`, a === 'installed' ? undefined : 'Run `recall init` to install/refresh the managed block.');
+    }
+    catch (err) {
+        add('agent instructions', false, err.message);
+    }
+    const g = gitInfo(p.root);
+    add('git', g.available, g.available ? (g.isRepo ? 'repository detected' : 'git installed, but not inside a repository') : 'git not installed (history features reduced)');
+    if (g.isRepo) {
+        const ch = recallChanges(p.root);
+        add('uncommitted recall changes', true, ch ? `${ch.length} path(s)` : 'unknown');
+    }
+    return checks;
+}

package/dist/core/git.d.ts

@@ -0,0 +1,27 @@
+export interface GitInfo {
+    available: boolean;
+    isRepo: boolean;
+}
+export declare function gitInfo(cwd: string): GitInfo;
+/** Uncommitted changes limited to the .recall path only. */
+export declare function recallChanges(root: string, recallRel?: string): string[] | null;
+/** Uncommitted changed file paths across the repository (excluding .recall). */
+export declare function repoChanges(root: string): string[] | null;
+export interface Commit {
+    hash: string;
+    date: string;
+    subject: string;
+}
+/** Committed history for .recall only. Returns null when unavailable. */
+export declare function recallHistory(root: string, limit: number, recallRel?: string): Commit[] | null;
+export interface UndoResult {
+    ok: boolean;
+    message: string;
+    dryRun?: boolean;
+    restored?: string[];
+    cleaned?: string[];
+}
+/** Revert all uncommitted changes and delete untracked files in .recall/ (never touches gitignored files) */
+export declare function undoRecall(root: string, recallRel?: string, opts?: {
+    dryRun?: boolean;
+}): UndoResult;

package/dist/core/git.js

@@ -0,0 +1,107 @@
+import { spawnSync } from 'node:child_process';
+function run(args, cwd) {
+    // --no-optional-locks keeps status strictly read-only (no index refresh writes).
+    const r = spawnSync('git', ['--no-optional-locks', '-c', 'core.quotepath=off', ...args], {
+        cwd,
+        encoding: 'utf8',
+        windowsHide: true,
+    });
+    if (r.error || r.status !== 0)
+        return { ok: false, out: '' };
+    return { ok: true, out: r.stdout };
+}
+export function gitInfo(cwd) {
+    const v = spawnSync('git', ['--version'], { encoding: 'utf8', windowsHide: true });
+    if (v.error || v.status !== 0)
+        return { available: false, isRepo: false };
+    const r = run(['rev-parse', '--is-inside-work-tree'], cwd);
+    return { available: true, isRepo: r.ok && r.out.trim() === 'true' };
+}
+/** Uncommitted changes limited to the .recall path only. */
+export function recallChanges(root, recallRel = '.recall') {
+    const r = run(['status', '--porcelain', '--', recallRel], root);
+    if (!r.ok)
+        return null;
+    return r.out.split('\n').filter(Boolean);
+}
+/** Uncommitted changed file paths across the repository (excluding .recall). */
+export function repoChanges(root) {
+    const r = run(['status', '--porcelain', '-uall'], root);
+    if (!r.ok)
+        return null;
+    const files = [];
+    for (const line of r.out.split('\n')) {
+        if (!line || line.length < 4)
+            continue;
+        // Porcelain v1 format is: XY <path> or XY <orig> -> <new>
+        let p = line.slice(3).trim();
+        if (p.includes(' -> ')) {
+            p = p.split(' -> ')[1].trim();
+        }
+        if (p.startsWith('"') && p.endsWith('"')) {
+            p = p.slice(1, -1);
+        }
+        const normalized = p.replace(/\\/g, '/');
+        if (!normalized.startsWith('.recall/') && normalized !== '.recall') {
+            files.push(normalized);
+        }
+    }
+    return [...new Set(files)];
+}
+/** Committed history for .recall only. Returns null when unavailable. */
+export function recallHistory(root, limit, recallRel = '.recall') {
+    const r = run(['log', `-n${limit}`, '--format=%h%x09%ad%x09%s', '--date=short', '--', recallRel], root);
+    if (!r.ok)
+        return null;
+    return r.out
+        .split('\n')
+        .filter(Boolean)
+        .map((l) => {
+        const [hash = '', date = '', ...rest] = l.split('\t');
+        return { hash, date, subject: rest.join('\t') };
+    });
+}
+/** Revert all uncommitted changes and delete untracked files in .recall/ (never touches gitignored files) */
+export function undoRecall(root, recallRel = '.recall', opts = {}) {
+    const info = gitInfo(root);
+    if (!info.isRepo) {
+        return { ok: false, message: 'Not inside a Git repository. Cannot revert via Git.' };
+    }
+    const diffWorktree = run(['diff', '--name-only', '--', recallRel], root).out.split('\n').filter(Boolean);
+    const diffStaged = run(['diff', '--cached', '--name-only', '--', recallRel], root).out.split('\n').filter(Boolean);
+    const tracked = [...new Set([...diffWorktree, ...diffStaged])];
+    const cleanDry = run(['clean', '-nd', '--', recallRel], root).out.split('\n').filter(Boolean)
+        .map((l) => l.replace(/^Would remove\s+/, ''));
+    if (opts.dryRun) {
+        return {
+            ok: true,
+            dryRun: true,
+            message: `[dry-run] Would restore ${tracked.length} tracked file(s) and delete ${cleanDry.length} untracked file(s). Gitignored files are never touched.`,
+            restored: tracked,
+            cleaned: cleanDry,
+        };
+    }
+    // 1. Restore tracked changes (both staged and worktree)
+    const hasHead = run(['rev-parse', '--verify', 'HEAD'], root).ok;
+    if (hasHead) {
+        let res = run(['restore', '--staged', '--worktree', '--', recallRel], root);
+        if (!res.ok) {
+            run(['reset', 'HEAD', '--', recallRel], root);
+            run(['checkout', '--', recallRel], root);
+        }
+    }
+    else {
+        run(['rm', '--cached', '-r', '-f', '--quiet', '--', recallRel], root);
+    }
+    // 2. Remove untracked files and directories within .recall/
+    const cleanRes = run(['clean', '-fd', '--', recallRel], root);
+    if (!cleanRes.ok) {
+        return { ok: false, message: `Failed to clean untracked files in ${recallRel}.` };
+    }
+    return {
+        ok: true,
+        message: `Reverted all uncommitted changes and removed untracked files in ${recallRel}. Gitignored files were untouched.`,
+        restored: tracked,
+        cleaned: cleanDry,
+    };
+}

package/dist/core/index-builder.d.ts

@@ -0,0 +1,11 @@
+import { type LoadResult } from './memory.js';
+/** Deterministic: depends only on memory metadata, sorted by id. */
+export declare function buildIndexBlock(loaded: LoadResult): string;
+export declare function indexPath(recallDir: string): string;
+export declare function renderIndex(existing: string, loaded: LoadResult): string;
+/** Rebuild INDEX.md; text outside the managed block is preserved. */
+export declare function rebuildIndex(recallDir: string): LoadResult;
+export type IndexState = 'missing' | 'up_to_date' | 'stale' | 'no_managed_block';
+export declare function indexState(recallDir: string): IndexState;
+/** Relative link targets in INDEX.md that do not exist. */
+export declare function brokenIndexLinks(recallDir: string): string[];