@vishnuvmx/recall-memory 0.0.0-stage → 0.1.0

package/dist/core/service.js

@@ -0,0 +1,228 @@
+import { agentState } from './agent.js';
+import { recordCheckpoint, pruneSessions } from './checkpoint.js';
+import { loadConfig } from './config.js';
+import { gitInfo, recallChanges, recallHistory, undoRecall } from './git.js';
+import { indexState, rebuildIndex } from './index-builder.js';
+import { generateProjectMap } from './mapper.js';
+import { appendChangelog, createMemory, loadAll, rewriteMemory, updateMemory } from './memory.js';
+import { requireInitialized } from './project.js';
+import { search, tokenize } from './retrieval.js';
+import { where } from './where.js';
+import { PROFILE_BUDGETS } from '../schemas/index.js';
+import fs from 'node:fs';
+import { resolveInside } from '../utils/fs.js';
+/** Create a memory, log it, and refresh the index. */
+export function remember(start, input, action = 'remember') {
+    const p = requireInitialized(start);
+    const m = createMemory(p.recallDir, input);
+    appendChangelog(p.recallDir, action, m);
+    rebuildIndex(p.recallDir);
+    return m;
+}
+/** Agent-facing: always lands as `proposed` and is excluded from search until approved. */
+export function propose(start, input) {
+    return remember(start, { ...input, status: 'proposed' }, 'propose');
+}
+const normTitle = (t) => t.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+/** Same normalized title, or high word overlap (Jaccard >= 0.7 over >= 2 words each). */
+export function findDuplicate(candidates, title) {
+    const n = normTitle(title);
+    const exact = candidates.find((m) => normTitle(m.title) === n);
+    if (exact)
+        return exact;
+    const a = new Set(tokenize(title));
+    if (a.size < 2)
+        return undefined;
+    let best;
+    for (const m of candidates) {
+        const b = new Set(tokenize(m.title));
+        if (b.size < 2)
+            continue;
+        const inter = [...a].filter((t) => b.has(t)).length;
+        const j = inter / (a.size + b.size - inter);
+        if (j >= 0.7 && (!best || j > best.j))
+            best = { m, j };
+    }
+    return best?.m;
+}
+/**
+ * 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 function agentRemember(start, input) {
+    const p = requireInitialized(start);
+    let mode = 'auto';
+    try {
+        mode = loadConfig(p.recallDir).writes;
+    }
+    catch {
+        /* surfaced by `recall doctor` */
+    }
+    const status = input.status ?? (mode === 'review' || process.env.RECALL_AGENT === '1' ? 'proposed' : 'active');
+    const type = input.type ?? 'fact';
+    // In review mode never silently rewrite an approved memory; only merge into other proposals.
+    const candidates = loadAll(p.recallDir).memories.filter((m) => m.type === type && (status === 'active' ? m.status === 'active' || m.status === 'proposed' : m.status === 'proposed'));
+    const dup = findDuplicate(candidates, input.title);
+    const memory = dup
+        ? rewriteMemory(p.recallDir, dup.id, { ...input, type, status })
+        : createMemory(p.recallDir, { ...input, type, status });
+    appendChangelog(p.recallDir, dup ? 'update' : 'remember', memory);
+    rebuildIndex(p.recallDir);
+    return { memory, action: dup ? 'updated' : 'created' };
+}
+export function whereIs(start, query, limit) {
+    const p = requireInitialized(start);
+    return where(p.root, p.recallDir, query, limit);
+}
+export function approve(start, id) {
+    const p = requireInitialized(start);
+    const m = updateMemory(p.recallDir, id, { status: 'active' });
+    appendChangelog(p.recallDir, 'approve', m);
+    rebuildIndex(p.recallDir);
+    return m;
+}
+export function archive(start, id) {
+    const p = requireInitialized(start);
+    const m = updateMemory(p.recallDir, id, { status: 'archived' });
+    appendChangelog(p.recallDir, 'archive', m);
+    rebuildIndex(p.recallDir);
+    return m;
+}
+export function context(start, query, opts = {}) {
+    const p = requireInitialized(start);
+    return search(loadAll(p.recallDir).memories, query, opts);
+}
+function estimateTokens(chars) {
+    return Math.ceil(chars / 4);
+}
+function computeTokenFootprint(recallDir, profile = 'standard') {
+    const targets = ['MEMORY.md', 'INDEX.md', 'PROJECT_MAP.md', 'CURRENT_STATE.md'];
+    const files = {};
+    let totalChars = 0;
+    for (const f of targets) {
+        const p = resolveInside(recallDir, f);
+        if (fs.existsSync(p)) {
+            try {
+                const content = fs.readFileSync(p, 'utf8');
+                const tok = estimateTokens(content.length);
+                files[f] = tok;
+                totalChars += content.length;
+            }
+            catch {
+                files[f] = 0;
+            }
+        }
+        else {
+            files[f] = 0;
+        }
+    }
+    return {
+        totalTokens: estimateTokens(totalChars),
+        budgetTokens: PROFILE_BUDGETS[profile],
+        profile,
+        files,
+    };
+}
+export function status(start) {
+    const p = requireInitialized(start);
+    const loaded = loadAll(p.recallDir);
+    const count = (key) => {
+        const out = {};
+        for (const m of loaded.memories)
+            out[m[key]] = (out[m[key]] ?? 0) + 1;
+        return out;
+    };
+    let agentFile = 'AGENTS.md';
+    let agent = 'unknown';
+    let profile = 'standard';
+    try {
+        const cfg = loadConfig(p.recallDir);
+        agentFile = cfg.agentFile;
+        profile = cfg.profile ?? 'standard';
+        agent = agentState(p.root, agentFile);
+    }
+    catch {
+        /* surfaced by `recall doctor` */
+    }
+    const g = gitInfo(p.root);
+    return {
+        project: p,
+        byType: count('type'),
+        byStatus: count('status'),
+        problems: loaded.problems.length,
+        index: indexState(p.recallDir),
+        agentFile,
+        agent,
+        git: { ...g, changes: g.isRepo ? recallChanges(p.root) : null },
+        tokens: computeTokenFootprint(p.recallDir, profile),
+        profile,
+    };
+}
+export function getProposals(start) {
+    const p = requireInitialized(start);
+    return loadAll(p.recallDir).memories.filter((m) => m.status === 'proposed');
+}
+export function approveAll(start) {
+    const p = requireInitialized(start);
+    const proposals = getProposals(start);
+    const approved = [];
+    for (const m of proposals) {
+        const updated = updateMemory(p.recallDir, m.id, { status: 'active' });
+        appendChangelog(p.recallDir, 'approve', updated);
+        approved.push(updated);
+    }
+    if (approved.length > 0) {
+        rebuildIndex(p.recallDir);
+    }
+    return approved;
+}
+export function archiveAll(start) {
+    const p = requireInitialized(start);
+    const proposals = getProposals(start);
+    const archived = [];
+    for (const m of proposals) {
+        const updated = updateMemory(p.recallDir, m.id, { status: 'archived' });
+        appendChangelog(p.recallDir, 'archive', updated);
+        archived.push(updated);
+    }
+    if (archived.length > 0) {
+        rebuildIndex(p.recallDir);
+    }
+    return archived;
+}
+export function log(start, limit) {
+    const p = requireInitialized(start);
+    const g = gitInfo(p.root);
+    if (g.isRepo) {
+        const committed = recallHistory(p.root, limit);
+        if (committed) {
+            return { source: 'git', committed, uncommitted: recallChanges(p.root) ?? [], changelog: [] };
+        }
+    }
+    const file = resolveInside(p.recallDir, 'logs', 'CHANGELOG.md');
+    const lines = fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split('\n').filter((l) => l.startsWith('- ')) : [];
+    return { source: 'changelog', committed: [], uncommitted: [], changelog: lines.slice(-limit).reverse() };
+}
+export function map(start, profile) {
+    const p = requireInitialized(start);
+    return generateProjectMap(p.root, p.recallDir, profile);
+}
+export function checkpoint(start, summary, opts) {
+    const p = requireInitialized(start);
+    return recordCheckpoint(p.root, p.recallDir, summary, opts);
+}
+export function prune(start, opts) {
+    const p = requireInitialized(start);
+    return pruneSessions(p.recallDir, opts);
+}
+export function undo(start, opts) {
+    const p = requireInitialized(start);
+    const res = undoRecall(p.root, '.recall', opts);
+    if (!opts?.dryRun && res.ok && fs.existsSync(p.recallDir)) {
+        rebuildIndex(p.recallDir);
+    }
+    return res;
+}

