@pencil-agent/nano-pencil 1.4.2 → 1.4.4

package/dist/core/sdk.js

@@ -252,9 +252,15 @@ export async function createAgentSession(options = {}) {
     let soulManager;
     if (isSoulEnabled(options)) {
         try {
-            soulManager = createSoulManager();
-            await soulManager.initialize();
-            time("soul.initialize");
+            const soulMgr = await createSoulManager();
+            if (soulMgr) {
+                soulManager = soulMgr;
+                await soulManager.initialize();
+                time("soul.initialize");
+            }
+            else {
+                console.warn("Soul not available (nanosoul package not installed). Skipping...");
+            }
         }
         catch (error) {
             console.warn(`Failed to initialize Soul: ${error}`);

package/dist/core/soul-integration.d.ts

@@ -4,8 +4,7 @@
  * [POS]: Integration layer - bridges Soul and NanoPencil
  */
 import type { CreateAgentSessionOptions } from "../core/sdk.js";
-import type { InteractionContext } from "nanosoul";
-import { SoulManager } from "nanosoul";
+import type { InteractionContext, SoulManager } from "nanosoul";
 /**
  * Default Soul configuration for NanoPencil
  */
@@ -36,8 +35,13 @@ export declare function getSoulConfig(): {
 };
 /**
  * Create a SoulManager instance for NanoPencil
+ * Returns null if nanosoul is not installed
  */
-export declare function createSoulManager(): SoulManager;
+export declare function createSoulManager(): Promise<SoulManager | null>;
+/**
+ * Check if Soul is available
+ */
+export declare function isSoulAvailable(): boolean;
 /**
  * Convert NanoPencil context to Soul InteractionContext
  */

package/dist/core/soul-integration.js

@@ -3,9 +3,14 @@
  * [OUTPUT]: Configured SoulManager with NanoPencil defaults
  * [POS]: Integration layer - bridges Soul and NanoPencil
  */
-import { SoulManager } from "nanosoul";
 import { join } from "node:path";
 import { getAgentDir } from "../config.js";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Try to load from bundled packages first (dist/packages/nanosoul)
+const BUNDLED_SOUL = join(__dirname, "packages", "nanosoul");
 /**
  * Default Soul configuration for NanoPencil
  */
@@ -38,11 +43,44 @@ export function getSoulConfig() {
 }
 /**
  * Create a SoulManager instance for NanoPencil
+ * Returns null if nanosoul is not installed
  */
-export function createSoulManager() {
-    return new SoulManager({
-        config: getSoulConfig(),
-    });
+export async function createSoulManager() {
+    try {
+        // Try bundled package first (dist/packages/nanosoul)
+        if (existsSync(BUNDLED_SOUL)) {
+            const { SoulManager: SM } = await import(join(BUNDLED_SOUL, "index.js"));
+            return new SM({
+                config: getSoulConfig(),
+            });
+        }
+        // Fall back to node_modules
+        const { SoulManager: SM } = await import("nanosoul");
+        return new SM({
+            config: getSoulConfig(),
+        });
+    }
+    catch {
+        // nanosoul not installed or failed to load
+        return null;
+    }
+}
+/**
+ * Check if Soul is available
+ */
+export function isSoulAvailable() {
+    // Check bundled version first
+    if (existsSync(BUNDLED_SOUL)) {
+        return existsSync(join(BUNDLED_SOUL, "index.js"));
+    }
+    // Fall back to checking node_modules
+    try {
+        require.resolve("nanosoul");
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Convert NanoPencil context to Soul InteractionContext
@@ -53,10 +91,12 @@ export function toSoulContext(project, tags, complexity, toolUsage, userFeedback
         tags,
         complexity,
         toolUsage,
-        userFeedback: userFeedback ? {
-            rating: userFeedback.rating || 5,
-            comment: userFeedback.comment,
-        } : undefined,
+        userFeedback: userFeedback
+            ? {
+                rating: userFeedback.rating || 5,
+                comment: userFeedback.comment,
+            }
+            : undefined,
         timestamp: new Date(),
     };
 }

package/dist/packages/nanomem/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * [INPUT]: process.argv
+ * [OUTPUT]: stats | search <query> | forget <id> | export | insights — terminal output or JSON or HTML
+ * [POS]: Standalone CLI for NanoMem — no host dependency
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/packages/nanomem/cli.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * [INPUT]: process.argv
+ * [OUTPUT]: stats | search <query> | forget <id> | export | insights — terminal output or JSON or HTML
+ * [POS]: Standalone CLI for NanoMem — no host dependency
+ */
+import { writeFileSync } from "node:fs";
+import { NanoMemEngine } from "./engine.js";
+import { renderInsightsHtml } from "./insights-html.js";
+const args = process.argv.slice(2);
+const sub = args[0];
+const engine = new NanoMemEngine();
+async function main() {
+    if (!sub || sub === "help" || sub === "-h" || sub === "--help") {
+        console.log(`nanomem — NanoMem memory CLI
+
+Usage:
+  nanomem stats              Show memory counts (sessions, knowledge, lessons, preferences, work, episodes, facets)
+  nanomem search <query>     Search memories by query text
+  nanomem forget <id>        Remove a memory entry by ID
+  nanomem export             Export all memories as JSON to stdout
+  nanomem insights [--output <path>]   Generate HTML insights report (default: ./nanomem-insights.html)
+  nanomem help               Show this help
+`);
+        return;
+    }
+    if (sub === "stats") {
+        const s = await engine.getStats();
+        console.log(`Sessions: ${s.totalSessions}`);
+        console.log(`Knowledge: ${s.knowledge}`);
+        console.log(`Lessons: ${s.lessons}`);
+        console.log(`Preferences: ${s.preferences}`);
+        console.log(`Work: ${s.work}`);
+        console.log(`Episodes: ${s.episodes}`);
+        return;
+    }
+    if (sub === "search") {
+        const query = args.slice(1).join(" ").trim() || " ";
+        const results = await engine.searchEntries(query);
+        if (!results.length) {
+            console.log("No matching memories.");
+            return;
+        }
+        for (const e of results) {
+            console.log(`[${e.type}] ${e.id} — ${e.content.slice(0, 100)}`);
+        }
+        return;
+    }
+    if (sub === "forget") {
+        const id = args[1];
+        if (!id) {
+            console.error("Usage: nanomem forget <id>");
+            process.exit(1);
+        }
+        const ok = await engine.forgetEntry(id);
+        console.log(ok ? `Removed entry ${id}` : `Entry ${id} not found`);
+        return;
+    }
+    if (sub === "export") {
+        const data = await engine.exportAll();
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    if (sub === "insights") {
+        const outputIdx = args.indexOf("--output");
+        const outputPath = outputIdx >= 0 && args[outputIdx + 1] ? args[outputIdx + 1] : "./nanomem-insights.html";
+        const report = await engine.generateInsights();
+        const html = renderInsightsHtml(report, engine.cfg.locale);
+        writeFileSync(outputPath, html, "utf-8");
+        console.log(`Insights report written to: ${outputPath}`);
+        return;
+    }
+    console.error(`Unknown command: ${sub}. Run 'nanomem help' for usage.`);
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/packages/nanomem/config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * [INPUT]: process.env, optional overrides
+ * [OUTPUT]: NanomemConfig — memory dir, token budget, scoring weights, etc.
+ * [POS]: Shared by engine and adapters; host products configure via this
+ */
+import type { MemoryScope } from "./types.js";
+export interface NanomemConfig {
+    memoryDir: string;
+    tokenBudget: number;
+    budget: {
+        lessons: number;
+        knowledge: number;
+        episodes: number;
+        preferences: number;
+        work: number;
+        facets: number;
+    };
+    halfLife: Record<string, number>;
+    maxEntries: {
+        knowledge: number;
+        lessons: 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;
+}
+export declare function getConfig(overrides?: Partial<NanomemConfig>): NanomemConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/packages/nanomem/config.js

@@ -0,0 +1,48 @@
+/**
+ * [INPUT]: process.env, optional overrides
+ * [OUTPUT]: NanomemConfig — memory dir, token budget, scoring weights, etc.
+ * [POS]: Shared by engine and adapters; host products configure via this
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+const DEFAULT_BUDGET = {
+    lessons: 0.2,
+    knowledge: 0.2,
+    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,
+    work: 45,
+    pattern: 180,
+    struggle: 120,
+};
+const DEFAULT_MAX_ENTRIES = { knowledge: 200, lessons: 100, preferences: 50, work: 80, facets: 80 };
+const DEFAULT_SCORE_WEIGHTS = { recency: 1, importance: 1, relevance: 1 };
+const DEFAULT_EVICTION_WEIGHTS = { accessFrequency: 0.4, baseImpact: 0.6 };
+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";
+    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,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/packages/nanomem/consolidation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * [INPUT]: unconsolidated episodes, LlmFn (optional), config
+ * [OUTPUT]: newly extracted MemoryEntries (facts + lessons) promoted to long-term storage
+ * [POS]: Episodic→Semantic consolidation — heart of multi-store memory model
+ *
+ * Two modes:
+ *   LLM-powered (preferred): produces high-quality semantic extraction
+ *   Heuristic fallback: frequency-based file/error extraction
+ */
+import type { NanomemConfig } from "./config.js";
+import type { Episode, LlmFn, MemoryEntry } from "./types.js";
+export declare function consolidateEpisodes(episodes: Episode[], cfg: NanomemConfig, llmFn?: LlmFn): Promise<MemoryEntry[]>;
+//# sourceMappingURL=consolidation.d.ts.map

package/dist/packages/nanomem/consolidation.js

@@ -0,0 +1,111 @@
+/**
+ * [INPUT]: unconsolidated episodes, LlmFn (optional), config
+ * [OUTPUT]: newly extracted MemoryEntries (facts + lessons) promoted to long-term storage
+ * [POS]: Episodic→Semantic consolidation — heart of multi-store memory model
+ *
+ * Two modes:
+ *   LLM-powered (preferred): produces high-quality semantic extraction
+ *   Heuristic fallback: frequency-based file/error extraction
+ */
+import { PROMPTS } from "./i18n.js";
+import { extractTags } from "./scoring.js";
+function makeId() {
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export async function consolidateEpisodes(episodes, cfg, llmFn) {
+    const unconsolidated = episodes.filter((ep) => !ep.consolidated);
+    if (unconsolidated.length < cfg.consolidationThreshold)
+        return [];
+    let newEntries;
+    if (llmFn) {
+        newEntries = await llmConsolidation(unconsolidated, cfg, llmFn);
+    }
+    else {
+        newEntries = heuristicConsolidation(unconsolidated, cfg);
+    }
+    for (const ep of unconsolidated)
+        ep.consolidated = true;
+    return newEntries;
+}
+async function llmConsolidation(episodes, cfg, llmFn) {
+    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");
+    const raw = await llmFn(p.consolidationSystem, summary);
+    try {
+        const items = JSON.parse(raw);
+        const now = new Date().toISOString();
+        return items.map((item) => {
+            const type = item.type === "lesson" ? "lesson" : "fact";
+            return {
+                id: makeId(),
+                type,
+                content: item.content,
+                tags: extractTags(item.content),
+                project: episodes[0]?.project ?? "unknown",
+                importance: item.importance ?? 6,
+                strength: cfg.halfLife[type] ?? 30,
+                created: now,
+                eventTime: now,
+                accessCount: 0,
+                relatedIds: [],
+                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 content = `Frequently modified files: ${hotFiles.map(([f, c]) => `${f} (${c}x)`).join(", ")}`;
+        result.push({
+            id: makeId(),
+            type: "fact",
+            content,
+            tags: extractTags(content),
+            project: episodes[0]?.project ?? "unknown",
+            importance: 5,
+            strength: cfg.halfLife.fact ?? 60,
+            created: now,
+            eventTime: now,
+            accessCount: 0,
+            relatedIds: [],
+            scope: cfg.defaultScope,
+        });
+    }
+    const allErrors = episodes.flatMap((ep) => ep.errors).filter(Boolean);
+    if (allErrors.length) {
+        const errorSet = [...new Set(allErrors)].slice(0, 5);
+        const content = `Recurring issues: ${errorSet.join("; ")}`;
+        result.push({
+            id: makeId(),
+            type: "lesson",
+            content,
+            tags: extractTags(content),
+            project: episodes[0]?.project ?? "unknown",
+            importance: 7,
+            strength: cfg.halfLife.lesson ?? 90,
+            created: now,
+            eventTime: now,
+            accessCount: 0,
+            relatedIds: [],
+            scope: cfg.defaultScope,
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=consolidation.js.map

package/dist/packages/nanomem/engine.d.ts

@@ -0,0 +1,66 @@
+/**
+ * [INPUT]: NanomemConfig, optional LlmFn
+ * [OUTPUT]: NanoMemEngine — unified API for memory CRUD, injection, consolidation
+ * [POS]: Facade layer — composes store, scoring, eviction, update, linking, privacy, extraction, consolidation
+ *
+ * Host products create an engine instance and call its methods.
+ * No dependency on any specific AI framework — LLM is pluggable.
+ */
+import { type NanomemConfig } from "./config.js";
+import type { Episode, ExtractedItem, InsightsReport, LlmFn, MemoryEntry, MemoryScope, Meta, WorkEntry } from "./types.js";
+export declare class NanoMemEngine {
+    readonly cfg: NanomemConfig;
+    private llmFn?;
+    private knowledgePath;
+    private lessonsPath;
+    private preferencesPath;
+    private facetsPath;
+    private workPath;
+    private metaPath;
+    private episodesDir;
+    constructor(overrides?: Partial<NanomemConfig>, llmFn?: LlmFn);
+    setLlmFn(fn: LlmFn): void;
+    extractAndStore(conversation: string, project: string): Promise<ExtractedItem[]>;
+    extractAndStoreWork(conversation: string, project: string, sessionGoal?: string): Promise<void>;
+    saveEpisode(ep: Episode): Promise<void>;
+    consolidate(): Promise<MemoryEntry[]>;
+    getMemoryInjection(project: string, contextTags: string[], scope?: MemoryScope): Promise<string>;
+    getStats(): Promise<{
+        knowledge: number;
+        lessons: number;
+        preferences: number;
+        facets: number;
+        episodes: number;
+        work: number;
+        totalSessions: number;
+    }>;
+    getAllEntries(): Promise<{
+        knowledge: MemoryEntry[];
+        lessons: MemoryEntry[];
+        preferences: MemoryEntry[];
+        facets: MemoryEntry[];
+    }>;
+    getAllWork(): Promise<WorkEntry[]>;
+    getAllEpisodes(): Promise<Episode[]>;
+    searchEntries(query: string, scope?: MemoryScope): Promise<MemoryEntry[]>;
+    forgetEntry(id: string): Promise<boolean>;
+    exportAll(): Promise<{
+        knowledge: MemoryEntry[];
+        lessons: MemoryEntry[];
+        preferences: MemoryEntry[];
+        facets: MemoryEntry[];
+        work: WorkEntry[];
+        episodes: Episode[];
+        meta: Meta;
+    }>;
+    generateInsights(): Promise<InsightsReport>;
+    private generateRecommendations;
+    private generateRulesBasedRecommendations;
+    private filterAndCleanEntries;
+    private filterAndCleanWork;
+    private reinforceEntries;
+    private reinforceWork;
+    private reconsolidateIfNeeded;
+    private buildInjectionText;
+}
+//# sourceMappingURL=engine.d.ts.map