@stackmemoryai/stackmemory 0.2.6 → 0.2.8

package/dist/src/core/retrieval/types.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Types for LLM-Driven Context Retrieval System
+ * Implements intelligent context selection based on compressed summaries
+ */
+import { Frame, Anchor, Event } from '../context/frame-manager.js';
+import { StackMemoryQuery } from '../query/query-parser.js';
+/**
+ * Compressed summary of recent session activity
+ */
+export interface RecentSessionSummary {
+    /** Recent frames with their key attributes */
+    frames: FrameSummary[];
+    /** Dominant operations performed */
+    dominantOperations: OperationSummary[];
+    /** Files that were touched */
+    filesTouched: FileSummary[];
+    /** Errors encountered */
+    errorsEncountered: ErrorSummary[];
+    /** Time range covered */
+    timeRange: {
+        start: number;
+        end: number;
+        durationMs: number;
+    };
+}
+export interface FrameSummary {
+    frameId: string;
+    name: string;
+    type: string;
+    depth: number;
+    eventCount: number;
+    anchorCount: number;
+    score: number;
+    createdAt: number;
+    closedAt?: number;
+    digestPreview?: string;
+}
+export interface OperationSummary {
+    operation: string;
+    count: number;
+    lastOccurrence: number;
+    successRate: number;
+}
+export interface FileSummary {
+    path: string;
+    operationCount: number;
+    lastModified: number;
+    operations: string[];
+}
+export interface ErrorSummary {
+    errorType: string;
+    message: string;
+    count: number;
+    lastOccurrence: number;
+    resolved: boolean;
+}
+/**
+ * Historical patterns extracted from memory
+ */
+export interface HistoricalPatterns {
+    /** Frame counts by topic */
+    topicFrameCounts: Record<string, number>;
+    /** Key decisions made */
+    keyDecisions: DecisionSummary[];
+    /** Recurring issues */
+    recurringIssues: IssueSummary[];
+    /** Common tool sequences */
+    commonToolSequences: ToolSequence[];
+    /** Time-based activity patterns */
+    activityPatterns: ActivityPattern[];
+}
+export interface DecisionSummary {
+    id: string;
+    text: string;
+    frameId: string;
+    timestamp: number;
+    impact: 'low' | 'medium' | 'high';
+    relatedFiles?: string[];
+}
+export interface IssueSummary {
+    issueType: string;
+    occurrenceCount: number;
+    lastSeen: number;
+    resolutionRate: number;
+    commonFixes?: string[];
+}
+export interface ToolSequence {
+    pattern: string;
+    frequency: number;
+    avgDuration: number;
+    successRate: number;
+}
+export interface ActivityPattern {
+    periodType: 'hourly' | 'daily' | 'weekly';
+    peakPeriods: string[];
+    avgEventsPerPeriod: number;
+}
+/**
+ * Queryable indices for fast retrieval
+ */
+export interface QueryableIndices {
+    /** Index by error type */
+    byErrorType: Record<string, string[]>;
+    /** Index by timeframe */
+    byTimeframe: Record<string, string[]>;
+    /** Index by contributor */
+    byContributor: Record<string, string[]>;
+    /** Index by topic */
+    byTopic: Record<string, string[]>;
+    /** Index by file */
+    byFile: Record<string, string[]>;
+}
+/**
+ * Complete compressed summary for LLM analysis
+ */
+export interface CompressedSummary {
+    /** Project identifier */
+    projectId: string;
+    /** Generation timestamp */
+    generatedAt: number;
+    /** Recent session summary */
+    recentSession: RecentSessionSummary;
+    /** Historical patterns */
+    historicalPatterns: HistoricalPatterns;
+    /** Queryable indices */
+    queryableIndices: QueryableIndices;
+    /** Summary statistics */
+    stats: SummaryStats;
+}
+export interface SummaryStats {
+    totalFrames: number;
+    totalEvents: number;
+    totalAnchors: number;
+    totalDecisions: number;
+    oldestFrame: number;
+    newestFrame: number;
+    avgFrameDepth: number;
+    avgEventsPerFrame: number;
+}
+/**
+ * LLM analysis request
+ */
+export interface LLMAnalysisRequest {
+    /** Current user query */
+    currentQuery: string;
+    /** Parsed structured query */
+    parsedQuery?: StackMemoryQuery;
+    /** Compressed summary */
+    compressedSummary: CompressedSummary;
+    /** Token budget for context */
+    tokenBudget: number;
+    /** Optional hints for retrieval */
+    hints?: RetrievalHints;
+}
+export interface RetrievalHints {
+    /** Prefer recent frames */
+    preferRecent?: boolean;
+    /** Focus on specific topics */
+    focusTopics?: string[];
+    /** Include error context */
+    includeErrors?: boolean;
+    /** Include decision history */
+    includeDecisions?: boolean;
+    /** Minimum relevance score */
+    minRelevance?: number;
+}
+/**
+ * LLM analysis response
+ */
+export interface LLMAnalysisResponse {
+    /** Reasoning for the retrieval decision (auditable) */
+    reasoning: string;
+    /** Frames to retrieve with priority order */
+    framesToRetrieve: FrameRetrievalPlan[];
+    /** Confidence score (0.0 - 1.0) */
+    confidenceScore: number;
+    /** Additional context recommendations */
+    recommendations: ContextRecommendation[];
+    /** Analysis metadata */
+    metadata: AnalysisMetadata;
+}
+export interface FrameRetrievalPlan {
+    frameId: string;
+    priority: number;
+    reason: string;
+    includeEvents: boolean;
+    includeAnchors: boolean;
+    includeDigest: boolean;
+    estimatedTokens: number;
+}
+export interface ContextRecommendation {
+    type: 'include' | 'exclude' | 'summarize';
+    target: string;
+    reason: string;
+    impact: 'low' | 'medium' | 'high';
+}
+export interface AnalysisMetadata {
+    analysisTimeMs: number;
+    summaryTokens: number;
+    queryComplexity: 'simple' | 'moderate' | 'complex';
+    matchedPatterns: string[];
+    fallbackUsed: boolean;
+}
+/**
+ * Retrieved context result
+ */
+export interface RetrievedContext {
+    /** Assembled context string */
+    context: string;
+    /** Frames included */
+    frames: Frame[];
+    /** Anchors included */
+    anchors: Anchor[];
+    /** Events included */
+    events: Event[];
+    /** LLM analysis that drove retrieval */
+    analysis: LLMAnalysisResponse;
+    /** Token usage */
+    tokenUsage: {
+        budget: number;
+        used: number;
+        remaining: number;
+    };
+    /** Retrieval metadata */
+    metadata: RetrievalMetadata;
+}
+export interface RetrievalMetadata {
+    retrievalTimeMs: number;
+    cacheHit: boolean;
+    framesScanned: number;
+    framesIncluded: number;
+    compressionRatio: number;
+}
+/**
+ * Configuration for the retrieval system
+ */
+export interface RetrievalConfig {
+    /** Maximum frames to include in summary */
+    maxSummaryFrames: number;
+    /** Default token budget */
+    defaultTokenBudget: number;
+    /** Cache TTL in seconds */
+    cacheTtlSeconds: number;
+    /** Minimum confidence to use LLM suggestions */
+    minConfidenceThreshold: number;
+    /** Enable fallback to heuristic retrieval */
+    enableFallback: boolean;
+    /** LLM provider configuration */
+    llmConfig: {
+        provider: 'anthropic' | 'openai' | 'local';
+        model: string;
+        maxTokens: number;
+        temperature: number;
+    };
+}
+export declare const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/core/retrieval/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/retrieval/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,oCAAoC;IACpC,kBAAkB,EAAE,gBAAgB,EAAE,CAAC;IACvC,8BAA8B;IAC9B,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,yBAAyB;IACzB,iBAAiB,EAAE,YAAY,EAAE,CAAC;IAClC,yBAAyB;IACzB,SAAS,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,yBAAyB;IACzB,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,uBAAuB;IACvB,eAAe,EAAE,YAAY,EAAE,CAAC;IAChC,4BAA4B;IAC5B,mBAAmB,EAAE,YAAY,EAAE,CAAC;IACpC,mCAAmC;IACnC,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,2BAA2B;IAC3B,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACxC,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAClC,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,aAAa,EAAE,oBAAoB,CAAC;IACpC,0BAA0B;IAC1B,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,wBAAwB;IACxB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,yBAAyB;IACzB,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,yBAAyB;IACzB,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,4BAA4B;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;IACvC,mCAAmC;IACnC,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,eAAe,EAAE,qBAAqB,EAAE,CAAC;IACzC,wBAAwB;IACxB,QAAQ,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;IACnD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,uBAAuB;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sBAAsB;IACtB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,wCAAwC;IACxC,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,kBAAkB;IAClB,UAAU,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,yBAAyB;IACzB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,2BAA2B;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2BAA2B;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,sBAAsB,EAAE,MAAM,CAAC;IAC/B,6CAA6C;IAC7C,cAAc,EAAE,OAAO,CAAC;IACxB,iCAAiC;IACjC,SAAS,EAAE;QACT,QAAQ,EAAE,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;QAC3C,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,eAAO,MAAM,wBAAwB,EAAE,eAYtC,CAAC"}

