mindcache 3.4.3 → 3.5.0

package/README.md

@@ -0,0 +1,22 @@
+# MindCache
+
+A TypeScript library for managing short-term memory in AI agents through an LLM-friendly key-value repository.
+
+## Documentation
+
+*   **[API Reference](./docs/mindcache-api.md)**: Detailed method signatures and type definitions. Optimized for AI agents (like Cursor, Claude, etc.) to understand the library's capabilities.
+*   **[Full Documentation](https://mindcache.dev/llms-full.md)**: Comprehensive guide with examples and deep dives.
+
+## Quick Start
+
+```typescript
+import { mindcache } from 'mindcache';
+
+// Store values
+mindcache.set_value('userName', 'Alice');
+
+// Generate tools for Vercel AI SDK
+const tools = mindcache.get_aisdk_tools();
+```
+
+See the [root README](../../README.md) for more details.

package/dist/{CloudAdapter-CJS3Sh4f.d.mts → CloudAdapter-CM7nyJaG.d.mts}

@@ -3,18 +3,30 @@ import * as Y from 'yjs';
 /**
  * Access level for MindCache operations
  * - 'user': Can only manage content tags (default)
- * - 'system': Can manage both content tags and system tags
+ * - 'admin': Can manage both content tags and system tags
  */
-type AccessLevel = 'user' | 'system';
+type AccessLevel = 'user' | 'admin';
+/**
+ * Context rules for filtering keys by contentTags.
+ * When context is set, only keys matching ALL specified tags are visible.
+ * Context is client-local and not persisted.
+ */
+interface ContextRules {
+    /** Tags that a key must have (AND logic - all tags must match) */
+    tags: string[];
+    /** Default contentTags added to keys created via create_key() in this context */
+    defaultContentTags?: string[];
+    /** Default systemTags added to keys created via create_key() in this context */
+    defaultSystemTags?: SystemTag[];
+}
 /**
  * Known system tags that control key behavior
  * - 'SystemPrompt': Include in system prompt (visible to LLM context)
  * - 'LLMRead': LLM can read this key via tools
  * - 'LLMWrite': LLM can write to this key via tools
- * - 'protected': Cannot be deleted
  * - 'ApplyTemplate': Process value through template injection
  */
-type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'protected' | 'ApplyTemplate';
+type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'ApplyTemplate';
 /**
  * Type of value stored in a MindCache key
  */
@@ -91,8 +103,6 @@ declare const SystemTagHelpers: {
     isLLMReadable: (attrs: KeyAttributes) => boolean;
     /** Check if key is included in system prompt */
     isInSystemPrompt: (attrs: KeyAttributes) => boolean;
-    /** Check if key is protected from deletion */
-    isProtected: (attrs: KeyAttributes) => boolean;
     /** Check if key uses template injection */
     hasTemplateInjection: (attrs: KeyAttributes) => boolean;
 };
@@ -101,8 +111,8 @@ declare const SystemTagHelpers: {
  * Cloud configuration options for MindCache constructor
  */
 interface MindCacheCloudOptions {
-    /** Instance ID to connect to */
-    instanceId: string;
+    /** Instance ID to connect to (not needed for OAuth - auto-provisioned) */
+    instanceId?: string;
     /** Project ID (optional, defaults to 'default') */
     projectId?: string;
     /** API endpoint to fetch WS token (recommended for browser) */
@@ -113,6 +123,20 @@ interface MindCacheCloudOptions {
     apiKey?: string;
     /** WebSocket base URL (defaults to production) */
     baseUrl?: string;
+    /**
+     * OAuth configuration for browser apps using "Sign in with MindCache"
+     * When set, user authentication and instance provisioning is automatic
+     */
+    oauth?: {
+        /** Client ID from MindCache developer portal */
+        clientId: string;
+        /** Redirect URI for OAuth callback (defaults to current URL) */
+        redirectUri?: string;
+        /** Scopes to request (default: ['read', 'write']) */
+        scopes?: string[];
+        /** Auto-redirect to login if not authenticated (default: false) */
+        autoLogin?: boolean;
+    };
 }
 interface MindCacheIndexedDBOptions {
     /** Database name (defaults to 'mindcache_db') */
@@ -134,24 +158,27 @@ interface MindCacheOptions {
     indexedDB?: MindCacheIndexedDBOptions;
     /** History tracking options (enabled in IndexedDB and Cloud modes) */
     history?: HistoryOptions;
-    /** Access level for tag operations. 'system' allows managing system tags. */
+    /** Access level for tag operations. 'admin' allows managing system tags. */
     accessLevel?: AccessLevel;
     /** Optional existing Y.Doc instance (for server-side hydration) */
     doc?: Y.Doc;
+    /** Context filtering rules. When set, only keys matching the rules are visible. */
+    context?: ContextRules;
 }
 type ConnectionState$1 = 'disconnected' | 'connecting' | 'connected' | 'error';
 declare class MindCache {
     doc: Y.Doc;
-    private rootMap;
+    rootMap: Y.Map<Y.Map<any>>;
     private listeners;
     private globalListeners;
     readonly version = "3.3.2";
-    private normalizeSystemTags;
+    normalizeSystemTags(tags: SystemTag[]): SystemTag[];
     private _cloudAdapter;
     private _connectionState;
     private _isLoaded;
     private _cloudConfig;
     private _accessLevel;
+    private _contextRules;
     private _initPromise;
     private _idbProvider;
     private _undoManagers;
@@ -206,6 +233,36 @@ declare class MindCache {
     restoreToVersion(_versionId: string): boolean;
     get accessLevel(): AccessLevel;
     get hasSystemAccess(): boolean;
+    /**
+     * Check if context filtering is currently active.
+     */
+    get hasContext(): boolean;
+    /**
+     * Get current context rules, or null if no context is set.
+     */
+    get_context(): ContextRules | null;
+    /**
+     * Set context filtering rules.
+     * When context is set, only keys with ALL specified tags are visible.
+     *
+     * @param rules - Context rules, or array of tags (shorthand for { tags: [...] })
+     */
+    set_context(rules: ContextRules | string[]): void;
+    /**
+     * Clear context filtering. All keys become visible again.
+     */
+    reset_context(): void;
+    /**
+     * Check if a key matches the current context rules.
+     * Returns true if no context is set.
+     */
+    keyMatchesContext(key: string): boolean;
+    /**
+     * Create a new key with optional default tags from context.
+     *
+     * @throws Error if key already exists
+     */
+    create_key(key: string, value: any, attributes?: Partial<KeyAttributes>): void;
     private _initCloud;
     private _initYIndexedDB;
     private _initIndexedDB;
@@ -245,8 +302,9 @@ declare class MindCache {
     /**
      * Update only the attributes of a key without modifying the value.
      * Useful for updating tags, permissions etc. on document type keys.
+     * @returns true if attributes were updated, false if key doesn't exist or is protected
      */
-    set_attributes(key: string, attributes: Partial<KeyAttributes>): void;
+    set_attributes(key: string, attributes: Partial<KeyAttributes>): boolean;
     set_value(key: string, value: any, attributes?: Partial<KeyAttributes>): void;
     /**
      * LLM-safe method to write a value to a key.
@@ -283,15 +341,15 @@ declare class MindCache {
      */
     size(): number;
     /**
-     * Get all keys in MindCache (including temporal keys).
+     * Get all keys in MindCache.
      */
     keys(): string[];
     /**
-     * Get all values in MindCache (including temporal values).
+     * Get all values in MindCache.
      */
     values(): any[];
     /**
-     * Get all key-value entries (including temporal entries).
+     * Get all key-value entries.
      */
     entries(): Array<[string, any]>;
     /**
@@ -306,7 +364,6 @@ declare class MindCache {
     getSTM(): string;
     /**
      * Get the STM as an object with values directly (no attributes).
-     * Includes system keys ($date, $time).
      * @deprecated Use getAll() for full STM format
      */
     getSTMObject(): Record<string, any>;
@@ -342,7 +399,7 @@ declare class MindCache {
     getKeysByTag(tag: string): string[];
     /**
      * Add a system tag to a key (requires system access).
-     * System tags: 'SystemPrompt', 'LLMRead', 'LLMWrite', 'readonly', 'protected', 'ApplyTemplate'
+     * System tags: 'SystemPrompt', 'LLMRead', 'LLMWrite', 'ApplyTemplate'
      */
     systemAddTag(key: string, tag: SystemTag): boolean;
     /**
@@ -367,8 +424,9 @@ declare class MindCache {
     systemGetKeysByTag(tag: SystemTag): string[];
     /**
      * Helper to get sorted keys (by zIndex).
+     * Respects context filtering when set.
      */
-    private getSortedKeys;
+    getSortedKeys(): string[];
     /**
      * Serialize to JSON string.
      */
@@ -383,8 +441,10 @@ declare class MindCache {
     toMarkdown(): string;
     /**
      * Import from Markdown format.
+     * @param markdown The markdown string to import
+     * @param merge If false (default), clears existing data before importing. If true, merges with existing data.
      */
-    fromMarkdown(markdown: string): void;
+    fromMarkdown(markdown: string, merge?: boolean): void;
     /**
      * Set base64 binary data.
      */
@@ -426,17 +486,17 @@ declare class MindCache {
      */
     delete_text(key: string, index: number, length: number): void;
     /**
-     * Replace all text in a document key (private - use set_value for public API).
+     * Replace all text in a document key.
      * Uses diff-based updates when changes are < diffThreshold (default 80%).
      * This preserves concurrent edits and provides better undo granularity.
      */
-    private _replaceDocumentText;
+    _replaceDocumentText(key: string, newText: string, diffThreshold?: number): void;
     subscribe(key: string, listener: Listener): () => void;
     subscribeToAll(listener: GlobalListener): () => void;
     unsubscribeFromAll(listener: GlobalListener): void;
-    private notifyGlobalListeners;
-    private sanitizeKeyForTool;
-    private findKeyFromSanitizedTool;
+    notifyGlobalListeners(): void;
+    sanitizeKeyForTool(key: string): string;
+    findKeyFromSanitizedTool(sanitizedKey: string): string | undefined;
     /**
      * Generate Vercel AI SDK compatible tools for writable keys.
      * For document type keys, generates additional tools: append_, insert_, edit_
@@ -552,4 +612,4 @@ declare class CloudAdapter {
     private scheduleReconnect;
 }
 
-export { type AccessLevel as A, type CloudConfig as C, type DeleteOperation as D, type GlobalListener as G, type HistoryEntry as H, type KeyAttributes as K, type Listener as L, MindCache as M, type Operation as O, type SetOperation as S, CloudAdapter as a, type ConnectionState as b, type CloudAdapterEvents as c, type ClearOperation as d, type MindCacheOptions as e, type KeyType as f, type SystemTag as g, type STM as h, type STMEntry as i, type HistoryOptions as j, type MindCacheCloudOptions as k, type MindCacheIndexedDBOptions as l, DEFAULT_KEY_ATTRIBUTES as m, SystemTagHelpers as n };
+export { type AccessLevel as A, type CloudConfig as C, type DeleteOperation as D, type GlobalListener as G, type HistoryEntry as H, type KeyAttributes as K, type Listener as L, MindCache as M, type Operation as O, type SetOperation as S, CloudAdapter as a, type ConnectionState as b, type CloudAdapterEvents as c, type ClearOperation as d, type MindCacheOptions as e, type KeyType as f, type SystemTag as g, type ContextRules as h, type STM as i, type STMEntry as j, type HistoryOptions as k, type MindCacheCloudOptions as l, type MindCacheIndexedDBOptions as m, DEFAULT_KEY_ATTRIBUTES as n, SystemTagHelpers as o };

package/dist/{CloudAdapter-CJS3Sh4f.d.ts → CloudAdapter-CM7nyJaG.d.ts}

@@ -3,18 +3,30 @@ import * as Y from 'yjs';
 /**
  * Access level for MindCache operations
  * - 'user': Can only manage content tags (default)
- * - 'system': Can manage both content tags and system tags
+ * - 'admin': Can manage both content tags and system tags
  */
-type AccessLevel = 'user' | 'system';
+type AccessLevel = 'user' | 'admin';
+/**
+ * Context rules for filtering keys by contentTags.
+ * When context is set, only keys matching ALL specified tags are visible.
+ * Context is client-local and not persisted.
+ */
+interface ContextRules {
+    /** Tags that a key must have (AND logic - all tags must match) */
+    tags: string[];
+    /** Default contentTags added to keys created via create_key() in this context */
+    defaultContentTags?: string[];
+    /** Default systemTags added to keys created via create_key() in this context */
+    defaultSystemTags?: SystemTag[];
+}
 /**
  * Known system tags that control key behavior
  * - 'SystemPrompt': Include in system prompt (visible to LLM context)
  * - 'LLMRead': LLM can read this key via tools
  * - 'LLMWrite': LLM can write to this key via tools
- * - 'protected': Cannot be deleted
  * - 'ApplyTemplate': Process value through template injection
  */
-type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'protected' | 'ApplyTemplate';
+type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'ApplyTemplate';
 /**
  * Type of value stored in a MindCache key
  */
@@ -91,8 +103,6 @@ declare const SystemTagHelpers: {
     isLLMReadable: (attrs: KeyAttributes) => boolean;
     /** Check if key is included in system prompt */
     isInSystemPrompt: (attrs: KeyAttributes) => boolean;
-    /** Check if key is protected from deletion */
-    isProtected: (attrs: KeyAttributes) => boolean;
     /** Check if key uses template injection */
     hasTemplateInjection: (attrs: KeyAttributes) => boolean;
 };
@@ -101,8 +111,8 @@ declare const SystemTagHelpers: {
  * Cloud configuration options for MindCache constructor
  */
 interface MindCacheCloudOptions {
-    /** Instance ID to connect to */
-    instanceId: string;
+    /** Instance ID to connect to (not needed for OAuth - auto-provisioned) */
+    instanceId?: string;
     /** Project ID (optional, defaults to 'default') */
     projectId?: string;
     /** API endpoint to fetch WS token (recommended for browser) */
@@ -113,6 +123,20 @@ interface MindCacheCloudOptions {
     apiKey?: string;
     /** WebSocket base URL (defaults to production) */
     baseUrl?: string;
+    /**
+     * OAuth configuration for browser apps using "Sign in with MindCache"
+     * When set, user authentication and instance provisioning is automatic
+     */
+    oauth?: {
+        /** Client ID from MindCache developer portal */
+        clientId: string;
+        /** Redirect URI for OAuth callback (defaults to current URL) */
+        redirectUri?: string;
+        /** Scopes to request (default: ['read', 'write']) */
+        scopes?: string[];
+        /** Auto-redirect to login if not authenticated (default: false) */
+        autoLogin?: boolean;
+    };
 }
 interface MindCacheIndexedDBOptions {
     /** Database name (defaults to 'mindcache_db') */
@@ -134,24 +158,27 @@ interface MindCacheOptions {
     indexedDB?: MindCacheIndexedDBOptions;
     /** History tracking options (enabled in IndexedDB and Cloud modes) */
     history?: HistoryOptions;
-    /** Access level for tag operations. 'system' allows managing system tags. */
+    /** Access level for tag operations. 'admin' allows managing system tags. */
     accessLevel?: AccessLevel;
     /** Optional existing Y.Doc instance (for server-side hydration) */
     doc?: Y.Doc;
+    /** Context filtering rules. When set, only keys matching the rules are visible. */
+    context?: ContextRules;
 }
 type ConnectionState$1 = 'disconnected' | 'connecting' | 'connected' | 'error';
 declare class MindCache {
     doc: Y.Doc;
-    private rootMap;
+    rootMap: Y.Map<Y.Map<any>>;
     private listeners;
     private globalListeners;
     readonly version = "3.3.2";
-    private normalizeSystemTags;
+    normalizeSystemTags(tags: SystemTag[]): SystemTag[];
     private _cloudAdapter;
     private _connectionState;
     private _isLoaded;
     private _cloudConfig;
     private _accessLevel;
+    private _contextRules;
     private _initPromise;
     private _idbProvider;
     private _undoManagers;
@@ -206,6 +233,36 @@ declare class MindCache {
     restoreToVersion(_versionId: string): boolean;
     get accessLevel(): AccessLevel;
     get hasSystemAccess(): boolean;
+    /**
+     * Check if context filtering is currently active.
+     */
+    get hasContext(): boolean;
+    /**
+     * Get current context rules, or null if no context is set.
+     */
+    get_context(): ContextRules | null;
+    /**
+     * Set context filtering rules.
+     * When context is set, only keys with ALL specified tags are visible.
+     *
+     * @param rules - Context rules, or array of tags (shorthand for { tags: [...] })
+     */
+    set_context(rules: ContextRules | string[]): void;
+    /**
+     * Clear context filtering. All keys become visible again.
+     */
+    reset_context(): void;
+    /**
+     * Check if a key matches the current context rules.
+     * Returns true if no context is set.
+     */
+    keyMatchesContext(key: string): boolean;
+    /**
+     * Create a new key with optional default tags from context.
+     *
+     * @throws Error if key already exists
+     */
+    create_key(key: string, value: any, attributes?: Partial<KeyAttributes>): void;
     private _initCloud;
     private _initYIndexedDB;
     private _initIndexedDB;
@@ -245,8 +302,9 @@ declare class MindCache {
     /**
      * Update only the attributes of a key without modifying the value.
      * Useful for updating tags, permissions etc. on document type keys.
+     * @returns true if attributes were updated, false if key doesn't exist or is protected
      */
-    set_attributes(key: string, attributes: Partial<KeyAttributes>): void;
+    set_attributes(key: string, attributes: Partial<KeyAttributes>): boolean;
     set_value(key: string, value: any, attributes?: Partial<KeyAttributes>): void;
     /**
      * LLM-safe method to write a value to a key.
@@ -283,15 +341,15 @@ declare class MindCache {
      */
     size(): number;
     /**
-     * Get all keys in MindCache (including temporal keys).
+     * Get all keys in MindCache.
      */
     keys(): string[];
     /**
-     * Get all values in MindCache (including temporal values).
+     * Get all values in MindCache.
      */
     values(): any[];
     /**
-     * Get all key-value entries (including temporal entries).
+     * Get all key-value entries.
      */
     entries(): Array<[string, any]>;
     /**
@@ -306,7 +364,6 @@ declare class MindCache {
     getSTM(): string;
     /**
      * Get the STM as an object with values directly (no attributes).
-     * Includes system keys ($date, $time).
      * @deprecated Use getAll() for full STM format
      */
     getSTMObject(): Record<string, any>;
@@ -342,7 +399,7 @@ declare class MindCache {
     getKeysByTag(tag: string): string[];
     /**
      * Add a system tag to a key (requires system access).
-     * System tags: 'SystemPrompt', 'LLMRead', 'LLMWrite', 'readonly', 'protected', 'ApplyTemplate'
+     * System tags: 'SystemPrompt', 'LLMRead', 'LLMWrite', 'ApplyTemplate'
      */
     systemAddTag(key: string, tag: SystemTag): boolean;
     /**
@@ -367,8 +424,9 @@ declare class MindCache {
     systemGetKeysByTag(tag: SystemTag): string[];
     /**
      * Helper to get sorted keys (by zIndex).
+     * Respects context filtering when set.
      */
-    private getSortedKeys;
+    getSortedKeys(): string[];
     /**
      * Serialize to JSON string.
      */
@@ -383,8 +441,10 @@ declare class MindCache {
     toMarkdown(): string;
     /**
      * Import from Markdown format.
+     * @param markdown The markdown string to import
+     * @param merge If false (default), clears existing data before importing. If true, merges with existing data.
      */
-    fromMarkdown(markdown: string): void;
+    fromMarkdown(markdown: string, merge?: boolean): void;
     /**
      * Set base64 binary data.
      */
@@ -426,17 +486,17 @@ declare class MindCache {
      */
     delete_text(key: string, index: number, length: number): void;
     /**
-     * Replace all text in a document key (private - use set_value for public API).
+     * Replace all text in a document key.
      * Uses diff-based updates when changes are < diffThreshold (default 80%).
      * This preserves concurrent edits and provides better undo granularity.
      */
-    private _replaceDocumentText;
+    _replaceDocumentText(key: string, newText: string, diffThreshold?: number): void;
     subscribe(key: string, listener: Listener): () => void;
     subscribeToAll(listener: GlobalListener): () => void;
     unsubscribeFromAll(listener: GlobalListener): void;
-    private notifyGlobalListeners;
-    private sanitizeKeyForTool;
-    private findKeyFromSanitizedTool;
+    notifyGlobalListeners(): void;
+    sanitizeKeyForTool(key: string): string;
+    findKeyFromSanitizedTool(sanitizedKey: string): string | undefined;
     /**
      * Generate Vercel AI SDK compatible tools for writable keys.
      * For document type keys, generates additional tools: append_, insert_, edit_
@@ -552,4 +612,4 @@ declare class CloudAdapter {
     private scheduleReconnect;
 }
 
-export { type AccessLevel as A, type CloudConfig as C, type DeleteOperation as D, type GlobalListener as G, type HistoryEntry as H, type KeyAttributes as K, type Listener as L, MindCache as M, type Operation as O, type SetOperation as S, CloudAdapter as a, type ConnectionState as b, type CloudAdapterEvents as c, type ClearOperation as d, type MindCacheOptions as e, type KeyType as f, type SystemTag as g, type STM as h, type STMEntry as i, type HistoryOptions as j, type MindCacheCloudOptions as k, type MindCacheIndexedDBOptions as l, DEFAULT_KEY_ATTRIBUTES as m, SystemTagHelpers as n };
+export { type AccessLevel as A, type CloudConfig as C, type DeleteOperation as D, type GlobalListener as G, type HistoryEntry as H, type KeyAttributes as K, type Listener as L, MindCache as M, type Operation as O, type SetOperation as S, CloudAdapter as a, type ConnectionState as b, type CloudAdapterEvents as c, type ClearOperation as d, type MindCacheOptions as e, type KeyType as f, type SystemTag as g, type ContextRules as h, type STM as i, type STMEntry as j, type HistoryOptions as k, type MindCacheCloudOptions as l, type MindCacheIndexedDBOptions as m, DEFAULT_KEY_ATTRIBUTES as n, SystemTagHelpers as o };

package/dist/cloud/index.d.mts

@@ -1,5 +1,5 @@
-import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../CloudAdapter-CJS3Sh4f.mjs';
-export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../CloudAdapter-CJS3Sh4f.mjs';
+import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../CloudAdapter-CM7nyJaG.mjs';
+export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../CloudAdapter-CM7nyJaG.mjs';
 import 'yjs';
 
 /**

package/dist/cloud/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../CloudAdapter-CJS3Sh4f.js';
-export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../CloudAdapter-CJS3Sh4f.js';
+import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../CloudAdapter-CM7nyJaG.js';
+export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../CloudAdapter-CM7nyJaG.js';
 import 'yjs';
 
 /**