@pencil-agent/nano-mem 0.0.1

package/src/store.ts

@@ -0,0 +1,84 @@
+/**
+ * [INPUT]: file paths, data objects
+ * [OUTPUT]: async JSON read/write with directory auto-creation
+ * [POS]: Persistence layer — all other modules go through here
+ */
+
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { Episode, MemoryEntry, Meta, WorkEntry } from "./types.js";
+
+async function ensureDir(dir: string): Promise<void> {
+	if (!existsSync(dir)) await mkdir(dir, { recursive: true });
+}
+
+export async function readJson<T>(path: string, fallback: T): Promise<T> {
+	try {
+		if (!existsSync(path)) return fallback;
+		const raw = await readFile(path, "utf-8");
+		return JSON.parse(raw) as T;
+	} catch {
+		return fallback;
+	}
+}
+
+export async function writeJson(path: string, data: unknown): Promise<void> {
+	await ensureDir(dirname(path));
+	await writeFile(path, JSON.stringify(data, null, 2), "utf-8");
+}
+
+export async function loadEntries(path: string): Promise<MemoryEntry[]> {
+	return readJson<MemoryEntry[]>(path, []);
+}
+
+export async function saveEntries(
+	path: string,
+	entries: MemoryEntry[],
+	max: number,
+	utilityFn: (e: MemoryEntry) => number,
+): Promise<void> {
+	if (entries.length > max) {
+		entries.sort((a, b) => utilityFn(b) - utilityFn(a));
+		entries.length = max;
+	}
+	await writeJson(path, entries);
+}
+
+export async function loadEpisodes(episodesDir: string): Promise<Episode[]> {
+	await ensureDir(episodesDir);
+	const files = await readdir(episodesDir);
+	const results: Episode[] = [];
+	for (const f of files) {
+		if (!f.endsWith(".json")) continue;
+		const ep = await readJson<Episode | null>(join(episodesDir, f), null);
+		if (ep) results.push(ep);
+	}
+	return results;
+}
+
+export async function saveEpisode(episodesDir: string, ep: Episode): Promise<void> {
+	await ensureDir(episodesDir);
+	await writeJson(join(episodesDir, `${ep.date}-${ep.sessionId.slice(0, 8)}.json`), ep);
+}
+
+export async function loadWork(path: string): Promise<WorkEntry[]> {
+	return readJson<WorkEntry[]>(path, []);
+}
+
+export async function saveWork(
+	path: string,
+	entries: WorkEntry[],
+	max: number,
+	utilityFn: (w: WorkEntry) => number,
+): Promise<void> {
+	if (entries.length > max) {
+		entries.sort((a, b) => utilityFn(b) - utilityFn(a));
+		entries.length = max;
+	}
+	await writeJson(path, entries);
+}
+
+export async function loadMeta(path: string): Promise<Meta> {
+	return readJson<Meta>(path, { totalSessions: 0, version: 1 });
+}

package/src/types.ts