package/dist/src/core/retrieval/types.js

@@ -0,0 +1,18 @@
+/**
+ * Types for LLM-Driven Context Retrieval System
+ * Implements intelligent context selection based on compressed summaries
+ */
+export const DEFAULT_RETRIEVAL_CONFIG = {
+    maxSummaryFrames: 15,
+    defaultTokenBudget: 8000,
+    cacheTtlSeconds: 300,
+    minConfidenceThreshold: 0.6,
+    enableFallback: true,
+    llmConfig: {
+        provider: 'anthropic',
+        model: 'claude-3-haiku-20240307',
+        maxTokens: 1024,
+        temperature: 0.3,
+    },
+};
+//# sourceMappingURL=types.js.map

package/dist/src/core/retrieval/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/retrieval/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoRH,MAAM,CAAC,MAAM,wBAAwB,GAAoB;IACvD,gBAAgB,EAAE,EAAE;IACpB,kBAAkB,EAAE,IAAI;IACxB,eAAe,EAAE,GAAG;IACpB,sBAAsB,EAAE,GAAG;IAC3B,cAAc,EAAE,IAAI;IACpB,SAAS,EAAE;QACT,QAAQ,EAAE,WAAW;QACrB,KAAK,EAAE,yBAAyB;QAChC,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,GAAG;KACjB;CACF,CAAC"}

