obsidian-lean-coder 0.0.0-stage → 0.1.1

package/dist/init/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Safe, idempotent project initialization (OLC-022, PRD §7.4 init flow).
+ *
+ * `initProject` never overwrites an existing file: every target is either
+ * created (when missing) or reported as preserved / attention-needed.
+ * Anything requiring a human choice (confirming the proposed project_id,
+ * providing a vault path, resolving a duplicate id) is returned as
+ * `status: "needs-decision"` with an actionable message — the caller
+ * (agent or user) supplies the answer on a follow-up call. No prompting
+ * happens inside this module, so it stays testable and non-interactive.
+ *
+ * Report entry actions: `created` | `preserved` | `attention`.
+ * With `dryRun: true` nothing is written; `created` then means "would create".
+ */
+export declare const OLC_DIR = ".olc";
+export declare const CONFIG_FILE = "config.json";
+export declare const AGENTS_FILE = "AGENTS.md";
+export interface InitEntry {
+    path: string;
+    action: "created" | "preserved" | "attention";
+    note?: string;
+}
+export interface InitReport {
+    status: "ready" | "needs-decision";
+    projectRoot: string;
+    repoRoot: string;
+    projectId: string;
+    vaultRoot: string | null;
+    dryRun: boolean;
+    entries: InitEntry[];
+    /** Present when status is needs-decision: what the caller must supply. */
+    decision?: string;
+}
+export interface InitOptions {
+    projectRoot: string;
+    /** Explicitly approved project_id. Omit to get a proposal (needs-decision). */
+    projectId?: string;
+    /** Explicit vault path. Falls back to OLC_VAULT_PATH, then existing config. */
+    vaultPath?: string;
+    env?: NodeJS.ProcessEnv;
+    dryRun?: boolean;
+}
+/** Derive a safe project_id proposal from the repository directory name. */
+export declare function proposeProjectId(repoRoot: string): string;
+export declare function initProject(options: InitOptions): InitReport;

package/dist/init/index.js

