agent-recall-core 3.3.14 → 3.3.16

package/dist/digest/match.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Digest matching — find cached digests relevant to a query.
+ *
+ * Scoring formula (weights sum to 1.0):
+ *   score = keywordOverlap * 0.50 + scopeOverlap * 0.30 + recency * 0.20
+ *
+ * Recency uses Ebbinghaus forgetting curve with Zipf-adjusted half-life:
+ *   R = e^(-t / S_eff)
+ *   S_eff = S * max(1, log2(1 + access_count))
+ *
+ * Access frequency is integrated into decay rather than added as a bonus.
+ * A digest accessed 10× has an effective half-life of ~3.5× longer.
+ * A digest accessed 100× has ~6.6× longer. Useful digests persist; stale
+ * ones decay naturally. Score normalization is preserved (max = 1.0).
+ */
+import { type MatchedDigest } from "./types.js";
+/**
+ * Compute keyword overlap ratio between two keyword sets.
+ * Returns 0..1 where 1 = perfect overlap.
+ */
+export declare function keywordOverlap(a: string[], b: string[]): number;
+export interface FindDigestsOptions {
+    includeStale?: boolean;
+    includeGlobal?: boolean;
+    limit?: number;
+}
+/**
+ * Find digests matching a query across project + global stores.
+ */
+export declare function findMatchingDigests(query: string, project: string, opts?: FindDigestsOptions): MatchedDigest[];
+//# sourceMappingURL=match.d.ts.map

package/dist/digest/match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/digest/match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAGL,KAAK,aAAa,EAInB,MAAM,YAAY,CAAC;AAQpB;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ/D;AAmBD,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,kBAAkB,GACxB,aAAa,EAAE,CA0BjB"}

package/dist/digest/match.js

