diff --git a/AGENTS.md b/AGENTS.md index b05d83c..4632668 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ # Reminders * examples use npm not pnpm -* before merging, check the CI pipeline, lint, build, etc... then npm login and npm publish mindcache if relevant. +* when the user wants to merge a branch, check the CI pipeline, lint, build, etc... then npm login and npm publish mindcache if relevant. diff --git a/docs/index.html b/docs/index.html index 95251f2..ced8ebe 100644 --- a/docs/index.html +++ b/docs/index.html @@ -6,7 +6,7 @@ MindCache - AI Agent Memory Management + content="MindCache - TypeScript library for AI agent memory. Local-first React components, cloud sync, GitHub persistence with GitStore. Build AI chat apps in 15 lines of code."> MindCache
- Cloud Local-First + Cloud Features Examples Docs @@ -48,15 +48,15 @@
- 🚀 MindCache 3.2 — Real-Time Collaborative Documents! + 🚀 MindCache 3.7 — React Components & Local-First AI Chat!

AI Agent Memory
Made Simple

- MindCache is a TypeScript library for managing short-term memory in AI agents through a simple, - LLM-friendly key-value repository. Now with cloud persistence, real-time sync, and collaboration. + MindCache is a TypeScript library for managing short-term memory in AI agents. + Drop-in React components for local-first AI chat, cloud persistence, real-time sync, and GitHub storage.

@@ -71,58 +71,6 @@

-
-
- 3.3 - Version -
-
- Real-time - Sync -
-
- TypeScript - First -
-
-
-
- - - -
-
-
-

MindCache 2.0 Cloud

-

A hosted, collaborative key-value store for AI agents

-
-
-
-
☁️
-

Cloud Persistence

-

All key-value data stored securely in the cloud with automatic sync between clients.

-
-
-
⚡
-

Real-Time Sync

-

WebSocket-based live updates. Subscribe to specific keys or entire instances.

-
-
-
👥
-

Collaboration

-

Share projects and instances with teams. Granular permissions for read/write/admin access.

-
-
-
🤖
-

Built-in AI APIs

-

Chat API, image generation, web search, and transform APIs — all reading from MindCache.

-
-
-
- - ☁️ Start Using MindCache Cloud - -

Free tier available • No credit card required

@@ -170,13 +118,43 @@

React Components

); }
-
- - 📦 @mindcache/gitstore - - - 💡 Example App +
+ + + +
+
+
+

MindCache Cloud

+

A hosted, collaborative key-value store for AI agents

+
+
+
+
☁️
+

Cloud Persistence

+

All key-value data stored securely in the cloud with automatic sync between clients.

+
+
+
⚡
+

Real-Time Sync

+

WebSocket-based live updates. Subscribe to specific keys or entire instances.

+
+
+
👥
+

Collaboration

+

Share projects and instances with teams. Granular permissions for read/write/admin access.

+
+
+
🤖
+

Built-in AI APIs

+

Chat API, image generation, web search, and transform APIs — all reading from MindCache.

+
+
+
+ + ☁️ Start Using MindCache Cloud +

Free tier available • No credit card required

@@ -227,8 +205,8 @@

Local Persistence

⚛️
-

React Hook

-

useMindCache hook handles async init, loading state, and cleanup automatically

+

React Components

+

Drop-in <MindCacheChat> component and hooks for building AI apps in minutes

@@ -242,12 +220,54 @@

Examples

Real-world use cases for AI agents

- + +
-
+
+
+ 
// Full AI Chat App in ~15 Lines
+import { MindCacheProvider, MindCacheChat } from 'mindcache';
+
+function App() {
+  return (
+    <MindCacheProvider
+      ai={{
+        provider: 'openai',       // or 'anthropic'
+        model: 'gpt-4o',
+        keyStorage: 'localStorage' // API key stored locally
+      }}
+      mindcache={{
+        indexedDB: { dbName: 'my-app' } // Local persistence
+      }}
+    >
+      <MindCacheChat 
+        welcomeMessage="Hello! I'm your AI assistant."
+        placeholder="Type a message..."
+      />
+    </MindCacheProvider>
+  );
+}
+
+// That's it! No server, no API routes, no backend.
+
+
+

Local-First React Components

+

Drop-in AI chat with streaming responses, tool integration, and MindCache memory. + API keys stay in the browser. Works offline with IndexedDB persistence.

+
+ Hooks available: +
    +
  • useMindCacheContext() - Access MindCache instance & AI config
    • +
  • useClientChat() - Build custom chat UIs
    • +
  • useLocalFirstSync() - Sync to GitHub
    • +