@@ -0,0 +1,178 @@
+/**
+ * Safe, idempotent project initialization (OLC-022, PRD §7.4 init flow).
+ *
+ * `initProject` never overwrites an existing file: every target is either
+ * created (when missing) or reported as preserved / attention-needed.
+ * Anything requiring a human choice (confirming the proposed project_id,
+ * providing a vault path, resolving a duplicate id) is returned as
+ * `status: "needs-decision"` with an actionable message — the caller
+ * (agent or user) supplies the answer on a follow-up call. No prompting
+ * happens inside this module, so it stays testable and non-interactive.
+ *
+ * Report entry actions: `created` | `preserved` | `attention`.
+ * With `dryRun: true` nothing is written; `created` then means "would create".
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { CONFIG_SCHEMA_VERSION, VAULT_PATH_ENV, parseConfig } from "../config/index.js";
+import { REGISTRY_REL_PATH, resolveRepoRoot } from "../core/project-identity.js";
+export const OLC_DIR = ".olc";
+export const CONFIG_FILE = "config.json";
+export const AGENTS_FILE = "AGENTS.md";
+const AGENTS_STUB = (projectId) => `# OLC project instructions — ${projectId}\n\n` +
+    "Review and customize this file. OLC agents read it before memory operations.\n";
+const VAULT_INDEX = (projectId) => `# ${projectId}\n\nOLC project memory root. See current-state.md for the latest status.\n`;
+const VAULT_STATE = (projectId) => `# Current state — ${projectId}\n\nInitialized. No activity recorded yet.\n`;
+/** Derive a safe project_id proposal from the repository directory name. */
+export function proposeProjectId(repoRoot) {
+    const cleaned = basename(resolve(repoRoot))
+        .toLowerCase()
+        .replace(/[^a-z0-9-_]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+    return cleaned || "project";
+}
+function readRegistryFile(path) {
+    if (!existsSync(path))
+        return { registry: { projects: {} }, existed: false };
+    const json = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof json !== "object" || json === null || Array.isArray(json)) {
+        throw new Error("invalid registry shape");
+    }
+    const projects = json.projects;
+    if (typeof projects !== "object" || projects === null)
+        throw new Error("invalid registry shape");
+    return { registry: json, existed: true };
+}
+function planFile(path, content, dryRun) {
+    if (existsSync(path))
+        return { path, action: "preserved" };
+    if (!dryRun) {
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(path, content);
+    }
+    return { path, action: "created" };
+}
+export function initProject(options) {
+    const dryRun = options.dryRun === true;
+    const env = options.env ?? process.env;
+    const projectRoot = resolve(options.projectRoot);
+    const repoRoot = resolveRepoRoot(projectRoot);
+    const base = { projectRoot, repoRoot, projectId: "", vaultRoot: null, dryRun, entries: [] };
+    // 1. Project id: explicit, existing config, or proposal needing approval.
+    let projectId = options.projectId?.trim();
+    const configPath = join(projectRoot, OLC_DIR, CONFIG_FILE);
+    let existingConfigId = null;
+    if (existsSync(configPath)) {
+        try {
+            existingConfigId = parseConfig(JSON.parse(readFileSync(configPath, "utf8"))).projectId;
+        }
+        catch {
+            base.entries.push({
+                path: configPath,
+                action: "attention",
+                note: "Existing config is invalid — fix or delete it, then re-run init. It was NOT overwritten.",
+            });
+            return { ...base, status: "needs-decision", decision: "repair-or-remove-invalid-config" };
+        }
+    }
+    if (!projectId) {
+        if (existingConfigId) {
+            projectId = existingConfigId;
+        }
+        else {
+            return {
+                ...base,
+                projectId: proposeProjectId(repoRoot),
+                status: "needs-decision",
+                decision: `Proposed project_id "${proposeProjectId(repoRoot)}" (from repository name). ` +
+                    "Re-run init with projectId set to this value to approve, or pass a different one.",
+            };
+        }
+    }
+    base.projectId = projectId;
+    // 2. Vault path: explicit > env > existing config > ask.
+    let vaultInput = options.vaultPath?.trim() || env[VAULT_PATH_ENV]?.trim() || null;
+    if (!vaultInput && existingConfigId && existingConfigId === projectId) {
+        try {
+            const parsed = parseConfig(JSON.parse(readFileSync(configPath, "utf8")));
+            vaultInput = parsed.vaultPath?.trim() || null;
+        }
+        catch {
+            /* already validated above; unreachable */
+        }
+    }
+    if (!vaultInput) {
+        return {
+            ...base,
+            status: "needs-decision",
+            decision: `No vault path for project "${projectId}". Re-run init with vaultPath set, ` +
+                `or set the ${VAULT_PATH_ENV} environment variable. OLC never invents a vault location.`,
+        };
+    }
+    const vaultRoot = resolve(repoRoot, vaultInput);
+    base.vaultRoot = vaultRoot;
+    // 3. Duplicate project_id check BEFORE any write.
+    const registryPath = join(vaultRoot, REGISTRY_REL_PATH);
+    let registry;
+    let registryExisted;
+    try {
+        ({ registry, existed: registryExisted } = readRegistryFile(registryPath));
+    }
+    catch {
+        base.entries.push({
+            path: registryPath,
+            action: "attention",
+            note: "Existing registry is corrupt — fix it or back it up, then re-run init. Nothing was written.",
+        });
+        return { ...base, status: "needs-decision", decision: "repair-corrupt-registry" };
+    }
+    const owner = registry.projects[projectId]?.repoRoot;
+    if (owner && resolve(owner) !== repoRoot) {
+        return {
+            ...base,
+            status: "needs-decision",
+            decision: `project_id "${projectId}" is already registered to another repository (${resolve(owner)}). ` +
+                "Re-run init with a different projectId for this checkout. Nothing was written.",
+        };
+    }
+    // 4. Write phase (skipped entirely under dryRun): create only missing files.
+    const entries = base.entries;
+    if (!existsSync(configPath)) {
+        const content = JSON.stringify({ schemaVersion: CONFIG_SCHEMA_VERSION, projectId, vaultPath: vaultInput }, null, 2) + "\n";
+        if (!dryRun) {
+            mkdirSync(join(configPath, ".."), { recursive: true });
+            writeFileSync(configPath, content);
+        }
+        entries.push({ path: configPath, action: "created" });
+    }
+    else {
+        entries.push({ path: configPath, action: "preserved" });
+    }
+    entries.push(planFile(join(projectRoot, OLC_DIR, AGENTS_FILE), AGENTS_STUB(projectId), dryRun));
+    const projectDir = join(vaultRoot, "OLC", "Projects", projectId);
+    entries.push(planFile(join(projectDir, "index.md"), VAULT_INDEX(projectId), dryRun));
+    entries.push(planFile(join(projectDir, "current-state.md"), VAULT_STATE(projectId), dryRun));
+    for (const sub of ["decisions", "tasks", "logs", "memory", "taste"]) {
+        const dir = join(projectDir, sub);
+        if (existsSync(dir)) {
+            entries.push({ path: dir, action: "preserved" });
+        }
+        else {
+            if (!dryRun)
+                mkdirSync(dir, { recursive: true });
+            entries.push({ path: dir, action: "created" });
+        }
+    }
+    if (!registryExisted || !owner) {
+        if (!dryRun) {
+            mkdirSync(join(registryPath, ".."), { recursive: true });
+            writeFileSync(registryPath, JSON.stringify({ projects: { ...registry.projects, [projectId]: { repoRoot } } }, null, 2) + "\n");
+        }
+        entries.push({ path: registryPath, action: "created" });
+    }
+    else {
+        entries.push({ path: registryPath, action: "preserved" });
+    }
+    return { ...base, status: "ready" };
+}

