MindCache

A TypeScript library for managing short-term memory in AI agents through an LLM-friendly key-value repository.

Motivation

MindCache was born from three core motivations:

1. Learning by Doing: Building real-world AI agent applications reveals patterns and challenges that theoretical knowledge alone cannot provide. This library captures those learnings.

2. Code Mutualization: Instead of rewriting memory management logic for each project, MindCache provides a shared foundation that can be reused across various AI agent applications.

3. Pattern Discovery: Through practical use, MindCache explores and implements patterns that are essential for effective context window management and tools orchestration in AI systems.

What Problem Does It Solve?

AI agents need to maintain context during conversations and across tool calls. MindCache provides:

• Short-term memory management for session-based context
• LLM-optimized storage that agents can easily read and write
• Automatic tool generation so agents can interact with memory without manual tool definitions
• System prompt generation that summarizes memory state efficiently
• Context window optimization through visibility controls and smart formatting

Note: Cross-session persistence is out of scope. MindCache focuses on short-term memory within a single session.

Core Concepts

Universal Storage

Store any data type an LLM can process: text, JSON, images, and files. All data is stored in an LLM-friendly format.

LLM-Native Interface

• Readable: Memory is formatted for easy LLM consumption
• Writable: Agents can directly modify memory through automatically generated tools
• Template Injection: Use {{key}} syntax to inject memory values into prompts and templates

Smart Context Management

• Visibility Controls: Mark keys as visible/invisible to control what appears in system prompts
• Read-only Keys: Protect certain values from modification
• Tags: Organize and filter memory entries by category
• Templates: Enable dynamic value resolution with circular reference protection

Automatic Tool Generation

Tools are automatically generated for each writable key, allowing agents to read and write memory without manual tool definitions. Tools integrate seamlessly with Vercel AI SDK and other AI frameworks.

Custom Types (v3.6+)

Define structured data schemas using human-readable Markdown, then assign types to keys for consistent LLM output:

// Define a custom type with Markdown schemamc.registerType('Contact',`#Contact* name: full name of the contact* email: email address* phone: phone number* notes: any additional context`);// Create a key with this typemc.set_value('contact_alice',JSON.stringify({name: 'Alice',email: 'alice@example.com'}));mc.setType('contact_alice','Contact');// LLM tools will enforce the schemaconsttools=mc.create_vercel_ai_tools();// For Vercel AI SDK// orconstrawTools=mc.create_tools();// For other frameworks (OpenAI, Anthropic, etc.)

Quick Start

import{MindCache}from'mindcache';constmc=newMindCache();// Store valuesmc.set_value('userName','Alice');mc.set_value('favoriteColor','blue');// Generate system prompt for your AI agentconstsystemPrompt=mc.get_system_prompt();// Generate tools for Vercel AI SDKconsttools=mc.create_vercel_ai_tools();// Use with AI SDKimport{generateText}from'ai';const{ text }=awaitgenerateText({model: openai('gpt-4'),
tools,system: systemPrompt,prompt: 'Remember that I love green now, not blue.'});// AI automatically calls write_favoriteColor('green')

Key Features

Template Injection

mindcache.set_value('name','Alice');mindcache.set_value('city','New York');constmessage=mindcache.injectSTM('Hello {{name}} from {{city}}!');// "Hello Alice from New York!"

System Tags & Attributes

// Control LLM access with systemTagsmindcache.set_value('userPrefs','{"theme":"dark"}',{type: 'json',systemTags: ['SystemPrompt','LLMWrite']// Visible in prompt, writable by LLM});// Mark as template for dynamic resolutionmindcache.set_value('greeting','Hello {{name}}!',{systemTags: ['ApplyTemplate']// Templates are processed on read});
### Image&FileSupport```typescript// Store imagesmindcache.add_image('profilePic',base64Data,'image/png');// Store filesmindcache.set_base64('document',base64Data,'application/pdf','file');// Get as data URLconstimageUrl=mindcache.get_data_url('profilePic');

Tag-Based Organization

mindcache.set_value('userName','Alice',{tags: ['user']});mindcache.set_value('userRole','developer',{tags: ['user']});mindcache.set_value('tempNote','Meeting at 3pm');// No tags// Get only tagged entriesconstuserData=mindcache.getTagged('user');// "userName: Alice, userRole: developer"

Markdown Serialization

// Export to markdownconstmarkdown=mindcache.toMarkdown();// Import from markdownmindcache.fromMarkdown(markdown);

Context Filtering

// Filter keys by tags during a sessionmindcache.setContext({includeTags: ['user']});mindcache.get_system_prompt();// Only includes keys tagged 'user'mindcache.clearContext();// Remove filter// Scoped contextmindcache.withContext({includeTags: ['admin']},()=>{constadminPrompt=mindcache.get_system_prompt();});

Integration

Vercel AI SDK

import{streamText}from'ai';import{MindCache}from'mindcache';constmc=newMindCache();mc.set_value('userName','Alice',{systemTags: ['SystemPrompt','LLMRead','LLMWrite']});consttools=mc.create_vercel_ai_tools();constsystemPrompt=mc.get_system_prompt();constresult=awaitstreamText({model: openai('gpt-4'),
tools,system: systemPrompt,prompt: userMessage});

Other AI Frameworks (OpenAI, Anthropic, LangChain)

