@pencil-agent/nano-mem 0.0.1

package/CLAUDE.md

@@ -0,0 +1,258 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+NanoMem is a TypeScript-based persistent memory management system for AI assistants. It implements a sophisticated memory architecture with spaced repetition, intelligent eviction, privacy controls, and AI-powered memory extraction.
+
+**Key characteristics:**
+- Pure TypeScript ESM modules (no build step, requires Node.js 20+ with TypeScript execution via tsx or similar)
+- JSON file-based persistence in `~/.nanomem/memory`
+- Pluggable LLM integration - works with any LLM provider via a simple function signature
+- Bilingual support (English/Chinese) for prompts and UI
+
+## Running the Code
+
+This project uses `.ts` imports and requires TypeScript execution:
+
+```bash
+# Run the CLI directly with tsx
+npx tsx cli.ts stats
+npx tsx cli.ts search "query"
+npx tsx cli.ts insights
+
+# Or use node with --loader
+node --loader tsx cli.ts stats
+```
+
+## Environment Configuration
+
+Configure via environment variables:
+
+- `NANOMEM_TOKEN_BUDGET` - Total token budget for memory injection (default: 6000)
+- `NANOMEM_MEMORY_DIR` - Directory for JSON storage (default: `~/.nanomem/memory`)
+- `NANOMEM_LOCALE` - Language locale: `en` or `zh` (default: `en`)
+
+## Architecture Overview
+
+The codebase follows a clean layered architecture with clear module boundaries:
+
+### Core Engine (`engine.ts`)
+The `NanoMemEngine` class is the main API facade. It orchestrates all other modules and provides:
+- Memory extraction and storage from conversations
+- Episode management and consolidation
+- Memory retrieval with budget-aware injection
+- Statistics and insights generation
+
+### Memory Storage (`store.ts`)
+JSON-based persistence with automatic directory creation. Stores data in separate files:
+- `knowledge.json` - Facts, entities, decisions
+- `lessons.json` - Lessons learned
+- `preferences.json` - User preferences
+- `facets.json` - Patterns and struggles (behavioral insights)
+- `work.json` - Work/task history
+- `episodes/*.json` - Session summaries
+- `meta.json` - Metadata (session count, last consolidation)
+
+### Memory Types (`types.ts`)
+
+**MemoryEntry** - Core memory types:
+- `fact` - Technical knowledge, project structure, API details
+- `lesson` - Mistakes, solutions, debugging insights
+- `preference` - User style, naming, tool preferences
+- `decision` - Architectural choices, design trade-offs
+- `entity` - Named entities (people, services, etc.)
+- `pattern` - Habitual user behaviors (with `facetData`)
+- `struggle` - Failure experiences with resolution (with `facetData`)
+
+**FacetData** - Structured data for behavioral insights:
+```typescript
+type FacetData =
+  | { kind: "pattern"; trigger: string; behavior: string }
+  | { kind: "struggle"; problem: string; attempts: string[]; solution: string }
+```
+
+**Episode** - Session summaries with metadata (files, tools, errors, observations)
+
+**WorkEntry** - Task-oriented memories with goal and summary
+
+### Key Algorithms
+
+**Spaced Repetition** (`scoring.ts`, `engine.ts`):
+- Memory `strength` grows with each successful recall (Ebbinghaus model)
+- Growth factor configurable via `strengthGrowthFactor` (default: 1.5)
+- Strength used in retrieval scoring
+
+**Scoring System** (`scoring.ts`):
+- Stanford-style retrieval scoring with three components:
+  - `recency` - Based on `strength` (half-life decay)
+  - `importance` - Explicit 1-10 rating
+  - `relevance` - Tag overlap with context
+- Weights configurable via `scoreWeights`
+
+**Eviction** (`eviction.ts`):
+- Utility-based eviction: combines access frequency and base impact
+- Different half-life values per memory type (configurable)
+- Enforces `maxEntries` limits per memory type
+
+**Memory Linking** (`linking.ts`):
+- A-MEM style relationship discovery between memories
+- Uses tag overlap and semantic similarity
+- Related memories shown in injection: `fact content [→ related; summaries]`
+
+### Dual-Path Extraction (`extraction.ts`)
+
+The system works with or without an LLM:
+1. **LLM path**: Uses `LlmFn` to extract structured memories from conversations
+2. **Heuristic fallback**: Pattern-based extraction when no LLM available
+
+### Privacy & Scoping (`privacy.ts`)
+
+- **PII filtering**: Basic PII redaction from memories
+- **Scoping**: Multi-user support via `MemoryScope` (`userId`, `agentId`)
+- **TTL**: Time-to-live based auto-eviction
+- **Scope filtering**: All retrieval operations respect scope
+
+### Consolidation (`consolidation.ts`)
+
+- Batch processing of episode summaries into long-term memories
+- Runs automatically on session start
+- Marks episodes as `consolidated: true`
+
+### Internationalization (`i18n.ts`)
+
+All user-facing strings and LLM prompts support English and Chinese:
+- Extraction prompts
+- Injection section headers
+- Memory behavior instructions
+- Insights generation prompts
+
+## Extension Integration (`extension.ts`)
+
+The only module depending on `@pencil-agent/nano-pencil`. Bridges NanoPencil events to the engine:
+
+**Lifecycle hooks:**
+- `session_start` - Triggers consolidation
+- `before_agent_start` - Injects memory into system prompt
+- `tool_execution_start/end` - Tracks tool usage and observations
+- `agent_end` - Extracts memories from conversation
+- `session_shutdown` - Saves episode summary
+
+**Registered commands:**
+- `mem-search <query>` - Search memories
+- `mem-stats` - Show statistics
+- `mem-insights [path]` - Generate HTML report
+
+## Configuration System (`config.ts`)
+
+Comprehensive configuration via `getConfig(overrides)`:
+
+```typescript
+{
+  memoryDir: string,           // Storage location
+  tokenBudget: number,         // Total tokens for injection
+  budget: {                    // Allocation ratios per memory type
+    lessons: number,
+    knowledge: number,
+    episodes: number,
+    preferences: number,
+    work: number,
+    facets: number
+  },
+  halfLife: Record<string, number>,  // Decay rates per type
+  maxEntries: {...},           // Capacity limits per type
+  consolidationThreshold: number,     // Episodes before consolidation
+  scoreWeights: { recency, importance, relevance },
+  evictionWeights: { accessFrequency, baseImpact },
+  defaultScope?: MemoryScope,
+  locale: "en" | "zh",
+  strengthGrowthFactor: number
+}
+```
+
+## Memory Injection Format
+
+Generated memory injection follows this structure:
+
+```markdown
+## Long-term Memory
+
+### Lessons Learned
+- lesson content
+
+### Knowledge Base
+- fact content [→ related; summaries]
+
+### Recent Sessions
+- [date] project: summary (Goal: user goal)
+
+### User Preferences
+- preference content
+
+### Work History
+- [date] goal: summary
+
+### Behavioral Patterns
+- When trigger → behavior
+
+### Past Struggles
+- Problem: problem | Tried: attempt1, attempt2 | Solved: solution
+
+---
+IMPORTANT: These memories are your personal recollections...
+(memory behavior instructions - natural memory usage)
+```
+
+## Important Patterns
+
+### POS Comments
+Each file has a `[POS]` comment explaining its position in the architecture. These describe the module's role and dependencies.
+
+### LLM Function Type
+```typescript
+type LlmFn = (systemPrompt: string, userMessage: string) => Promise<string>;
+```
+Simple async function - host products provide their own LLM integration.
+
+### Graceful Degradation
+The system works without an LLM through heuristic extraction. LLM features fail silently and fall back to rules-based behavior.
+
+### Bi-temporal Memory
+- `created` - When the system recorded the memory
+- `eventTime` - When the fact actually occurred (optional)
+
+### Update Operations (`update.ts`)
+Mem0-style updates: `add | update | delete | noop` based on content similarity and explicit retraction.
+
+### Export/Import
+Full data export available via `exportAll()` - returns all memories, episodes, and metadata.
+
+## CLI Usage (`cli.ts`)
+
+```bash
+nanomem stats              # Show memory counts
+nanomem search <query>     # Search memories
+nanomem forget <id>        # Delete a memory
+nanomem export             # Export all as JSON
+nanomem insights [--output <path>]  # Generate HTML report
+```
+
+## Files Reference
+
+- `index.ts` - Barrel export (public API surface)
+- `engine.ts` - Main engine class (690 lines)
+- `config.ts` - Configuration management
+- `types.ts` - All type definitions
+- `store.ts` - JSON persistence layer
+- `extraction.ts` - Memory extraction (LLM + heuristic)
+- `consolidation.ts` - Episode consolidation
+- `scoring.ts` - Retrieval and ranking algorithms
+- `privacy.ts` - PII filtering, scoping, TTL
+- `linking.ts` - Memory relationship discovery
+- `i18n.ts` - Internationalization (en/zh)
+- `eviction.ts` - Memory eviction algorithms
+- `update.ts` - Memory update operations
+- `extension.ts` - NanoPencil extension adapter
+- `insights-html.ts` - HTML report generation
+- `cli.ts` - Standalone CLI tool