package/dist/log/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Activity event log (OLC-060).
+ *
+ * Important OLC activity is recorded as durable Markdown under the validated
+ * project scope: `<vault>/OLC/Projects/<project_id>/logs/YYYY-MM-DD.md`
+ * (one file per day — that date split IS the rotation; no size-based
+ * rotation for MVP).
+ *
+ * Design constraints (from the task spec):
+ * - Every write validates vault identity first (OLC-021); invalid vault →
+ *   throw with zero files created.
+ * - Appends use a single O_APPEND write, so an interruption can never
+ *   corrupt previously written entries. A file missing its trailing newline
+ *   (crash remnant) is normalized before the next append.
+ * - Secrets are scrubbed, never stored: known credential patterns in
+ *   summary/details are replaced with `[redacted]` and the entry is marked.
+ * - This module never hooks tool calls; events are recorded only by explicit
+ *   `logEvent` calls, so there is no per-tool-call noise by construction.
+ * - Readers take explicit paths; callers that cross project boundaries
+ *   (e.g. resume) must run `validateIdentity` themselves first.
+ */
+import type { ResolvedConfig } from "../config/index.js";
+export type LogErrorCode = "INVALID_EVENT" | "INVALID_DATE" | "LOG_WRITE_FAILED" | "LOG_READ_FAILED";
+export declare class LogError extends Error {
+    readonly code: LogErrorCode;
+    constructor(code: LogErrorCode, message: string);
+}
+export type LogEventKind = "milestone" | "checkpoint" | "task-status" | "decision" | "verify" | "session" | "scope-change";
+export interface LogEventInput {
+    kind: LogEventKind;
+    summary: string;
+    taskId?: string;
+    details?: string;
+    gitSha?: string;
+    /** ISO timestamp; defaults to now. Inject a fixed value in tests. */
+    date?: string;
+}
+export interface LoggedEvent {
+    kind: string;
+    summary: string;
+    taskId?: string;
+    details?: string;
+    gitSha?: string;
+    date: string;
+    redacted: boolean;
+}
+export interface LogEventArgs {
+    projectRoot: string;
+    config: ResolvedConfig;
+    event: LogEventInput;
+}
+/**
+ * Validate identity, then append one event to the day's log file.
+ * Returns the file path and the stored (scrubbed) entry.
+ */
+export declare function logEvent(args: LogEventArgs): {
+    file: string;
+    entry: LoggedEvent;
+};
+/** Parse entries from log Markdown (frontmatter header ignored). */
+export declare function parseEntries(text: string): LoggedEvent[];
+/** Read one day's log file; missing file → empty list (not an error). */
+export declare function readLogDay(vaultRoot: string, projectId: string, day: string): LoggedEvent[];
+/**
+ * Newest-first events across day files, up to `limit`. Day files sort
+ * lexicographically (YYYY-MM-DD), so no directory walk beyond `logs/`.
+ */
+export declare function readLastEvents(vaultRoot: string, projectId: string, limit: number): LoggedEvent[];

