mindcache 3.5.3 → 3.7.0

package/README.md

@@ -10,13 +10,38 @@ A TypeScript library for managing short-term memory in AI agents through an LLM-
 ## Quick Start
 
 ```typescript
-import { mindcache } from 'mindcache';
+import { MindCache } from 'mindcache';
 
-// Store values
-mindcache.set_value('userName', 'Alice');
+const mc = new MindCache();
+
+// Store values with LLM access
+mc.set_value('userName', 'Alice', { 
+  systemTags: ['SystemPrompt', 'LLMRead', 'LLMWrite'] 
+});
 
 // Generate tools for Vercel AI SDK
-const tools = mindcache.get_aisdk_tools();
+const tools = mc.create_vercel_ai_tools();
+
+// Or for other frameworks (OpenAI, Anthropic, LangChain)
+const rawTools = mc.create_tools();
+```
+
+## Custom Types (v3.6+)
+
+Define structured schemas for consistent LLM output:
+
+```typescript
+// Register a custom type with Markdown schema
+mc.registerType('Contact', `
+#Contact
+* name: full name
+* email: email address
+* phone: phone number
+`);
+
+// Assign type to a key
+mc.set_value('contact_alice', JSON.stringify({ name: 'Alice' }));
+mc.setType('contact_alice', 'Contact');
 ```
 
 See the [root README](../../README.md) for more details.

package/dist/{CloudAdapter-DK4YecbV.d.mts → CloudAdapter-PLGvGjoA.d.mts}

@@ -31,6 +31,26 @@ type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'ApplyTemplate';
  * Type of value stored in a MindCache key
  */
 type KeyType = 'text' | 'image' | 'file' | 'json' | 'document';
+/**
+ * A field in a custom type definition
+ */
+interface CustomTypeField {
+    /** Field name */
+    name: string;
+    /** Human-readable description of the field */
+    description: string;
+}
+/**
+ * A parsed custom type definition
+ */
+interface CustomTypeDefinition {
+    /** Type name (e.g., 'Contact') */
+    name: string;
+    /** Fields that make up this type */
+    fields: CustomTypeField[];
+    /** Original markdown schema */
+    rawSchema: string;
+}
 /**
  * Attributes that can be set on a MindCache key
  */
@@ -45,6 +65,8 @@ interface KeyAttributes {
     systemTags: SystemTag[];
     /** Z-index for ordering keys (lower values appear first) */
     zIndex: number;
+    /** Custom type name (registered via registerType) */
+    customType?: string;
 }
 /**
  * Default attributes for new keys
@@ -171,7 +193,7 @@ declare class MindCache {
     rootMap: Y.Map<Y.Map<any>>;
     private listeners;
     private globalListeners;
-    readonly version = "3.3.2";
+    readonly version = "3.6.0";
     normalizeSystemTags(tags: SystemTag[]): SystemTag[];
     private _cloudAdapter;
     private _connectionState;
@@ -186,6 +208,7 @@ declare class MindCache {
     private _history;
     private _historyOptions;
     private _historyEnabled;
+    private _typeRegistry;
     constructor(options?: MindCacheOptions);
     private getUndoManager;
     /**
@@ -422,6 +445,49 @@ declare class MindCache {
      * Get all keys with a specific system tag (requires system access).
      */
     systemGetKeysByTag(tag: SystemTag): string[];