package/dist/src/core/session/index.d.ts

@@ -0,0 +1,2 @@
+export { SessionManager, sessionManager, type Session, type SessionOptions, FrameQueryMode } from './session-manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/core/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,cAAc,EACd,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,cAAc,EACf,MAAM,sBAAsB,CAAC"}

package/dist/src/core/session/index.js

@@ -0,0 +1,2 @@
+export { SessionManager, sessionManager, FrameQueryMode } from './session-manager.js';
+//# sourceMappingURL=index.js.map

package/dist/src/core/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,cAAc,EAGd,cAAc,EACf,MAAM,sBAAsB,CAAC"}

package/dist/src/core/session/session-manager.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Session Management for StackMemory
+ * Provides session persistence and recovery across CLI invocations
+ */
+export interface Session {
+    sessionId: string;
+    runId: string;
+    projectId: string;
+    branch?: string;
+    startedAt: number;
+    lastActiveAt: number;
+    metadata: {
+        user?: string;
+        environment?: string;
+        tags?: string[];
+        cliVersion?: string;
+    };
+    state: 'active' | 'suspended' | 'closed';
+}
+export interface SessionOptions {
+    sessionId?: string;
+    projectPath?: string;
+    branch?: string;
+    metadata?: Session['metadata'];
+}
+export declare enum FrameQueryMode {
+    CURRENT_SESSION = "current",
+    PROJECT_ACTIVE = "project",
+    ALL_ACTIVE = "all",
+    HISTORICAL = "historical"
+}
+export declare class SessionManager {
+    private static instance;
+    private sessionsDir;
+    private currentSession;
+    private readonly STALE_THRESHOLD;
+    private constructor();
+    static getInstance(): SessionManager;
+    initialize(): Promise<void>;
+    getOrCreateSession(options?: SessionOptions): Promise<Session>;
+    createSession(params: {
+        projectId: string;
+        branch?: string;
+        metadata?: Session['metadata'];
+    }): Promise<Session>;
+    loadSession(sessionId: string): Promise<Session | null>;
+    saveSession(session: Session): Promise<void>;
+    suspendSession(sessionId?: string): Promise<void>;
+    resumeSession(sessionId: string): Promise<Session>;
+    closeSession(sessionId?: string): Promise<void>;
+    listSessions(filter?: {
+        projectId?: string;
+        state?: Session['state'];
+        branch?: string;
+    }): Promise<Session[]>;
+    mergeSessions(sourceId: string, targetId: string): Promise<Session>;
+    cleanupStaleSessions(maxAge?: number): Promise<number>;
+    getCurrentSession(): Session | null;
+    getSessionRunId(): string;
+    private getProjectHash;
+    private getGitBranch;
+    private findProjectBranchSession;
+    private findLastActiveSession;
+    private setProjectActiveSession;
+    private isSessionRecent;
+    private touchSession;
+}
+export declare const sessionManager: SessionManager;
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/src/core/session/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../../../src/core/session/session-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,MAAM,WAAW,OAAO;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,KAAK,EAAE,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;CAC1C;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC;AAED,oBAAY,cAAc;IACxB,eAAe,YAAY;IAC3B,cAAc,YAAY;IAC1B,UAAU,QAAQ;IAClB,UAAU,eAAe;CAC1B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiB;IACxC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;IAEvD,OAAO;IAKP,MAAM,CAAC,WAAW,IAAI,cAAc;IAO9B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAc3B,kBAAkB,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAqD9D,aAAa,CAAC,MAAM,EAAE;QAC1B,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;KAChC,GAAG,OAAO,CAAC,OAAO,CAAC;IAgCd,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAiBvD,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjD,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBlD,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/C,YAAY,CAAC,MAAM,CAAC,EAAE;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACzB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAuBhB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAkCnE,oBAAoB,CAAC,MAAM,GAAE,MAAiC,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBtF,iBAAiB,IAAI,OAAO,GAAG,IAAI;IAInC,eAAe,IAAI,MAAM;YAIX,cAAc;YAsBd,YAAY;YAcZ,wBAAwB;YAexB,qBAAqB;YASrB,uBAAuB;IASrC,OAAO,CAAC,eAAe;YAIT,YAAY;CAI3B;AAED,eAAO,MAAM,cAAc,gBAA+B,CAAC"}