package/dist/log/index.js

@@ -0,0 +1,224 @@
+/**
+ * Activity event log (OLC-060).
+ *
+ * Important OLC activity is recorded as durable Markdown under the validated
+ * project scope: `<vault>/OLC/Projects/<project_id>/logs/YYYY-MM-DD.md`
+ * (one file per day — that date split IS the rotation; no size-based
+ * rotation for MVP).
+ *
+ * Design constraints (from the task spec):
+ * - Every write validates vault identity first (OLC-021); invalid vault →
+ *   throw with zero files created.
+ * - Appends use a single O_APPEND write, so an interruption can never
+ *   corrupt previously written entries. A file missing its trailing newline
+ *   (crash remnant) is normalized before the next append.
+ * - Secrets are scrubbed, never stored: known credential patterns in
+ *   summary/details are replaced with `[redacted]` and the entry is marked.
+ * - This module never hooks tool calls; events are recorded only by explicit
+ *   `logEvent` calls, so there is no per-tool-call noise by construction.
+ * - Readers take explicit paths; callers that cross project boundaries
+ *   (e.g. resume) must run `validateIdentity` themselves first.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateIdentity } from "../core/project-identity.js";
+import { projectScopeRoot, withFrontmatter } from "../vault/index.js";
+export class LogError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "LogError";
+        this.code = code;
+    }
+}
+/** Credential shapes that must never reach the vault. Documented, minimal. */
+const SECRET_PATTERNS = [
+    /sk-[A-Za-z0-9_-]{8,}/g,
+    /gh[pousr]_[A-Za-z0-9_]+/g,
+    /xox[bpas]-[A-Za-z0-9-]+/g,
+    /AKIA[0-9A-Z]{16}/g,
+    /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/g,
+    /(password|passwd|secret|token)\s*[:=]\s*\S+/gi,
+];
+function scrubSecrets(text) {
+    let out = text;
+    let redacted = false;
+    for (const pattern of SECRET_PATTERNS) {
+        pattern.lastIndex = 0;
+        if (pattern.test(out)) {
+            redacted = true;
+            pattern.lastIndex = 0;
+            out = out.replace(pattern, "[redacted]");
+        }
+    }
+    return { text: out, redacted };
+}
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
+function dayOf(iso) {
+    if (!ISO_DATE_RE.test(iso)) {
+        throw new LogError("INVALID_DATE", `Invalid log event date ${JSON.stringify(iso)}: expected an ISO timestamp like 2026-10-12T14:03:22Z.`);
+    }
+    return iso.slice(0, 10);
+}
+function logsDir(vaultRoot, projectId) {
+    return join(projectScopeRoot(vaultRoot, projectId), "logs");
+}
+function ensureDayFile(path, projectId, day) {
+    if (existsSync(path))
+        return;
+    mkdirSync(join(path, ".."), { recursive: true });
+    // "wx" fails when another process won the race — that is fine, the file
+    // (with an identical header) already exists and we just append below.
+    try {
+        const header = withFrontmatter({ project: projectId, type: "activity-log", date: day }, "");
+        appendFileSync(path, header.endsWith("\n") ? header : header + "\n", { flag: "wx" });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw new LogError("LOG_WRITE_FAILED", `Cannot create log file at ${path}: ${error.message}. Check vault permissions.`);
+        }
+    }
+}
+function formatEntry(event, iso) {
+    const scrubbedSummary = scrubSecrets(event.summary);
+    const scrubbedDetails = event.details !== undefined ? scrubSecrets(event.details) : null;
+    const redacted = scrubbedSummary.redacted || (scrubbedDetails?.redacted ?? false);
+    const lines = [`## ${iso} — ${event.kind}${event.taskId ? ` — task ${event.taskId}` : ""}`];
+    lines.push(`- summary: ${scrubbedSummary.text}`);
+    if (scrubbedDetails !== null)
+        lines.push(`- details: ${scrubbedDetails.text}`);
+    if (event.gitSha)
+        lines.push(`- sha: ${event.gitSha}`);
+    if (redacted)
+        lines.push(`- redacted: true`);
+    return lines.join("\n") + "\n";
+}
+/**
+ * Validate identity, then append one event to the day's log file.
+ * Returns the file path and the stored (scrubbed) entry.
+ */
+export function logEvent(args) {
+    const { event } = args;
+    if (!event || typeof event.summary !== "string" || event.summary.trim() === "") {
+        throw new LogError("INVALID_EVENT", "Invalid log event: a non-empty summary is required.");
+    }
+    if (typeof event.kind !== "string" || event.kind.trim() === "") {
+        throw new LogError("INVALID_EVENT", "Invalid log event: a kind is required (e.g. milestone, checkpoint, session).");
+    }
+    const identity = validateIdentity(args.projectRoot, args.config);
+    const iso = event.date ?? new Date().toISOString();
+    const day = dayOf(iso);
+    const dir = logsDir(identity.vaultRoot, identity.projectId);
+    const file = join(dir, `${day}.md`);
+    ensureDayFile(file, identity.projectId, day);
+    // Normalize a crash remnant: a file not ending in newline gets one, so the
+    // new entry always starts on its own line and prior entries stay intact.
+    // An unreadable target fails here as LOG_WRITE_FAILED, before any append.
+    let tail;
+    try {
+        tail = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new LogError("LOG_WRITE_FAILED", `Cannot read log file at ${file}: ${error.message}. Check vault permissions.`);
+    }
+    const prefix = tail === "" || tail.endsWith("\n") ? "" : "\n";
+    const body = formatEntry(event, iso);
+    try {
+        appendFileSync(file, prefix + body);
+    }
+    catch (error) {
+        throw new LogError("LOG_WRITE_FAILED", `Cannot append to log file at ${file}: ${error.message}. Check vault permissions.`);
+    }
+    const parsed = parseEntries(prefix + body);
+    return { file, entry: parsed[parsed.length - 1] };
+}
+/** Parse entries from log Markdown (frontmatter header ignored). */
+export function parseEntries(text) {
+    const events = [];
+    const normalized = text.startsWith("## ") ? "\n" + text : text;
+    const chunks = normalized.split("\n## ");
+    for (let i = 1; i < chunks.length; i++) {
+        const lines = chunks[i].split("\n");
+        const head = lines[0].split(" — ");
+        if (head.length < 2)
+            continue;
+        const [iso, kind, taskPart] = head;
+        if (!ISO_DATE_RE.test(iso) || !kind)
+            continue;
+        const entry = { kind, summary: "", date: iso, redacted: false };
+        if (taskPart?.startsWith("task "))
+            entry.taskId = taskPart.slice(5);
+        let current = null;
+        for (const line of lines.slice(1)) {
+            if (line.startsWith("## ") || line === "")
+                break;
+            const m = /^- (summary|details|sha|redacted): ?(.*)$/.exec(line);
+            if (m) {
+                const [, key, value] = m;
+                if (key === "summary") {
+                    entry.summary = value;
+                    current = "summary";
+                }
+                else if (key === "details") {
+                    entry.details = value;
+                    current = "details";
+                }
+                else if (key === "sha") {
+                    entry.gitSha = value;
+                    current = null;
+                }
+                else if (key === "redacted" && value.trim() === "true") {
+                    entry.redacted = true;
+                    current = null;
+                }
+                else
+                    current = null;
+            }
+            else if (line.startsWith("  ") && (current === "summary" || current === "details")) {
+                entry[current] += "\n" + line.slice(2);
+            }
+            else {
+                current = null;
+            }
+        }
+        events.push(entry);
+    }
+    return events;
+}
+/** Read one day's log file; missing file → empty list (not an error). */
+export function readLogDay(vaultRoot, projectId, day) {
+    const file = join(logsDir(vaultRoot, projectId), `${day}.md`);
+    if (!existsSync(file))
+        return [];
+    try {
+        return parseEntries(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new LogError("LOG_READ_FAILED", `Cannot read log file at ${file}: ${error.message}. Check vault permissions.`);
+    }
+}
+/**
+ * Newest-first events across day files, up to `limit`. Day files sort
+ * lexicographically (YYYY-MM-DD), so no directory walk beyond `logs/`.
+ */
+export function readLastEvents(vaultRoot, projectId, limit) {
+    const dir = logsDir(vaultRoot, projectId);
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f)).sort().reverse();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw new LogError("LOG_READ_FAILED", `Cannot list log directory at ${dir}: ${error.message}. Check vault permissions.`);
+    }
+    const out = [];
+    for (const file of files) {
+        const events = readLogDay(vaultRoot, projectId, file.slice(0, 10));
+        for (let i = events.length - 1; i >= 0 && out.length < limit; i--)
+            out.push(events[i]);
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Progressive memory retrieval (OLC-062).
+ *
+ * Read the small things first (`index.md`, `current-state.md`), then pull
+ * only the memory/decision docs, task docs, and log events relevant to the
+ * caller's query. Never scans the whole vault: every read is resolved inside
+ * the validated project's scope, so unrelated project folders are untouched
+ * by construction. Writes (`recordMemory`) go through the same identity gate
+ * and land only inside the validated project scope.
+ *
+ * Reuses: identity gate (OLC-021), scope-enforced vault paths + atomic
+ * writes (OLC-023), newest-first log readers (OLC-060).
+ */
+import type { ResolvedConfig } from "../config/index.js";
+import { type LoggedEvent } from "../log/index.js";
+export type MemoryErrorCode = "INVALID_NAME" | "INVALID_INPUT";
+export declare class MemoryError extends Error {
+    readonly code: MemoryErrorCode;
+    constructor(code: MemoryErrorCode, message: string);
+}
+/** Directories searched for relevant docs — always inside one project scope. */
+declare const SEARCH_DIRS: readonly ["memory", "decisions"];
+export interface MemoryMatch {
+    /** Which scope dir the doc lives in (`memory/` or `decisions/`). */
+    dir: (typeof SEARCH_DIRS)[number];
+    file: string;
+    score: number;
+    excerpt: string;
+    truncated: boolean;
+}
+export interface RecallTaskDocs {
+    taskId: string;
+    intent: string | null;
+    plan: string | null;
+}
+export interface RecallInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    /** Free-text query; empty/omitted means "base context only, no doc scan". */
+    query?: string;
+    /** When set, that task's intent/plan docs are included (missing → null). */
+    taskId?: string;
+    /** Default true: include recent log events (query-filtered when set). */
+    includeLogs?: boolean;
+    /** Max log events to consider. Default 10. */
+    logLimit?: number;
+    /** Max doc matches. Default 8. */
+    limit?: number;
+}
+export interface RecallResult {
+    projectId: string;
+    branch: string;
+    /** Project index, or null when not yet written. */
+    index: string | null;
+    /** Current state, or null when not yet written. */
+    currentState: string | null;
+    taskDocs: RecallTaskDocs | null;
+    /** Relevant docs, best score first (empty without a query). */
+    matches: MemoryMatch[];
+    /** Recent log events, newest first (query-filtered when a query is set). */
+    logEvents: LoggedEvent[];
+}
+/**
+ * Recall relevant memory. Validates identity first (wrong project or
+ * unavailable vault throws before any read), then reads index + state,
+ * the requested task's docs, query-matching scope docs, and recent logs.
+ * Read-only: never writes, never leaves the validated project scope.
+ */
+export declare function recallMemory(input: RecallInput): RecallResult;
+export interface RecordMemoryInput {
+    /** Any directory inside the project (identity resolution starts here). */
+    projectRoot: string;
+    config: ResolvedConfig;
+    /** Plain name (`auth-notes` → `memory/auth-notes.md`). No paths. */
+    name: string;
+    /** Markdown body. Must be non-empty. */
+    content: string;
+    /** Must be true to replace an existing note. Default false. */
+    overwrite?: boolean;
+}
+/**
+ * Record one memory note inside the validated project scope.
+ * Identity failures throw before any write; existing notes are never
+ * silently replaced (`overwrite: true` required).
+ * Returns the vault-relative path of the note.
+ */
+export declare function recordMemory(input: RecordMemoryInput): string;
+export {};