@pencil-agent/nano-mem 0.0.1

package/src/cli.ts

@@ -0,0 +1,99 @@
+#!/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 { renderFullInsightsHtml } from "./full-insights-html.js";
+import { renderInsightsHtml } from "./insights-html.js";
+
+const args = process.argv.slice(2);
+const sub = args[0];
+const engine = new NanoMemEngine();
+
+async function main(): Promise<void> {
+	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 full HTML insights report (default: ./nanomem-insights.html)
+  nanomem insights --simple [--output <path>]   Generate simple insights report (rules-only, no LLM)
+  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 simple = args.includes("--simple");
+		const outputIdx = args.indexOf("--output");
+		const outputPath = outputIdx >= 0 && args[outputIdx + 1] ? args[outputIdx + 1] : "./nanomem-insights.html";
+
+		if (simple) {
+			const report = await engine.generateInsights();
+			const html = renderInsightsHtml(report, engine.cfg.locale);
+			writeFileSync(outputPath, html, "utf-8");
+		} else {
+			const report = await engine.generateFullInsights();
+			const html = renderFullInsightsHtml(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);
+});

package/src/config.ts

@@ -0,0 +1,72 @@
+/**
+ * [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";
+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;
+}
+
+const DEFAULT_BUDGET = {
+	lessons: 0.2,
+	knowledge: 0.2,
+	episodes: 0.18,
+	preferences: 0.1,
+	work: 0.2,
+	facets: 0.12,
+} as const;
+
+const DEFAULT_HALF_LIFE: Record<string, number> = {
+	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?: Partial<NanomemConfig>): NanomemConfig {
+	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 as "en" | "zh") || 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,
+	};
+}

package/src/consolidation.ts

@@ -0,0 +1,127 @@
+/**
+ * [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 { PROMPTS } from "./i18n.js";
+import { extractTags } from "./scoring.js";
+import type { Episode, LlmFn, MemoryEntry } from "./types.js";
+
+function makeId(): string {
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export async function consolidateEpisodes(
+	episodes: Episode[],
+	cfg: NanomemConfig,
+	llmFn?: LlmFn,
+): Promise<MemoryEntry[]> {
+	const unconsolidated = episodes.filter((ep) => !ep.consolidated);
+	if (unconsolidated.length < cfg.consolidationThreshold) return [];
+
+	let newEntries: MemoryEntry[];
+	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: Episode[], cfg: NanomemConfig, llmFn: LlmFn): Promise<MemoryEntry[]> {
+	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) as Array<{ type: string; content: string; importance?: number }>;
+		const now = new Date().toISOString();
+		return items.map((item) => {
+			const type: MemoryEntry["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: Episode[], cfg: NanomemConfig): MemoryEntry[] {
+	const now = new Date().toISOString();
+	const result: MemoryEntry[] = [];
+
+	const fileCounts = new Map<string, number>();
+	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;
+}