+
+
+
+ 
// Auto Tool Generation for AI Agents
 import { mindcache } from 'mindcache';
@@ -334,7 +354,7 @@ 
Context Management & System Prompts
- 
// MindCache 2.0 Cloud Sync
+                        
// MindCache Cloud Sync
 import { MindCache } from 'mindcache';
 
 // Connect to MindCache Cloud with built-in sync
@@ -368,7 +388,7 @@ 
Context Management & System Prompts

Cloud Sync & Real-Time Collaboration

-

MindCache 2.0 adds seamless cloud persistence. Same simple API — data automatically syncs +

Seamless cloud persistence with the same simple API — data automatically syncs across all clients in real-time. Share instances with your team, connect AI agents, and build collaborative workflows.

Full LLM friendly Documentation

Comprehensive llms-full.md for LLMs, AI agents, and vibe coding — copy the entire file into your context

 + +
⚛️
+

React Components

+

MindCacheProvider, MindCacheChat, and hooks for local-first AI apps

+
📚

API Reference

@@ -424,7 +449,7 @@

Examples

-

© 2025 MindCache. Released under the MIT License. Made with ❤️ by © 2026 MindCache. Released under the MIT License. Made with ❤️ by Damien Henry

diff --git a/docs/llms-full.md b/docs/llms-full.md index 5380d4e..d176a47 100644 --- a/docs/llms-full.md +++ b/docs/llms-full.md @@ -18,15 +18,16 @@ 12. [Image & File Support](#image--file-support) 13. [Cloud Sync](#cloud-sync) 14. [Local Persistence (IndexedDB)](#local-persistence-indexeddb) -15. [React Hook - useMindCache](#react-hook---usemindcache) -16. [Server-Side Usage](#server-side-usage) -17. [Integration Patterns](#integration-patterns) -18. [Common Use Cases](#common-use-cases) -19. [Error Handling](#error-handling) -20. [TypeScript Types](#typescript-types) -21. [Quick Reference](#quick-reference) -22. [Complete App Examples](#complete-app-examples) -23. [Best Practices Summary](#best-practices-summary) +15. [React Components (v3.7+)](#react-components-v37) +16. [React Hook - useMindCache](#react-hook---usemindcache) +17. [Server-Side Usage](#server-side-usage) +18. [Integration Patterns](#integration-patterns) +19. [Common Use Cases](#common-use-cases) +20. [Error Handling](#error-handling) +21. [TypeScript Types](#typescript-types) +22. [Quick Reference](#quick-reference) +23. [Complete App Examples](#complete-app-examples) +24. [Best Practices Summary](#best-practices-summary) --- @@ -34,6 +35,9 @@ MindCache is a TypeScript library for managing short-term memory in AI agents. It provides: +- **React Components** - Drop-in `` for AI chat in ~15 lines (v3.7+) +- **Local-first architecture** - API keys in browser, no server required (v3.7+) +- **GitHub persistence** - Sync to any repo via `@mindcache/gitstore` (v3.7+) - **Key-value storage** optimized for LLM consumption - **Document type** for collaborative Markdown editing (v3.1+) - **Automatic tool generation** for Vercel AI SDK integration @@ -1106,7 +1110,7 @@ mindcache.add_image('screenshot', screenshotBase64, 'image/png'); ## Cloud Sync -MindCache 2.0+ supports cloud persistence and real-time sync via WebSockets. +MindCache supports cloud persistence and real-time sync via WebSockets. ### Authentication Patterns @@ -1429,6 +1433,168 @@ const mc = new MindCache({ --- +## React Components (v3.7+) + +MindCache 3.7 introduces drop-in React components for building local-first AI chat applications with zero server setup. + +### Quick Start + +```tsx +import { MindCacheProvider, MindCacheChat } from 'mindcache'; + +function App() { + return ( + + + + ); +} +``` + +That's it! Full AI chat with streaming, MindCache tools, and mobile-friendly UI. + +### MindCacheProvider + +Wraps your app and provides MindCache + AI configuration. + +```tsx + + {children} + +``` + +### MindCacheChat + +Pre-built chat UI component with streaming and tool support. + +```tsx + +``` + +### useMindCacheContext() + +Access MindCache and AI configuration from any component. + +```tsx +const { + mindcache, // MindCache instance + isLoaded, // Ready to use? + hasApiKey, // API key configured? + setApiKey, // Set API key + getModel, // Get AI model instance + syncToGitStore // Manual sync to GitHub +} = useMindCacheContext(); +``` + +### useClientChat() + +Build custom chat UI with full control. + +```tsx +const { + messages, + sendMessage, + isLoading, + error, + streamingContent, + stop +} = useClientChat({ + systemPrompt: 'You are a helpful assistant.', + maxToolCalls: 5, + onFinish: (message) => console.log('Done:', message), + onMindCacheChange: () => console.log('MindCache updated') +}); +``` + +### useLocalFirstSync() + +Sync MindCache to GitHub via `@mindcache/gitstore`. + +```tsx +const { + status, // 'idle' | 'loading' | 'saving' | 'error' + lastSyncAt, + hasLocalChanges, + save, // Manual save + load, // Manual load + sync // Load then save +} = useLocalFirstSync({ + mindcache, + gitstore: { + owner: 'me', + repo: 'data', + token: async () => getToken() + }, + autoSyncInterval: 30000, + saveDebounceMs: 5000 +}); +``` + +### Custom AI Provider + +For providers not built-in, use `modelProvider`: + +```tsx +import { createAnthropic } from '@ai-sdk/anthropic'; + + { + const anthropic = createAnthropic({ apiKey }); + return anthropic('claude-3-5-sonnet-20241022'); + } + }} +> +``` + +### Architecture + +``` +Browser +├── MindCache (IndexedDB) ← Local persistence +├── AI SDK (streamText) ← Streaming responses +└── OpenAI/Anthropic API ← Direct API calls (no server) +``` + +No server required. API keys stored in browser localStorage. + +--- + ## React Hook - useMindCache The `useMindCache` hook is the simplest way to use MindCache in React applications. It handles async initialization, loading state, and cleanup automatically. diff --git a/docs/llms.txt b/docs/llms.txt index 74469a8..bad5d02 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -1,8 +1,8 @@ # MindCache -> AI Agent Memory Management - Collaborative key-value store for AI agents with real-time sync. +> AI Agent Memory Management - Local-first AI apps with React components, cloud sync, and GitHub persistence. -MindCache 3.4 provides persistent, collaborative memory for AI agents with automatic tool generation, document editing, and real-time sync. +MindCache 3.7 provides persistent memory for AI agents with drop-in React components, automatic tool generation, and local-first architecture. ## Quick Links @@ -79,13 +79,36 @@ mc.undoAll(); // Global undo mc.getGlobalHistory(); // Get history ``` -## React Hooks +## React Components (v3.7+) ```tsx -import { useMindCache, useMindCacheDocument } from 'mindcache/react'; +import { MindCacheProvider, MindCacheChat } from 'mindcache'; + +// Full AI chat app in ~15 lines +function App() { + return ( + + + + ); +} +``` + +### Hooks + +```tsx +import { useMindCacheContext, useClientChat, useLocalFirstSync } from 'mindcache'; + +// Access MindCache instance +const { mindcache, isLoaded, hasApiKey, setApiKey, getModel } = useMindCacheContext(); + +// Build custom chat UI +const { messages, sendMessage, isLoading, streamingContent } = useClientChat(); -const { mindcache, isLoaded } = useMindCache({ indexedDB: { dbName: 'app' } }); -const { text, yText, replaceText } = useMindCacheDocument(mc, 'notes'); +// Sync to GitHub +const { status, save, load } = useLocalFirstSync({ mindcache, gitstore: { owner, repo, token } }); ``` ## Core Methods diff --git a/packages/mindcache/package.json b/packages/mindcache/package.json index 355d6ca..00612ea 100644 --- a/packages/mindcache/package.json +++ b/packages/mindcache/package.json @@ -1,6 +1,6 @@ { "name": "mindcache", - "version": "3.6.0", + "version": "3.7.0", "description": "A TypeScript library for managing short-term memory in AI agents through an LLM-friendly key-value repository", "main": "./dist/index.js", "module": "./dist/index.mjs", diff --git a/packages/mindcache/src/core/MindCache.ts b/packages/mindcache/src/core/MindCache.ts index 630f827..7c23cf1 100644 --- a/packages/mindcache/src/core/MindCache.ts +++ b/packages/mindcache/src/core/MindCache.ts @@ -4,6 +4,9 @@ import { IndexeddbPersistence } from 'y-indexeddb'; import diff from 'fast-diff'; import type { KeyAttributes, STM, Listener, GlobalListener, AccessLevel, SystemTag, HistoryEntry, HistoryOptions, ContextRules, CustomTypeDefinition } from './types'; import { DEFAULT_KEY_ATTRIBUTES } from './types'; + +// Re-export SystemTag for convenience +export type { SystemTag } from './types'; import { SchemaParser } from './SchemaParser'; import { MarkdownSerializer } from './MarkdownSerializer'; import { AIToolBuilder } from './AIToolBuilder';