@pencil-agent/nano-pencil 1.11.18 → 1.11.19

package/dist/packages/mem-core/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * [UPSTREAM]: Depends on node:fs, engine, insights
+ * [SURFACE]: NanoMem CLI - stats, search, forget, export, insights commands
+ * [LOCUS]: packages/mem-core/src/cli.ts - NanoMem standalone CLI
+ * [COVENANT]: Change CLI → update this header
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/packages/mem-core/config.d.ts

@@ -0,0 +1,78 @@
+/**
+ * [UPSTREAM]: Depends on node:os, node:path, ./types.js
+ * [SURFACE]: ProgressiveRecallConfig, NanomemConfig, getConfig, BudgetConfig, ScoreWeights
+ * [LOCUS]: packages/mem-core/src/config.ts - configuration management for memory system
+ * [COVENANT]: Change config structure → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import type { MemoryScope } from "./types.js";
+export interface ProgressiveRecallConfig {
+    /** Score threshold for Active tier — inject full detail */
+    thresholdActive: number;
+    /** Score threshold for Cue tier — inject name + summary + id */
+    thresholdCue: number;
+    /** Budget ratio for Active tier (default 0.15 = 15%) */
+    budgetActive: number;
+    /** Budget ratio for Cue tier (default 0.70 = 70%) */
+    budgetCue: number;
+    /** Force entries created within this many hours to Active tier */
+    forceRecentHours: number;
+    /** Force entries with importance >= this value to Active tier */
+    forceImportanceMin: number;
+}
+export interface EmbeddingConfig {
+    enabled: boolean;
+    model: string;
+    dim: number;
+    autoSync: boolean;
+}
+export interface NanomemConfig {
+    memoryDir: string;
+    tokenBudget: number;
+    budget: {
+        lessons: number;
+        knowledge: number;
+        events: number;
+        episodes: number;
+        preferences: number;
+        work: number;
+        facets: number;
+    };
+    halfLife: Record<string, number>;
+    maxEntries: {
+        knowledge: number;
+        lessons: number;
+        events: number;
+        preferences: number;
+        work: number;
+        facets: number;
+    };
+    consolidationThreshold: number;
+    /** Stanford-style retrieval scoring weights */
+    scoreWeights: {
+        recency: number;
+        importance: number;
+        relevance: number;
+    };
+    /** Utility-weighted eviction: access frequency vs base impact */
+    evictionWeights: {
+        accessFrequency: number;
+        baseImpact: number;
+    };
+    /** Default scope for all operations */
+    defaultScope?: MemoryScope;
+    /** Locale for LLM prompts and injection templates */
+    locale: "en" | "zh";
+    /** Strength growth factor on each successful recall (spaced repetition) */
+    strengthGrowthFactor: number;
+    /** Progressive recall injection configuration */
+    progressiveRecall: ProgressiveRecallConfig;
+    /** Default forgetting windows for less important memories */
+    forgetting: {
+        ambientTtlDays: number;
+        workTtlDays: number;
+    };
+    /** Embedding configuration for semantic episodic/procedural recall */
+    embeddings: EmbeddingConfig;
+}
+export declare function getConfig(overrides?: Partial<NanomemConfig>): NanomemConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/packages/mem-core/config.js

