# Memory Intelligence SDK 🧠✨ [![npm version](https://badge.fury.io/js/%40lanonasis%2Fmem-intel-sdk.svg)](https://www.npmjs.com/package/@lanonasis/mem-intel-sdk) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/) [![Tests](https://img.shields.io/badge/tests-89%20passing-brightgreen.svg)]() **The AI that anticipates what you need before you realize it.** An AI-powered memory intelligence SDK for the LanOnasis Memory-as-a-Service platform. Beyond storage and retrieval - this SDK **predicts** what memories you'll need based on your current context. ```typescript // The magic moment const predictions = await client.predictiveRecall({ userId: "user-123", context: { currentProject: "Building dashboard components", recentTopics: ["React", "performance"] } }); // "Sarah, here's what you might need" // [92%] React Hooks Performance Optimization // → Reason: Highly relevant to your current work // → Action: Apply ``` ## Features ### NEW in v2.0.0: Predictive Memory System - **Predictive Recall** - AI anticipates what you'll need before you search - **Personalized Responses** - "Sarah, here's what you might need" - **Explainable Predictions** - Every suggestion includes confidence score and reasoning - **Learning Loop** - Feedback improves future predictions ### Core Intelligence - **Pattern Recognition** - Understand usage trends and productivity patterns - **Smart Organization** - AI-powered tag suggestions and duplicate detection - **Semantic Intelligence** - Find related memories using vector similarity - **Behavioral Learning** - Record, recall, and suggest next actions from successful workflows - **Actionable Insights** - Extract key learnings and opportunities from your knowledge base - **Health Monitoring** - Ensure your memory database stays organized and healthy ## Platform Support - ✅ **Node.js** - Full support with environment variable configuration - ✅ **Browser** - Universal client for web applications - ✅ **React** - Hooks with React Query integration - ✅ **Vue 3** - Composables for Vue applications - ✅ **MCP Server** - Create Model Context Protocol servers ## Installation ```bash # npm npm install @lanonasis/mem-intel-sdk # yarn yarn add @lanonasis/mem-intel-sdk # pnpm pnpm add @lanonasis/mem-intel-sdk ``` ### Framework-specific peer dependencies For React applications: ```bash npm install react @tanstack/react-query ``` For Vue applications: ```bash npm install vue ``` For MCP Server: ```bash npm install @modelcontextprotocol/sdk ``` ## Quick Start ### Basic Usage ```typescript import { MemoryIntelligenceClient } from "@lanonasis/mem-intel-sdk"; const client = new MemoryIntelligenceClient({ apiKey: "lano_xxxxxxxxxx", // Your Lanonasis API key }); // Analyze memory patterns const analysis = await client.analyzePatterns({ userId: "user-123", timeRangeDays: 30, }); console.log(`Total memories: ${analysis.total_memories}`); ``` ### Node.js with Environment Variables ```typescript import { NodeMemoryIntelligenceClient } from "@lanonasis/mem-intel-sdk/node"; // Automatically reads LANONASIS_API_KEY from environment const client = NodeMemoryIntelligenceClient.fromEnv(); ``` ### React Integration ```tsx import { MemoryIntelligenceProvider, usePatternAnalysis, } from "@lanonasis/mem-intel-sdk/react"; // Wrap your app function App() { return ( ); } // Use hooks in components function Dashboard() { const { data, isLoading } = usePatternAnalysis({ userId: "user-123", timeRangeDays: 30, }); if (isLoading) return

; return

Total: {data?.total_memories}