package/dist/core/where.d.ts

@@ -0,0 +1,14 @@
+import { type Landmark } from './landmarks.js';
+export interface WhereHit {
+    file: string;
+    line: number;
+    name: string;
+    kind: Landmark['kind'] | 'file';
+    totalLines: number;
+}
+/**
+ * Symbol/file lookup over live landmarks (mtime-cached in `.recall/.cache`), so results are never
+ * stale and the agent pays for a handful of `file:line` rows instead of reading PROJECT_MAP.md.
+ */
+export declare function where(root: string, recallDir: string, query: string, limit?: number): WhereHit[];
+export declare function formatWhere(hits: WhereHit[]): string;

package/dist/core/where.js

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { scanLandmarks } from './landmarks.js';
+import { DEFAULT_IGNORED_DIRS, createGitignoreFilter } from './mapper.js';
+import { toPosix } from '../utils/fs.js';
+/**
+ * Symbol/file lookup over live landmarks (mtime-cached in `.recall/.cache`), so results are never
+ * stale and the agent pays for a handful of `file:line` rows instead of reading PROJECT_MAP.md.
+ */
+export function where(root, recallDir, query, limit = 15) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const files = scanLandmarks(root, 1, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, recallDir);
+    const ranked = [];
+    const seenFiles = new Set();
+    for (const f of files) {
+        seenFiles.add(f.relativePath);
+        const p = f.relativePath.toLowerCase();
+        if (p.includes(q)) {
+            const base = p.slice(p.lastIndexOf('/') + 1);
+            ranked.push({ hit: { file: f.relativePath, line: 1, name: f.relativePath, kind: 'file', totalLines: f.totalLines }, rank: base === q ? 0 : base.startsWith(q) ? 1 : 3 });
+        }
+        for (const lm of f.landmarks) {
+            const n = lm.name.toLowerCase();
+            const rank = n === q ? 0 : n.startsWith(q) ? 2 : n.includes(q) ? 4 : -1;
+            if (rank >= 0)
+                ranked.push({ hit: { file: f.relativePath, line: lm.line, name: lm.name, kind: lm.kind, totalLines: f.totalLines }, rank });
+        }
+    }
+    // Also check non-code project files (configs, package.json, Dockerfile, etc.)
+    const isGitignored = createGitignoreFilter(root);
+    function walk(currentDir, depth = 0) {
+        if (depth > 5)
+            return;
+        let entries = [];
+        try {
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') && entry.name !== '.gitignore' && entry.name !== '.env.example') {
+                if (entry.isDirectory())
+                    continue;
+            }
+            const full = path.join(currentDir, entry.name);
+            const rel = toPosix(path.relative(root, full));
+            if (entry.isDirectory()) {
+                if (DEFAULT_IGNORED_DIRS.has(entry.name) || isGitignored(rel, true))
+                    continue;
+                walk(full, depth + 1);
+            }
+            else if (entry.isFile()) {
+                if (seenFiles.has(rel) || isGitignored(rel, false))
+                    continue;
+                const p = rel.toLowerCase();
+                if (p.includes(q)) {
+                    let lineCount = 0;
+                    try {
+                        const stat = fs.statSync(full);
+                        if (stat.size <= 2 * 1024 * 1024) {
+                            lineCount = fs.readFileSync(full, 'utf8').split('\n').length;
+                        }
+                    }
+                    catch {
+                        // ignore unreadable
+                    }
+                    const base = p.slice(p.lastIndexOf('/') + 1);
+                    ranked.push({ hit: { file: rel, line: 1, name: rel, kind: 'file', totalLines: lineCount }, rank: base === q ? 0 : base.startsWith(q) ? 1 : 3 });
+                }
+            }
+        }
+    }
+    walk(root);
+    ranked.sort((a, b) => a.rank - b.rank || a.hit.file.localeCompare(b.hit.file) || a.hit.line - b.hit.line);
+    return ranked.slice(0, limit).map((r) => r.hit);
+}
+export function formatWhere(hits) {
+    if (hits.length === 0)
+        return 'No match.';
+    return hits
+        .map((h) => (h.kind === 'file' ? `${h.file} (${h.totalLines} lines)` : `${h.file}:${h.line} ${h.name} (${h.kind})`))
+        .join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { initProject } from './core/init.js';
+export { search } from './core/retrieval.js';
+export { loadAll, createMemory } from './core/memory.js';
+export { findProject } from './core/project.js';
+export { rebuildIndex } from './core/index-builder.js';
+export { remember, propose, approve, approveAll, archive, archiveAll, getProposals, context, status, log, map, checkpoint, prune, agentRemember, whereIs } from './core/service.js';
+export { seed } from './core/seed.js';
+export { generateProjectMap } from './core/mapper.js';
+export { recordCheckpoint, pruneSessions, pruneSessionLog } from './core/checkpoint.js';
+export { costReport } from './core/cost.js';
+export { where, formatWhere } from './core/where.js';

package/dist/index.js

@@ -0,0 +1,11 @@
+export { initProject } from './core/init.js';
+export { search } from './core/retrieval.js';
+export { loadAll, createMemory } from './core/memory.js';
+export { findProject } from './core/project.js';
+export { rebuildIndex } from './core/index-builder.js';
+export { remember, propose, approve, approveAll, archive, archiveAll, getProposals, context, status, log, map, checkpoint, prune, agentRemember, whereIs } from './core/service.js';
+export { seed } from './core/seed.js';
+export { generateProjectMap } from './core/mapper.js';
+export { recordCheckpoint, pruneSessions, pruneSessionLog } from './core/checkpoint.js';
+export { costReport } from './core/cost.js';
+export { where, formatWhere } from './core/where.js';

package/dist/mcp/server.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Minimal MCP server over stdio (newline-delimited JSON-RPC 2.0), no SDK dependency.
+ *
+ * TOKEN BUDGET: every listed tool schema is sent to the model on every turn, so the list is kept to
+ * three terse tools (enforced by tests/budget.test.ts). Bookkeeping (checkpoints, map refresh, status)
+ * is NOT exposed to the model; those run from hooks/CLI. Legacy tool names stay callable, unlisted.
+ */
+export declare const TOOLS: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+            };
+            name?: undefined;
+            title?: undefined;
+            text?: undefined;
+            type?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            name: {
+                type: string;
+            };
+            query?: undefined;
+            title?: undefined;
+            text?: undefined;
+            type?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            title: {
+                type: string;
+            };
+            text: {
+                type: string;
+            };
+            type: {
+                type: string;
+                enum: string[];
+            };
+            query?: undefined;
+            name?: undefined;
+        };
+        required: string[];
+    };
+})[];
+type Json = Record<string, unknown>;
+export declare function handleMessage(cwd: string, msg: Json): Json | null;
+export declare function serveStdio(cwd: string): void;
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,121 @@
+import readline from 'node:readline';
+import { agentRemember, checkpoint, context, map, propose, status, whereIs } from '../core/service.js';
+import { formatHitsCompact } from '../core/retrieval.js';
+import { formatWhere } from '../core/where.js';
+import { MEMORY_TYPES } from '../schemas/index.js';
+/**
+ * Minimal MCP server over stdio (newline-delimited JSON-RPC 2.0), no SDK dependency.
+ *
+ * TOKEN BUDGET: every listed tool schema is sent to the model on every turn, so the list is kept to
+ * three terse tools (enforced by tests/budget.test.ts). Bookkeeping (checkpoints, map refresh, status)
+ * is NOT exposed to the model; those run from hooks/CLI. Legacy tool names stay callable, unlisted.
+ */
+export const TOOLS = [
+    {
+        name: 'recall_context',
+        description: 'Search project memory (decisions, conventions, lessons). Capped output.',
+        inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+    },
+    {
+        name: 'recall_where',
+        description: 'Find a symbol or file: returns file:line rows.',
+        inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+    },
+    {
+        name: 'recall_remember',
+        description: 'Save a non-obvious decision, convention, or lesson. Similar titles update in place.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string' },
+                text: { type: 'string' },
+                type: { type: 'string', enum: ['decision', 'convention', 'lesson', 'bugfix', 'failed_approach'] },
+            },
+            required: ['title', 'text'],
+        },
+    },
+];
+const asType = (v) => (MEMORY_TYPES.includes(v) ? v : 'fact');
+const asTags = (v) => (Array.isArray(v) ? v.map(String) : []);
+function callTool(cwd, name, args) {
+    if (name === 'recall_context') {
+        return formatHitsCompact(context(cwd, String(args.query ?? ''), { limit: Number(args.limit) || 5 }));
+    }
+    if (name === 'recall_where') {
+        return formatWhere(whereIs(cwd, String(args.name ?? args.query ?? '')));
+    }
+    if (name === 'recall_remember') {
+        const r = agentRemember(cwd, { title: String(args.title ?? ''), text: String(args.text ?? ''), type: asType(args.type), tags: asTags(args.tags) });
+        return `${r.action === 'updated' ? 'Updated' : 'Saved'} ${r.memory.id} (${r.memory.status}).`;
+    }
+    // ---- Legacy tools: callable for older clients, deliberately not listed ----
+    if (name === 'recall_propose') {
+        const m = propose(cwd, { title: String(args.title ?? ''), text: String(args.text ?? ''), type: asType(args.type), tags: asTags(args.tags) });
+        return `Proposed ${m.id} at ${m.file}. A human must run \`recall approve ${m.id}\`.`;
+    }
+    if (name === 'recall_checkpoint') {
+        const summary = args.summary ? String(args.summary) : undefined;
+        const nextSteps = args.nextSteps ? String(args.nextSteps) : undefined;
+        const res = checkpoint(cwd, summary, { nextSteps, auto: !args.summary });
+        return `Checkpoint recorded [${res.timestamp}]: ${res.summary}`;
+    }
+    if (name === 'recall_map') {
+        return `Project map refreshed at ${map(cwd)}.`;
+    }
+    if (name === 'recall_status') {
+        const s = status(cwd);
+        const types = Object.entries(s.byType).map(([k, v]) => `${k}: ${v}`).join(', ') || 'none';
+        const statuses = Object.entries(s.byStatus).map(([k, v]) => `${k}: ${v}`).join(', ') || 'none';
+        return `Recall Status:\n- Types: ${types}\n- Statuses: ${statuses}\n- Index: ${s.index}\n- Problems: ${s.problems}`;
+    }
+    throw new Error(`Unknown tool: ${name}`);
+}
+export function handleMessage(cwd, msg) {
+    const id = msg.id;
+    const reply = (result) => ({ jsonrpc: '2.0', id, result });
+    const fail = (code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+    if (id === undefined)
+        return null; // notifications need no response
+    switch (msg.method) {
+        case 'initialize': {
+            const params = (msg.params ?? {});
+            return reply({
+                protocolVersion: typeof params.protocolVersion === 'string' ? params.protocolVersion : '2024-11-05',
+                capabilities: { tools: {} },
+                serverInfo: { name: 'recall', version: '0.1.0' },
+            });
+        }
+        case 'ping':
+            return reply({});
+        case 'tools/list':
+            return reply({ tools: TOOLS });
+        case 'tools/call': {
+            const p = (msg.params ?? {});
+            try {
+                const text = callTool(cwd, String(p.name), (p.arguments ?? {}));
+                return reply({ content: [{ type: 'text', text }] });
+            }
+            catch (err) {
+                return reply({ content: [{ type: 'text', text: err.message }], isError: true });
+            }
+        }
+        default:
+            return fail(-32601, `Method not found: ${String(msg.method)}`);
+    }
+}
+export function serveStdio(cwd) {
+    const rl = readline.createInterface({ input: process.stdin });
+    rl.on('line', (line) => {
+        if (!line.trim())
+            return;
+        let out;
+        try {
+            out = handleMessage(cwd, JSON.parse(line));
+        }
+        catch {
+            out = { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } };
+        }
+        if (out)
+            process.stdout.write(`${JSON.stringify(out)}\n`);
+    });
+}