@@ -0,0 +1,81 @@
+/**
+ * [UPSTREAM]: Depends on node:os, node:path, ./types.js
+ * [SURFACE]: ProgressiveRecallConfig, NanomemConfig, getConfig, BudgetConfig, ScoreWeights
+ * [LOCUS]: packages/mem-core/src/config.ts - configuration management for memory system
+ * [COVENANT]: Change config structure → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+const DEFAULT_BUDGET = {
+    lessons: 0.18,
+    knowledge: 0.17,
+    events: 0.15,
+    episodes: 0.18,
+    preferences: 0.1,
+    work: 0.2,
+    facets: 0.12,
+};
+const DEFAULT_HALF_LIFE = {
+    lesson: 90,
+    fact: 60,
+    episode: 14,
+    preference: 120,
+    decision: 45,
+    entity: 30,
+    event: 180,
+    work: 45,
+    pattern: 180,
+    struggle: 120,
+};
+const DEFAULT_MAX_ENTRIES = { knowledge: 1000, lessons: 500, events: 300, preferences: 200, work: 400, facets: 400 };
+const DEFAULT_SCORE_WEIGHTS = { recency: 1, importance: 1, relevance: 1 };
+const DEFAULT_EVICTION_WEIGHTS = { accessFrequency: 0.4, baseImpact: 0.6 };
+const DEFAULT_PROGRESSIVE_RECALL = {
+    thresholdActive: 0.7,
+    thresholdCue: 0.35,
+    budgetActive: 0.15,
+    budgetCue: 0.70,
+    forceRecentHours: 24,
+    forceImportanceMin: 9,
+};
+const DEFAULT_FORGETTING = {
+    ambientTtlDays: 45,
+    workTtlDays: 21,
+};
+const DEFAULT_EMBEDDINGS = {
+    enabled: true,
+    model: "local-hash-v1",
+    dim: 256,
+    autoSync: true,
+};
+export function getConfig(overrides) {
+    const tokenBudget = Number(process.env.NANOMEM_TOKEN_BUDGET) || 6000;
+    const memoryDir = process.env.NANOMEM_MEMORY_DIR || overrides?.memoryDir || join(homedir(), ".nanomem", "memory");
+    const locale = process.env.NANOMEM_LOCALE || overrides?.locale || "en";
+    const embeddingsEnabled = process.env.NANOMEM_EMBEDDINGS_ENABLED;
+    const embeddingsDim = Number(process.env.NANOMEM_EMBEDDINGS_DIM) || DEFAULT_EMBEDDINGS.dim;
+    const embeddingsModel = process.env.NANOMEM_EMBEDDINGS_MODEL || DEFAULT_EMBEDDINGS.model;
+    return {
+        memoryDir,
+        tokenBudget: overrides?.tokenBudget ?? tokenBudget,
+        budget: overrides?.budget ?? { ...DEFAULT_BUDGET },
+        halfLife: overrides?.halfLife ?? { ...DEFAULT_HALF_LIFE },
+        maxEntries: overrides?.maxEntries ?? { ...DEFAULT_MAX_ENTRIES },
+        consolidationThreshold: overrides?.consolidationThreshold ?? 10,
+        scoreWeights: overrides?.scoreWeights ?? { ...DEFAULT_SCORE_WEIGHTS },
+        evictionWeights: overrides?.evictionWeights ?? { ...DEFAULT_EVICTION_WEIGHTS },
+        defaultScope: overrides?.defaultScope,
+        locale,
+        strengthGrowthFactor: overrides?.strengthGrowthFactor ?? 1.5,
+        progressiveRecall: overrides?.progressiveRecall ?? { ...DEFAULT_PROGRESSIVE_RECALL },
+        forgetting: overrides?.forgetting ?? { ...DEFAULT_FORGETTING },
+        embeddings: overrides?.embeddings ??
+            {
+                enabled: embeddingsEnabled ? embeddingsEnabled.toLowerCase() !== "false" : DEFAULT_EMBEDDINGS.enabled,
+                model: embeddingsModel,
+                dim: embeddingsDim,
+                autoSync: DEFAULT_EMBEDDINGS.autoSync,
+            },
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/packages/mem-core/consolidate-v2.d.ts

@@ -0,0 +1,15 @@
+/**
+ * [UPSTREAM]: Depends on ./config.js, ./scoring.js, ./store.js, ./types.js, ./types-v2.js
+ * [SURFACE]: consolidateV2Memories
+ * [LOCUS]: packages/mem-core/src/consolidate-v2.ts - v2 episodic/procedural to semantic consolidation
+ * [COVENANT]: Change v2 semantic promotion rules → update this header and keep compatibility with MemoryEntry
+ */
+import type { NanomemConfig } from "./config.js";
+import type { MemoryEntry } from "./types.js";
+import type { EpisodeFacet, EpisodeMemory, ProceduralMemory, SemanticMemory } from "./types-v2.js";
+export declare function consolidateV2Memories(episodes: EpisodeMemory[], facets: EpisodeFacet[], procedural: ProceduralMemory[], cfg: NanomemConfig): {
+    entries: MemoryEntry[];
+    semantic: SemanticMemory[];
+    episodeSemanticMap: Map<string, string[]>;
+};
+//# sourceMappingURL=consolidate-v2.d.ts.map

