anno-extension 0.1.0

package/src/types-v2.ts

@@ -0,0 +1,244 @@
+/**
+ * [WHO]: EpisodeMemory, EpisodeFacet, ProceduralMemory, ProceduralStep, SemanticCluster, StateMemory, MemoryLink, MemoryScopeV2
+ * [FROM]: Depends on ./types.js (MemoryScope)
+ * [TO]: Consumed by packages/mem-core/src/index.ts
+ * [HERE]: packages/mem-core/src/types-v2.ts - foundation layer for NanoMem v2 layered-memory data model (episodic/semantic/procedural/state)
+ */
+
+import type { MemoryScope } from "./types.js";
+
+export interface MemoryScopeV2 extends MemoryScope {
+	project?: string;
+	workspaceId?: string;
+	branch?: string;
+}
+
+export type MemoryKind = "episode" | "facet" | "semantic" | "procedural" | "state";
+
+export type SemanticKind =
+	| "fact"
+	| "lesson"
+	| "preference"
+	| "decision"
+	| "entity"
+	| "pattern"
+	| "struggle"
+	| "event";
+
+export type FacetKind =
+	| "goal"
+	| "decision"
+	| "constraint"
+	| "error"
+	| "fix"
+	| "insight"
+	| "outcome"
+	| "pattern"
+	| "preference"
+	| "entity"
+	| "context";
+
+export type ProcedureStatus = "active" | "draft" | "deprecated" | "superseded";
+
+export type MemoryStabilityV2 = "stable" | "situational" | "volatile";
+
+export type MemoryRetentionV2 = "core" | "key-event" | "ambient";
+
+export type AbstractionLevel = "instance" | "generalization" | "principle";
+
+export type EvidenceSourceType = "conversation" | "file" | "tool-output" | "session-summary";
+
+export type StateType = "mood" | "pressure" | "focus" | "preference-shift" | "working-style";
+
+export type StateHorizon = "momentary" | "short-term" | "medium-term";
+
+export type MemoryLinkType =
+	| "has-facet"
+	| "mentions-entity"
+	| "supports"
+	| "derived-from"
+	| "generalizes"
+	| "specializes"
+	| "causes"
+	| "caused-by"
+	| "similar-to"
+	| "conflicts-with"
+	| "supersedes"
+	| "retrieved-with";
+
+export interface EmbeddingRef {
+	model: string;
+	dim: number;
+	updatedAt: string;
+	checksum: string;
+	vectorId: string;
+}
+
+export type EmbeddingFn = (texts: string[]) => Promise<number[][]>;
+
+export interface EmbeddingIndexRecord {
+	id: string;
+	memoryId: string;
+	memoryKind: "episode" | "facet" | "semantic" | "procedural";
+	model: string;
+	dim: number;
+	checksum: string;
+	text: string;
+	vector: number[];
+	updatedAt: string;
+}
+
+export interface EvidenceRef {
+	id: string;
+	sourceType: EvidenceSourceType;
+	sourceId?: string;
+	excerpt?: string;
+	startOffset?: number;
+	endOffset?: number;
+	filePath?: string;
+	createdAt: string;
+}
+
+export interface BaseMemoryV2 {
+	id: string;
+	kind: MemoryKind;
+	scope?: MemoryScopeV2;
+	createdAt: string;
+	updatedAt: string;
+	lastAccessedAt?: string;
+	accessCount: number;
+	importance: number;
+	salience: number;
+	confidence: number;
+	retention: MemoryRetentionV2;
+	stability: MemoryStabilityV2;
+	archivedAt?: string;
+	archiveReason?: string;
+	revivedAt?: string;
+	validFrom?: string;
+	validTo?: string;
+	ttlDays?: number;
+	tags: string[];
+	embedding?: EmbeddingRef;
+	sourceEpisodeIds?: string[];
+	evidence?: EvidenceRef[];
+	/** SAL structural anchor — module/file path where this memory is located in the project terrain. Written by SAL extension at agent_end; undefined when SAL is disabled. */
+	structuralAnchor?: { modulePath?: string; filePath?: string };
+}
+
+export interface EpisodeMemory extends BaseMemoryV2 {
+	kind: "episode";
+	sessionId: string;
+	title?: string;
+	summary: string;
+	startedAt?: string;
+	endedAt?: string;
+	timeZone?: string;
+	userGoal?: string;
+	outcome?: string;
+	affect?: {
+		valence?: number;
+		intensity?: number;
+		label?: string;
+	};
+	filesModified: string[];
+	toolsUsed: Record<string, number>;
+	entities: string[];
+	facetIds: string[];
+	derivedSemanticIds: string[];
+	derivedProcedureIds: string[];
+	consolidatedAt?: string;
+	reconsolidatedAt?: string;
+}
+
+export interface EpisodeFacet extends BaseMemoryV2 {
+	kind: "facet";
+	episodeId: string;
+	facetType: FacetKind;
+	searchText: string;
+	anchorText?: string;
+	summary?: string;
+	detail?: string;
+	entityRefs?: string[];
+	aliases?: string[];
+	causalRole?: "cause" | "effect" | "constraint" | "resolution" | "signal";
+	outcomeScore?: number;
+}
+
+export interface SemanticMemory extends BaseMemoryV2 {
+	/** Browser migration: stable links to legacy records for edits and deletion. */
+	legacyIds?: string[];
+	kind: "semantic";
+	semanticType: SemanticKind;
+	name: string;
+	summary: string;
+	detail?: string;
+	supersedesIds?: string[];
+	supersededById?: string;
+	abstractionLevel?: AbstractionLevel;
+	conflictWithIds?: string[];
+}
+
+export interface ProceduralStep {
+	id: string;
+	text: string;
+	kind?: "step" | "warning" | "precondition" | "heuristic" | "validation";
+}
+
+export interface ProceduralMemory extends BaseMemoryV2 {
+	kind: "procedural";
+	name: string;
+	summary: string;
+	searchText: string;
+	applicability?: string;
+	boundaries?: string;
+	contextText?: string;
+	steps: ProceduralStep[];
+	status: ProcedureStatus;
+	version: number;
+	sourceFacetIds?: string[];
+	sourceSemanticIds?: string[];
+	supersedesIds?: string[];
+	supersededById?: string;
+}
+
+export interface StateMemory extends BaseMemoryV2 {
+	kind: "state";
+	stateType: StateType;
+	summary: string;
+	detail?: string;
+	horizon: StateHorizon;
+}
+
+export interface MemoryLink {
+	id: string;
+	fromId: string;
+	toId: string;
+	type: MemoryLinkType;
+	weight: number;
+	explicit: boolean;
+	createdAt: string;
+	updatedAt: string;
+	evidence?: EvidenceRef[];
+}
+
+export interface V2Meta {
+	version: number;
+	lastMigrationAt?: string;
+	lastEmbeddingSyncAt?: string;
+	lastReconsolidationAt?: string;
+	lastMaintenanceAt?: string;
+	lastMaintenanceVersion?: number;
+	lastBackupAt?: string;
+	lastBackupVersion?: number;
+}
+
+export interface NanoMemV2Snapshot {
+	episodes: EpisodeMemory[];
+	facets: EpisodeFacet[];
+	semantic: SemanticMemory[];
+	procedural: ProceduralMemory[];
+	state: StateMemory[];
+	links: MemoryLink[];
+	meta: V2Meta;
+}

