@vishnuvmx/recall-memory 0.0.0-stage → 0.1.0

package/dist/core/mapper.js

@@ -0,0 +1,357 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { scanLandmarks, formatLandmarksMarkdown } from './landmarks.js';
+import { loadConfig } from './config.js';
+import { atomicWrite, resolveInside, toPosix } from '../utils/fs.js';
+import { applyManagedBlock } from '../utils/managed.js';
+export const DEFAULT_IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.recall',
+    'dist',
+    'build',
+    'out',
+    '.next',
+    '.nuxt',
+    '.turbo',
+    'coverage',
+    '.cache',
+    '.venv',
+    'venv',
+    '__pycache__',
+    '.idea',
+    '.vscode',
+    '.gemini',
+    'target',
+    'bin',
+    'obj',
+]);
+const ENTRY_FILENAMES = new Set([
+    'index.ts',
+    'index.js',
+    'main.ts',
+    'main.js',
+    'app.ts',
+    'app.js',
+    'main.py',
+    'app.py',
+    'main.go',
+    'main.rs',
+    'index.html',
+    'main.dart',
+    'mainactivity.kt',
+    'mainactivity.java',
+    'appdelegate.swift',
+]);
+const CONFIG_FILENAMES = new Set([
+    'package.json',
+    'tsconfig.json',
+    'pyproject.toml',
+    'requirements.txt',
+    'Cargo.toml',
+    'go.mod',
+    'pom.xml',
+    'build.gradle',
+    'Makefile',
+    'Dockerfile',
+    'docker-compose.yml',
+    'vite.config.ts',
+    'vite.config.js',
+    'next.config.js',
+    'next.config.mjs',
+]);
+const THEME_FILENAMES = new Set([
+    'app_theme.dart',
+    'theme.dart',
+    'app_colors.dart',
+    'colors.dart',
+    'typography.dart',
+    'tokens.css',
+    'theme.ts',
+    'theme.js',
+    'tailwind.config.js',
+    'tailwind.config.ts',
+]);
+import ignore from 'ignore';
+export function createGitignoreFilter(root) {
+    const ignoreFile = path.join(root, '.gitignore');
+    const ig = ignore();
+    if (fs.existsSync(ignoreFile)) {
+        try {
+            ig.add(fs.readFileSync(ignoreFile, 'utf8'));
+        }
+        catch {
+            // ignore syntax issues
+        }
+    }
+    return (relPath, isDir) => {
+        if (!relPath || relPath === '.')
+            return false;
+        const testPath = isDir ? (relPath.endsWith('/') ? relPath : `${relPath}/`) : relPath;
+        try {
+            return ig.ignores(testPath);
+        }
+        catch {
+            return false;
+        }
+    };
+}
+export function parseGitignore(root) {
+    const ignoreFile = path.join(root, '.gitignore');
+    const ignores = new Set();
+    if (!fs.existsSync(ignoreFile))
+        return ignores;
+    const lines = fs.readFileSync(ignoreFile, 'utf8').split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const cleaned = trimmed.replace(/^\/+|\/+$/g, '');
+        if (cleaned && !cleaned.includes('*') && !cleaned.includes('/')) {
+            ignores.add(cleaned);
+        }
+    }
+    return ignores;
+}
+export function scanProject(root, maxDepth = 3, opts) {
+    const isGitignored = createGitignoreFilter(root);
+    const entryPoints = [];
+    const configFiles = [];
+    const themeFiles = [];
+    const directories = [];
+    const treeLines = [];
+    function walk(currentDir, currentDepth, prefix) {
+        if (currentDepth > maxDepth)
+            return;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const dirs = [];
+        const files = [];
+        const extCount = new Map();
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') && entry.name !== '.gitignore' && entry.name !== '.env.example') {
+                if (entry.isDirectory())
+                    continue;
+            }
+            const rel = toPosix(path.relative(root, path.join(currentDir, entry.name)));
+            if (entry.isDirectory()) {
+                if (DEFAULT_IGNORED_DIRS.has(entry.name) || isGitignored(rel, true))
+                    continue;
+                dirs.push(entry);
+            }
+            else if (entry.isFile()) {
+                if (isGitignored(rel, false))
+                    continue;
+                files.push(entry);
+                const ext = path.extname(entry.name).toLowerCase();
+                if (ext)
+                    extCount.set(ext, (extCount.get(ext) ?? 0) + 1);
+                if (currentDepth <= 2 && CONFIG_FILENAMES.has(entry.name)) {
+                    configFiles.push(rel);
+                }
+                const lowerName = entry.name.toLowerCase();
+                if (ENTRY_FILENAMES.has(lowerName) || lowerName.endsWith('sdk.kt') || lowerName.endsWith('plugin.kt')) {
+                    entryPoints.push(rel);
+                }
+                if (THEME_FILENAMES.has(lowerName)) {
+                    themeFiles.push(rel);
+                }
+            }
+        }
+        const relDir = toPosix(path.relative(root, currentDir));
+        if (relDir && relDir !== '.') {
+            const topExts = [...extCount.entries()]
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 3)
+                .map(([e]) => e);
+            directories.push({
+                path: relDir,
+                filesCount: files.length,
+                extensions: topExts,
+            });
+        }
+        dirs.sort((a, b) => a.name.localeCompare(b.name));
+        files.sort((a, b) => a.name.localeCompare(b.name));
+        for (let i = 0; i < dirs.length; i++) {
+            const d = dirs[i];
+            const isLast = i === dirs.length - 1 && files.length === 0;
+            const pointer = isLast ? '\\-- ' : '|-- ';
+            treeLines.push(`${prefix}${pointer}${d.name}/`);
+            walk(path.join(currentDir, d.name), currentDepth + 1, `${prefix}${isLast ? '    ' : '|   '}`);
+        }
+        if (currentDepth <= 1) {
+            const displayFiles = files.slice(0, 6);
+            for (let i = 0; i < displayFiles.length; i++) {
+                const f = displayFiles[i];
+                const isLast = i === displayFiles.length - 1 && displayFiles.length === files.length;
+                const pointer = isLast ? '\\-- ' : '|-- ';
+                treeLines.push(`${prefix}${pointer}${f.name}`);
+            }
+            if (files.length > displayFiles.length) {
+                treeLines.push(`${prefix}\\-- ... (${files.length - displayFiles.length} more files)`);
+            }
+        }
+    }
+    walk(root, 0, '');
+    let projectType = 'Generic project';
+    if (fs.existsSync(path.join(root, 'pubspec.yaml')))
+        projectType = 'Flutter / Dart';
+    else if (fs.existsSync(path.join(root, 'package.json')))
+        projectType = 'Node.js / TypeScript / JavaScript';
+    else if (fs.existsSync(path.join(root, 'Cargo.toml')))
+        projectType = 'Rust';
+    else if (fs.existsSync(path.join(root, 'pyproject.toml')) || fs.existsSync(path.join(root, 'requirements.txt')))
+        projectType = 'Python';
+    else if (fs.existsSync(path.join(root, 'go.mod')))
+        projectType = 'Go';
+    const profile = opts?.profile ?? 'standard';
+    let minLines = 40;
+    let maxFiles = 25;
+    let maxSymbols = 16;
+    if (profile === 'compact') {
+        minLines = 300;
+        maxFiles = 5;
+        maxSymbols = 10;
+    }
+    else if (profile === 'frontier') {
+        minLines = 15;
+        maxFiles = 60;
+        maxSymbols = 30;
+    }
+    const landmarks = scanLandmarks(root, minLines, maxFiles, maxSymbols, opts?.recallDir);
+    return {
+        projectType,
+        entryPoints: [...new Set(entryPoints)].sort(),
+        configFiles: [...new Set(configFiles)].sort(),
+        themeFiles: [...new Set(themeFiles)].sort(),
+        directories,
+        treeView: treeLines.join('\n'),
+        landmarks,
+    };
+}
+export function buildProjectMapMarkdown(data, maxChars = 6000) {
+    // Priority 1: Core Header, Entry Points, Design Tokens, Configs
+    const headerLines = [
+        '# Project Map & Topology',
+        '',
+        '> **AI AGENTS**: Use this blueprint to locate files directly. **DO NOT** execute recursive `list_dir` or crawl directories.',
+        '',
+        `**Project Type**: ${data.projectType}`,
+        '',
+    ];
+    if (data.entryPoints.length > 0) {
+        headerLines.push('## Primary Entry Points');
+        const shown = data.entryPoints.slice(0, 8);
+        for (const ep of shown)
+            headerLines.push(`- \`${ep}\``);
+        if (data.entryPoints.length > 8) {
+            headerLines.push(`- _... (${data.entryPoints.length - 8} more entry points)_`);
+        }
+        headerLines.push('');
+    }
+    if (data.themeFiles && data.themeFiles.length > 0) {
+        headerLines.push('## Design System & Theme Tokens');
+        headerLines.push('When modifying UI components, reuse tokens from:');
+        const shown = data.themeFiles.slice(0, 5);
+        for (const tf of shown)
+            headerLines.push(`- \`${tf}\``);
+        if (data.themeFiles.length > 5) {
+            headerLines.push(`- _... (${data.themeFiles.length - 5} more theme files)_`);
+        }
+        headerLines.push('');
+    }
+    if (data.configFiles.length > 0) {
+        headerLines.push('## Configuration Files');
+        const shown = data.configFiles.slice(0, 8);
+        for (const cf of shown)
+            headerLines.push(`- \`${cf}\``);
+        if (data.configFiles.length > 8) {
+            headerLines.push(`- _... (${data.configFiles.length - 8} more config files)_`);
+        }
+        headerLines.push('');
+    }
+    // Priority 2: High-Value Landmarks (Placed before directory trees so they are protected)
+    const landmarkSection = data.landmarks && data.landmarks.length > 0
+        ? `${formatLandmarksMarkdown(data.landmarks)}\n`
+        : '';
+    // Priority 3: Directory Topology Table
+    const dirTableLines = ['## Directory Topology'];
+    if (data.directories.length === 0) {
+        dirTableLines.push('_Flat directory structure._', '');
+    }
+    else {
+        dirTableLines.push('| Directory | Files | Primary Extensions |');
+        dirTableLines.push('| :--- | :--- | :--- |');
+        const displayDirs = data.directories.slice(0, 15);
+        for (const d of displayDirs) {
+            const exts = d.extensions.length > 0 ? d.extensions.join(', ') : '-';
+            dirTableLines.push(`| \`${d.path}/\` | ${d.filesCount} | ${exts} |`);
+        }
+        if (data.directories.length > 15) {
+            dirTableLines.push(`| _... (${data.directories.length - 15} more subdirectories)_ | - | _(use targeted live search)_ |`);
+        }
+        dirTableLines.push('');
+    }
+    // Priority 4: Structural Directory Tree View (Lowest priority section, dropped first on budget pressure)
+    const treeSection = data.treeView.trim()
+        ? `## Directory Tree (Top Levels)\n\`\`\`text\n${data.treeView}\n\`\`\`\n\n`
+        : '';
+    // Assembly via Priority Budgeting
+    let result = headerLines.join('\n') + (landmarkSection ? `${landmarkSection}\n` : '');
+    // Add Directory Table if it fits within maxChars (leaving at least 300 chars buffer)
+    const dirTableText = `${dirTableLines.join('\n')}\n`;
+    if (result.length + dirTableText.length < maxChars) {
+        result += dirTableText;
+    }
+    else {
+        result += '## Directory Topology\n> _[Directory table omitted to protect landmark budget. Use live targeted search.]_\n\n';
+    }
+    // Add Directory Tree View only if remaining budget permits
+    if (treeSection && result.length + treeSection.length < maxChars) {
+        result += treeSection;
+    }
+    else if (treeSection) {
+        const remaining = maxChars - result.length - 150;
+        if (remaining > 200) {
+            const cut = treeSection.slice(0, remaining);
+            const lastNl = cut.lastIndexOf('\n');
+            result += `${cut.slice(0, lastNl > 0 ? lastNl : cut.length)}\n\`\`\`\n> ... [Directory tree truncated to preserve landmark budget]\n\n`;
+        }
+    }
+    // Hard safety bound
+    if (result.length > maxChars) {
+        const cut = result.slice(0, maxChars - 160);
+        const lastNl = cut.lastIndexOf('\n');
+        result = `${cut.slice(0, lastNl > 0 ? lastNl : cut.length)}\n\n> ... [Project map capped at ${maxChars} chars to protect prompt budget.]\n`;
+    }
+    return result;
+}
+export const MAP_BLOCK_NAME = 'recall:project-map';
+export function renderProjectMap(existing, data, profile = 'standard') {
+    const maxChars = profile === 'compact' ? 5600 : profile === 'frontier' ? 80000 : 24000;
+    const content = buildProjectMapMarkdown(data, maxChars);
+    const base = existing.trim() === '' ? '# Project Map\n' : existing;
+    return applyManagedBlock(base, content, MAP_BLOCK_NAME);
+}
+export function generateProjectMap(root, recallDir, profile) {
+    let effectiveProfile = profile ?? 'standard';
+    if (!profile) {
+        try {
+            effectiveProfile = loadConfig(recallDir).profile ?? 'standard';
+        }
+        catch {
+            effectiveProfile = 'standard';
+        }
+    }
+    const data = scanProject(root, 3, { profile: effectiveProfile, recallDir });
+    const file = resolveInside(recallDir, 'PROJECT_MAP.md');
+    const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const rendered = renderProjectMap(existing, data, effectiveProfile);
+    atomicWrite(file, rendered);
+    return file;
+}

