@chude/memory 4.0.0

package/dist/domain/entities/entity.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Entity Domain Type
+ *
+ * Represents extracted metadata from Claude Code sessions.
+ * Four variants: concept, file, decision, term.
+ *
+ * Entity properties:
+ * - Has identity (id when persisted)
+ * - Immutable after construction
+ * - Type-specific metadata for structured storage
+ */
+/**
+ * Entity type variants for extracted metadata.
+ * (Named ExtractedEntityType to distinguish from link.ts EntityType)
+ */
+export type ExtractedEntityType = "concept" | "file" | "decision" | "term";
+/**
+ * Metadata for concept entities (technical concepts).
+ */
+export interface ConceptMetadata {
+    /** Category of the concept (e.g., "architecture", "database", "testing") */
+    category?: string;
+}
+/**
+ * Metadata for file entities (file paths referenced in session).
+ */
+export interface FileMetadata {
+    /** Operation performed on the file */
+    operation?: "read" | "write" | "edit";
+    /** Number of lines in the file */
+    lineCount?: number;
+}
+/**
+ * Metadata for decision entities (explicit choices made).
+ * Required fields: subject, decision
+ */
+export interface DecisionMetadata {
+    /** What was being decided */
+    subject: string;
+    /** The final decision */
+    decision: string;
+    /** Alternatives that were rejected */
+    rejected: string[];
+    /** Reasoning behind the decision */
+    rationale: string;
+}
+/**
+ * Metadata for term entities (domain-specific terminology).
+ */
+export interface TermMetadata {
+    /** Definition of the term */
+    definition?: string;
+}
+/**
+ * Union type for all entity metadata variants.
+ */
+export type EntityMetadata = ConceptMetadata | FileMetadata | DecisionMetadata | TermMetadata;
+interface EntityParams {
+    id?: number | undefined;
+    type: ExtractedEntityType;
+    name: string;
+    confidence: number;
+    metadata?: EntityMetadata | undefined;
+    createdAt?: Date | undefined;
+}
+export declare class Entity {
+    private readonly _id?;
+    private readonly _type;
+    private readonly _name;
+    private readonly _confidence;
+    private readonly _metadata?;
+    private readonly _createdAt?;
+    private constructor();
+    /**
+     * Create an Entity.
+     * @throws Error if name is empty, confidence is out of range, or type is invalid
+     * @throws Error if decision type lacks required metadata fields
+     */
+    static create(params: EntityParams): Entity;
+    /**
+     * The database identifier (undefined until persisted).
+     */
+    get id(): number | undefined;
+    /**
+     * The entity type (concept, file, decision, term).
+     */
+    get type(): ExtractedEntityType;
+    /**
+     * The entity name/value.
+     */
+    get name(): string;
+    /**
+     * Confidence score (0-1) for quality filtering.
+     */
+    get confidence(): number;
+    /**
+     * Type-specific metadata (defensive copy).
+     */
+    get metadata(): EntityMetadata | undefined;
+    /**
+     * When the entity was created (defensive copy).
+     */
+    get createdAt(): Date | undefined;
+    /**
+     * Type guard: is this a concept entity?
+     */
+    get isConcept(): boolean;
+    /**
+     * Type guard: is this a file entity?
+     */
+    get isFile(): boolean;
+    /**
+     * Type guard: is this a decision entity?
+     */
+    get isDecision(): boolean;
+    /**
+     * Type guard: is this a term entity?
+     */
+    get isTerm(): boolean;
+    /**
+     * Check equality with another Entity.
+     * Compares by id when both have ids, otherwise by type+name.
+     */
+    equals(other: Entity): boolean;
+    /**
+     * Return a new Entity with the specified id.
+     * Used after database insert to assign the generated id.
+     */
+    withId(id: number): Entity;
+}
+export {};

package/dist/domain/entities/extraction-state.d.ts