@@ -0,0 +1,132 @@
+/**
+ * Digest matching — find cached digests relevant to a query.
+ *
+ * Scoring formula (weights sum to 1.0):
+ *   score = keywordOverlap * 0.50 + scopeOverlap * 0.30 + recency * 0.20
+ *
+ * Recency uses Ebbinghaus forgetting curve with Zipf-adjusted half-life:
+ *   R = e^(-t / S_eff)
+ *   S_eff = S * max(1, log2(1 + access_count))
+ *
+ * Access frequency is integrated into decay rather than added as a bonus.
+ * A digest accessed 10× has an effective half-life of ~3.5× longer.
+ * A digest accessed 100× has ~6.6× longer. Useful digests persist; stale
+ * ones decay naturally. Score normalization is preserved (max = 1.0).
+ */
+import { digestDir, digestGlobalDir } from "../storage/paths.js";
+import { readJsonSafe } from "../storage/fs-utils.js";
+import { extractKeywords } from "../helpers/auto-name.js";
+import { MIN_MATCH_THRESHOLD, DIGEST_HALF_LIFE_DAYS, MAX_EXCERPT_LENGTH, } from "./types.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ---------------------------------------------------------------------------
+// Keyword overlap (exported for use by store.ts dedup check)
+// ---------------------------------------------------------------------------
+/**
+ * Compute keyword overlap ratio between two keyword sets.
+ * Returns 0..1 where 1 = perfect overlap.
+ */
+export function keywordOverlap(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    const setB = new Set(b.map((k) => k.toLowerCase()));
+    let matches = 0;
+    for (const kw of a) {
+        if (setB.has(kw.toLowerCase()))
+            matches++;
+    }
+    return matches / Math.max(a.length, b.length);
+}
+// ---------------------------------------------------------------------------
+// Ebbinghaus decay
+// ---------------------------------------------------------------------------
+/**
+ * Ebbinghaus retention: R = e^(-t/S)
+ * t = time since creation in days, S = half-life in days.
+ */
+function ebbinghausDecay(ageMs, halfLifeDays) {
+    const ageDays = ageMs / 86_400_000;
+    return Math.exp(-ageDays / halfLifeDays);
+}
+/**
+ * Find digests matching a query across project + global stores.
+ */
+export function findMatchingDigests(query, project, opts) {
+    const includeStale = opts?.includeStale ?? false;
+    const includeGlobal = opts?.includeGlobal ?? true;
+    const limit = opts?.limit ?? 5;
+    const queryKeywords = extractKeywords(query, 8);
+    if (queryKeywords.length === 0)
+        return [];
+    const candidates = [];
+    const now = Date.now();
+    // Search project digests
+    const projectDir = digestDir(project);
+    const projectEntries = loadEntries(projectDir);
+    scoreEntries(projectEntries, queryKeywords, now, includeStale, projectDir, candidates);
+    // Search global digests
+    if (includeGlobal) {
+        const globalDir = digestGlobalDir();
+        const globalEntries = loadEntries(globalDir);
+        scoreEntries(globalEntries, queryKeywords, now, includeStale, globalDir, candidates);
+    }
+    // Sort by score descending, take top N
+    candidates.sort((a, b) => b.score - a.score);
+    return candidates.slice(0, limit);
+}
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+function loadEntries(dir) {
+    const idx = readJsonSafe(path.join(dir, "index.json"));
+    return idx?.entries ?? [];
+}
+function scoreEntries(entries, queryKeywords, now, includeStale, dir, out) {
+    for (const entry of entries) {
+        if (entry.stale && !includeStale)
+            continue;
+        // Keyword overlap with title+keywords
+        const kwOverlap = keywordOverlap(queryKeywords, entry.keywords);
+        // Scope overlap — separate signal from scope field
+        const scopeKeywords = extractKeywords(entry.scope, 6);
+        const scopeOverlap = keywordOverlap(queryKeywords, scopeKeywords);
+        // Ebbinghaus recency with Zipf-adjusted half-life.
+        // High-access digests decay slower: S_eff = S * max(1, log2(1 + n))
+        const ageMs = now - new Date(entry.updated).getTime();
+        const effectiveHalfLife = DIGEST_HALF_LIFE_DAYS * Math.max(1, Math.log2(1 + entry.access_count));
+        const recency = ebbinghausDecay(ageMs, effectiveHalfLife);
+        // Final score — weights sum to 1.0, max score = 1.0
+        const score = kwOverlap * 0.50 + scopeOverlap * 0.30 + recency * 0.20;
+        if (score < MIN_MATCH_THRESHOLD)
+            continue;
+        const ageHours = Math.round(ageMs / 3_600_000);
+        // Read excerpt from content file (use caller-resolved dir, not entry.project)
+        const contentFile = path.join(dir, `${entry.id}.md`);
+        let excerpt = "";
+        if (fs.existsSync(contentFile)) {
+            const raw = fs.readFileSync(contentFile, "utf-8");
+            // Skip YAML frontmatter, then find first non-heading paragraph
+            const body = raw.replace(/^---[\s\S]*?---\n?/, "").trim();
+            const firstPara = body
+                .split(/\n\n+/)
+                .map((p) => p.trim())
+                .find((p) => p.length > 0 && !p.startsWith("#")) ?? body;
+            excerpt = firstPara.slice(0, MAX_EXCERPT_LENGTH);
+            if (firstPara.length > MAX_EXCERPT_LENGTH)
+                excerpt += "...";
+        }
+        out.push({
+            id: entry.id,
+            title: entry.title,
+            scope: entry.scope,
+            score: Math.round(score * 1000) / 1000,
+            token_estimate: entry.token_estimate,
+            stale: entry.stale,
+            stale_reason: entry.stale_reason,
+            age_hours: ageHours,
+            excerpt,
+            project: entry.project,
+        });
+    }
+}
+//# sourceMappingURL=match.js.map

package/dist/digest/match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"match.js","sourceRoot":"","sources":["../../src/digest/match.ts"],"names":[],"mappings":"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"}