package/dist/core/memory.d.ts

@@ -0,0 +1,44 @@
+import { type Lifecycle, type MemoryMeta, type MemoryType, type Verification } from '../schemas/index.js';
+export interface Memory extends MemoryMeta {
+    body: string;
+    /** Path relative to the .recall directory, POSIX separators. */
+    file: string;
+}
+export interface Problem {
+    file: string;
+    error: string;
+}
+export interface LoadResult {
+    memories: Memory[];
+    /** Plain Markdown docs in rules/ with no frontmatter (hand-written rules). */
+    plainDocs: string[];
+    problems: Problem[];
+}
+export declare const TYPE_DIR: Record<MemoryType, string>;
+export declare const MEMORY_DIRS: readonly ["rules", "decisions", "lessons", "tasks"];
+export declare function slugify(title: string): string;
+export declare function loadAll(recallDir: string): LoadResult;
+export interface NewMemory {
+    title: string;
+    text: string;
+    type?: MemoryType;
+    tags?: string[];
+    sources?: string[];
+    status?: Lifecycle;
+}
+export declare function createMemory(recallDir: string, input: NewMemory): Memory;
+export declare function findMemory(recallDir: string, id: string): Memory;
+export interface Patch {
+    status?: Lifecycle;
+    verification?: Verification;
+}
+export declare function updateMemory(recallDir: string, id: string, patch: Patch): Memory;
+/**
+ * Replace a memory's text in place (same id and file). Latest knowledge wins so memory stays small;
+ * tags and sources are merged. Git history keeps the previous wording.
+ */
+export declare function rewriteMemory(recallDir: string, id: string, input: NewMemory): Memory;
+export declare function appendChangelog(recallDir: string, action: string, m: {
+    id: string;
+    title: string;
+}): void;