@@ -0,0 +1,128 @@
+/**
+ * ExtractionState Entity
+ *
+ * Tracks the state of extracting a session from JSONL files.
+ * Enables incremental sync and progress tracking.
+ *
+ * Entity properties:
+ * - Has unique identity (id)
+ * - Immutable after construction (state changes return new instances)
+ * - Tracks extraction lifecycle (pending -> in_progress -> complete/error)
+ */
+export type ExtractionStatus = "pending" | "in_progress" | "complete" | "error";
+interface ExtractionStateParams {
+    id: string;
+    sessionPath: string;
+    startedAt: Date;
+    status?: ExtractionStatus | undefined;
+    completedAt?: Date | undefined;
+    messagesExtracted?: number | undefined;
+    errorMessage?: string | undefined;
+    fileMtime?: Date | undefined;
+    fileSize?: number | undefined;
+}
+export declare class ExtractionState {
+    private readonly _id;
+    private readonly _sessionPath;
+    private readonly _startedAt;
+    private readonly _status;
+    private readonly _completedAt?;
+    private readonly _messagesExtracted;
+    private readonly _errorMessage?;
+    private readonly _fileMtime?;
+    private readonly _fileSize?;
+    private constructor();
+    /**
+     * Create an ExtractionState entity.
+     * @throws Error if id or sessionPath is empty, status is invalid, or messagesExtracted is negative
+     */
+    static create(params: ExtractionStateParams): ExtractionState;
+    /**
+     * The unique extraction state identifier.
+     */
+    get id(): string;
+    /**
+     * The path to the session JSONL file being extracted.
+     */
+    get sessionPath(): string;
+    /**
+     * When the extraction started.
+     */
+    get startedAt(): Date;
+    /**
+     * The current extraction status.
+     */
+    get status(): ExtractionStatus;
+    /**
+     * When the extraction completed (if complete or error).
+     */
+    get completedAt(): Date | undefined;
+    /**
+     * Number of messages extracted so far.
+     */
+    get messagesExtracted(): number;
+    /**
+     * Error message if extraction failed.
+     */
+    get errorMessage(): string | undefined;
+    /**
+     * File modification time when extraction started.
+     * Used for incremental sync detection.
+     */
+    get fileMtime(): Date | undefined;
+    /**
+     * File size in bytes when extraction started.
+     * Used for incremental sync detection.
+     */
+    get fileSize(): number | undefined;
+    /**
+     * Whether extraction is pending.
+     */
+    get isPending(): boolean;
+    /**
+     * Whether extraction is in progress.
+     */
+    get isInProgress(): boolean;
+    /**
+     * Whether extraction is complete.
+     */
+    get isComplete(): boolean;
+    /**
+     * Whether extraction failed.
+     */
+    get isError(): boolean;
+    /**
+     * Duration of extraction in milliseconds (only available when complete).
+     */
+    get durationMs(): number | undefined;
+    /**
+     * Check equality with another ExtractionState (based on id).
+     */
+    equals(other: ExtractionState): boolean;
+    /**
+     * Start processing this extraction.
+     * Returns a new ExtractionState instance (immutability).
+     */
+    startProcessing(): ExtractionState;
+    /**
+     * Mark extraction as complete.
+     * Returns a new ExtractionState instance (immutability).
+     */
+    complete(completedAt: Date): ExtractionState;
+    /**
+     * Mark extraction as failed.
+     * Returns a new ExtractionState instance (immutability).
+     */
+    fail(errorMessage: string): ExtractionState;
+    /**
+     * Increment the count of extracted messages.
+     * Returns a new ExtractionState instance (immutability).
+     */
+    incrementMessages(count?: number): ExtractionState;
+    /**
+     * Set file metadata for incremental sync detection.
+     * Returns a new ExtractionState instance (immutability).
+     */
+    withFileMetadata(mtime: Date, size: number): ExtractionState;
+}
+export {};