package/src/types.ts

@@ -0,0 +1,372 @@
+/**
+ * [WHO]: LlmFn, MemoryScope, MemoryRetention, MemoryStability, FacetData, MemoryEntry, MemoryRelation, Episode, WorkEntry, EventData, StateData
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by packages/mem-core/src/index.ts
+ * [HERE]: packages/mem-core/src/types.ts - foundation layer type definitions for all memory data structures
+ */
+
+
+/** 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;
+}
+
+export type MemoryRetention = "core" | "key-event" | "ambient";
+export type MemoryStability = "stable" | "situational";
+
+/** 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 EventData {
+	kind: string;
+	outcome?: string;
+	emotionalWeight?: number;
+}
+
+export interface StateData {
+	mood: string;
+	intensity?: number;
+	horizon?: "momentary" | "short-term";
+}
+
+export interface MemoryRelation {
+	id: string;
+	kind: "same-project" | "tag-overlap" | "cause-of" | "caused-by" | "preference-shapes" | "repeated-pattern";
+	weight: number;
+}
+
+export interface MemoryEntry {
+	id: string;
+	type: "fact" | "lesson" | "preference" | "decision" | "entity" | "pattern" | "struggle" | "event";
+	/** @deprecated Use name/summary/detail instead. Kept for backward compatibility reads. */
+	content?: string;
+	/** Short title (≤30 chars) for quick identification */
+	name?: string;
+	/** One-liner cue (≤150 chars) for Memory Cue injection */
+	summary?: string;
+	/** Full content body — only injected in Active tier or via recall_memory tool */
+	detail?: 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;
+	retention?: MemoryRetention;
+	salience?: number;
+	stability?: MemoryStability;
+	archivedAt?: string;
+	archiveReason?: string;
+	revivedAt?: string;
+	stateData?: StateData;
+	relations?: MemoryRelation[];
+	/** Structured data for pattern/struggle types (Facets) */
+	facetData?: FacetData;
+	eventData?: EventData;
+}
+
+export interface Episode {
+	sessionId: string;
+	project: string;
+	date: string;
+	startedAt?: string;
+	endedAt?: string;
+	timeZone?: 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;
+	/** Full work detail — only injected in Active tier or via recall_memory tool */
+	detail?: string;
+	project: string;
+	tags: string[];
+	importance: number;
+	strength?: number;
+	created: string;
+	eventTime?: string;
+	lastAccessed?: string;
+	accessCount: number;
+	relatedIds?: string[];
+	ttl?: number;
+	archivedAt?: string;
+	archiveReason?: string;
+	revivedAt?: string;
+	scope?: MemoryScope;
+}
+
+export interface Meta {
+	totalSessions: number;
+	lastConsolidation?: string;
+	version: number;
+	lastMaintenanceAt?: string;
+	lastMaintenanceVersion?: number;
+	lastBackupAt?: string;
+	lastBackupVersion?: number;
+}
+
+/** Mem0-style update operations */
+export type UpdateAction = "add" | "update" | "delete" | "noop";
+
+export interface ExtractedItem {
+	type: "preference" | "fact" | "lesson" | "decision" | "retract" | "pattern" | "struggle" | "event";
+	/** @deprecated Use name/summary/detail instead. */
+	content?: string;
+	/** Short title (≤30 chars) */
+	name?: string;
+	/** One-liner summary (≤150 chars) */
+	summary?: string;
+	/** Full content body */
+	detail?: string;
+	/** Structured data for pattern/struggle types (populated by LLM extraction) */
+	facetData?: FacetData;
+	eventData?: EventData;
+	retention?: MemoryRetention;
+	salience?: number;
+	stability?: MemoryStability;
+	stateData?: StateData;
+}
+
+export interface ExtractedWork {
+	goal: string;
+	summary: string;
+	/** Full detail of work accomplished */
+	detail?: 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;
+}
+
+export interface AlignmentSnapshot {
+	identityCore: MemoryEntry[];
+	keyEvents: MemoryEntry[];
+	behaviorDrivers: MemoryEntry[];
+	currentState: MemoryEntry[];
+	relationshipEdges: Array<{
+		fromId: string;
+		toId: string;
+		kind: MemoryRelation["kind"];
+		weight: number;
+	}>;
+	conflicts: Array<{
+		aId: string;
+		bId: string;
+		reason: string;
+		severity: number;
+		recommendation: "merge" | "demote" | "forget" | "mark-situational";
+		rationale: 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;
+}
+
+// ─── Developer Persona (Human-Readable) ──────────────────────────────
+
+export interface DeveloperPersona {
+	/** Plain language description of what this person does */
+	whatTheyDo: string;
+	/** Experience level description */
+	experienceLevel: string;
+	/** Areas of strength */
+	superpowers: string[];
+	/** Frequent blockers */
+	painPoints: string[];
+	/** Work style description */
+	workStyle: string;
+	/** One-sentence summary */
+	summary: string;
+}
+
+// ─── Human-Readable Insights ──────────────────────────────
+
+export interface HumanInsight {
+	/** Insight title - grabs attention */
+	title: string;
+	/** Insight content - like chatting with a friend */
+	content: string;
+	/** Emoji icon */
+	icon: string;
+	/** Utility level */
+	utility: "high" | "medium" | "low";
+	/** Category tags */
+	tags: string[];
+}
+
+// ─── Root Cause Analysis Insights ──────────────────────────────
+
+export interface RootCauseInsight {
+	/** Surface symptom */
+	symptom: string;
+	/** Root cause (in plain language) */
+	rootCause: string;
+	/** Evidence */
+	evidence: string[];
+	/** Suggestion */
+	suggestion: string;
+}
+
+// ─── Comparative Insights ──────────────────────────────
+
+export interface ComparativeInsight {
+	/** Comparison dimension */
+	dimension: string;
+	/** User's actual situation */
+	youAre: string;
+	/** How typical users are */
+	typical: string;
+	/** Conclusion */
+	verdict: string;
+}
+
+// ─── Enhanced Full Insights Report ──────────────────────────────────────
+
+export interface EnhancedInsightsReport extends FullInsightsReport {
+	/** Developer persona */
+	persona?: DeveloperPersona;
+	/** Human-readable insights */
+	humanInsights: HumanInsight[];
+	/** Root cause analysis */
+	rootCauses: RootCauseInsight[];
+	/** Comparative insights */
+	comparisons: ComparativeInsight[];
+}
+
+// ─── Progressive Recall Types ────────────────────────────
+
+/** Injection tier for progressive recall */
+export type InjectionLevel = "active" | "cue" | "dormant";