; } ``` ### Vue Integration ```vue ``` ## Behavior Learning APIs Use behavior methods when you want the SDK to learn from successful execution patterns and suggest next actions on future tasks. ### 1) Record a successful workflow ```typescript const record = await client.recordBehavior({ user_id: "user-123", trigger: "Need to migrate endpoint auth middleware to bearer-first flow", context: { project: "lanonasis-cli", current_task: "auth transport migration", }, actions: [ { tool: "read_file", params: { path: "src/utils/api.ts" } }, { tool: "edit_file", params: { path: "src/utils/api.ts" } }, { tool: "run_tests", params: { target: "api-client-auth-header.test.ts" } }, ], final_outcome: "Bearer flow migration completed and tests passed", confidence: 0.82, }); console.log(record.data.was_duplicate, record.data.pattern.id); ``` ### 2) Recall similar behavior for a new task ```typescript const recall = await client.recallBehavior({ user_id: "user-123", context: { current_task: "Add token refresh to memory command execution path", }, limit: 5, similarity_threshold: 0.7, }); for (const match of recall.data.patterns) { console.log(match.similarity_score, match.pattern.trigger); } ``` ### 3) Suggest next actions from learned patterns ```typescript const suggestion = await client.suggestAction({ user_id: "user-123", current_state: { task_description: "Finalize CLI release notes and dry-run publish", completed_steps: [ { tool: "update_changelog" }, { tool: "bump_version" }, ], }, max_suggestions: 3, }); console.log(suggestion.data.suggestions); ``` ### 4) List existing behavior patterns ```typescript const patterns = await client.listBehaviorPatterns("user-123", { limit: 20, offset: 0, }); ``` ## Predictive Memory System (v2.0.0) The flagship feature that makes your memory system feel magical. ### How It Works ``` Your Current Context │ ▼ ┌──────────────────────────────────────────┐ │ PREDICTION ENGINE │ │ │ │ Semantic (40%) ─┐ │ │ Temporal (30%) ─┼──► Combined Score │ │ Frequency (20%) ─┤ │ │ Serendipity (10%)┘ │ └──────────────────────────────────────────┘ │ ▼ "Here's what you'll need" ``` ### Basic Usage ```typescript const predictions = await client.predictiveRecall({ userId: "user-123", context: { currentProject: "Building dashboard components", recentTopics: ["React", "TypeScript", "performance"], activeFiles: ["/src/components/Dashboard.tsx"], contextText: "Optimizing render performance for data tables" }, limit: 5, minConfidence: 50 }); // Each prediction includes: for (const pred of predictions.data.predictions) { console.log(`[${pred.confidence}%] ${pred.title}`); console.log(` Why: ${pred.reason}`); console.log(` Action: ${pred.suggestedAction}`); console.log(` Scores: semantic=${pred.scoreBreakdown.semanticScore}, temporal=${pred.scoreBreakdown.temporalScore}`); } ``` ### With Personalization ```typescript // Response includes personalized greeting const result = await client.predictiveRecall({ userId: "user-123", context: { currentProject: "My project" } }); console.log(result.personalization?.greeting); // → "Sarah, here's what you might need" console.log(result.personalization?.tier); // → "pro" ``` ### Recording Feedback (Improves Future Predictions) ```typescript // When user clicks on a prediction await client.recordPredictionFeedback({ memoryId: prediction.id, userId: "user-123", useful: true, action: "clicked" }); // → { success: true, message: "Thanks Sarah! We'll use this to improve your predictions." } ``` ### React Hook ```tsx import { usePredictiveRecall, usePredictionFeedback } from "@lanonasis/mem-intel-sdk/react"; function PredictionsPanel({ userId }) { const { data, isLoading } = usePredictiveRecall({ userId, context: { currentProject: "Dashboard", recentTopics: ["React", "charts"] } }); const { mutate: recordFeedback } = usePredictionFeedback(); if (isLoading) return

Finding relevant memories...