package/dist/domain/entities/fact.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Fact Domain Entity
+ *
+ * Represents a structured fact or event in the system.
+ * Part of the hybrid event-log Source of Truth (SSOT).
+ *
+ * Immutable after construction.
+ */
+export type FactType = "decision" | "learning" | "preference" | "friction" | "observation" | "supersedence";
+export interface FactParams {
+    id?: number | undefined;
+    uuid?: string | undefined;
+    type: FactType;
+    project: string;
+    content: string;
+    metadata?: Record<string, any> | undefined;
+    observedAt: Date;
+    supersededAt?: Date | null | undefined;
+    supersededBy?: string | null | undefined;
+}
+export interface CandidateFact {
+    type: "decision" | "learning" | "preference" | "friction" | "observation";
+    content: string;
+    metadata?: Record<string, any> | undefined;
+    confidence: number;
+}
+export declare class Fact {
+    private readonly _id?;
+    private readonly _uuid;
+    private readonly _type;
+    private readonly _project;
+    private readonly _content;
+    private readonly _metadata?;
+    private readonly _observedAt;
+    private readonly _supersededAt;
+    private readonly _supersededBy;
+    private constructor();
+    /**
+     * Creates a Fact entity and validates invariants.
+     */
+    static create(params: FactParams): Fact;
+    get id(): number | undefined;
+    get uuid(): string;
+    get type(): FactType;
+    get project(): string;
+    get content(): string;
+    get metadata(): Record<string, any> | undefined;
+    get observedAt(): Date;
+    get supersededAt(): Date | null;
+    get supersededBy(): string | null;
+    /**
+     * Returns a new Fact instance with the specified database primary key ID.
+     */
+    withId(id: number): Fact;
+    /**
+     * Returns a new Fact instance marked as superseded by a replacement Fact.
+     */
+    withSuperseded(supersededAt: Date, supersededByUuid: string): Fact;
+}

package/dist/domain/entities/friction-entry.d.ts

@@ -0,0 +1,84 @@
+/**
+ * FrictionEntry Entity
+ *
+ * Represents a logged friction point with a tool.
+ * Friction entries track tool-specific issues (search failures,
+ * unhelpful output, missing features, workarounds needed) for
+ * self-improvement feedback loops.
+ *
+ * Entity properties:
+ * - Has identity (id when persisted)
+ * - Immutable after construction
+ * - Validated on creation via static create()
+ */
+/**
+ * Severity levels for friction entries.
+ */
+export type FrictionSeverity = "low" | "medium" | "high" | "critical";
+/**
+ * Categories of friction. Any non-empty string is valid.
+ */
+export type FrictionCategory = string;
+/**
+ * Common friction categories. Not enforced -- any non-empty string is valid.
+ */
+export declare const COMMON_CATEGORIES: readonly ["search", "sync", "cli", "context", "integration", "ux"];
+/**
+ * Lifecycle status of a friction entry.
+ */
+export type FrictionStatus = "open" | "resolved" | "wont-fix";
+interface FrictionEntryParams {
+    id?: number | undefined;
+    description: string;
+    severity: FrictionSeverity;
+    category: FrictionCategory;
+    status: FrictionStatus;
+    tool: string;
+    tags?: string[] | undefined;
+    lastReviewedAt?: Date | undefined;
+    context?: string | undefined;
+    sourceProject?: string | undefined;
+    loggedAt: Date;
+    resolvedAt?: Date | undefined;
+    resolution?: string | undefined;
+}
+export declare class FrictionEntry {
+    private readonly _id?;
+    private readonly _description;
+    private readonly _severity;
+    private readonly _category;
+    private readonly _status;
+    private readonly _tool;
+    private readonly _tags?;
+    private readonly _lastReviewedAt?;
+    private readonly _context?;
+    private readonly _sourceProject?;
+    private readonly _loggedAt;
+    private readonly _resolvedAt?;
+    private readonly _resolution?;
+    private constructor();
+    /**
+     * Create a FrictionEntry entity.
+     * @throws Error if description is empty or whitespace-only
+     * @throws Error if severity is not a valid FrictionSeverity
+     * @throws Error if category is empty or whitespace-only
+     * @throws Error if status is not a valid FrictionStatus
+     * @throws Error if tool is empty or whitespace-only
+     * @throws Error if status is "open" but resolvedAt is provided
+     */
+    static create(params: FrictionEntryParams): FrictionEntry;
+    get id(): number | undefined;
+    get description(): string;
+    get severity(): FrictionSeverity;
+    get category(): FrictionCategory;
+    get status(): FrictionStatus;
+    get tool(): string;
+    get tags(): string[] | undefined;
+    get lastReviewedAt(): Date | undefined;
+    get context(): string | undefined;
+    get sourceProject(): string | undefined;
+    get loggedAt(): Date;
+    get resolvedAt(): Date | undefined;
+    get resolution(): string | undefined;
+}
+export {};