package/dist/digest/store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Digest store — CRUD operations for pre-computed context cache.
+ *
+ * All writes are atomic via writeJsonAtomic and protected by filelock.
+ * Digests are stored as index.json (metadata) + {id}.md (content).
+ */
+import { type DigestEntry, type DigestStoreInput, type DigestStoreResult } from "./types.js";
+/**
+ * Store a new digest or refresh an existing one if title overlaps.
+ */
+export declare function createDigest(input: DigestStoreInput): DigestStoreResult;
+/**
+ * Read a digest's metadata and content.
+ */
+export declare function readDigest(project: string, id: string, global?: boolean): {
+    meta: DigestEntry | null;
+    content: string | null;
+};
+/**
+ * List all digests for a project.
+ */
+export declare function listDigests(project: string, opts?: {
+    stale?: boolean;
+    global?: boolean;
+}): DigestEntry[];
+/**
+ * Mark a digest as stale (soft-delete).
+ */
+export declare function markStale(project: string, id: string, reason: string, global?: boolean): void;
+/**
+ * Record an access (bump count + timestamp).
+ */
+export declare function recordAccess(project: string, id: string, global?: boolean): void;
+/**
+ * Check for expired digests and mark them stale. Returns newly staled entries.
+ */
+export declare function checkExpiry(project: string, global?: boolean): DigestEntry[];
+/**
+ * Permanently delete stale digests older than threshold.
+ */
+export declare function pruneStale(project: string, olderThanDays?: number, global?: boolean): number;
+//# sourceMappingURL=store.d.ts.map

package/dist/digest/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/digest/store.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAKvB,MAAM,YAAY,CAAC;AAqDpB;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,iBAAiB,CA4DvE;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,OAAO,GACf;IAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAStD;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3C,WAAW,EAAE,CAUf;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAW7F;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAWhF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,CAuB5E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,GAAE,MAAW,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAwBhG"}

package/dist/digest/store.js