package/dist/packages/mem-core/consolidation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * [UPSTREAM]: Depends on ./config.js, ./i18n.js, ./scoring.js, ./store.js, ./types.js
+ * [SURFACE]: consolidateEpisodes, extractFactsFromEpisodes, extractLessonsFromEpisodes
+ * [LOCUS]: packages/mem-core/src/consolidation.ts - episodic→semantic consolidation, heart of multi-store memory model
+ * [COVENANT]: Change consolidation logic → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import type { NanomemConfig } from "./config.js";
+import type { Episode, LlmFn, MemoryEntry } from "./types.js";
+export declare function consolidateEpisodes(episodes: Episode[], cfg: NanomemConfig, llmFn?: LlmFn, options?: {
+    signal?: AbortSignal;
+}): Promise<MemoryEntry[]>;
+//# sourceMappingURL=consolidation.d.ts.map

package/dist/packages/mem-core/consolidation.js

@@ -0,0 +1,182 @@
+/**
+ * [UPSTREAM]: Depends on ./config.js, ./i18n.js, ./scoring.js, ./store.js, ./types.js
+ * [SURFACE]: consolidateEpisodes, extractFactsFromEpisodes, extractLessonsFromEpisodes
+ * [LOCUS]: packages/mem-core/src/consolidation.ts - episodic→semantic consolidation, heart of multi-store memory model
+ * [COVENANT]: Change consolidation logic → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import { PROMPTS } from "./i18n.js";
+import { extractTags } from "./scoring.js";
+import { deriveNameFromContent, deriveSummaryFromContent } from "./store.js";
+function makeId() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export async function consolidateEpisodes(episodes, cfg, llmFn, options) {
+    const unconsolidated = episodes.filter((ep) => !ep.consolidated);
+    if (unconsolidated.length < cfg.consolidationThreshold)
+        return [];
+    if (options?.signal?.aborted) {
+        throw new Error("AbortError");
+    }
+    let newEntries;
+    if (llmFn) {
+        newEntries = await llmConsolidation(unconsolidated, cfg, llmFn, options?.signal);
+    }
+    else {
+        newEntries = heuristicConsolidation(unconsolidated, cfg);
+    }
+    if (options?.signal?.aborted) {
+        throw new Error("AbortError");
+    }
+    for (const ep of unconsolidated)
+        ep.consolidated = true;
+    return newEntries;
+}
+async function llmConsolidation(episodes, cfg, llmFn, signal) {
+    const p = PROMPTS[cfg.locale] ?? PROMPTS.en;
+    const summary = episodes
+        .map((ep) => `[${ep.date}] ${ep.project}: ${ep.summary}\nFiles: ${ep.filesModified.join(", ")}\nErrors: ${ep.errors.join("; ") || "none"}`)
+        .join("\n\n");
+    if (signal?.aborted)
+        throw new Error("AbortError");
+    const raw = await llmFn(p.consolidationSystem, summary);
+    if (signal?.aborted)
+        throw new Error("AbortError");
+    try {
+        const items = JSON.parse(raw);
+        const now = new Date().toISOString();
+        return items.map((item) => {
+            const type = item.type === "lesson" ? "lesson" : item.type === "event" ? "event" : "fact";
+            const detail = item.detail || item.content || "";
+            const name = item.name || deriveNameFromContent(detail);
+            const summary = item.summary || deriveSummaryFromContent(detail);
+            return {
+                id: makeId(),
+                type,
+                name,
+                summary,
+                detail,
+                content: detail,
+                tags: extractTags(`${name} ${summary} ${detail}`),
+                project: episodes[0]?.project ?? "unknown",
+                importance: item.importance ?? 6,
+                strength: cfg.halfLife[type] ?? 30,
+                created: now,
+                eventTime: now,
+                accessCount: 0,
+                relatedIds: [],
+                retention: type === "event" ? "key-event" : type === "lesson" ? "key-event" : "ambient",
+                salience: type === "event" ? Math.max(8, item.importance ?? 8) : item.importance ?? 6,
+                stability: type === "event" ? "stable" : type === "lesson" ? "stable" : "situational",
+                scope: cfg.defaultScope,
+            };
+        });
+    }
+    catch {
+        return heuristicConsolidation(episodes, cfg);
+    }
+}
+function heuristicConsolidation(episodes, cfg) {
+    const now = new Date().toISOString();
+    const result = [];
+    const fileCounts = new Map();
+    for (const ep of episodes) {
+        for (const f of ep.filesModified)
+            fileCounts.set(f, (fileCounts.get(f) ?? 0) + 1);
+    }
+    const hotFiles = [...fileCounts.entries()]
+        .filter(([, c]) => c >= 3)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5);
+    if (hotFiles.length) {
+        const detail = `Frequently modified files: ${hotFiles.map(([f, c]) => `${f} (${c}x)`).join(", ")}`;
+        const name = deriveNameFromContent(detail);
+        const summary = deriveSummaryFromContent(detail);
+        result.push({
+            id: makeId(),
+            type: "fact",
+            name,
+            summary,
+            detail,
+            content: detail,
+            tags: extractTags(detail),
+            project: episodes[0]?.project ?? "unknown",
+            importance: 5,
+            strength: cfg.halfLife.fact ?? 60,
+            created: now,
+            eventTime: now,
+            accessCount: 0,
+            relatedIds: [],
+            stability: "situational",
+            scope: cfg.defaultScope,
+        });
+    }
+    const allErrors = episodes.flatMap((ep) => ep.errors).filter(Boolean);
+    if (allErrors.length) {
+        const errorSet = [...new Set(allErrors)].slice(0, 5);
+        const detail = `Recurring issues: ${errorSet.join("; ")}`;
+        const name = deriveNameFromContent(detail);
+        const summary = deriveSummaryFromContent(detail);
+        result.push({
+            id: makeId(),
+            type: "lesson",
+            name,
+            summary,
+            detail,
+            content: detail,
+            tags: extractTags(detail),
+            project: episodes[0]?.project ?? "unknown",
+            importance: 7,
+            strength: cfg.halfLife.lesson ?? 90,
+            created: now,
+            eventTime: now,
+            accessCount: 0,
+            relatedIds: [],
+            retention: "key-event",
+            salience: 8,
+            stability: "stable",
+            scope: cfg.defaultScope,
+        });
+    }
+    const significantEpisodes = [...episodes]
+        .filter((ep) => ep.importance >= 8 || ep.errors.length >= 2)
+        .sort((a, b) => b.importance - a.importance)
+        .slice(0, 3);
+    for (const ep of significantEpisodes) {
+        const detailParts = [
+            ep.summary,
+            ep.userGoal ? `Goal: ${ep.userGoal}` : "",
+            ep.errors.length ? `Errors: ${ep.errors.join("; ")}` : "",
+            ep.keyObservations.length ? `Observations: ${ep.keyObservations.slice(0, 4).join("; ")}` : "",
+        ].filter(Boolean);
+        const detail = detailParts.join("\n");
+        const name = ep.userGoal ? deriveNameFromContent(ep.userGoal) : deriveNameFromContent(ep.summary);
+        const summary = deriveSummaryFromContent(ep.summary || ep.userGoal || detail);
+        result.push({
+            id: makeId(),
+            type: "event",
+            name,
+            summary,
+            detail,
+            content: detail,
+            tags: extractTags(`${ep.project} ${ep.summary} ${ep.userGoal || ""} ${ep.errors.join(" ")}`),
+            project: ep.project || "unknown",
+            importance: Math.min(10, Math.max(8, ep.importance)),
+            strength: cfg.halfLife.event ?? 180,
+            created: now,
+            eventTime: ep.date ? new Date(ep.date).toISOString() : now,
+            accessCount: 0,
+            relatedIds: [],
+            retention: "key-event",
+            salience: Math.min(10, Math.max(8, ep.importance + ep.errors.length)),
+            stability: ep.errors.length ? "situational" : "stable",
+            eventData: {
+                kind: ep.errors.length ? "incident" : "milestone",
+                outcome: ep.errors.length ? "Captured from a high-friction session" : "Captured from a high-importance session",
+                emotionalWeight: Math.min(10, ep.importance),
+            },
+            scope: cfg.defaultScope,
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=consolidation.js.map

package/dist/packages/mem-core/dedup.d.ts

@@ -0,0 +1,18 @@
+/**
+ * [UPSTREAM]: Depends on ./scoring.js, ./types.js, ./update.js
+ * [SURFACE]: dedupeMemoryEntries, dedupeWorkEntries, mergeRelatedIds
+ * [LOCUS]: packages/mem-core/src/dedup.ts - batch deduplication and cross-entry merge logic
+ * [COVENANT]: Change dedup algorithm → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import type { MemoryEntry, WorkEntry } from "./types.js";
+/** Deduplicate MemoryEntry array. Keeps best of each duplicate group, merges relatedIds. */
+export declare function deduplicateMemoryEntries(entries: MemoryEntry[]): {
+    deduped: MemoryEntry[];
+    removedCount: number;
+};
+/** Deduplicate WorkEntry array. */
+export declare function deduplicateWorkEntries(entries: WorkEntry[]): {
+    deduped: WorkEntry[];
+    removedCount: number;
+};
+//# sourceMappingURL=dedup.d.ts.map