package/dist/src/core/session/session-manager.js

@@ -0,0 +1,311 @@
+/**
+ * Session Management for StackMemory
+ * Provides session persistence and recovery across CLI invocations
+ */
+import { v4 as uuidv4 } from 'uuid';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { logger } from '../monitoring/logger.js';
+import { SystemError, ErrorCode } from '../errors/index.js';
+export var FrameQueryMode;
+(function (FrameQueryMode) {
+    FrameQueryMode["CURRENT_SESSION"] = "current";
+    FrameQueryMode["PROJECT_ACTIVE"] = "project";
+    FrameQueryMode["ALL_ACTIVE"] = "all";
+    FrameQueryMode["HISTORICAL"] = "historical";
+})(FrameQueryMode || (FrameQueryMode = {}));
+export class SessionManager {
+    static instance;
+    sessionsDir;
+    currentSession = null;
+    STALE_THRESHOLD = 24 * 60 * 60 * 1000; // 24 hours
+    constructor() {
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        this.sessionsDir = path.join(homeDir, '.stackmemory', 'sessions');
+    }
+    static getInstance() {
+        if (!SessionManager.instance) {
+            SessionManager.instance = new SessionManager();
+        }
+        return SessionManager.instance;
+    }
+    async initialize() {
+        try {
+            await fs.mkdir(this.sessionsDir, { recursive: true });
+            await fs.mkdir(path.join(this.sessionsDir, 'projects'), { recursive: true });
+            await fs.mkdir(path.join(this.sessionsDir, 'history'), { recursive: true });
+        }
+        catch (error) {
+            throw new SystemError('Failed to initialize session directories', ErrorCode.INITIALIZATION_ERROR, { error, sessionsDir: this.sessionsDir });
+        }
+    }
+    async getOrCreateSession(options) {
+        // 1. Check explicit session ID
+        if (options?.sessionId) {
+            const session = await this.loadSession(options.sessionId);
+            if (session) {
+                this.currentSession = session;
+                return session;
+            }
+        }
+        // 2. Check environment variable
+        const envSessionId = process.env.STACKMEMORY_SESSION;
+        if (envSessionId) {
+            const session = await this.loadSession(envSessionId);
+            if (session) {
+                this.currentSession = session;
+                return session;
+            }
+        }
+        // 3. Check project + branch context
+        const projectHash = await this.getProjectHash(options?.projectPath);
+        const branch = options?.branch || await this.getGitBranch(options?.projectPath);
+        if (projectHash) {
+            // Try project+branch session
+            const branchSession = await this.findProjectBranchSession(projectHash, branch);
+            if (branchSession && this.isSessionRecent(branchSession)) {
+                await this.touchSession(branchSession);
+                this.currentSession = branchSession;
+                return branchSession;
+            }
+            // Try last active for project
+            const lastActive = await this.findLastActiveSession(projectHash);
+            if (lastActive && this.isSessionRecent(lastActive)) {
+                await this.touchSession(lastActive);
+                this.currentSession = lastActive;
+                return lastActive;
+            }
+        }
+        // 4. Create new session
+        const newSession = await this.createSession({
+            projectId: projectHash || 'global',
+            branch,
+            metadata: options?.metadata
+        });
+        this.currentSession = newSession;
+        return newSession;
+    }
+    async createSession(params) {
+        const session = {
+            sessionId: uuidv4(),
+            runId: uuidv4(),
+            projectId: params.projectId,
+            branch: params.branch,
+            startedAt: Date.now(),
+            lastActiveAt: Date.now(),
+            metadata: {
+                ...params.metadata,
+                user: process.env.USER,
+                environment: process.env.NODE_ENV || 'development',
+                cliVersion: process.env.npm_package_version
+            },
+            state: 'active'
+        };
+        await this.saveSession(session);
+        await this.setProjectActiveSession(params.projectId, session.sessionId);
+        // Set as current session
+        this.currentSession = session;
+        logger.info('Created new session', {
+            sessionId: session.sessionId,
+            projectId: session.projectId,
+            branch: session.branch
+        });
+        return session;
+    }
+    async loadSession(sessionId) {
+        try {
+            const sessionPath = path.join(this.sessionsDir, `${sessionId}.json`);
+            const data = await fs.readFile(sessionPath, 'utf-8');
+            return JSON.parse(data);
+        }
+        catch (error) {
+            // Check history
+            try {
+                const historyPath = path.join(this.sessionsDir, 'history', `${sessionId}.json`);
+                const data = await fs.readFile(historyPath, 'utf-8');
+                return JSON.parse(data);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    async saveSession(session) {
+        const sessionPath = path.join(this.sessionsDir, `${session.sessionId}.json`);
+        await fs.writeFile(sessionPath, JSON.stringify(session, null, 2));
+    }
+    async suspendSession(sessionId) {
+        const id = sessionId || this.currentSession?.sessionId;
+        if (!id)
+            return;
+        const session = await this.loadSession(id);
+        if (session) {
+            session.state = 'suspended';
+            session.lastActiveAt = Date.now();
+            await this.saveSession(session);
+        }
+    }
+    async resumeSession(sessionId) {
+        const session = await this.loadSession(sessionId);
+        if (!session) {
+            throw new SystemError('Session not found', ErrorCode.NOT_FOUND, { sessionId });
+        }
+        session.state = 'active';
+        session.lastActiveAt = Date.now();
+        await this.saveSession(session);
+        this.currentSession = session;
+        return session;
+    }
+    async closeSession(sessionId) {
+        const id = sessionId || this.currentSession?.sessionId;
+        if (!id)
+            return;
+        const session = await this.loadSession(id);
+        if (session) {
+            session.state = 'closed';
+            session.lastActiveAt = Date.now();
+            // Move to history
+            const sessionPath = path.join(this.sessionsDir, `${session.sessionId}.json`);
+            const historyPath = path.join(this.sessionsDir, 'history', `${session.sessionId}.json`);
+            await fs.rename(sessionPath, historyPath);
+        }
+    }
+    async listSessions(filter) {
+        const sessions = [];
+        // Load active sessions
+        const files = await fs.readdir(this.sessionsDir);
+        for (const file of files) {
+            if (file.endsWith('.json')) {
+                const session = await this.loadSession(file.replace('.json', ''));
+                if (session) {
+                    sessions.push(session);
+                }
+            }
+        }
+        // Apply filters
+        return sessions.filter(s => {
+            if (filter?.projectId && s.projectId !== filter.projectId)
+                return false;
+            if (filter?.state && s.state !== filter.state)
+                return false;
+            if (filter?.branch && s.branch !== filter.branch)
+                return false;
+            return true;
+        });
+    }
+    async mergeSessions(sourceId, targetId) {
+        const source = await this.loadSession(sourceId);
+        const target = await this.loadSession(targetId);
+        if (!source || !target) {
+            throw new SystemError('Session not found for merge', ErrorCode.NOT_FOUND, { sourceId, targetId });
+        }
+        // Merge metadata
+        target.metadata = {
+            ...target.metadata,
+            ...source.metadata,
+            tags: [...(target.metadata.tags || []), ...(source.metadata.tags || [])]
+        };
+        // Update timestamps
+        target.lastActiveAt = Date.now();
+        // Close source session
+        await this.closeSession(sourceId);
+        await this.saveSession(target);
+        logger.info('Merged sessions', {
+            source: sourceId,
+            target: targetId
+        });
+        return target;
+    }
+    async cleanupStaleSessions(maxAge = 30 * 24 * 60 * 60 * 1000) {
+        const historyDir = path.join(this.sessionsDir, 'history');
+        const files = await fs.readdir(historyDir);
+        const cutoff = Date.now() - maxAge;
+        let cleaned = 0;
+        for (const file of files) {
+            if (file.endsWith('.json')) {
+                const filePath = path.join(historyDir, file);
+                const stats = await fs.stat(filePath);
+                if (stats.mtimeMs < cutoff) {
+                    await fs.unlink(filePath);
+                    cleaned++;
+                }
+            }
+        }
+        logger.info(`Cleaned up ${cleaned} stale sessions`);
+        return cleaned;
+    }
+    getCurrentSession() {
+        return this.currentSession;
+    }
+    getSessionRunId() {
+        return this.currentSession?.runId || uuidv4();
+    }
+    async getProjectHash(projectPath) {
+        try {
+            const cwd = projectPath || process.cwd();
+            // Try to use the basename of the directory as project ID
+            const path = await import('path');
+            const projectName = path.basename(cwd);
+            // Check if it looks like a demo/development project
+            if (projectName === 'stackmemory') {
+                return 'stackmemory-demo';
+            }
+            // Otherwise use hash for consistency
+            const hash = crypto.createHash('sha256');
+            hash.update(cwd);
+            return hash.digest('hex').substring(0, 12);
+        }
+        catch {
+            return null;
+        }
+    }
+    async getGitBranch(projectPath) {
+        try {
+            const { execSync } = await import('child_process');
+            const cwd = projectPath || process.cwd();
+            const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+                cwd,
+                encoding: 'utf-8'
+            }).trim();
+            return branch;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async findProjectBranchSession(projectHash, branch) {
+        if (!branch)
+            return null;
+        const sessions = await this.listSessions({
+            projectId: projectHash,
+            state: 'active',
+            branch
+        });
+        return sessions.sort((a, b) => b.lastActiveAt - a.lastActiveAt)[0] || null;
+    }
+    async findLastActiveSession(projectHash) {
+        const sessions = await this.listSessions({
+            projectId: projectHash,
+            state: 'active'
+        });
+        return sessions.sort((a, b) => b.lastActiveAt - a.lastActiveAt)[0] || null;
+    }
+    async setProjectActiveSession(projectId, sessionId) {
+        const projectFile = path.join(this.sessionsDir, 'projects', `${projectId}.json`);
+        await fs.writeFile(projectFile, JSON.stringify({
+            projectId,
+            activeSessionId: sessionId,
+            updatedAt: Date.now()
+        }, null, 2));
+    }
+    isSessionRecent(session) {
+        return Date.now() - session.lastActiveAt < this.STALE_THRESHOLD;
+    }
+    async touchSession(session) {
+        session.lastActiveAt = Date.now();
+        await this.saveSession(session);
+    }
+}
+export const sessionManager = SessionManager.getInstance();
+//# sourceMappingURL=session-manager.js.map