@@ -0,0 +1,209 @@
+/**
+ * [INPUT]: None (pure type definitions)
+ * [OUTPUT]: All core data types for NanoMem
+ * [POS]: Foundation layer — every other module imports from here
+ */
+
+/** Pluggable LLM function: system prompt + user message → raw text response */
+export type LlmFn = (systemPrompt: string, userMessage: string) => Promise<string>;
+
+export interface MemoryScope {
+	userId?: string;
+	agentId?: string;
+}
+
+/** Structured data for Facets (Pattern/Struggle) memory types */
+export type FacetData =
+	| { kind: "pattern"; trigger: string; behavior: string }
+	| { kind: "struggle"; problem: string; attempts: string[]; solution: string };
+
+export interface MemoryEntry {
+	id: string;
+	type: "fact" | "lesson" | "preference" | "decision" | "entity" | "pattern" | "struggle";
+	content: string;
+	tags: string[];
+	project: string;
+	importance: number;
+	/** Adaptive memory strength (days). Grows with each successful recall — Ebbinghaus spaced repetition. */
+	strength?: number;
+	/** Ingestion time: when the system recorded this entry */
+	created: string;
+	/** Event time: when the fact actually occurred (bi-temporal, defaults to created) */
+	eventTime?: string;
+	lastAccessed?: string;
+	accessCount: number;
+	/** A-MEM style links to related memory entries */
+	relatedIds?: string[];
+	/** TTL in days — auto-evicted after expiry. undefined = permanent */
+	ttl?: number;
+	scope?: MemoryScope;
+	/** Structured data for pattern/struggle types (Facets) */
+	facetData?: FacetData;
+}
+
+export interface Episode {
+	sessionId: string;
+	project: string;
+	date: string;
+	summary: string;
+	userGoal?: string;
+	filesModified: string[];
+	toolsUsed: Record<string, number>;
+	keyObservations: string[];
+	errors: string[];
+	tags: string[];
+	importance: number;
+	consolidated: boolean;
+	scope?: MemoryScope;
+}
+
+export interface WorkEntry {
+	id: string;
+	goal: string;
+	summary: string;
+	project: string;
+	tags: string[];
+	importance: number;
+	strength?: number;
+	created: string;
+	eventTime?: string;
+	lastAccessed?: string;
+	accessCount: number;
+	relatedIds?: string[];
+	ttl?: number;
+	scope?: MemoryScope;
+}
+
+export interface Meta {
+	totalSessions: number;
+	lastConsolidation?: string;
+	version: number;
+}
+
+/** Mem0-style update operations */
+export type UpdateAction = "add" | "update" | "delete" | "noop";
+
+export interface ExtractedItem {
+	type: "preference" | "fact" | "lesson" | "decision" | "retract" | "pattern" | "struggle";
+	content: string;
+	/** Structured data for pattern/struggle types (populated by LLM extraction) */
+	facetData?: FacetData;
+}
+
+export interface ExtractedWork {
+	goal: string;
+	summary: string;
+}
+
+// ─── Insights Types ──────────────────────────────────────
+
+export interface PatternInsight {
+	entry: MemoryEntry;
+	weight: number;
+	trigger: string;
+	behavior: string;
+}
+
+export interface StruggleInsight {
+	entry: MemoryEntry;
+	weight: number;
+	problem: string;
+	attempts: string[];
+	solution: string;
+	resolved: boolean;
+}
+
+export interface InsightsReport {
+	patterns: PatternInsight[];
+	struggles: StruggleInsight[];
+	topLessons: MemoryEntry[];
+	topKnowledge: MemoryEntry[];
+	preferences: MemoryEntry[];
+	stats: {
+		knowledge: number;
+		lessons: number;
+		preferences: number;
+		facets: number;
+		episodes: number;
+		work: number;
+		totalSessions: number;
+	};
+	recommendations: string[];
+	generatedAt: string;
+}
+
+// ─── Full Insights Report (rich narrative + charts) ──────────────────────
+
+export interface FullInsightsAtAGlance {
+	working: string;
+	hindering: string;
+	quickWins: string;
+	ambitious: string;
+}
+
+export interface FullInsightsProjectArea {
+	name: string;
+	sessionCount: number;
+	description: string;
+}
+
+export interface FullInsightsChartRow {
+	label: string;
+	value: number;
+}
+
+export interface FullInsightsChart {
+	id: string;
+	title: string;
+	rows: FullInsightsChartRow[];
+}
+
+export interface FullInsightsWin {
+	title: string;
+	description: string;
+}
+
+export interface FullInsightsFriction {
+	title: string;
+	description: string;
+	examples?: string[];
+}
+
+export interface FullInsightsFeatureToTry {
+	title: string;
+	oneLiner: string;
+	whyForYou: string;
+	exampleCode?: string;
+}
+
+export interface FullInsightsUsagePattern {
+	title: string;
+	summary: string;
+	detail: string;
+	pastePrompt?: string;
+}
+
+export interface FullInsightsReport {
+	stats: {
+		knowledge: number;
+		lessons: number;
+		preferences: number;
+		facets: number;
+		episodes: number;
+		work: number;
+		totalSessions: number;
+		aggregateToolCount?: number;
+		aggregateFileCount?: number;
+	};
+	atAGlance: FullInsightsAtAGlance;
+	projectAreas: FullInsightsProjectArea[];
+	charts: FullInsightsChart[];
+	wins: FullInsightsWin[];
+	frictions: FullInsightsFriction[];
+	patterns: PatternInsight[];
+	recommendations: string[];
+	featuresToTry: FullInsightsFeatureToTry[];
+	usagePatterns: FullInsightsUsagePattern[];
+	generatedAt: string;
+	locale: string;
+}

package/src/update.ts