package/dist/schemas/index.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+export declare const MEMORY_TYPES: readonly ["fact", "decision", "convention", "lesson", "bugfix", "failed_approach", "task", "design_system"];
+export declare const LIFECYCLE: readonly ["proposed", "active", "superseded", "archived"];
+export declare const VERIFICATION: readonly ["unverified", "verified", "needs_review"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+export type Lifecycle = (typeof LIFECYCLE)[number];
+export type Verification = (typeof VERIFICATION)[number];
+export declare const memoryMetaSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodEnum<["fact", "decision", "convention", "lesson", "bugfix", "failed_approach", "task", "design_system"]>;
+    created: z.ZodEffects<z.ZodString, string, unknown>;
+    updated: z.ZodEffects<z.ZodString, string, unknown>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    status: z.ZodEnum<["proposed", "active", "superseded", "archived"]>;
+    verification: z.ZodEnum<["unverified", "verified", "needs_review"]>;
+    sources: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    created: string;
+    updated: string;
+    type: "fact" | "decision" | "convention" | "lesson" | "bugfix" | "failed_approach" | "task" | "design_system";
+    status: "proposed" | "active" | "superseded" | "archived";
+    id: string;
+    title: string;
+    tags: string[];
+    verification: "unverified" | "verified" | "needs_review";
+    sources: string[];
+}, {
+    type: "fact" | "decision" | "convention" | "lesson" | "bugfix" | "failed_approach" | "task" | "design_system";
+    status: "proposed" | "active" | "superseded" | "archived";
+    id: string;
+    title: string;
+    verification: "unverified" | "verified" | "needs_review";
+    created?: unknown;
+    updated?: unknown;
+    tags?: string[] | undefined;
+    sources?: string[] | undefined;
+}>;
+export type MemoryMeta = z.infer<typeof memoryMetaSchema>;
+export declare const PROFILE_TIERS: readonly ["compact", "standard", "frontier"];
+export type ProfileTier = (typeof PROFILE_TIERS)[number];
+export declare const PROFILE_BUDGETS: Record<ProfileTier, number>;
+export declare const WRITE_MODES: readonly ["auto", "review"];
+export type WriteMode = (typeof WRITE_MODES)[number];
+export declare const configSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    agentFile: z.ZodDefault<z.ZodString>;
+    profile: z.ZodDefault<z.ZodEnum<["compact", "standard", "frontier"]>>;
+    retentionDays: z.ZodDefault<z.ZodNumber>;
+    maxLogEntries: z.ZodDefault<z.ZodNumber>;
+    /** `auto`: agent memory writes are active immediately. `review`: they land as `proposed` for human approval. */
+    writes: z.ZodDefault<z.ZodEnum<["auto", "review"]>>;
+}, "strict", z.ZodTypeAny, {
+    version: 1;
+    agentFile: string;
+    profile: "compact" | "standard" | "frontier";
+    retentionDays: number;
+    maxLogEntries: number;
+    writes: "auto" | "review";
+}, {
+    version: 1;
+    agentFile?: string | undefined;
+    profile?: "compact" | "standard" | "frontier" | undefined;
+    retentionDays?: number | undefined;
+    maxLogEntries?: number | undefined;
+    writes?: "auto" | "review" | undefined;
+}>;
+export type RecallConfig = z.infer<typeof configSchema>;