package/README.md

@@ -0,0 +1,146 @@
+# @nanopencil/nanomem
+
+> Persistent memory engine for AI coding agents with consolidation, scoring, and insights.
+
+## Features
+
+- **Dual-path extraction**: LLM-based or heuristic regex fallback
+- **Seven memory types**: Knowledge, Lessons, Preferences, Decisions, Entities, Patterns, Struggles
+- **Stanford-style scoring**: Recency, importance, and relevance weighting
+- **Utility-based eviction**: Access frequency vs base impact
+- **A-MEM style linking**: Automatic memory association
+- **Mem0-style updates**: Add, update, delete, retract operations
+- **Spaced repetition**: Ebbinghaus forgetting curve reinforcement
+- **Privacy protection**: PII filtering and TTL expiration
+- **Bilingual prompts**: Chinese and English support
+- **Insights reports**: Pattern/struggle analysis with recommendations
+
+## Installation
+
+```bash
+npm install @nanopencil/nanomem
+```
+
+## Quick Start
+
+```typescript
+import { NanoMemEngine, getConfig } from '@nanopencil/nanomem';
+
+// Create engine with defaults
+const engine = new NanoMemEngine();
+
+// Extract memories from conversation
+const items = await engine.extractAndStore(
+  "User: The API endpoint is /api/v1/users\nAssistant: Got it, I'll remember.",
+  "my-project"
+);
+
+// Get memory injection for system prompt
+const injection = await engine.getMemoryInjection(
+  "my-project",
+  ["api", "rest", "typescript"]
+);
+
+console.log(injection);
+// ## Memory Injection
+//
+// ### Knowledge
+// - The API endpoint is /api/v1/users
+//
+// ---
+// This memory injection is based on your conversation history...
+```
+
+## Memory Types
+
+| Type | Purpose | Half-Life |
+|------|---------|-----------|
+| `knowledge` | Project facts, API info | 60 days |
+| `lessons` | Errors, solutions, learnings | 90 days |
+| `preferences` | User preferences, style habits | 120 days |
+| `decisions` | Architectural choices | 45 days |
+| `entities` | Named entities (people, projects) | 30 days |
+| `patterns` | Behavioral patterns (trigger→behavior) | 180 days |
+| `struggles` | Struggle experiences (problem→attempts→solution) | 120 days |
+| `work` | Work summaries (goal + summary) | 45 days |
+
+## Configuration
+
+```typescript
+import { NanoMemEngine, getConfig } from '@nanopencil/nanomem';
+
+const config = getConfig({
+  memoryDir: './my-memory',
+  tokenBudget: 8000,
+  budget: {
+    lessons: 0.25,
+    knowledge: 0.25,
+    episodes: 0.15,
+    preferences: 0.1,
+    work: 0.15,
+    facets: 0.1
+  },
+  halfLife: {
+    lesson: 90,
+    fact: 60,
+    pattern: 180
+  },
+  locale: 'zh' // or 'en'
+});
+
+const engine = new NanoMemEngine(config);
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+constructor(overrides?: Partial<NanomemConfig>, llmFn?: LlmFn)
+```
+
+### Methods
+
+- `extractAndStore(conversation, project)` - Extract and store memories
+- `getMemoryInjection(project, contextTags, scope?)` - Get memory for system prompt
+- `saveEpisode(episode)` - Save a conversation episode
+- `consolidate()` - Consolidate episodes into long-term memory
+- `searchEntries(query, scope?)` - Search memories
+- `forgetEntry(id)` - Delete a memory
+- `getStats()` - Get memory statistics
+- `generateInsights()` - Generate insights report
+
+### Extension Integration
+
+For NanoPencil integration:
+
+```typescript
+import nanomemExtension from '@nanopencil/nanomem/extension';
+
+// In NanoPencil
+pi.registerExtension(() => nanomemExtension);
+```
+
+## Storage Structure
+
+```
+~/.nanomem/memory/
+├── knowledge.json
+├── lessons.json
+├── preferences.json
+├── facets.json
+├── work.json
+├── meta.json
+└── episodes/
+    ├── *.jsonl
+```
+
+## Environment Variables
+
+- `NANOMEM_MEMORY_DIR` - Override memory directory (default: `~/.nanomem/memory`)
+- `NANOMEM_TOKEN_BUDGET` - Token budget for injections (default: 6000)
+- `NANOMEM_LOCALE` - Locale for prompts (`en` or `zh`, default: `en`)
+
+## License
+
+MIT

