@deepagents/context 0.6.0 → 0.8.0

package/dist/lib/store/store.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Graph-based context store types and abstract interface.
+ *
+ * The storage model uses a DAG (Directed Acyclic Graph) for messages:
+ * - Messages are immutable nodes with parentId forming the graph
+ * - Branches are pointers to head (tip) messages
+ * - Checkpoints are pointers to specific messages
+ * - History is preserved through branching (rewind creates new branch)
+ */
+/**
+ * Data for creating/storing a chat.
+ */
+export interface ChatData {
+    id: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Information about a chat for listing.
+ */
+export interface ChatInfo {
+    id: string;
+    title?: string;
+    messageCount: number;
+    branchCount: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Data for creating/storing a message (graph node).
+ */
+export interface MessageData {
+    id: string;
+    chatId: string;
+    parentId: string | null;
+    name: string;
+    type?: string;
+    data: unknown;
+    persist: boolean;
+    createdAt: number;
+}
+/**
+ * Message with computed properties for listing.
+ */
+export interface MessageInfo extends MessageData {
+    hasChildren: boolean;
+}
+/**
+ * Data for creating/storing a branch.
+ * A branch is a pointer to a head message in the graph.
+ */
+export interface BranchData {
+    id: string;
+    chatId: string;
+    name: string;
+    headMessageId: string | null;
+    isActive: boolean;
+    createdAt: number;
+}
+/**
+ * Information about a branch for listing.
+ */
+export interface BranchInfo {
+    id: string;
+    name: string;
+    headMessageId: string | null;
+    isActive: boolean;
+    messageCount: number;
+    createdAt: number;
+}
+/**
+ * Data for creating/storing a checkpoint.
+ * A checkpoint is a pointer to a specific message in the graph.
+ */
+export interface CheckpointData {
+    id: string;
+    chatId: string;
+    name: string;
+    messageId: string;
+    createdAt: number;
+}
+/**
+ * Information about a checkpoint for listing.
+ */
+export interface CheckpointInfo {
+    id: string;
+    name: string;
+    messageId: string;
+    createdAt: number;
+}
+/**
+ * Options for searching messages.
+ */
+export interface SearchOptions {
+    /** Only search in specific roles (e.g., ['user', 'assistant']) */
+    roles?: string[];
+    /** Maximum results to return (default: 20) */
+    limit?: number;
+}
+/**
+ * Search result with relevance ranking.
+ */
+export interface SearchResult {
+    /** The matched message */
+    message: MessageData;
+    /** BM25 relevance score (lower = more relevant) */
+    rank: number;
+    /** Highlighted snippet with matched terms */
+    snippet?: string;
+}
+/**
+ * A node in the visualization graph.
+ */
+export interface GraphNode {
+    id: string;
+    parentId: string | null;
+    role: string;
+    content: string;
+    createdAt: number;
+}
+/**
+ * A branch pointer for visualization.
+ */
+export interface GraphBranch {
+    name: string;
+    headMessageId: string | null;
+    isActive: boolean;
+}
+/**
+ * A checkpoint pointer for visualization.
+ */
+export interface GraphCheckpoint {
+    name: string;
+    messageId: string;
+}
+/**
+ * Complete graph data for visualization.
+ */
+export interface GraphData {
+    chatId: string;
+    nodes: GraphNode[];
+    branches: GraphBranch[];
+    checkpoints: GraphCheckpoint[];
+}
+/**
+ * Abstract base class for graph-based context storage.
+ *
+ * Implementations provide persistence for the message graph, branches,
+ * and checkpoints. The graph model enables:
+ * - Branching: rewind creates a new branch, original stays intact
+ * - Checkpoints: pointers to specific messages for easy restore
+ * - No data loss: soft delete only, all history preserved
+ */
+export declare abstract class ContextStore {
+    /**
+     * Create a new chat.
+     */
+    abstract createChat(chat: ChatData): Promise<void>;
+    /**
+     * Get a chat by ID.
+     */
+    abstract getChat(chatId: string): Promise<ChatData | undefined>;
+    /**
+     * Update chat metadata.
+     */
+    abstract updateChat(chatId: string, updates: Partial<Pick<ChatData, 'title' | 'metadata' | 'updatedAt'>>): Promise<void>;
+    /**
+     * List all chats, sorted by updatedAt descending.
+     */
+    abstract listChats(): Promise<ChatInfo[]>;
+    /**
+     * Add a message to the graph.
+     */
+    abstract addMessage(message: MessageData): Promise<void>;
+    /**
+     * Get a message by ID.
+     */
+    abstract getMessage(messageId: string): Promise<MessageData | undefined>;
+    /**
+     * Walk up the parent chain from a head message, returning messages in
+     * chronological order (root first).
+     */
+    abstract getMessageChain(headId: string): Promise<MessageData[]>;
+    /**
+     * Check if a message has children (is a fork point).
+     */
+    abstract hasChildren(messageId: string): Promise<boolean>;
+    /**
+     * Create a new branch.
+     */
+    abstract createBranch(branch: BranchData): Promise<void>;
+    /**
+     * Get a branch by chat ID and name.
+     */
+    abstract getBranch(chatId: string, name: string): Promise<BranchData | undefined>;
+    /**
+     * Get the active branch for a chat.
+     */
+    abstract getActiveBranch(chatId: string): Promise<BranchData | undefined>;
+    /**
+     * Set a branch as active (and deactivate others).
+     */
+    abstract setActiveBranch(chatId: string, branchId: string): Promise<void>;
+    /**
+     * Update a branch's head message.
+     */
+    abstract updateBranchHead(branchId: string, messageId: string | null): Promise<void>;
+    /**
+     * List all branches for a chat.
+     */
+    abstract listBranches(chatId: string): Promise<BranchInfo[]>;
+    /**
+     * Create a checkpoint.
+     */
+    abstract createCheckpoint(checkpoint: CheckpointData): Promise<void>;
+    /**
+     * Get a checkpoint by chat ID and name.
+     */
+    abstract getCheckpoint(chatId: string, name: string): Promise<CheckpointData | undefined>;
+    /**
+     * List all checkpoints for a chat.
+     */
+    abstract listCheckpoints(chatId: string): Promise<CheckpointInfo[]>;
+    /**
+     * Delete a checkpoint.
+     */
+    abstract deleteCheckpoint(chatId: string, name: string): Promise<void>;
+    /**
+     * Search messages using full-text search.
+     *
+     * @param chatId - The chat to search in
+     * @param query - FTS5 query string (supports AND, OR, NOT, phrases, prefix*)
+     * @param options - Search options
+     * @returns Search results ordered by relevance (lower rank = more relevant)
+     */
+    abstract searchMessages(chatId: string, query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Get the complete graph data for a chat.
+     * Returns all messages, branches, and checkpoints.
+     */
+    abstract getGraph(chatId: string): Promise<GraphData>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/lib/store/store.d.ts.map

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

package/dist/lib/visualize.d.ts

@@ -0,0 +1,15 @@
+import type { GraphData } from './store/store.ts';
+/**
+ * Render a graph as ASCII art.
+ *
+ * @param data - The graph data to visualize
+ * @returns ASCII art representation of the graph
+ *
+ * @example
+ * ```ts
+ * const graph = await store.getGraph('my-chat');
+ * console.log(visualizeGraph(graph));
+ * ```
+ */
+export declare function visualizeGraph(data: GraphData): string;
+//# sourceMappingURL=visualize.d.ts.map

package/dist/lib/visualize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualize.d.ts","sourceRoot":"","sources":["../../src/lib/visualize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAgFtD"}

package/dist/usage.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepagents/context",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "MIT",
   "repository": {
     "type": "git",