import{MindCache}from'mindcache';constmc=newMindCache();consttools=mc.create_tools();// Raw JSON Schema tools// Use with OpenAI SDKconstresponse=awaitopenai.chat.completions.create({model: 'gpt-4',tools: Object.values(tools).map(t=>({type: 'function',function: {name: t.name,description: t.description,parameters: t.parameters}})),messages: [{role: 'user',content: userMessage}]});

Next.js

See the Next.js example for a complete integration.

Framework Agnostic

MindCache works in any TypeScript/JavaScript environment, including:

• Serverless functions
• Edge runtimes
• Browser applications
• Node.js servers

Server-Side Usage

MindCache provides a dedicated server export for use in Node.js, Cloudflare Workers, Durable Objects, and other server environments.

Server Import

// Use the server-specific export (no browser dependencies)import{MindCache}from'mindcache/server';constmc=newMindCache();mc.set_value('key','value');

Advanced: Injecting an Existing Yjs Document

For advanced server-side scenarios (e.g., Cloudflare Durable Objects, collaborative backends), you can inject an existing Y.Doc instance. This allows MindCache to operate directly on your authoritative document without creating a separate copy.

import{MindCache}from'mindcache/server';import*asYfrom'yjs';// Your existing Yjs document (e.g., from a Durable Object)constexistingDoc: Y.Doc=getYourYjsDocument();// Create MindCache instance wrapping your documentconstmc=newMindCache({doc: existingDoc,accessLevel: 'system'// Required for full access when using doc injection});// All operations now apply directly to existingDocmc.fromMarkdown(markdownContent);mc.set_value('imported',true);// Changes are reflected in the original document// No need to sync - you're operating on the source of truth

Use Cases for Server-Side MindCache

1. Server-Side Import/Hydration: Parse and import markdown content directly into your data store without network overhead.

2. Background Processing: Process or transform MindCache data in serverless functions or workers.

3. AI Agent Backends: Use MindCache in your AI service layer to manage agent memory server-side.

4. Durable Object Integration: Wrap your Durable Object's Yjs document with MindCache for a higher-level API.

Example: Cloudflare Durable Object

import{MindCache}from'mindcache/server';import*asYfrom'yjs';exportclassMyDurableObject{privatedoc: Y.Doc;constructor(state: DurableObjectState){this.doc=newY.Doc();}// Create a MindCache instance for this requestprivategetSDK(): MindCache{returnnewMindCache({doc: this.doc,accessLevel: 'system'});}asynchandleImport(markdown: string): Promise<void>{constsdk=this.getSDK();sdk.fromMarkdown(markdown);// Changes are now in this.doc}asyncgetValue(key: string): Promise<string|undefined>{constsdk=this.getSDK();returnsdk.get_value(key);}}

API Reference

Core Methods

• set_value(key, value, attributes?) - Store a value with optional attributes
• get_value(key) - Retrieve a value (supports template processing)
• delete_key(key) - Remove a key-value pair
• has(key) - Check if a key exists
• clear() - Clear all memory
• keys() - Get all key names

Custom Types (v3.6+)

• registerType(name, markdownSchema) - Register a custom type with Markdown schema
• setType(key, typeName) - Assign a custom type to a key (also sets type to 'json')
• getKeyType(key) - Get the custom type name for a key
• getTypeSchema(typeName) - Get the parsed schema definition
• getRegisteredTypes() - List all registered type names

LLM Tool Generation

• create_vercel_ai_tools() - Generate Zod-based tools for Vercel AI SDK v5
• create_tools() - Generate raw JSON Schema tools (OpenAI, Anthropic, LangChain)
• get_system_prompt() - Generate system prompt from visible keys

Memory Management

• injectSTM(template) - Inject memory values into template strings
• getSTM() - Get formatted string of all visible entries

Serialization

• toJSON() - Serialize to JSON string
• fromJSON(jsonString) - Deserialize from JSON string
• toMarkdown() - Export to markdown format
• fromMarkdown(markdown, merge?) - Import from markdown format (merge=false clears first)
• serialize() - Get complete state object
• deserialize(data) - Restore complete state

Context Filtering

• setContext(rules) - Filter keys by tags (includeTags, excludeTags)
• clearContext() - Remove context filter
• withContext(rules, fn) - Run function with temporary context
• getContext() - Get current context rules

Attributes & Tags

• set_attributes(key, attributes) - Update key attributes
• get_attributes(key) - Get key attributes
• addTag(key, tag) - Add a tag to a key
• removeTag(key, tag) - Remove a tag from a key
• getTags(key) - Get all tags for a key
• getTagged(tag) - Get all entries with a specific tag

Event System

• subscribe(key, listener) - Subscribe to changes for a specific key
• unsubscribe(key, listener) - Unsubscribe from key changes
• subscribeToAll(listener) - Subscribe to all changes
• unsubscribeFromAll(listener) - Unsubscribe from all changes

Examples

See the examples directory for complete implementations:

• Contact Extractor - AI-powered contact extraction using custom types
• MindCache Server Local - local API + browser client for tag-based key discovery
• Form management with AI assistant
• Image processing workflows
• Multi-step workflows with memory persistence
• Client-side STM editor

Installation

npm install mindcache

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0.0
• Optional: ai package >= 3.0.0 for Vercel AI SDK integration

License

MIT License - see LICENSE for details.