package/dist/packages/mem-core/dedup.js

@@ -0,0 +1,85 @@
+/**
+ * [UPSTREAM]: Depends on ./scoring.js, ./types.js, ./update.js
+ * [SURFACE]: dedupeMemoryEntries, dedupeWorkEntries, mergeRelatedIds
+ * [LOCUS]: packages/mem-core/src/dedup.ts - batch deduplication and cross-entry merge logic
+ * [COVENANT]: Change dedup algorithm → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import { tagOverlap } from "./scoring.js";
+import { contentSimilarity } from "./update.js";
+const NOOP_TAG_THRESHOLD = 0.75;
+const NOOP_CONTENT_THRESHOLD = 0.8;
+function isMemoryDuplicate(a, b) {
+    if (a.type !== b.type)
+        return false;
+    const aText = `${a.name || ""} ${a.summary || ""} ${a.content || ""}`.trim();
+    const bText = `${b.name || ""} ${b.summary || ""} ${b.content || ""}`.trim();
+    const tagMatch = tagOverlap(a.tags, b.tags) >= NOOP_TAG_THRESHOLD;
+    const contentMatch = contentSimilarity(aText, bText) >= NOOP_CONTENT_THRESHOLD;
+    return tagMatch || contentMatch;
+}
+function isWorkDuplicate(a, b) {
+    const aText = `${a.goal} ${a.summary}`.trim();
+    const bText = `${b.goal} ${b.summary}`.trim();
+    const tagMatch = tagOverlap(a.tags, b.tags) >= NOOP_TAG_THRESHOLD;
+    const contentMatch = contentSimilarity(aText, bText) >= NOOP_CONTENT_THRESHOLD;
+    return tagMatch || contentMatch;
+}
+/** Merge duplicate into keeper: relatedIds union, max importance/accessCount, latest lastAccessed */
+function mergeMemoryInto(keeper, duplicate) {
+    const ids = new Set([...(keeper.relatedIds || []), ...(duplicate.relatedIds || []), duplicate.id]);
+    keeper.relatedIds = [...ids];
+    keeper.importance = Math.max(keeper.importance, duplicate.importance);
+    keeper.accessCount = Math.max(keeper.accessCount, duplicate.accessCount);
+    if ((duplicate.lastAccessed || "") > (keeper.lastAccessed || ""))
+        keeper.lastAccessed = duplicate.lastAccessed;
+}
+function mergeWorkInto(keeper, duplicate) {
+    const ids = new Set([...(keeper.relatedIds || []), ...(duplicate.relatedIds || []), duplicate.id]);
+    keeper.relatedIds = [...ids];
+    keeper.importance = Math.max(keeper.importance, duplicate.importance);
+    keeper.accessCount = Math.max(keeper.accessCount, duplicate.accessCount);
+    if ((duplicate.lastAccessed || "") > (keeper.lastAccessed || ""))
+        keeper.lastAccessed = duplicate.lastAccessed;
+}
+/** Sort by quality (best first) so we keep the best of each duplicate group */
+function memoryQuality(e) {
+    return (e.accessCount + 1) * e.importance;
+}
+function workQuality(w) {
+    return (w.accessCount + 1) * w.importance;
+}
+/** Deduplicate MemoryEntry array. Keeps best of each duplicate group, merges relatedIds. */
+export function deduplicateMemoryEntries(entries) {
+    const sorted = [...entries].sort((a, b) => memoryQuality(b) - memoryQuality(a));
+    const kept = [];
+    let removedCount = 0;
+    for (const e of sorted) {
+        const existing = kept.find((k) => isMemoryDuplicate(k, e));
+        if (existing) {
+            mergeMemoryInto(existing, e);
+            removedCount++;
+        }
+        else {
+            kept.push(e);
+        }
+    }
+    return { deduped: kept, removedCount };
+}
+/** Deduplicate WorkEntry array. */
+export function deduplicateWorkEntries(entries) {
+    const sorted = [...entries].sort((a, b) => workQuality(b) - workQuality(a));
+    const kept = [];
+    let removedCount = 0;
+    for (const e of sorted) {
+        const existing = kept.find((k) => isWorkDuplicate(k, e));
+        if (existing) {
+            mergeWorkInto(existing, e);
+            removedCount++;
+        }
+        else {
+            kept.push(e);
+        }
+    }
+    return { deduped: kept, removedCount };
+}
+//# sourceMappingURL=dedup.js.map