package/dist/schemas/index.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export const MEMORY_TYPES = [
+    'fact',
+    'decision',
+    'convention',
+    'lesson',
+    'bugfix',
+    'failed_approach',
+    'task',
+    'design_system',
+];
+export const LIFECYCLE = ['proposed', 'active', 'superseded', 'archived'];
+export const VERIFICATION = ['unverified', 'verified', 'needs_review'];
+const dateString = z.preprocess((v) => (v instanceof Date ? v.toISOString().slice(0, 10) : v), z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'expected YYYY-MM-DD'));
+export const memoryMetaSchema = z.object({
+    id: z.string().regex(/^mem_[a-z0-9_]+$/i, 'expected mem_<id>'),
+    title: z.string().trim().min(1),
+    type: z.enum(MEMORY_TYPES),
+    created: dateString,
+    updated: dateString,
+    tags: z.array(z.string()).default([]),
+    status: z.enum(LIFECYCLE),
+    verification: z.enum(VERIFICATION),
+    sources: z.array(z.string()).default([]),
+});
+export const PROFILE_TIERS = ['compact', 'standard', 'frontier'];
+export const PROFILE_BUDGETS = {
+    compact: 3000,
+    standard: 12000,
+    frontier: 45000,
+};
+export const WRITE_MODES = ['auto', 'review'];
+export const configSchema = z
+    .object({
+    version: z.literal(1),
+    agentFile: z.string().min(1).default('AGENTS.md'),
+    profile: z.enum(PROFILE_TIERS).default('standard'),
+    retentionDays: z.number().int().positive().default(14),
+    maxLogEntries: z.number().int().positive().default(50),
+    /** `auto`: agent memory writes are active immediately. `review`: they land as `proposed` for human approval. */
+    writes: z.enum(WRITE_MODES).default('auto'),
+})
+    .strict();