@vishnuvmx/recall-memory 0.0.0-stage → 0.1.0

package/dist/core/retrieval.js

@@ -0,0 +1,180 @@
+const STOP = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'are', 'was',
+    'how', 'why', 'what', 'when', 'should', 'can', 'could', 'would', 'will',
+    'have', 'has', 'had', 'been', 'about', 'each', 'more', 'some', 'than',
+    'them', 'then', 'they', 'does', 'did', 'done', 'also', 'such',
+]);
+export function stemCandidates(word) {
+    const s = word.toLowerCase();
+    const cands = new Set();
+    if (s.endsWith('ing') && s.length > 4) {
+        const base = s.slice(0, -3);
+        cands.add(base);
+        cands.add(`${base}e`);
+        if (/(.)\1$/.test(base)) {
+            cands.add(base.slice(0, -1));
+        }
+    }
+    else if (s.endsWith('ies') && s.length > 4) {
+        cands.add(s.slice(0, -3) + 'y');
+    }
+    else if (s.endsWith('es') && s.length > 4) {
+        cands.add(s.slice(0, -2));
+        cands.add(s.slice(0, -1));
+    }
+    else if (s.endsWith('ed') && s.length > 4) {
+        const base = s.slice(0, -2);
+        cands.add(base);
+        cands.add(`${base}e`);
+        if (/(.)\1$/.test(base)) {
+            cands.add(base.slice(0, -1));
+        }
+    }
+    else if (s.endsWith('s') && !s.endsWith('ss') && s.length > 3) {
+        cands.add(s.slice(0, -1));
+    }
+    return [...cands].filter((c) => c.length > 2 && c !== s);
+}
+export function stem(word) {
+    const c = stemCandidates(word);
+    return c[0] ?? word.toLowerCase();
+}
+export function tokenize(text) {
+    const raw = text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+    const words = raw.filter((t) => t.length > 1 && !STOP.has(t));
+    return [...new Set(words)];
+}
+function headings(body) {
+    return body
+        .split('\n')
+        .filter((l) => /^#{1,6}\s/.test(l))
+        .join(' ')
+        .toLowerCase();
+}
+function hasWord(haystack, needle) {
+    const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?:^|[^\\p{L}\\p{N}])${escaped}(?:$|[^\\p{L}\\p{N}])`, 'iu').test(haystack);
+}
+function excerptFor(body, tokens) {
+    const lines = body.split('\n').map((l) => l.trim()).filter((l) => l && !/^#{1,6}\s/.test(l));
+    const hit = lines.find((l) => tokens.some((t) => hasWord(l.toLowerCase(), t))) ?? lines[0] ?? '';
+    return hit.length > 220 ? `${hit.slice(0, 217)}...` : hit;
+}
+const STATUS_WEIGHT = { active: 1, proposed: 0.5, superseded: 0.3, archived: 0.1 };
+function buildMatcher(token) {
+    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const wordRe = new RegExp(`(?:^|[^\\p{L}\\p{N}])${escaped}(?:$|[^\\p{L}\\p{N}])`, 'iu');
+    const prefixRe = new RegExp(`(?:^|[^\\p{L}\\p{N}])${escaped}[\\p{L}\\p{N}]*`, 'iu');
+    const countRe = new RegExp(`(?:^|[^\\p{L}\\p{N}])${escaped}(?:$|[^\\p{L}\\p{N}])`, 'giu');
+    const stemRes = stemCandidates(token).map((st) => {
+        const escSt = st.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return {
+            wordRe: new RegExp(`(?:^|[^\\p{L}\\p{N}])${escSt}(?:$|[^\\p{L}\\p{N}])`, 'iu'),
+            prefixRe: new RegExp(`(?:^|[^\\p{L}\\p{N}])${escSt}[\\p{L}\\p{N}]*`, 'iu'),
+        };
+    });
+    return { token, wordRe, prefixRe, countRe, stemRes };
+}
+/** Deterministic keyword search. This is NOT semantic search. */
+export function search(memories, query, opts = {}) {
+    const tokens = tokenize(query);
+    const phrase = query.trim().toLowerCase();
+    if (tokens.length === 0)
+        return [];
+    const matchers = tokens.map(buildMatcher);
+    const hits = [];
+    const now = Date.now();
+    for (const m of memories) {
+        if (m.status === 'archived' && !opts.includeArchived)
+            continue;
+        if (m.status === 'proposed' && !opts.includeProposed)
+            continue;
+        if (opts.type && m.type !== opts.type)
+            continue;
+        if (opts.tag && !m.tags.some((t) => t.toLowerCase() === opts.tag.toLowerCase()))
+            continue;
+        const title = m.title.toLowerCase();
+        const tags = m.tags.join(' ').toLowerCase();
+        const heads = headings(m.body);
+        const body = m.body.toLowerCase();
+        let score = 0;
+        let matched = 0;
+        if (title === phrase)
+            score += 15;
+        else if (title.includes(phrase))
+            score += 8;
+        for (const mtr of matchers) {
+            let s = 0;
+            if (mtr.wordRe.test(title))
+                s += 3;
+            else if (mtr.stemRes.some((sr) => sr.wordRe.test(title) || sr.prefixRe.test(title)))
+                s += 2;
+            if (mtr.wordRe.test(tags))
+                s += 2;
+            else if (mtr.stemRes.some((sr) => sr.wordRe.test(tags) || sr.prefixRe.test(tags)))
+                s += 1.5;
+            if (mtr.wordRe.test(heads))
+                s += 2;
+            else if (mtr.stemRes.some((sr) => sr.wordRe.test(heads) || sr.prefixRe.test(heads)))
+                s += 1.5;
+            const matches = body.match(mtr.countRe);
+            const c = matches ? matches.length : 0;
+            if (c > 0)
+                s += Math.min(c, 3);
+            else if (mtr.stemRes.some((sr) => sr.wordRe.test(body) || sr.prefixRe.test(body)))
+                s += 1;
+            if (s > 0)
+                matched++;
+            score += s;
+        }
+        if (matched === 0)
+            continue;
+        if (tokens.length > 1)
+            score += (matched / tokens.length) * 5;
+        if (m.verification === 'verified')
+            score += 0.5;
+        // Recency bonus: recent memories are slightly more relevant
+        try {
+            const dateStr = m.updated || m.created;
+            const ageDays = (now - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24);
+            if (ageDays <= 14)
+                score += 0.2;
+            else if (ageDays <= 30)
+                score += 0.1;
+        }
+        catch {
+            // ignore invalid dates
+        }
+        score *= STATUS_WEIGHT[m.status];
+        const finalScore = Math.round(score * 100) / 100;
+        if (opts.minScore && finalScore < opts.minScore)
+            continue;
+        hits.push({ memory: m, score: finalScore, excerpt: excerptFor(m.body, tokens) });
+    }
+    hits.sort((a, b) => b.score - a.score || a.memory.id.localeCompare(b.memory.id));
+    return hits.slice(0, opts.limit ?? 5);
+}
+/** Default cap for agent-facing context output: ~400 tokens at ~4 chars/token. */
+export 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 function formatHitsCompact(hits, maxChars = CONTEXT_MAX_CHARS) {
+    if (hits.length === 0)
+        return 'No relevant memory.';
+    const top = hits[0].score;
+    const out = [];
+    let used = 0;
+    for (const h of hits) {
+        if (h.score < top * 0.3)
+            break;
+        const flag = h.memory.status === 'active' ? '' : `, ${h.memory.status}`;
+        const entry = `- ${h.memory.title} [${h.memory.type}${flag}] .recall/${h.memory.file}${h.excerpt ? `\n  ${h.excerpt}` : ''}`;
+        if (out.length > 0 && used + entry.length + 1 > maxChars)
+            break;
+        out.push(entry.length > maxChars ? `${entry.slice(0, maxChars - 3)}...` : entry);
+        used += entry.length + 1;
+    }
+    return out.join('\n');
+}

package/dist/core/seed.d.ts

@@ -0,0 +1,25 @@
+import type { MemoryType } from '../schemas/index.js';
+export interface SeedOptions {
+    from?: 'git' | 'docs' | 'all';
+    limit?: number;
+    dryRun?: boolean;
+}
+export interface SeedCandidate {
+    title: string;
+    text: string;
+    type: MemoryType;
+    tags: string[];
+    source: string;
+}
+export interface SeedResult {
+    proposed: Array<{
+        id?: string;
+        title: string;
+        type: string;
+        source: string;
+    }>;
+    candidates: SeedCandidate[];
+    dryRun: boolean;
+    sourcesUsed: string[];
+}
+export declare function seed(start: string, opts?: SeedOptions): SeedResult;

package/dist/core/seed.js

@@ -0,0 +1,196 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { requireInitialized } from './project.js';
+import { propose } from './service.js';
+import { loadAll } from './memory.js';
+import { findSecrets } from '../utils/secrets.js';
+const COMMIT_TYPE_MAP = [
+    { prefix: /^feat(\([^)]+\))?:\s*/i, type: 'decision', tag: 'feature' },
+    { prefix: /^fix(\([^)]+\))?:\s*/i, type: 'bugfix', tag: 'bugfix' },
+    { prefix: /^refactor(\([^)]+\))?:\s*/i, type: 'decision', tag: 'refactor' },
+    { prefix: /^perf(\([^)]+\))?:\s*/i, type: 'lesson', tag: 'performance' },
+    { prefix: /^arch(\([^)]+\))?:\s*/i, type: 'decision', tag: 'architecture' },
+];
+const IGNORED_SUBJECTS = [
+    /^bump\b/i,
+    /^merge\b/i,
+    /^release\b/i,
+    /^update dependencies/i,
+    /^chore\b/i,
+    /^wip\b/i,
+    /^typo\b/i,
+    /^format\b/i,
+];
+function extractGitCandidates(root, maxCommits = 40) {
+    let output = '';
+    try {
+        output = execFileSync('git', ['log', `-n`, String(maxCommits), '--pretty=format:%h|%ad|%s', '--date=short'], {
+            cwd: root,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    }
+    catch {
+        return [];
+    }
+    const lines = output.trim().split('\n').filter(Boolean);
+    const candidates = [];
+    for (const line of lines) {
+        const parts = line.split('|');
+        if (parts.length < 3)
+            continue;
+        const hash = parts[0]?.trim() ?? '';
+        const date = parts[1]?.trim() ?? '';
+        const subject = parts.slice(2).join('|').trim();
+        if (!subject || IGNORED_SUBJECTS.some((re) => re.test(subject)))
+            continue;
+        let matchedType = 'decision';
+        let matchedTag = 'git-history';
+        let cleanTitle = subject;
+        for (const mapping of COMMIT_TYPE_MAP) {
+            if (mapping.prefix.test(subject)) {
+                matchedType = mapping.type;
+                matchedTag = mapping.tag;
+                cleanTitle = subject.replace(mapping.prefix, '').trim();
+                break;
+            }
+        }
+        if (cleanTitle.length < 5)
+            continue;
+        // Capitalize first letter
+        cleanTitle = cleanTitle.charAt(0).toUpperCase() + cleanTitle.slice(1);
+        const text = `Seeded from commit ${hash} (${date}):\n${subject}`;
+        if (findSecrets(cleanTitle).length > 0 || findSecrets(text).length > 0)
+            continue;
+        candidates.push({
+            title: cleanTitle.slice(0, 80),
+            text,
+            type: matchedType,
+            tags: [matchedTag, 'seed'],
+            source: `git:${hash}`,
+        });
+    }
+    return candidates;
+}
+function extractDocsCandidates(root) {
+    const candidates = [];
+    const searchDirs = ['docs', 'doc'];
+    for (const d of searchDirs) {
+        const absDir = path.join(root, d);
+        if (!fs.existsSync(absDir))
+            continue;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(absDir).filter((f) => f.endsWith('.md'));
+        }
+        catch {
+            continue;
+        }
+        for (const file of entries) {
+            const fullPath = path.join(absDir, file);
+            let content = '';
+            try {
+                content = fs.readFileSync(fullPath, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            // Look for H2/H3 headings that suggest decisions or architecture
+            const sections = content.split(/\n(?=##\s+)/);
+            for (const section of sections) {
+                const match = /^##\s+([^\n]+)\n([\s\S]*)/.exec(section);
+                if (!match)
+                    continue;
+                const heading = match[1]?.trim() ?? '';
+                const body = match[2]?.trim() ?? '';
+                if (/^(overview|introduction|table of contents|license|links)/i.test(heading))
+                    continue;
+                if (body.length < 40)
+                    continue;
+                const firstPara = body.split(/\n\s*\n/)[0]?.trim() ?? '';
+                if (firstPara.length < 20)
+                    continue;
+                const title = heading.slice(0, 80);
+                const text = firstPara.slice(0, 500);
+                if (findSecrets(title).length > 0 || findSecrets(text).length > 0)
+                    continue;
+                candidates.push({
+                    title,
+                    text: `# ${heading}\n\n${text}\n\nSource: \`${d}/${file}\``,
+                    type: 'decision',
+                    tags: ['architecture', 'docs', 'seed'],
+                    source: `${d}/${file}`,
+                });
+            }
+        }
+    }
+    return candidates;
+}
+export function seed(start, opts = {}) {
+    const p = requireInitialized(start);
+    const from = opts.from ?? 'all';
+    const limit = opts.limit ?? 5;
+    const isDryRun = !!opts.dryRun;
+    const existing = loadAll(p.recallDir).memories;
+    const existingTitles = new Set(existing.map((m) => m.title.toLowerCase().trim()));
+    const allCandidates = [];
+    const sourcesUsed = [];
+    if (from === 'all' || from === 'git') {
+        const gitCands = extractGitCandidates(p.root);
+        if (gitCands.length > 0) {
+            allCandidates.push(...gitCands);
+            sourcesUsed.push('git');
+        }
+    }
+    if (from === 'all' || from === 'docs') {
+        const docCands = extractDocsCandidates(p.root);
+        if (docCands.length > 0) {
+            allCandidates.push(...docCands);
+            sourcesUsed.push('docs');
+        }
+    }
+    // Deduplicate against existing memories and within candidates
+    const uniqueCandidates = [];
+    const seenTitles = new Set();
+    for (const cand of allCandidates) {
+        const norm = cand.title.toLowerCase().trim();
+        if (existingTitles.has(norm) || seenTitles.has(norm))
+            continue;
+        seenTitles.add(norm);
+        uniqueCandidates.push(cand);
+        if (uniqueCandidates.length >= limit)
+            break;
+    }
+    const proposed = [];
+    for (const cand of uniqueCandidates) {
+        if (isDryRun) {
+            proposed.push({
+                title: cand.title,
+                type: cand.type,
+                source: cand.source,
+            });
+        }
+        else {
+            const m = propose(p.root, {
+                title: cand.title,
+                text: cand.text,
+                type: cand.type,
+                tags: cand.tags,
+                sources: [cand.source],
+            });
+            proposed.push({
+                id: m.id,
+                title: m.title,
+                type: m.type,
+                source: cand.source,
+            });
+        }
+    }
+    return {
+        proposed,
+        candidates: uniqueCandidates,
+        dryRun: isDryRun,
+        sourcesUsed,
+    };
+}