package/dist/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/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;GAIG"}

package/dist/cli.js

@@ -0,0 +1,90 @@
+#!/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() {
+    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);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/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/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACpH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACtG,sBAAsB,EAAE,MAAM,CAAC;IAC/B,+CAA+C;IAC/C,YAAY,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,iEAAiE;IACjE,eAAe,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,uCAAuC;IACvC,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,qDAAqD;IACrD,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,2EAA2E;IAC3E,oBAAoB,EAAE,MAAM,CAAC;CAC7B;AA2BD,wBAAgB,SAAS,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAiB3E"}

package/dist/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/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAsBjC,MAAM,cAAc,GAAG;IACtB,OAAO,EAAE,GAAG;IACZ,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,IAAI;IACd,WAAW,EAAE,GAAG;IAChB,IAAI,EAAE,GAAG;IACT,MAAM,EAAE,IAAI;CACH,CAAC;AAEX,MAAM,iBAAiB,GAA2B;IACjD,MAAM,EAAE,EAAE;IACV,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,EAAE;IACX,UAAU,EAAE,GAAG;IACf,QAAQ,EAAE,EAAE;IACZ,MAAM,EAAE,EAAE;IACV,IAAI,EAAE,EAAE;IACR,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;CACb,CAAC;AAEF,MAAM,mBAAmB,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACpG,MAAM,qBAAqB,GAAG,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;AAC1E,MAAM,wBAAwB,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;AAE3E,MAAM,UAAU,SAAS,CAAC,SAAkC;IAC3D,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,IAAI,CAAC;IACrE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;IAClH,MAAM,MAAM,GAAI,OAAO,CAAC,GAAG,CAAC,cAA8B,IAAI,SAAS,EAAE,MAAM,IAAI,IAAI,CAAC;IACxF,OAAO;QACN,SAAS;QACT,WAAW,EAAE,SAAS,EAAE,WAAW,IAAI,WAAW;QAClD,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,EAAE,GAAG,cAAc,EAAE;QAClD,QAAQ,EAAE,SAAS,EAAE,QAAQ,IAAI,EAAE,GAAG,iBAAiB,EAAE;QACzD,UAAU,EAAE,SAAS,EAAE,UAAU,IAAI,EAAE,GAAG,mBAAmB,EAAE;QAC/D,sBAAsB,EAAE,SAAS,EAAE,sBAAsB,IAAI,EAAE;QAC/D,YAAY,EAAE,SAAS,EAAE,YAAY,IAAI,EAAE,GAAG,qBAAqB,EAAE;QACrE,eAAe,EAAE,SAAS,EAAE,eAAe,IAAI,EAAE,GAAG,wBAAwB,EAAE;QAC9E,YAAY,EAAE,SAAS,EAAE,YAAY;QACrC,MAAM;QACN,oBAAoB,EAAE,SAAS,EAAE,oBAAoB,IAAI,GAAG;KAC5D,CAAC;AACH,CAAC"}

package/dist/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/consolidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolidation.d.ts","sourceRoot":"","sources":["../src/consolidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM9D,wBAAsB,mBAAmB,CACxC,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,aAAa,EAClB,KAAK,CAAC,EAAE,KAAK,GACX,OAAO,CAAC,WAAW,EAAE,CAAC,CAaxB"}