package/dist/core/memory.js

@@ -0,0 +1,199 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { memoryMetaSchema, } from '../schemas/index.js';
+import { RecallError, atomicWrite, resolveInside, toPosix, today } from '../utils/fs.js';
+import { assertNoSecrets } from '../utils/secrets.js';
+export const TYPE_DIR = {
+    decision: 'decisions',
+    lesson: 'lessons',
+    bugfix: 'lessons',
+    failed_approach: 'lessons',
+    task: 'tasks',
+    fact: 'rules',
+    convention: 'rules',
+    design_system: 'rules',
+};
+export const MEMORY_DIRS = ['rules', 'decisions', 'lessons', 'tasks'];
+export function slugify(title) {
+    const s = title
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48)
+        .replace(/-+$/g, '');
+    return s || 'memory';
+}
+/** Only regular .md files directly in a memory dir; symlinks are never followed. */
+function listMarkdown(recallDir, dir) {
+    const abs = path.join(recallDir, dir);
+    if (!fs.existsSync(abs))
+        return [];
+    return fs
+        .readdirSync(abs, { withFileTypes: true })
+        .filter((d) => d.isFile() && !d.isSymbolicLink() && d.name.toLowerCase().endsWith('.md'))
+        .map((d) => d.name)
+        .sort();
+}
+export function loadAll(recallDir) {
+    const result = { memories: [], plainDocs: [], problems: [] };
+    for (const dir of MEMORY_DIRS) {
+        for (const name of listMarkdown(recallDir, dir)) {
+            const rel = `${dir}/${name}`;
+            let raw;
+            try {
+                raw = fs.readFileSync(resolveInside(recallDir, dir, name), 'utf8');
+            }
+            catch (err) {
+                result.problems.push({ file: rel, error: err.message });
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = matter(raw);
+            }
+            catch (err) {
+                result.problems.push({ file: rel, error: `Invalid frontmatter YAML: ${err.message.split('\n')[0]}` });
+                continue;
+            }
+            if (Object.keys(parsed.data).length === 0) {
+                if (dir === 'rules')
+                    result.plainDocs.push(rel);
+                else
+                    result.problems.push({ file: rel, error: 'Missing frontmatter.' });
+                continue;
+            }
+            const meta = memoryMetaSchema.safeParse(parsed.data);
+            if (!meta.success) {
+                const msg = meta.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+                result.problems.push({ file: rel, error: `Invalid metadata: ${msg}` });
+                continue;
+            }
+            result.memories.push({ ...meta.data, body: parsed.content.trim(), file: rel });
+        }
+    }
+    const seen = new Map();
+    for (const m of result.memories) {
+        const prev = seen.get(m.id);
+        if (prev)
+            result.problems.push({ file: m.file, error: `Duplicate id ${m.id} (also in ${prev}).` });
+        else
+            seen.set(m.id, m.file);
+    }
+    result.memories.sort((a, b) => a.id.localeCompare(b.id));
+    return result;
+}
+function maxIdNumber(recallDir, loaded) {
+    let max = 0;
+    for (const m of loaded)
+        max = Math.max(max, Number(m.id.slice(4)));
+    // Also consider ids embedded in filenames so malformed files never cause id reuse.
+    for (const dir of MEMORY_DIRS) {
+        for (const name of listMarkdown(recallDir, dir)) {
+            const hit = /^mem_(\d+)/.exec(name);
+            if (hit)
+                max = Math.max(max, Number(hit[1]));
+        }
+    }
+    return max;
+}
+function serialize(meta, body) {
+    const ordered = {
+        id: meta.id,
+        title: meta.title,
+        type: meta.type,
+        created: meta.created,
+        updated: meta.updated,
+        tags: meta.tags,
+        status: meta.status,
+        verification: meta.verification,
+        ...(meta.sources.length > 0 ? { sources: meta.sources } : {}),
+    };
+    return matter.stringify(`\n${body.trim()}\n`, ordered);
+}
+export function createMemory(recallDir, input) {
+    const title = input.title.trim();
+    const text = input.text.trim();
+    if (!title)
+        throw new RecallError('A memory needs a non-empty title.');
+    if (!text)
+        throw new RecallError('A memory needs non-empty text.');
+    assertNoSecrets(`${title}\n${text}`);
+    const type = input.type ?? 'fact';
+    const dir = TYPE_DIR[type];
+    const loaded = loadAll(recallDir).memories;
+    let n = maxIdNumber(recallDir, loaded) + 1;
+    for (let attempt = 0; attempt < 100; attempt++, n++) {
+        const id = `mem_${String(n).padStart(3, '0')}`;
+        const date = today();
+        const meta = memoryMetaSchema.parse({
+            id,
+            title,
+            type,
+            created: date,
+            updated: date,
+            tags: [...new Set((input.tags ?? []).map((t) => t.trim()).filter(Boolean))],
+            status: input.status ?? (process.env.RECALL_AGENT === '1' ? 'proposed' : 'active'),
+            verification: 'unverified',
+            sources: input.sources ?? [],
+        });
+        const name = `${id}-${slugify(title)}.md`;
+        const abs = resolveInside(recallDir, dir, name);
+        const body = text.startsWith('#') ? text : `# ${title}\n\n${text}`;
+        try {
+            fs.mkdirSync(path.dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, serialize(meta, body), { encoding: 'utf8', flag: 'wx' });
+        }
+        catch (err) {
+            if (err.code === 'EEXIST')
+                continue;
+            throw err;
+        }
+        return { ...meta, body, file: toPosix(path.join(dir, name)) };
+    }
+    throw new RecallError('Could not allocate a unique memory id.');
+}
+export function findMemory(recallDir, id) {
+    const m = loadAll(recallDir).memories.find((x) => x.id === id);
+    if (!m)
+        throw new RecallError(`No valid memory with id ${id}.`, 'Run `recall status` or `recall doctor` to inspect memory health.');
+    return m;
+}
+export function updateMemory(recallDir, id, patch) {
+    const m = findMemory(recallDir, id);
+    const next = { ...m, ...patch, updated: today() };
+    const abs = resolveInside(recallDir, ...m.file.split('/'));
+    atomicWrite(abs, serialize(next, m.body));
+    return { ...next, body: m.body, file: m.file };
+}
+/**
+ * Replace a memory's text in place (same id and file). Latest knowledge wins so memory stays small;
+ * tags and sources are merged. Git history keeps the previous wording.
+ */
+export function rewriteMemory(recallDir, id, input) {
+    const m = findMemory(recallDir, id);
+    const title = input.title.trim() || m.title;
+    const text = input.text.trim();
+    if (!text)
+        throw new RecallError('A memory needs non-empty text.');
+    assertNoSecrets(`${title}\n${text}`);
+    const next = memoryMetaSchema.parse({
+        ...m,
+        title,
+        updated: today(),
+        tags: [...new Set([...m.tags, ...(input.tags ?? []).map((t) => t.trim()).filter(Boolean)])],
+        sources: [...new Set([...m.sources, ...(input.sources ?? [])])],
+        status: input.status ?? m.status,
+        verification: 'unverified',
+    });
+    const body = text.startsWith('#') ? text : `# ${title}\n\n${text}`;
+    atomicWrite(resolveInside(recallDir, ...m.file.split('/')), serialize(next, body));
+    return { ...next, body, file: m.file };
+}
+export function appendChangelog(recallDir, action, m) {
+    const file = resolveInside(recallDir, 'logs', 'CHANGELOG.md');
+    const line = `- ${today()} ${action} ${m.id} "${m.title.replace(/\s+/g, ' ')}"\n`;
+    const prev = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '# Recall changelog\n\n';
+    atomicWrite(file, prev.endsWith('\n') ? prev + line : `${prev}\n${line}`);
+}