package/dist/packages/mem-core/dream-lock.d.ts

@@ -0,0 +1,11 @@
+/**
+ * [UPSTREAM]: Depends on node:fs, node:fs/promises
+ * [SURFACE]: DreamLock, tryAcquireDreamLock, releaseDreamLock, isDreamLocked, waitForDreamLock
+ * [LOCUS]: packages/mem-core/src/dream-lock.ts - file-based mutex for background consolidation (dream) process
+ * [COVENANT]: Change locking mechanism → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+export declare function readDreamLockMtimeMs(lockPath: string): Promise<number>;
+export declare function tryAcquireDreamLock(lockPath: string, holderStaleMs: number): Promise<number | null>;
+export declare function rollbackDreamLock(lockPath: string, priorMtimeMs: number): Promise<void>;
+export declare function stampDreamLock(lockPath: string): Promise<void>;
+//# sourceMappingURL=dream-lock.d.ts.map

package/dist/packages/mem-core/dream-lock.js

@@ -0,0 +1,84 @@
+/**
+ * [UPSTREAM]: Depends on node:fs, node:fs/promises
+ * [SURFACE]: DreamLock, tryAcquireDreamLock, releaseDreamLock, isDreamLocked, waitForDreamLock
+ * [LOCUS]: packages/mem-core/src/dream-lock.ts - file-based mutex for background consolidation (dream) process
+ * [COVENANT]: Change locking mechanism → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import { existsSync } from "node:fs";
+import { readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
+function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readDreamLockMtimeMs(lockPath) {
+    try {
+        if (!existsSync(lockPath))
+            return 0;
+        const s = await stat(lockPath);
+        return s.mtimeMs || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function tryAcquireDreamLock(lockPath, holderStaleMs) {
+    const now = Date.now();
+    let priorMtimeMs = 0;
+    try {
+        if (existsSync(lockPath)) {
+            const s = await stat(lockPath);
+            priorMtimeMs = s.mtimeMs || 0;
+            const body = await readFile(lockPath, "utf-8").catch(() => "");
+            const holderPid = Number.parseInt(body.trim(), 10);
+            const isFresh = now - priorMtimeMs < holderStaleMs;
+            if (isFresh && isPidAlive(holderPid))
+                return null;
+        }
+    }
+    catch {
+        // treat as missing/claimable
+    }
+    try {
+        await writeFile(lockPath, String(process.pid), "utf-8");
+        await utimes(lockPath, new Date(now), new Date(now));
+        const verify = await readFile(lockPath, "utf-8").catch(() => "");
+        if (verify.trim() !== String(process.pid))
+            return null;
+        return priorMtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+export async function rollbackDreamLock(lockPath, priorMtimeMs) {
+    try {
+        if (priorMtimeMs === 0) {
+            await rm(lockPath, { force: true });
+            return;
+        }
+        await writeFile(lockPath, "", "utf-8");
+        const prior = new Date(priorMtimeMs);
+        await utimes(lockPath, prior, prior);
+    }
+    catch {
+        // best-effort rollback
+    }
+}
+export async function stampDreamLock(lockPath) {
+    const now = Date.now();
+    try {
+        await writeFile(lockPath, String(process.pid), "utf-8");
+        await utimes(lockPath, new Date(now), new Date(now));
+    }
+    catch {
+        // best-effort stamp
+    }
+}
+//# sourceMappingURL=dream-lock.js.map

package/dist/packages/mem-core/eviction.d.ts

@@ -0,0 +1,14 @@
+/**
+ * [UPSTREAM]: Depends on ./scoring.js, ./types.js
+ * [SURFACE]: EvictionWeights, utilityEntry, utilityWork
+ * [LOCUS]: packages/mem-core/src/eviction.ts - utility-weighted memory eviction (Ebbinghaus-aligned decay)
+ * [COVENANT]: Change eviction formula → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import type { MemoryEntry, WorkEntry } from "./types.js";
+export interface EvictionWeights {
+    accessFrequency: number;
+    baseImpact: number;
+}
+export declare function utilityEntry(e: MemoryEntry, defaultHalfLife: Record<string, number>, w: EvictionWeights): number;
+export declare function utilityWork(w: WorkEntry, defaultHalfLife: Record<string, number>, ew: EvictionWeights): number;
+//# sourceMappingURL=eviction.d.ts.map

package/dist/packages/mem-core/eviction.js

@@ -0,0 +1,26 @@
+/**
+ * [UPSTREAM]: Depends on ./scoring.js, ./types.js
+ * [SURFACE]: EvictionWeights, utilityEntry, utilityWork
+ * [LOCUS]: packages/mem-core/src/eviction.ts - utility-weighted memory eviction (Ebbinghaus-aligned decay)
+ * [COVENANT]: Change eviction formula → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import { daysSince, decay } from "./scoring.js";
+export function utilityEntry(e, defaultHalfLife, w) {
+    const strength = e.strength || defaultHalfLife[e.type] || 30;
+    const accessNorm = Math.min(1, (e.accessCount ?? 0) / 10);
+    const impactNorm = Math.min(1, e.importance / 10);
+    const salienceNorm = Math.min(1, (e.salience ?? e.importance) / 10);
+    const retentionMultiplier = e.retention === "core" ? 1.25 : e.retention === "key-event" ? 1.35 : 0.9;
+    const stabilityMultiplier = e.stability === "stable" ? 1.08 : 0.78;
+    return ((w.accessFrequency * accessNorm + w.baseImpact * impactNorm + salienceNorm * 0.2) *
+        retentionMultiplier *
+        stabilityMultiplier *
+        decay(daysSince(e.created), strength));
+}
+export function utilityWork(w, defaultHalfLife, ew) {
+    const strength = w.strength || defaultHalfLife.work || 45;
+    const accessNorm = Math.min(1, (w.accessCount ?? 0) / 10);
+    const impactNorm = Math.min(1, w.importance / 10);
+    return (ew.accessFrequency * accessNorm + ew.baseImpact * impactNorm) * decay(daysSince(w.created), strength);
+}
+//# sourceMappingURL=eviction.js.map

package/dist/packages/mem-core/extension.d.ts

@@ -0,0 +1,12 @@
+/**
+ * [UPSTREAM]: Depends on node:fs, node:fs/promises, node:path, @sinclair/typebox, @pencil-agent/nano-pencil
+ * [SURFACE]: default export (Extension), nanomem extension for NanoPencil integration
+ * [LOCUS]: packages/mem-core/src/extension.ts - thin adapter bridging NanoPencil events to host-agnostic NanoMemEngine
+ * [COVENANT]: Change extension hooks → update this header and verify against packages/mem-core/CLAUDE.md
+ *
+ * NOTE: This is the ONLY module that depends on @pencil-agent/nano-pencil types.
+ * For non-NanoPencil hosts, import from the package root (index.ts) instead.
+ */
+import type { ExtensionAPI } from "@pencil-agent/nano-pencil";
+export default function nanomemExtension(pi: ExtensionAPI): void;
+//# sourceMappingURL=extension.d.ts.map

package/dist/packages/mem-core/extraction.d.ts

@@ -0,0 +1,11 @@
+/**
+ * [UPSTREAM]: Depends on ./config.js, ./i18n.js, ./store.js, ./types.js
+ * [SURFACE]: extractMemories, extractWork, extractState
+ * [LOCUS]: packages/mem-core/src/extraction.ts - dual-path extraction (LLM when available, regex heuristics fallback)
+ * [COVENANT]: Change extraction patterns → update this header and verify against packages/mem-core/CLAUDE.md
+ */
+import type { NanomemConfig } from "./config.js";
+import type { ExtractedItem, ExtractedWork, LlmFn } from "./types.js";
+export declare function extractMemories(conversation: string, cfg: NanomemConfig, llmFn?: LlmFn): Promise<ExtractedItem[]>;
+export declare function extractWork(conversation: string, cfg: NanomemConfig, llmFn?: LlmFn): Promise<ExtractedWork | null>;
+//# sourceMappingURL=extraction.d.ts.map