@@ -0,0 +1,296 @@
+/**
+ * Digest store — CRUD operations for pre-computed context cache.
+ *
+ * All writes are atomic via writeJsonAtomic and protected by filelock.
+ * Digests are stored as index.json (metadata) + {id}.md (content).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { digestDir, digestGlobalDir } from "../storage/paths.js";
+import { ensureDir, readJsonSafe, writeJsonAtomic } from "../storage/fs-utils.js";
+import { withLock } from "../storage/filelock.js";
+import { extractKeywords } from "../helpers/auto-name.js";
+import { DEFAULT_TTL_HOURS, MAX_DIGESTS_PER_PROJECT, REFRESH_OVERLAP_THRESHOLD, } from "./types.js";
+import { keywordOverlap } from "./match.js";
+// ---------------------------------------------------------------------------
+// Index helpers
+// ---------------------------------------------------------------------------
+/** Valid digest ID format: digest-{timestamp}-{8 hex chars} */
+const ID_PATTERN = /^digest-\d+-[a-f0-9]{8}$/;
+function indexPath(dir) {
+    return path.join(dir, "index.json");
+}
+function contentPath(dir, id) {
+    if (!ID_PATTERN.test(id)) {
+        throw new Error(`Invalid digest id: ${id}`);
+    }
+    return path.join(dir, `${id}.md`);
+}
+function readIndex(dir) {
+    const idx = readJsonSafe(indexPath(dir));
+    if (idx)
+        return idx;
+    return { version: "1.0", updated: new Date().toISOString(), entries: [] };
+}
+function writeIndex(dir, index) {
+    index.updated = new Date().toISOString();
+    writeJsonAtomic(indexPath(dir), index);
+}
+function generateId(title) {
+    const ts = Date.now();
+    const hash = crypto.createHash("sha256").update(title + ts).digest("hex").slice(0, 8);
+    return `digest-${ts}-${hash}`;
+}
+function computeExpiry(ttlHours) {
+    if (ttlHours <= 0)
+        return null;
+    return new Date(Date.now() + ttlHours * 3600_000).toISOString();
+}
+function estimateTokens(content) {
+    // Rough heuristic: ~4 bytes per token for English, ~2.5 for CJK-heavy.
+    // Use 3.5 as a blend.
+    return Math.ceil(content.length / 3.5);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Store a new digest or refresh an existing one if title overlaps.
+ */
+export function createDigest(input) {
+    const project = input.project ?? "unknown";
+    const isGlobal = input.global ?? false;
+    const dir = isGlobal ? digestGlobalDir() : digestDir(project);
+    ensureDir(dir);
+    const ttl = input.ttl_hours ?? DEFAULT_TTL_HOURS;
+    const keywords = extractKeywords(input.title + " " + input.scope, 8);
+    const tokenEst = estimateTokens(input.content);
+    const now = new Date().toISOString();
+    return withLock(`digest-${isGlobal ? "global" : project}`, () => {
+        const index = readIndex(dir);
+        // Check for existing digest with high keyword overlap → refresh instead of duplicate
+        const existing = findOverlappingEntry(index.entries, keywords);
+        if (existing) {
+            return refreshDigestInternal(dir, index, existing, input.content, tokenEst, ttl, now);
+        }
+        // Create new entry
+        const id = generateId(input.title);
+        const entry = {
+            id,
+            title: input.title,
+            scope: input.scope,
+            keywords,
+            created: now,
+            updated: now,
+            expires: computeExpiry(ttl),
+            ttl_hours: ttl,
+            token_estimate: tokenEst,
+            source_agent: input.source_agent ?? "unknown",
+            source_query: input.source_query ?? "",
+            invalidation: resolveInvalidation(input.invalidation),
+            access_count: 0,
+            last_accessed: now,
+            stale: false,
+            project: isGlobal ? "__global__" : project,
+        };
+        // Enforce max digests: prune oldest stale, then oldest by access
+        if (index.entries.length >= MAX_DIGESTS_PER_PROJECT) {
+            pruneOne(dir, index);
+        }
+        // Write content file first — orphaned .md is harmless, dangling index entry is not
+        fs.writeFileSync(contentPath(dir, id), input.content, "utf-8");
+        index.entries.push(entry);
+        writeIndex(dir, index);
+        return {
+            success: true,
+            id,
+            action: "created",
+            token_estimate: tokenEst,
+            expires: entry.expires,
+            project: entry.project,
+        };
+    });
+}
+/**
+ * Read a digest's metadata and content.
+ */
+export function readDigest(project, id, global) {
+    if (!ID_PATTERN.test(id))
+        return { meta: null, content: null };
+    const dir = global ? digestGlobalDir() : digestDir(project);
+    const index = readIndex(dir);
+    const meta = index.entries.find((e) => e.id === id) ?? null;
+    if (!meta)
+        return { meta: null, content: null };
+    const cPath = contentPath(dir, id);
+    const content = fs.existsSync(cPath) ? fs.readFileSync(cPath, "utf-8") : null;
+    return { meta, content };
+}
+/**
+ * List all digests for a project.
+ */
+export function listDigests(project, opts) {
+    const dir = opts?.global ? digestGlobalDir() : digestDir(project);
+    const index = readIndex(dir);
+    let entries = index.entries;
+    if (opts?.stale === false) {
+        entries = entries.filter((e) => !e.stale);
+    }
+    else if (opts?.stale === true) {
+        entries = entries.filter((e) => e.stale);
+    }
+    return entries;
+}
+/**
+ * Mark a digest as stale (soft-delete).
+ */
+export function markStale(project, id, reason, global) {
+    const dir = global ? digestGlobalDir() : digestDir(project);
+    withLock(`digest-${global ? "global" : project}`, () => {
+        const index = readIndex(dir);
+        const entry = index.entries.find((e) => e.id === id);
+        if (entry) {
+            entry.stale = true;
+            entry.stale_reason = reason;
+            writeIndex(dir, index);
+        }
+    });
+}
+/**
+ * Record an access (bump count + timestamp).
+ */
+export function recordAccess(project, id, global) {
+    const dir = global ? digestGlobalDir() : digestDir(project);
+    withLock(`digest-${global ? "global" : project}`, () => {
+        const index = readIndex(dir);
+        const entry = index.entries.find((e) => e.id === id);
+        if (entry) {
+            entry.access_count++;
+            entry.last_accessed = new Date().toISOString();
+            writeIndex(dir, index);
+        }
+    });
+}
+/**
+ * Check for expired digests and mark them stale. Returns newly staled entries.
+ */
+export function checkExpiry(project, global) {
+    const dir = global ? digestGlobalDir() : digestDir(project);
+    const newlyStale = [];
+    withLock(`digest-${global ? "global" : project}`, () => {
+        const index = readIndex(dir);
+        const now = Date.now();
+        for (const entry of index.entries) {
+            if (entry.stale)
+                continue;
+            if (entry.expires && new Date(entry.expires).getTime() < now) {
+                entry.stale = true;
+                entry.stale_reason = "TTL expired";
+                newlyStale.push(entry);
+            }
+        }
+        if (newlyStale.length > 0) {
+            writeIndex(dir, index);
+        }
+    });
+    return newlyStale;
+}
+/**
+ * Permanently delete stale digests older than threshold.
+ */
+export function pruneStale(project, olderThanDays = 30, global) {
+    const dir = global ? digestGlobalDir() : digestDir(project);
+    let pruned = 0;
+    const cutoff = Date.now() - olderThanDays * 86_400_000;
+    withLock(`digest-${global ? "global" : project}`, () => {
+        const index = readIndex(dir);
+        const keep = [];
+        for (const entry of index.entries) {
+            if (entry.stale && new Date(entry.updated).getTime() < cutoff) {
+                const cp = contentPath(dir, entry.id);
+                if (fs.existsSync(cp))
+                    fs.unlinkSync(cp);
+                pruned++;
+            }
+            else {
+                keep.push(entry);
+            }
+        }
+        index.entries = keep;
+        writeIndex(dir, index);
+    });
+    return pruned;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function findOverlappingEntry(entries, keywords) {
+    let best;
+    let bestScore = 0;
+    for (const entry of entries) {
+        if (entry.stale)
+            continue;
+        const score = keywordOverlap(keywords, entry.keywords);
+        if (score > REFRESH_OVERLAP_THRESHOLD && score > bestScore) {
+            bestScore = score;
+            best = entry;
+        }
+    }
+    return best;
+}
+function refreshDigestInternal(dir, index, existing, newContent, tokenEst, callerTtl, now) {
+    existing.updated = now;
+    existing.token_estimate = tokenEst;
+    existing.access_count++;
+    existing.last_accessed = now;
+    existing.stale = false;
+    existing.stale_reason = undefined;
+    // Caller may provide a different TTL on refresh — respect it
+    existing.ttl_hours = callerTtl;
+    existing.expires = computeExpiry(callerTtl);
+    // Write content first — safer ordering
+    fs.writeFileSync(contentPath(dir, existing.id), newContent, "utf-8");
+    writeIndex(dir, index);
+    return {
+        success: true,
+        id: existing.id,
+        action: "refreshed",
+        token_estimate: tokenEst,
+        expires: existing.expires,
+        project: existing.project,
+    };
+}
+function resolveInvalidation(partial) {
+    return {
+        strategy: partial?.strategy ?? "ttl",
+        content_hash: partial?.content_hash,
+        git_commit: partial?.git_commit,
+        watched_paths: partial?.watched_paths,
+    };
+}
+function pruneOne(dir, index) {
+    // Prefer removing stale entries first
+    const staleIdx = index.entries.findIndex((e) => e.stale);
+    if (staleIdx >= 0) {
+        const removed = index.entries.splice(staleIdx, 1)[0];
+        const cp = contentPath(dir, removed.id);
+        if (fs.existsSync(cp))
+            fs.unlinkSync(cp);
+        return;
+    }
+    // Otherwise remove least-accessed entry (Zipf: low-access entries rarely hit again)
+    let minAccess = Infinity;
+    let minIdx = 0;
+    for (let i = 0; i < index.entries.length; i++) {
+        if (index.entries[i].access_count < minAccess) {
+            minAccess = index.entries[i].access_count;
+            minIdx = i;
+        }
+    }
+    const removed = index.entries.splice(minIdx, 1)[0];
+    const cp = contentPath(dir, removed.id);
+    if (fs.existsSync(cp))
+        fs.unlinkSync(cp);
+}
+//# sourceMappingURL=store.js.map

package/dist/digest/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/digest/store.ts"],"names":[],"mappings":"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"}

package/dist/digest/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Digest store types — pre-computed context cache for token saving.
+ *
+ * A digest is a stored computation result (e.g., codebase analysis, business
+ * logic extraction) that can be recalled instead of re-computing.
+ */
+export type InvalidationStrategy = "ttl" | "content-hash" | "git-commit" | "manual";
+export interface DigestInvalidation {
+    strategy: InvalidationStrategy;
+    /** SHA-256 of watched files at creation time. */
+    content_hash?: string;
+    /** Git HEAD commit hash at creation time. */
+    git_commit?: string;
+    /** File paths to watch — if any change, digest is stale. */
+    watched_paths?: string[];
+}
+export interface DigestEntry {
+    id: string;
+    title: string;
+    scope: string;
+    keywords: string[];
+    created: string;
+    updated: string;
+    expires: string | null;
+    ttl_hours: number;
+    token_estimate: number;
+    source_agent: string;
+    source_query: string;
+    invalidation: DigestInvalidation;
+    access_count: number;
+    last_accessed: string;
+    stale: boolean;
+    stale_reason?: string;
+    project: string;
+}
+export interface DigestIndex {
+    version: string;
+    updated: string;
+    entries: DigestEntry[];
+}
+export interface DigestStoreInput {
+    title: string;
+    scope: string;
+    content: string;
+    source_agent?: string;
+    source_query?: string;
+    ttl_hours?: number;
+    invalidation?: Partial<DigestInvalidation>;
+    project?: string;
+    global?: boolean;
+}
+export interface DigestStoreResult {
+    success: boolean;
+    id: string;
+    action: "created" | "refreshed";
+    token_estimate: number;
+    expires: string | null;
+    project: string;
+}
+export interface DigestRecallInput {
+    query: string;
+    project?: string;
+    include_stale?: boolean;
+    include_global?: boolean;
+    limit?: number;
+}
+export interface MatchedDigest {
+    id: string;
+    title: string;
+    scope: string;
+    score: number;
+    token_estimate: number;
+    stale: boolean;
+    stale_reason?: string;
+    age_hours: number;
+    excerpt: string;
+    project: string;
+}
+export interface DigestRecallResult {
+    query: string;
+    digests: MatchedDigest[];
+    result_count: number;
+    tokens_saved_estimate: number;
+}
+export interface DigestReadInput {
+    digest_id: string;
+    project?: string;
+}
+export interface DigestReadResult {
+    success: boolean;
+    meta: DigestEntry | null;
+    content: string | null;
+}
+/** Default TTL in hours (7 days). */
+export declare const DEFAULT_TTL_HOURS = 168;
+/** Max digests per project before pruning oldest stale. */
+export declare const MAX_DIGESTS_PER_PROJECT = 50;
+/** Min keyword overlap score to consider a match. */
+export declare const MIN_MATCH_THRESHOLD = 0.2;
+/** Overlap ratio above which a store becomes a refresh (dedup). */
+export declare const REFRESH_OVERLAP_THRESHOLD = 0.6;
+/** Ebbinghaus decay constant for digests in days. R = e^(-t/S). S=30 (~37% retention at 30 days). */
+export declare const DIGEST_HALF_LIFE_DAYS = 30;
+/** Max excerpt length in recall results. */
+export declare const MAX_EXCERPT_LENGTH = 300;
+//# sourceMappingURL=types.d.ts.map

package/dist/digest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/digest/types.ts"],"names":[],"mappings":"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"}