package/dist/core/project.d.ts

@@ -0,0 +1,12 @@
+export interface Project {
+    /** Directory that contains (or will contain) `.recall/`. */
+    root: string;
+    recallDir: string;
+    initialized: boolean;
+    /** How the root was found. */
+    source: 'recall' | 'git' | 'cwd';
+}
+export declare const RECALL_DIR = ".recall";
+/** Nearest Recall config first, then nearest Git root, then the start directory. */
+export declare function findProject(start?: string): Project;
+export declare function requireInitialized(start?: string): Project;

package/dist/core/project.js

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { RecallError, resolveInside } from '../utils/fs.js';
+export const RECALL_DIR = '.recall';
+function walkUp(start, test) {
+    let dir = path.resolve(start);
+    for (;;) {
+        if (test(dir))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Nearest Recall config first, then nearest Git root, then the start directory. */
+export function findProject(start = process.cwd()) {
+    const recallRoot = walkUp(start, (d) => fs.existsSync(path.join(d, RECALL_DIR, 'config.json')));
+    if (recallRoot) {
+        return { root: recallRoot, recallDir: path.join(recallRoot, RECALL_DIR), initialized: true, source: 'recall' };
+    }
+    const gitRoot = walkUp(start, (d) => fs.existsSync(path.join(d, '.git')));
+    const root = gitRoot ?? path.resolve(start);
+    return { root, recallDir: path.join(root, RECALL_DIR), initialized: false, source: gitRoot ? 'git' : 'cwd' };
+}
+export function requireInitialized(start) {
+    const p = findProject(start);
+    if (!p.initialized) {
+        throw new RecallError('Recall is not initialized in this project.', 'Run `recall init` first.');
+    }
+    // Refuse a .recall that is a symlink pointing elsewhere.
+    resolveInside(p.root, RECALL_DIR);
+    return p;
+}

package/dist/core/retrieval.d.ts

@@ -0,0 +1,27 @@
+import type { MemoryType } from '../schemas/index.js';
+import type { Memory } from './memory.js';
+export interface SearchOptions {
+    limit?: number;
+    includeProposed?: boolean;
+    includeArchived?: boolean;
+    type?: MemoryType;
+    tag?: string;
+    minScore?: number;
+}
+export interface SearchHit {
+    memory: Memory;
+    score: number;
+    excerpt: string;
+}
+export declare function stemCandidates(word: string): string[];
+export declare function stem(word: string): string;
+export declare function tokenize(text: string): string[];
+/** Deterministic keyword search. This is NOT semantic search. */
+export declare function search(memories: Memory[], query: string, opts?: SearchOptions): SearchHit[];
+/** Default cap for agent-facing context output: ~400 tokens at ~4 chars/token. */
+export declare const CONTEXT_MAX_CHARS = 1600;
+/**
+ * Agent-facing rendering: one header line + one excerpt line per hit, hard-capped.
+ * Hits scoring under 30% of the best are dropped: they cost tokens and rarely help.
+ */
+export declare function formatHitsCompact(hits: SearchHit[], maxChars?: number): string;