package/dist/core/service.d.ts

@@ -0,0 +1,76 @@
+import { type AgentState } from './agent.js';
+import { type CheckpointOptions, type CheckpointResult } from './checkpoint.js';
+import { type Commit, type UndoResult } from './git.js';
+import { type IndexState } from './index-builder.js';
+import { type Memory, type NewMemory } from './memory.js';
+import { type Project } from './project.js';
+import { type SearchHit, type SearchOptions } from './retrieval.js';
+import { type WhereHit } from './where.js';
+import { type ProfileTier } from '../schemas/index.js';
+/** Create a memory, log it, and refresh the index. */
+export declare function remember(start: string, input: NewMemory, action?: string): Memory;
+/** Agent-facing: always lands as `proposed` and is excluded from search until approved. */
+export declare function propose(start: string, input: NewMemory): Memory;
+/** Same normalized title, or high word overlap (Jaccard >= 0.7 over >= 2 words each). */
+export declare function findDuplicate(candidates: Memory[], title: string): Memory | undefined;
+export interface RememberResult {
+    memory: Memory;
+    action: 'created' | 'updated';
+}
+/**
+ * The write path for agents (CLI `remember` and MCP `recall_remember`).
+ * - `writes: auto` (default): active immediately, so memory is useful without human ceremony.
+ * - `writes: review` or RECALL_AGENT=1: lands as `proposed`.
+ * A near-duplicate title updates the existing memory instead of adding another file, which keeps
+ * retrieval results (and their token cost) from growing with repetition.
+ */
+export declare function agentRemember(start: string, input: NewMemory): RememberResult;
+export declare function whereIs(start: string, query: string, limit?: number): WhereHit[];
+export declare function approve(start: string, id: string): Memory;
+export declare function archive(start: string, id: string): Memory;
+export declare function context(start: string, query: string, opts?: SearchOptions): SearchHit[];
+export interface TokenFootprint {
+    totalTokens: number;
+    budgetTokens: number;
+    profile: ProfileTier;
+    files: Record<string, number>;
+}
+export interface StatusReport {
+    project: Project;
+    byType: Record<string, number>;
+    byStatus: Record<string, number>;
+    problems: number;
+    index: IndexState;
+    agentFile: string;
+    agent: AgentState | 'unknown';
+    git: {
+        available: boolean;
+        isRepo: boolean;
+        changes: string[] | null;
+    };
+    tokens: TokenFootprint;
+    profile: ProfileTier;
+}
+export declare function status(start: string): StatusReport;
+export declare function getProposals(start: string): Memory[];
+export declare function approveAll(start: string): Memory[];
+export declare function archiveAll(start: string): Memory[];
+export interface LogReport {
+    source: 'git' | 'changelog';
+    committed: Commit[];
+    uncommitted: string[];
+    changelog: string[];
+}
+export declare function log(start: string, limit: number): LogReport;
+export declare function map(start: string, profile?: ProfileTier): string;
+export declare function checkpoint(start: string, summary?: string, opts?: CheckpointOptions): CheckpointResult;
+export declare function prune(start: string, opts?: {
+    retentionDays?: number;
+    maxEntries?: number;
+}): {
+    removedCount: number;
+    remainingCount: number;
+};
+export declare function undo(start: string, opts?: {
+    dryRun?: boolean;
+}): UndoResult;