@@ -0,0 +1,141 @@
+/**
+ * [INPUT]: extracted items, existing entries
+ * [OUTPUT]: entries mutated via Mem0 four-operation pipeline (ADD/UPDATE/DELETE/NOOP)
+ * [POS]: Implements Mem0 update semantics — slot-based, tag-overlap, and retract
+ *
+ * Key improvements over basic approach:
+ * - UPDATE generalized: any entry type, tag overlap > 0.7 triggers content replacement
+ * - DELETE: retract-type extractions find and remove matching entries
+ */
+
+import type { NanomemConfig } from "./config.js";
+import { linkNewEntry } from "./linking.js";
+import { filterPII } from "./privacy.js";
+import { extractTags, tagOverlap } from "./scoring.js";
+import type { ExtractedItem, MemoryEntry } from "./types.js";
+
+const UPDATE_OVERLAP_THRESHOLD = 0.7;
+const NOOP_SIMILARITY_THRESHOLD = 0.8;
+const CONTENT_SIMILARITY_THRESHOLD = 0.85;
+
+function makeId(): string {
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/** Simple content similarity check using character overlap */
+function contentSimilarity(a: string, b: string): number {
+	const aLower = a.toLowerCase().trim();
+	const bLower = b.toLowerCase().trim();
+	if (aLower === bLower) return 1;
+	const shorter = aLower.length < bLower.length ? aLower : bLower;
+	const longer = aLower.length >= bLower.length ? aLower : bLower;
+	if (longer.includes(shorter)) return shorter.length / longer.length;
+	// Simple word overlap
+	const aWords = new Set(aLower.split(/\s+/).filter((w) => w.length > 2));
+	const bWords = new Set(bLower.split(/\s+/).filter((w) => w.length > 2));
+	if (aWords.size === 0 || bWords.size === 0) return 0;
+	let overlap = 0;
+	for (const w of aWords) if (bWords.has(w)) overlap++;
+	return (2 * overlap) / (aWords.size + bWords.size);
+}
+
+/** Check if new content is too similar to an existing entry of same type */
+function isDuplicate(entries: MemoryEntry[], type: string, tags: string[], content: string): boolean {
+	return entries.some((e) => {
+		if (e.type !== type) return false;
+		// Check both tag overlap and content similarity
+		const tagMatch = tagOverlap(e.tags, tags) >= NOOP_SIMILARITY_THRESHOLD;
+		const contentMatch = contentSimilarity(e.content, content) >= CONTENT_SIMILARITY_THRESHOLD;
+		return tagMatch || contentMatch;
+	});
+}
+
+/** Find existing entry with high tag overlap for UPDATE */
+function findUpdateCandidate(entries: MemoryEntry[], type: string, tags: string[]): number {
+	return entries.findIndex((e) => e.type === type && tagOverlap(e.tags, tags) >= UPDATE_OVERLAP_THRESHOLD);
+}
+
+/** Process a single extracted item through the Mem0 pipeline */
+export function applyExtraction(
+	entries: MemoryEntry[],
+	item: ExtractedItem,
+	project: string,
+	cfg: NanomemConfig,
+): void {
+	if (item.type === "retract") {
+		applyDelete(entries, item.content);
+		return;
+	}
+
+	const memType = mapType(item.type);
+	const content = filterPII(item.content);
+	const tags = extractTags(content);
+
+	if (isDuplicate(entries, memType, tags, content)) return;
+
+	const updateIdx = findUpdateCandidate(entries, memType, tags);
+	if (updateIdx >= 0) {
+		const existing = entries[updateIdx]!;
+		entries[updateIdx] = {
+			...existing,
+			content,
+			tags,
+			lastAccessed: new Date().toISOString(),
+		};
+		return;
+	}
+
+	const now = new Date().toISOString();
+	const newEntry: MemoryEntry = {
+		id: makeId(),
+		type: memType,
+		content,
+		tags,
+		project,
+		importance:
+			item.type === "struggle"
+				? 9
+				: item.type === "lesson"
+					? 8
+					: item.type === "pattern"
+						? 7
+						: item.type === "preference"
+							? 6
+							: 5,
+		strength: cfg.halfLife[memType] ?? 30,
+		created: now,
+		eventTime: now,
+		accessCount: 0,
+		relatedIds: [],
+		scope: cfg.defaultScope,
+		facetData: item.facetData,
+	};
+
+	linkNewEntry(newEntry, entries);
+	entries.push(newEntry);
+}
+
+function applyDelete(entries: MemoryEntry[], content: string): void {
+	const tags = extractTags(content);
+	const idx = entries.findIndex(
+		(e) => (e.type === "fact" || e.type === "preference") && tagOverlap(e.tags, tags) >= UPDATE_OVERLAP_THRESHOLD,
+	);
+	if (idx >= 0) entries.splice(idx, 1);
+}
+
+function mapType(t: ExtractedItem["type"]): MemoryEntry["type"] {
+	switch (t) {
+		case "preference":
+			return "preference";
+		case "lesson":
+			return "lesson";
+		case "decision":
+			return "decision";
+		case "pattern":
+			return "pattern";
+		case "struggle":
+			return "struggle";
+		default:
+			return "fact";
+	}
+}