; return (

{data?.personalization?.greeting}

{data?.predictions.map(pred => (

recordFeedback({ memoryId: pred.id, userId, useful: true, action: "clicked" })}> {pred.confidence}%

{pred.title}

{pred.reason}

))}

); } ``` ### Scoring Algorithm | Factor | Weight | Description | |--------|--------|-------------| | **Semantic** | 40% | Cosine similarity between context embedding and memory embedding | | **Temporal** | 30% | Exponential decay (Ebbinghaus curve, 14-day half-life) | | **Frequency** | 20% | Logarithmic scaling of access counts | | **Serendipity** | 10% | Bonus for "adjacent possible" discoveries (0.3-0.6 similarity) | ## Overview This SDK is designed to **complement** your existing `@lanonasis/mcp-core` infrastructure by adding an intelligence layer on top of basic memory CRUD operations. While your core server handles memory creation, storage, and retrieval, this SDK focuses on: - **Pattern Recognition** - Understand usage trends and productivity patterns - **Smart Organization** - AI-powered tag suggestions and duplicate detection - **Semantic Intelligence** - Find related memories using vector similarity - **Actionable Insights** - Extract key learnings and opportunities from your knowledge base - **Health Monitoring** - Ensure your memory database stays organized and healthy ## Why This SDK? ### Modern MCP Patterns Uses the latest `server.registerTool()` API with: - Zod schema validation - Structured content output - Proper tool annotations - Both JSON and Markdown response formats ### Single Responsibility Unlike monolithic servers, this focuses solely on intelligence features, making it: - Easier to maintain - More composable - Better suited for specific use cases ### Production-Ready - Streamable HTTP transport support - Proper error handling with actionable messages - Character limit enforcement - Comprehensive logging ## MCP Server Setup For standalone MCP server usage: ```bash # Clone the repository git clone https://github.com/lanonasis/memory-intelligence-engine.git cd memory-intelligence-engine/mem-intelligence-sdk # Install dependencies npm install # Build the project npm run build ``` ## Configuration Create a `.env` file with your existing LanOnasis credentials: ```env # Required - Same as your @lanonasis/mcp-core ONASIS_SUPABASE_URL=https://.supabase.co REDACTED_SUPABASE_SERVICE_ROLE_KEY=REDACTED_SUPABASE_SERVICE_ROLE_KEY OPENAI_API_KEY=REDACTED_OPENAI_API_KEY # Optional TRANSPORT=stdio # or 'http' for HTTP mode PORT=3010 # HTTP port (default: 3010) ``` ## Usage ### Stdio Mode (Default) ```bash # Development npm run dev # Production npm start ``` ### HTTP Mode ```bash # Development npm run dev:http # Production npm run start:http ``` ## Available Tools ### 1. `memory_analyze_patterns` Analyze usage patterns and trends in your memory collection. ```json { "user_id": "uuid", "time_range_days": 30, "response_format": "markdown" } ``` **Returns:** - Memory distribution by type and time - Peak activity periods - Tag frequency analysis - AI-generated productivity insights --- ### 2. `memory_suggest_tags` Get AI-powered tag suggestions for a memory. ```json { "memory_id": "uuid", "user_id": "uuid", "max_suggestions": 5, "include_existing_tags": true } ``` **Returns:** - Tag suggestions with confidence scores - Reasoning for each suggestion - Consistency with existing tag vocabulary --- ### 3. `memory_find_related` Find semantically related memories using vector similarity. ```json { "memory_id": "uuid", "user_id": "uuid", "limit": 10, "similarity_threshold": 0.7 } ``` **Returns:** - Related memories ranked by similarity - Shared tags between memories - Content previews --- ### 4. `memory_detect_duplicates` Identify potential duplicate or near-duplicate memories. ```json { "user_id": "uuid", "similarity_threshold": 0.9, "max_pairs": 20 } ``` **Returns:** - Duplicate pairs with similarity scores - Recommendations (keep_newer, merge, etc.) - Estimated storage savings --- ### 5. `memory_extract_insights` Extract key insights and patterns from your knowledge base. ```json { "user_id": "uuid", "topic": "optional focus area", "memory_type": "project", "max_memories": 20 } ``` **Returns:** - Categorized insights (patterns, learnings, opportunities, risks, action items) - Supporting evidence from memories - Confidence scores - Executive summary --- ### 6. `memory_health_check` Analyze the organization quality of your memory collection. ```json { "user_id": "uuid", "response_format": "markdown" } ``` **Returns:** - Overall health score (0-100) - Embedding coverage - Tagging consistency - Type balance analysis - Actionable recommendations --- ### 7. `memory_predictive_recall` (NEW in v2.0.0) AI-powered prediction of memories you'll need based on current context. ```json { "user_id": "uuid", "context": { "current_project": "Building dashboard components", "recent_topics": ["React", "performance"], "context_text": "Optimizing render performance" }, "limit": 5, "min_confidence": 50, "include_serendipity": true } ``` **Returns:** - Predicted memories with confidence scores - Human-readable explanations - Score breakdown (semantic, temporal, frequency, serendipity) - Suggested actions (apply, review, explore, reference) - Personalized greeting with user's name --- ### 8. `memory_prediction_feedback` (NEW in v2.0.0) Record feedback on predictions to improve accuracy over time. ```json { "memory_id": "uuid", "user_id": "uuid", "useful": true, "action": "clicked" } ``` **Returns:** - Personalized thank you message - Feedback confirmation ## Integration with @lanonasis/mcp-core This server is designed to work alongside your existing infrastructure: ``` ┌─────────────────────────┐ ┌──────────────────────────┐ │ @lanonasis/mcp-core │ │ memory-intelligence-mcp │ │ │ │ │ │ ✅ create_memory │ ←── │ 🧠 memory_analyze_patterns │ │ ✅ search_memories │ │ 🏷️ memory_suggest_tags │ │ ✅ update_memory │ ←── │ 🔗 memory_find_related │ │ ✅ delete_memory │ │ 🔍 memory_detect_duplicates│ │ ✅ list_memories │ ←── │ 💡 memory_extract_insights │ │ ✅ API key management │ │ 🏥 memory_health_check │ └─────────────────────────┘ └──────────────────────────┘ │ │ └───────────┬───────────────────────┘ ▼ ┌─────────────────┐ │ Supabase │ │ (Shared DB) │ └─────────────────┘ ``` ### Example Workflow 1. **Create memory** using `@lanonasis/mcp-core` 2. **Get tag suggestions** from `memory_suggest_tags` 3. **Update memory** with suggested tags using core server 4. **Find related memories** to build knowledge connections 5. **Extract insights** periodically to surface learnings 6. **Run health checks** to maintain organization quality ## Claude Desktop Integration Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "lanonasis-core": { "command": "node", "args": ["/path/to/mcp-core/dist/index.js"], "env": { "ONASIS_SUPABASE_URL=https://.supabase.co "ONASIS_SUPABASE_SERVICE_KEY=REDACTED_SUPABASE_SERVICE_ROLE_KEY "OPENAI_API_KEY=REDACTED_OPENAI_API_KEY } }, "memory-intelligence": { "command": "node", "args": ["/path/to/memory-intelligence-mcp-server/dist/index.js"], "env": { "ONASIS_SUPABASE_URL=https://.supabase.co "ONASIS_SUPABASE_SERVICE_KEY=REDACTED_SUPABASE_SERVICE_ROLE_KEY "OPENAI_API_KEY=REDACTED_OPENAI_API_KEY } } } } ``` ## Testing with MCP Inspector ```bash npx @modelcontextprotocol/inspector dist/index.js ``` ## Response Formats All tools support both `markdown` (human-readable) and `json` (machine-readable) formats: ```json // Request with JSON format { "user_id": "...", "response_format": "json" } // Returns structured data { "content": [{ "type": "text", "text": "{...}" }], "structuredContent": { /* typed object */ } } ``` ## Error Handling Tools return actionable error messages: ```json { "isError": true, "content": [ { "type": "text", "text": "Error analyzing patterns: Database connection failed. Try checking your ONASIS_SUPABASE_URL=https://.supabase.co } ] } ``` ## Performance Considerations - **Duplicate detection**: Limited to 500 memories for performance - **Insight extraction**: Uses GPT-4o-mini for cost efficiency - **Vector search**: Requires embeddings in your memory_entries table - **Response truncation**: Automatic at 50,000 characters ## Prerequisites Your Supabase database must have: 1. `memory_entries` table with `embedding` column (vector) 2. `match_memories` RPC function for vector similarity search 3. Standard LanOnasis schema (id, title, content, type, tags, etc.) ## Architecture Benefits ### vs. Embedding in Core Server | Aspect | Monolithic | Intelligence Server | | ------------------ | -------------------------- | -------------------------- | | **Deployment** | Single point of failure | Independent scaling | | **Updates** | Risk to core functionality | Safe to iterate | | **Resource Usage** | Shared memory/CPU | Dedicated resources | | **Testing** | Complex integration tests | Focused unit tests | | **Reusability** | Tied to LanOnasis | Portable to other projects | ## What's Next ### v2.1.0 - Knowledge Gap Detection (Q1 2026) - [ ] "What should I learn next?" recommendations - [ ] Personalized learning paths - [ ] Integration with YouTube, Medium, Dev.to ### v2.2.0 - Team Knowledge Graph (Q2 2026) - [ ] "Who's the expert on X?" finder - [ ] Privacy-first team aggregation - [ ] Expertise scoring and visualization ### v3.0.0 - Market Leadership (Q3 2026) - [ ] Privacy-first local processing (ONNX Runtime) - [ ] Autonomous organization agent - [ ] API marketplace with 70/30 revenue share ### Backlog - [ ] Memory clustering with topic detection - [ ] Automatic summarization of memory collections - [ ] Anomaly detection in memory patterns - [ ] Content quality scoring - [ ] Multi-language support ## Publishing ### npm Publishing ```bash # Build and verify the package npm run publish:dry-run # Publish to npm (requires npm login) npm run publish:npm ``` ### GitHub Packages Publishing To publish to GitHub Packages, update `.npmrc`: ``` @lanonasis:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN} ``` Then publish: ```bash npm publish --access public ``` ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## Database Setup (v2.0.0) For predictive recall features, run the migration: ```bash # Option 1: Supabase CLI supabase db push # Option 2: Copy SQL to Supabase SQL Editor # File: supabase/migrations/20260113_prediction_system.sql ``` This creates: - `prediction_feedback` - Track prediction accuracy - `prediction_history` - Audit log - `increment_access_count()` - Frequency scoring - `get_user_profile_for_predictions()` - Personalization - `has_premium_feature()` - Premium tier gating - `get_prediction_accuracy()` - Metrics ### Premium Tier Setup (Optional) ```sql -- Enable predictive recall for a user UPDATE profiles SET subscription_tier = 'pro', feature_flags = '{"predictive_recall": true}'::jsonb WHERE id = 'user-uuid'; ``` ## License MIT License - See [LICENSE](./LICENSE) for details. --- **Built with care by the LanOnasis team.** We believe AI should anticipate your needs, not just respond to commands. [GitHub](https://github.com/lanonasis/memory-intelligence-engine) | [npm](https://www.npmjs.com/package/@lanonasis/mem-intel-sdk) | [Changelog](./CHANGELOG.md)