causantic 0.2.0

package/dist/storage/types.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Types for the storage layer.
+ *
+ * The storage layer provides persistence for the Causantic system.
+ * Key data structures include:
+ * - **Chunks**: Segments of conversation with metadata and vector clocks
+ * - **Edges**: Weighted directional connections between chunks
+ * - **Clusters**: Topic groupings of chunks (via HDBSCAN)
+ * - **Vector clocks**: For causality tracking and decay computation
+ *
+ * @module storage/types
+ */
+import type { VectorClock } from '../temporal/vector-clock.js';
+/**
+ * Edge direction for graph traversal.
+ *
+ * The memory graph maintains bidirectional edges between chunks:
+ * - `backward`: Points from later → earlier chunks (used for recall)
+ * - `forward`: Points from earlier → later chunks (used for prediction)
+ *
+ * Each transition creates both a backward and forward edge.
+ */
+export type EdgeType = 'backward' | 'forward';
+/**
+ * Reference types for edges.
+ *
+ * Indicates the evidence used to create the edge. Higher-evidence types
+ * receive higher initial weights:
+ *
+ * | Type | Weight | Description |
+ * |------|--------|-------------|
+ * | `file-path` | 1.0 | Shared file path reference |
+ * | `explicit-backref` | 0.9 | Explicit "the error", "that function" |
+ * | `error-fragment` | 0.9 | Discussing specific error message |
+ * | `brief` | 0.9 | Parent spawning sub-agent |
+ * | `debrief` | 0.9 | Sub-agent returning to parent |
+ * | `code-entity` | 0.8 | Shared function/class/variable name |
+ * | `tool-output` | 0.8 | Referencing tool results |
+ * | `cross-session` | 0.7 | Session continuation |
+ * | `adjacent` | 0.5 | Consecutive chunks (weak link) |
+ */
+export type ReferenceType = 'file-path' | 'code-entity' | 'explicit-backref' | 'error-fragment' | 'tool-output' | 'adjacent' | 'cross-session' | 'brief' | 'debrief';
+/**
+ * A chunk stored in the database.
+ *
+ * Chunks are the fundamental unit of storage, representing segments of
+ * conversation. Each chunk contains one or more turns and is assigned
+ * a vector clock for causality tracking.
+ */
+export interface StoredChunk {
+    /** Unique identifier (UUID format) */
+    id: string;
+    /** Claude session ID this chunk belongs to */
+    sessionId: string;
+    /** Project slug (folder name) for grouping sessions */
+    sessionSlug: string;
+    /** Turn indices included in this chunk (0-based) */
+    turnIndices: number[];
+    /** ISO timestamp of first message in chunk */
+    startTime: string;
+    /** ISO timestamp of last message in chunk */
+    endTime: string;
+    /** Rendered text content of the chunk */
+    content: string;
+    /** Number of code blocks (```...```) in content */
+    codeBlockCount: number;
+    /** Number of tool use blocks in content */
+    toolUseCount: number;
+    /** Approximate token count for budget calculation */
+    approxTokens: number;
+    /** ISO timestamp when chunk was stored */
+    createdAt: string;
+    /** Agent ID for sub-agent chunks, 'ui' for main session */
+    agentId: string | null;
+    /** Vector clock at time of chunk creation (for decay) */
+    vectorClock: VectorClock | null;
+    /** Nesting depth: 0=main, 1=sub-agent, 2=nested sub-agent */
+    spawnDepth: number;
+    /** Full cwd path for project disambiguation (optional) */
+    projectPath: string | null;
+}
+/**
+ * Input for creating a new chunk.
+ *
+ * Used when ingesting sessions. The `id` should be pre-generated to allow
+ * correlation with edge creation before database insertion.
+ */
+export interface ChunkInput {
+    /** Unique identifier (pre-generated UUID) */
+    id: string;
+    /** Claude session ID */
+    sessionId: string;
+    /** Project slug */
+    sessionSlug: string;
+    /** Turn indices included */
+    turnIndices: number[];
+    /** ISO start timestamp */
+    startTime: string;
+    /** ISO end timestamp */
+    endTime: string;
+    /** Rendered text content */
+    content: string;
+    /** Code block count */
+    codeBlockCount: number;
+    /** Tool use count */
+    toolUseCount: number;
+    /** Approximate tokens */
+    approxTokens: number;
+    /** Agent ID (optional, defaults to 'ui') */
+    agentId?: string;
+    /** Vector clock (optional, enables clock-based decay) */
+    vectorClock?: VectorClock;
+    /** Spawn depth (optional, defaults to 0) */
+    spawnDepth?: number;
+    /** Full cwd path for project disambiguation */
+    projectPath?: string;
+}
+/**
+ * An edge stored in the database.
+ *
+ * Edges represent causal connections between chunks. They have:
+ * - An `initialWeight` set at creation based on reference type
+ * - A `vectorClock` for computing time-based decay
+ * - A `linkCount` that increases when the same edge is created multiple times
+ */
+export interface StoredEdge {
+    /** Unique identifier (UUID format) */
+    id: string;
+    /** Source chunk ID (where edge originates) */
+    sourceChunkId: string;
+    /** Target chunk ID (where edge points) */
+    targetChunkId: string;
+    /** Direction: backward (recall) or forward (predict) */
+    edgeType: EdgeType;
+    /** Type of evidence for this connection */
+    referenceType: ReferenceType | null;
+    /** Weight at creation time (0-1), before decay */
+    initialWeight: number;
+    /** ISO timestamp when edge was created */
+    createdAt: string;
+    /** JSON-serialized vector clock for decay computation */
+    vectorClock: string | null;
+    /** Times this edge was created (boosted on duplicate) */
+    linkCount: number;
+}
+/**
+ * Input for creating a new edge.
+ *
+ * When creating edges, you specify source, target, and type. The system
+ * generates an ID and sets createdAt. Use `createOrBoostEdges()` to
+ * increment linkCount if the same edge already exists.
+ */
+export interface EdgeInput {
+    /** Source chunk ID */
+    sourceChunkId: string;
+    /** Target chunk ID */
+    targetChunkId: string;
+    /** Direction: backward or forward */
+    edgeType: EdgeType;
+    /** Reference type for initial weight calculation */
+    referenceType?: ReferenceType;
+    /** Explicit weight (overrides type-based default) */
+    initialWeight: number;
+    /** Vector clock for decay computation */
+    vectorClock?: VectorClock;
+}
+/**
+ * An edge with its computed weight at query time.
+ *
+ * During traversal, edge weights are computed by applying decay based on
+ * the reference clock. The effective weight determines traversal priority.
+ *
+ * Weight formula: `initialWeight × hopDecay × timeDecay`
+ */
+export interface WeightedEdge extends StoredEdge {
+    /** Computed weight after decay (0-1) */
+    weight: number;
+}
+/**
+ * A topic cluster stored in the database.
+ *
+ * Clusters group semantically related chunks. Created by HDBSCAN clustering
+ * on chunk embeddings. Each cluster has:
+ * - A centroid vector (mean of member embeddings)
+ * - Exemplar IDs (chunks closest to centroid)
+ * - A membership hash for detecting when reclustering is needed
+ */
+export interface StoredCluster {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable name (optional) */
+    name: string | null;
+    /** Description of cluster contents (optional) */
+    description: string | null;
+    /** Centroid vector (normalized mean of embeddings) */
+    centroid: number[] | null;
+    /** IDs of exemplar chunks (closest to centroid) */
+    exemplarIds: string[];
+    /** Hash of sorted member IDs (for change detection) */
+    membershipHash: string | null;
+    /** ISO timestamp when cluster was created */
+    createdAt: string;
+    /** ISO timestamp when cluster was last updated */
+    refreshedAt: string | null;
+}
+/**
+ * Input for creating or updating a cluster.
+ *
+ * All fields are optional for partial updates. Provide `id` to update
+ * an existing cluster; omit to create a new one.
+ */
+export interface ClusterInput {
+    /** ID for update, or undefined for create */
+    id?: string;
+    /** Human-readable name */
+    name?: string;
+    /** Description */
+    description?: string;
+    /** Centroid vector */
+    centroid?: number[];
+    /** Exemplar chunk IDs */
+    exemplarIds?: string[];
+    /** Membership hash */
+    membershipHash?: string;
+}
+/**
+ * Assignment of a chunk to a cluster.
+ *
+ * A chunk can belong to multiple clusters (soft clustering). The distance
+ * indicates how well the chunk fits the cluster (lower = better fit).
+ */
+export interface ChunkClusterAssignment {
+    /** Chunk being assigned */
+    chunkId: string;
+    /** Cluster to assign to */
+    clusterId: string;
+    /** Angular distance from chunk to cluster centroid (0-2) */
+    distance: number;
+}
+/**
+ * A chunk with its accumulated weight from traversal.
+ *
+ * During graph traversal, chunks accumulate weight from all paths that
+ * reach them (sum rule). The depth is the minimum hop count across paths.
+ */
+export interface WeightedChunk {
+    /** Chunk identifier */
+    chunkId: string;
+    /** Accumulated weight from all paths (sum rule) */
+    weight: number;
+    /** Minimum depth across all paths reaching this chunk */
+    depth: number;
+}
+/**
+ * Result of a graph traversal operation.
+ *
+ * Contains weighted chunks sorted by weight descending, plus statistics
+ * about the traversal for debugging/monitoring.
+ */
+export interface TraversalResult {
+    /** Chunks reached, sorted by weight descending */
+    chunks: WeightedChunk[];
+    /** Number of path segments explored */
+    visited: number;
+}
+/**
+ * Result from vector similarity search.
+ *
+ * Vector search returns chunks sorted by angular distance to the query.
+ * Lower distance = higher similarity.
+ */
+export interface VectorSearchResult {
+    /** Chunk ID */
+    id: string;
+    /** Angular distance (0 = identical, 2 = opposite) */
+    distance: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

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

package/dist/storage/types.js

@@ -0,0 +1,14 @@
+/**
+ * Types for the storage layer.
+ *
+ * The storage layer provides persistence for the Causantic system.
+ * Key data structures include:
+ * - **Chunks**: Segments of conversation with metadata and vector clocks
+ * - **Edges**: Weighted directional connections between chunks
+ * - **Clusters**: Topic groupings of chunks (via HDBSCAN)
+ * - **Vector clocks**: For causality tracking and decay computation
+ *
+ * @module storage/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/storage/vector-store.d.ts

@@ -0,0 +1,213 @@
+/**
+ * In-memory vector store with SQLite persistence.
+ *
+ * Provides vector similarity search for chunk embeddings using angular distance.
+ * Embeddings are stored as Float32Array blobs in SQLite and loaded into memory
+ * on first access for fast brute-force search.
+ *
+ * ## Architecture
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │                     VectorStore                             │
+ * │  ┌─────────────────────┐    ┌─────────────────────────────┐ │
+ * │  │  In-Memory Index    │    │    SQLite Persistence       │ │
+ * │  │  Map<id, number[]>  │ ◄──┤  vectors (id, embedding,    │ │
+ * │  └─────────────────────┘    │           last_accessed)    │ │
+ * │                             └─────────────────────────────┘ │
+ * └─────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## TTL (Time To Live)
+ *
+ * Vectors have a `last_accessed` timestamp that is updated when they are
+ * returned from search. Vectors that haven't been accessed within the TTL
+ * period can be cleaned up by the maintenance task.
+ *
+ * This allows vectors to persist for semantic search even after their
+ * associated chunks are pruned from the causal graph, while still eventually
+ * cleaning up truly stale vectors.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { vectorStore } from './vector-store.js';
+ *
+ * // Insert an embedding
+ * await vectorStore.insert('chunk-123', embedding);
+ *
+ * // Search for similar vectors
+ * const results = await vectorStore.search(queryEmbedding, 10);
+ * // Returns: [{ id: 'chunk-456', distance: 0.15 }, ...]
+ * // (also updates last_accessed for returned vectors)
+ * ```
+ *
+ * ## Distance Metric
+ *
+ * Uses angular distance (0 = identical, 2 = opposite):
+ * - `0.0`: Identical vectors
+ * - `0.5`: ~60° angle
+ * - `1.0`: Orthogonal (90°)
+ * - `2.0`: Opposite vectors
+ *
+ * ## Performance Notes
+ *
+ * - Initial load: O(n) to deserialize all vectors from SQLite
+ * - Insert: O(1) amortized (memory + single row insert)
+ * - Search: O(n) brute-force (sufficient for <100k vectors)
+ * - Memory: ~4KB per vector (1024 dimensions × 4 bytes)
+ *
+ * For larger scale, consider upgrading to LanceDB or FAISS.
+ *
+ * @module storage/vector-store
+ */
+import type { VectorSearchResult } from './types.js';
+/**
+ * In-memory vector index backed by SQLite for persistence.
+ *
+ * Uses lazy loading — vectors are loaded from SQLite on first operation.
+ * All operations are async to support future migration to async storage backends.
+ *
+ * Thread safety: Single-threaded (Node.js). For concurrent access, use
+ * the singleton `vectorStore` export which ensures consistent state.
+ */
+export declare class VectorStore {
+    private vectors;
+    private loaded;
+    /** chunkId → projectSlug index for project-filtered search */
+    private chunkProjectIndex;
+    /**
+     * Load vectors from database into memory.
+     */
+    load(): Promise<void>;
+    /**
+     * Insert a vector.
+     */
+    insert(id: string, embedding: number[]): Promise<void>;
+    /**
+     * Insert multiple vectors in a transaction.
+     */
+    insertBatch(items: Array<{
+        id: string;
+        embedding: number[];
+    }>): Promise<void>;
+    /**
+     * Get a vector by ID.
+     */
+    get(id: string): Promise<number[] | null>;
+    /**
+     * Search for similar vectors using angular distance.
+     *
+     * Uses brute-force search over all vectors in memory. For small to medium
+     * datasets (<100k vectors), this is fast enough. For larger datasets,
+     * consider approximate nearest neighbor (ANN) algorithms.
+     *
+     * Also updates `last_accessed` timestamp for returned vectors, keeping
+     * them alive for TTL purposes.
+     *
+     * @param query - Query embedding vector (must match stored dimensionality)
+     * @param limit - Maximum number of results to return
+     * @returns Results sorted by distance ascending (closest first)
+     *
+     * @example
+     * ```typescript
+     * const results = await vectorStore.search(queryEmbedding, 10);
+     * for (const { id, distance } of results) {
+     *   console.log(`${id}: distance=${distance.toFixed(3)}`);
+     * }
+     * ```
+     */
+    search(query: number[], limit: number): Promise<VectorSearchResult[]>;
+    /**
+     * Search within a subset of IDs.
+     * Also updates last_accessed for returned vectors.
+     */
+    searchWithinIds(query: number[], candidateIds: string[], limit: number): Promise<VectorSearchResult[]>;
+    /**
+     * Search for similar vectors filtered to specific project(s).
+     *
+     * Skips vectors not belonging to the specified project(s) during
+     * distance computation (more efficient than post-filtering).
+     *
+     * @param query - Query embedding vector
+     * @param projects - Single project slug or array of project slugs
+     * @param limit - Maximum results
+     * @returns Results sorted by distance ascending
+     */
+    searchByProject(query: number[], projects: string | string[], limit: number): Promise<VectorSearchResult[]>;
+    /**
+     * Get the project slug for a chunk ID.
+     */
+    getChunkProject(id: string): string | undefined;
+    /**
+     * Delete a vector.
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Delete multiple vectors.
+     */
+    deleteBatch(ids: string[]): Promise<number>;
+    /**
+     * Get vector count.
+     */
+    count(): Promise<number>;
+    /**
+     * Check if a vector exists.
+     */
+    has(id: string): Promise<boolean>;
+    /**
+     * Clear all vectors (for testing).
+     */
+    clear(): Promise<void>;
+    /**
+     * Get all vector IDs.
+     */
+    getAllIds(): Promise<string[]>;
+    /**
+     * Get all vectors as an array (for clustering).
+     */
+    getAllVectors(): Promise<Array<{
+        id: string;
+        embedding: number[];
+    }>>;
+    /**
+     * Reset loaded state (for testing).
+     */
+    reset(): void;
+    /**
+     * Update last_accessed timestamp for vectors.
+     * Called when vectors are returned from search to keep them alive.
+     */
+    private touchLastAccessed;
+    /**
+     * Mark a vector as orphaned (its associated chunk was deleted).
+     * The vector will be subject to TTL cleanup after this.
+     * Called by pruner when deleting orphaned chunks.
+     */
+    markOrphaned(id: string): Promise<void>;
+    /**
+     * Mark multiple vectors as orphaned.
+     */
+    markOrphanedBatch(ids: string[]): Promise<void>;
+    /**
+     * Clean up expired orphaned vectors and their corresponding chunks.
+     * Removes vectors that are orphaned AND haven't been accessed within the TTL period.
+     * Also deletes the corresponding chunks (FK cascades handle cluster assignments and edges).
+     *
+     * @param ttlDays - Number of days after which orphaned vectors expire
+     * @returns Number of vectors deleted
+     */
+    cleanupExpired(ttlDays: number): Promise<number>;
+    /**
+     * Get count of orphaned vectors.
+     */
+    getOrphanedCount(): Promise<number>;
+}
+/**
+ * Singleton vector store instance.
+ *
+ * Use this for all vector operations to ensure consistent state.
+ * The instance lazy-loads vectors from SQLite on first operation.
+ */
+export declare const vectorStore: VectorStore;
+//# sourceMappingURL=vector-store.d.ts.map

package/dist/storage/vector-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../src/storage/vector-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAMrD;;;;;;;;GAQG;AAEH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,MAAM,CAAS;IACvB,8DAA8D;IAC9D,OAAO,CAAC,iBAAiB,CAAkC;IAE3D;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsD3B;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5D;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCnF;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;IAK/C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAsB3E;;;OAGG;IACG,eAAe,CACnB,KAAK,EAAE,MAAM,EAAE,EACf,YAAY,EAAE,MAAM,EAAE,EACtB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAuBhC;;;;;;;;;;OAUG;IACG,eAAe,CACnB,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAC3B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAwBhC;;OAEG;IACH,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI/C;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAU1C;;OAEG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBjD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKvC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAKpC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAQ1E;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;;OAIG;IACG,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7C;;OAEG;IACG,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWrD;;;;;;;OAOG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA4CtD;;OAEG;IACG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;CAU1C;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,aAAoB,CAAC"}