+    /**
+     * Register a custom type with a markdown schema definition.
+     *
+     * Schema format:
+     * ```
+     * #TypeName
+     * * fieldName: description of the field
+     * * anotherField: description
+     * ```
+     *
+     * @param name - Type name (e.g., 'Contact')
+     * @param schema - Markdown schema definition
+     * @throws Error if schema format is invalid
+     */
+    registerType(name: string, schema: string): void;
+    /**
+     * Assign a custom type to a key.
+     * The key must exist and the type must be registered.
+     * Also sets the underlying type to 'json' since custom types are structured JSON data.
+     *
+     * @param key - Key to assign type to
+     * @param typeName - Registered type name
+     * @throws Error if key doesn't exist or type is not registered
+     */
+    setType(key: string, typeName: string): void;
+    /**
+     * Get a registered type schema definition.
+     *
+     * @param typeName - Type name to look up
+     * @returns The type definition or undefined if not registered
+     */
+    getTypeSchema(typeName: string): CustomTypeDefinition | undefined;
+    /**
+     * Get all registered type names.
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * Get the custom type assigned to a key.
+     *
+     * @param key - Key to check
+     * @returns Type name or undefined if no custom type assigned
+     */
+    getKeyType(key: string): string | undefined;
     /**
      * Helper to get sorted keys (by zIndex).
      * Respects context filtering when set.
@@ -497,9 +563,26 @@ declare class MindCache {
     notifyGlobalListeners(): void;
     sanitizeKeyForTool(key: string): string;
     findKeyFromSanitizedTool(sanitizedKey: string): string | undefined;
+    /**
+     * Generate framework-agnostic tools with raw JSON Schema.
+     * Works with: OpenAI SDK, Anthropic SDK, LangChain, and other frameworks.
+     *
+     * Tool format:
+     * {
+     *   description: string,
+     *   parameters: { type: 'object', properties: {...}, required: [...] },
+     *   execute: async (args) => result
+     * }
+     *
+     * Security: All tools use llm_set_key internally which:
+     * - Only modifies VALUES, never attributes/systemTags
+     * - Prevents LLMs from escalating privileges
+     */
+    create_tools(): Record<string, any>;
     /**
      * Generate Vercel AI SDK compatible tools for writable keys.
-     * For document type keys, generates additional tools: append_, insert_, edit_
+     * Wraps parameters with jsonSchema() for AI SDK v5 compatibility.
+     * Use this with: generateText(), streamText() from 'ai' package.
      *
      * Security: All tools use llm_set_key internally which:
      * - Only modifies VALUES, never attributes/systemTags
@@ -592,10 +675,6 @@ declare class CloudAdapter {
     private handleOffline;
     private _synced;
     constructor(config: CloudConfig);
-    /**
-     * Validate configuration and warn about common mistakes
-     */
-    private validateConfig;
     /** Browser network status - instantly updated via navigator.onLine */
     get isOnline(): boolean;
     private setupNetworkDetection;
@@ -616,4 +695,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 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 };
+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 CustomTypeDefinition as e, type MindCacheOptions as f, type KeyType as g, type SystemTag as h, type ContextRules as i, type STM as j, type STMEntry as k, type HistoryOptions as l, type MindCacheCloudOptions as m, type MindCacheIndexedDBOptions as n, type CustomTypeField as o, DEFAULT_KEY_ATTRIBUTES as p, SystemTagHelpers as q };

package/dist/{CloudAdapter-DK4YecbV.d.ts → CloudAdapter-PLGvGjoA.d.ts}

@@ -31,6 +31,26 @@ type SystemTag = 'SystemPrompt' | 'LLMRead' | 'LLMWrite' | 'ApplyTemplate';
  * Type of value stored in a MindCache key
  */
 type KeyType = 'text' | 'image' | 'file' | 'json' | 'document';
+/**
+ * A field in a custom type definition
+ */
+interface CustomTypeField {
+    /** Field name */
+    name: string;
+    /** Human-readable description of the field */
+    description: string;
+}
+/**
+ * A parsed custom type definition
+ */
+interface CustomTypeDefinition {
+    /** Type name (e.g., 'Contact') */
+    name: string;
+    /** Fields that make up this type */
+    fields: CustomTypeField[];
+    /** Original markdown schema */
+    rawSchema: string;
+}
 /**
  * Attributes that can be set on a MindCache key
  */
@@ -45,6 +65,8 @@ interface KeyAttributes {
     systemTags: SystemTag[];
     /** Z-index for ordering keys (lower values appear first) */
     zIndex: number;
+    /** Custom type name (registered via registerType) */
+    customType?: string;
 }
 /**
  * Default attributes for new keys
@@ -171,7 +193,7 @@ declare class MindCache {
     rootMap: Y.Map<Y.Map<any>>;
     private listeners;
     private globalListeners;
-    readonly version = "3.3.2";
+    readonly version = "3.6.0";
     normalizeSystemTags(tags: SystemTag[]): SystemTag[];
     private _cloudAdapter;
     private _connectionState;
@@ -186,6 +208,7 @@ declare class MindCache {
     private _history;
     private _historyOptions;
     private _historyEnabled;
+    private _typeRegistry;
     constructor(options?: MindCacheOptions);
     private getUndoManager;
     /**
@@ -422,6 +445,49 @@ declare class MindCache {
      * Get all keys with a specific system tag (requires system access).
      */
     systemGetKeysByTag(tag: SystemTag): string[];