package/dist/domain/entities/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Domain Entities
+ *
+ * Core business objects with identity and lifecycle.
+ */
+export { Entity, type ExtractedEntityType, type ConceptMetadata, type FileMetadata, type DecisionMetadata, type TermMetadata, type EntityMetadata, } from "./entity.js";
+export { ExtractionState, type ExtractionStatus, } from "./extraction-state.js";
+export { Link, type EntityType, type LinkType } from "./link.js";
+export { Message, type MessageRole } from "./message.js";
+export { Session } from "./session.js";
+export { ToolUse, type ToolUseStatus } from "./tool-use.js";
+export { MemoryFile, type MemoryFileType } from "./memory-file.js";
+export { FrictionEntry, type FrictionSeverity, type FrictionCategory, type FrictionStatus, } from "./friction-entry.js";
+export { BackfillState } from "./backfill-state.js";
+export { Fact, type FactType, type FactParams, type CandidateFact } from "./fact.js";

package/dist/domain/entities/link.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Link Entity
+ *
+ * Represents a relationship between entities for graph-like traversal.
+ * Enables cross-session and cross-topic navigation in the memory database.
+ *
+ * Entity properties:
+ * - Has composite identity (source + target + relationship)
+ * - Immutable after construction
+ * - Supports weighted relationships for relevance scoring
+ */
+export type EntityType = "session" | "message" | "topic";
+export type LinkType = "mentions" | "related_to" | "continues";
+interface LinkParams {
+    sourceType: EntityType;
+    sourceId: string;
+    targetType: EntityType;
+    targetId: string;
+    relationship: LinkType;
+    weight?: number;
+}
+export declare class Link {
+    private readonly _sourceType;
+    private readonly _sourceId;
+    private readonly _targetType;
+    private readonly _targetId;
+    private readonly _relationship;
+    private readonly _weight;
+    private constructor();
+    /**
+     * Create a Link entity.
+     * @throws Error if IDs are empty, types are invalid, or weight is out of range
+     */
+    static create(params: LinkParams): Link;
+    /**
+     * Composite identifier for this link.
+     */
+    get id(): string;
+    /**
+     * The type of the source entity.
+     */
+    get sourceType(): EntityType;
+    /**
+     * The ID of the source entity.
+     */
+    get sourceId(): string;
+    /**
+     * The type of the target entity.
+     */
+    get targetType(): EntityType;
+    /**
+     * The ID of the target entity.
+     */
+    get targetId(): string;
+    /**
+     * The type of relationship between entities.
+     */
+    get relationship(): LinkType;
+    /**
+     * The weight/strength of this relationship (0-1).
+     */
+    get weight(): number;
+    /**
+     * Check equality with another Link (based on composite id).
+     */
+    equals(other: Link): boolean;
+    /**
+     * Create a new Link with an updated weight.
+     * Returns a new Link instance (immutability).
+     * @throws Error if weight is out of range
+     */
+    withWeight(weight: number): Link;
+}
+export {};

package/dist/domain/entities/memory-file.d.ts