+    /**
+     * Register a custom type with a markdown schema definition.
+     *
+     * Schema format:
+     * ```
+     * #TypeName
+     * * fieldName: description of the field
+     * * anotherField: description
+     * ```
+     *
+     * @param name - Type name (e.g., 'Contact')
+     * @param schema - Markdown schema definition
+     * @throws Error if schema format is invalid
+     */
+    registerType(name: string, schema: string): void;
+    /**
+     * Assign a custom type to a key.
+     * The key must exist and the type must be registered.
+     * Also sets the underlying type to 'json' since custom types are structured JSON data.
+     *
+     * @param key - Key to assign type to
+     * @param typeName - Registered type name
+     * @throws Error if key doesn't exist or type is not registered
+     */
+    setType(key: string, typeName: string): void;
+    /**
+     * Get a registered type schema definition.
+     *
+     * @param typeName - Type name to look up
+     * @returns The type definition or undefined if not registered
+     */
+    getTypeSchema(typeName: string): CustomTypeDefinition | undefined;
+    /**
+     * Get all registered type names.
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * Get the custom type assigned to a key.
+     *
+     * @param key - Key to check
+     * @returns Type name or undefined if no custom type assigned
+     */
+    getKeyType(key: string): string | undefined;
     /**
      * Helper to get sorted keys (by zIndex).
      * Respects context filtering when set.
@@ -497,9 +563,26 @@ declare class MindCache {
     notifyGlobalListeners(): void;
     sanitizeKeyForTool(key: string): string;
     findKeyFromSanitizedTool(sanitizedKey: string): string | undefined;
+    /**
+     * Generate framework-agnostic tools with raw JSON Schema.
+     * Works with: OpenAI SDK, Anthropic SDK, LangChain, and other frameworks.
+     *
+     * Tool format:
+     * {
+     *   description: string,
+     *   parameters: { type: 'object', properties: {...}, required: [...] },
+     *   execute: async (args) => result
+     * }
+     *
+     * Security: All tools use llm_set_key internally which:
+     * - Only modifies VALUES, never attributes/systemTags
+     * - Prevents LLMs from escalating privileges
+     */
+    create_tools(): Record<string, any>;
     /**
      * Generate Vercel AI SDK compatible tools for writable keys.
-     * For document type keys, generates additional tools: append_, insert_, edit_
+     * Wraps parameters with jsonSchema() for AI SDK v5 compatibility.
+     * Use this with: generateText(), streamText() from 'ai' package.
      *
      * Security: All tools use llm_set_key internally which:
      * - Only modifies VALUES, never attributes/systemTags
@@ -592,10 +675,6 @@ declare class CloudAdapter {
     private handleOffline;
     private _synced;
     constructor(config: CloudConfig);
-    /**
-     * Validate configuration and warn about common mistakes
-     */
-    private validateConfig;
     /** Browser network status - instantly updated via navigator.onLine */
     get isOnline(): boolean;
     private setupNetworkDetection;
@@ -616,4 +695,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 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 };
+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 CustomTypeDefinition as e, type MindCacheOptions as f, type KeyType as g, type SystemTag as h, type ContextRules as i, type STM as j, type STMEntry as k, type HistoryOptions as l, type MindCacheCloudOptions as m, type MindCacheIndexedDBOptions as n, type CustomTypeField as o, DEFAULT_KEY_ATTRIBUTES as p, SystemTagHelpers as q };

package/dist/cloud/index.d.mts

@@ -1,5 +1,5 @@
-import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../CloudAdapter-DK4YecbV.mjs';
-export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../CloudAdapter-DK4YecbV.mjs';
+import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../CloudAdapter-PLGvGjoA.mjs';
+export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../CloudAdapter-PLGvGjoA.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-DK4YecbV.js';
-export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../CloudAdapter-DK4YecbV.js';
+import { M as MindCache, C as CloudConfig, a as CloudAdapter } from '../CloudAdapter-PLGvGjoA.js';
+export { d as ClearOperation, c as CloudAdapterEvents, b as ConnectionState, D as DeleteOperation, O as Operation, S as SetOperation } from '../CloudAdapter-PLGvGjoA.js';
 import 'yjs';
 
 /**