@@ -0,0 +1,78 @@
+/**
+ * MemoryFile Entity
+ *
+ * Represents an indexed legacy markdown memory file.
+ * Memory files are agent-written markdown files (daily logs, decisions,
+ * learnings, user preferences) that persist knowledge across sessions.
+ *
+ * Entity properties:
+ * - Has identity (id when persisted)
+ * - Immutable after construction
+ * - Validated on creation via static create()
+ */
+/**
+ * The four types of memory files supported.
+ */
+export type MemoryFileType = "daily_log" | "decisions" | "learnings" | "user_prefs";
+interface MemoryFileParams {
+    id?: number | undefined;
+    filePath: string;
+    fileType: MemoryFileType;
+    projectEncoded?: string | undefined;
+    content: string;
+    contentHash: string;
+    lastIndexedAt: Date;
+    createdAt?: Date | undefined;
+}
+export declare class MemoryFile {
+    private readonly _id?;
+    private readonly _filePath;
+    private readonly _fileType;
+    private readonly _projectEncoded?;
+    private readonly _content;
+    private readonly _contentHash;
+    private readonly _lastIndexedAt;
+    private readonly _createdAt;
+    private constructor();
+    /**
+     * Create a MemoryFile entity.
+     * @throws Error if filePath is empty
+     * @throws Error if content is empty
+     * @throws Error if contentHash is not 64 lowercase hex characters
+     * @throws Error if fileType is not a valid MemoryFileType
+     */
+    static create(params: MemoryFileParams): MemoryFile;
+    /**
+     * The database identifier (undefined until persisted).
+     */
+    get id(): number | undefined;
+    /**
+     * Path relative to the legacy memory-file root (uses forward slashes).
+     */
+    get filePath(): string;
+    /**
+     * The classified file type.
+     */
+    get fileType(): MemoryFileType;
+    /**
+     * Encoded project path, or undefined for global files.
+     */
+    get projectEncoded(): string | undefined;
+    /**
+     * Full file content.
+     */
+    get content(): string;
+    /**
+     * SHA-256 hash of file content (lowercase hex).
+     */
+    get contentHash(): string;
+    /**
+     * When this file was last indexed by sync (defensive copy).
+     */
+    get lastIndexedAt(): Date;
+    /**
+     * When this entity was created (defensive copy).
+     */
+    get createdAt(): Date;
+}
+export {};

package/dist/domain/entities/message.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Message Entity
+ *
+ * Represents a single message in a Claude Code session.
+ * Can be from the user or assistant, and may contain tool use references.
+ *
+ * Entity properties:
+ * - Has unique identity (id)
+ * - Immutable after construction
+ * - Can reference ToolUse entities by ID
+ */
+export type MessageRole = "user" | "assistant";
+interface MessageParams {
+    id: string;
+    role: MessageRole;
+    content: string;
+    timestamp: Date;
+    toolUseIds?: string[] | undefined;
+}
+export declare class Message {
+    private readonly _id;
+    private readonly _role;
+    private readonly _content;
+    private readonly _timestamp;
+    private readonly _toolUseIds;
+    private constructor();
+    /**
+     * Create a Message entity.
+     * @throws Error if id is empty or role is invalid
+     */
+    static create(params: MessageParams): Message;
+    /**
+     * The unique message identifier.
+     */
+    get id(): string;
+    /**
+     * The message role (user or assistant).
+     */
+    get role(): MessageRole;
+    /**
+     * The message text content.
+     */
+    get content(): string;
+    /**
+     * When the message was created.
+     */
+    get timestamp(): Date;
+    /**
+     * IDs of tool uses associated with this message.
+     */
+    get toolUses(): string[];
+    /**
+     * Whether this message has text content.
+     */
+    get hasContent(): boolean;
+    /**
+     * Whether this message has any tool uses.
+     */
+    get hasToolUses(): boolean;
+    /**
+     * Check equality with another Message (based on id).
+     */
+    equals(other: Message): boolean;
+    /**
+     * Add a tool use reference to this message.
+     * Returns a new Message instance (immutability).
+     */
+    addToolUse(toolUseId: string): Message;
+}
+export {};