@lanonasis/mem-intel-sdk 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-17
+
+### Added
+- Initial release of `@lanonasis/mem-intel-sdk`
+- Core `MemoryIntelligenceClient` with API-based architecture
+- Framework integrations:
+  - React hooks with React Query integration (`/react`)
+  - Vue composables (`/vue`)
+  - Node.js optimized client (`/node`)
+  - MCP Server creation (`/server`)
+- Memory intelligence features:
+  - `analyzePatterns` - Analyze usage patterns and trends
+  - `suggestTags` - AI-powered tag suggestions
+  - `findRelated` - Semantic similarity search
+  - `detectDuplicates` - Duplicate memory detection
+  - `extractInsights` - Extract insights from memories
+  - `healthCheck` - Memory collection health analysis
+- TypeScript support with full type definitions
+- Support for both ESM and CommonJS
+- Comprehensive error handling with custom error classes
+- Dual response format support (JSON and Markdown)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lanonasis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,490 @@
+# 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)
+
+An AI-powered memory intelligence SDK for the LanOnasis Memory-as-a-Service platform. Provides advanced analytics, insights, and intelligent organization features.
+
+## Features
+
+- **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
+
+## 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 (
+    <MemoryIntelligenceProvider config={{ apiKey: 'lano_xxx' }}>
+      <Dashboard />
+    </MemoryIntelligenceProvider>
+  );
+}
+
+// Use hooks in components
+function Dashboard() {
+  const { data, isLoading } = usePatternAnalysis({
+    userId: 'user-123',
+    timeRangeDays: 30,
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  return <div>Total: {data?.total_memories}</div>;
+}
+```
+
+### Vue Integration
+
+```vue
+<script setup>
+import { usePatternAnalysis } from '@lanonasis/mem-intel-sdk/vue';
+
+const { data, loading, execute } = usePatternAnalysis();
+
+onMounted(() => {
+  execute({ userId: 'user-123', timeRangeDays: 30 });
+});
+</script>
+```
+
+## 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-intel-mcp-server
+
+# 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=your_supabase_url
+ONASIS_SUPABASE_SERVICE_KEY=your_service_key
+OPENAI_API_KEY=your_openai_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
+
+## 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": "...",
+        "ONASIS_SUPABASE_SERVICE_KEY": "...",
+        "OPENAI_API_KEY": "..."
+      }
+    },
+    "memory-intelligence": {
+      "command": "node",
+      "args": ["/path/to/memory-intelligence-mcp-server/dist/index.js"],
+      "env": {
+        "ONASIS_SUPABASE_URL": "...",
+        "ONASIS_SUPABASE_SERVICE_KEY": "...",
+        "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 environment variable."
+  }]
+}
+```
+
+## 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 |
+
+## Future Enhancements
+
+- [ ] Memory clustering with topic detection
+- [ ] Automatic summarization of memory collections
+- [ ] Knowledge graph visualization
+- [ ] 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.
+
+## License
+
+MIT License - See [LICENSE](./LICENSE) for details.
+
+---
+
+Built with ❤️ for the LanOnasis platform by following MCP best practices.

package/dist/core/client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Core Memory Intelligence Client
+ */
+import { MemoryIntelligenceConfig, AnalyzePatternsParams, PatternAnalysis, SuggestTagsParams, TagSuggestionsResult, FindRelatedParams, RelatedMemoriesResult, DetectDuplicatesParams, DuplicatesResult, ExtractInsightsParams, InsightsResult, HealthCheckParams, MemoryHealth, QueryMemoriesOptions, MemoryEntry } from "./types";
+import { HttpClient } from "../utils/http-client";
+export declare class MemoryIntelligenceClient {
+    private httpClient;
+    private defaultResponseFormat;
+    constructor(config: MemoryIntelligenceConfig);
+    /**
+     * Get HTTP client for direct API access
+     */
+    getHttpClient(): HttpClient;
+    /**
+     * Query memories from the API
+     */
+    queryMemories(userId: string, options?: QueryMemoriesOptions): Promise<MemoryEntry[]>;
+    /**
+     * Analyze usage patterns and trends in memory collection
+     */
+    analyzePatterns(params: AnalyzePatternsParams): Promise<PatternAnalysis>;
+    /**
+     * Get AI-powered tag suggestions for a memory
+     */
+    suggestTags(params: SuggestTagsParams): Promise<TagSuggestionsResult>;
+    /**
+     * Find semantically related memories using vector similarity
+     */
+    findRelated(params: FindRelatedParams): Promise<RelatedMemoriesResult>;
+    /**
+     * Detect potential duplicate memories
+     */
+    detectDuplicates(params: DetectDuplicatesParams): Promise<DuplicatesResult>;
+    /**
+     * Extract insights and patterns from memories
+     */
+    extractInsights(params: ExtractInsightsParams): Promise<InsightsResult>;
+    /**
+     * Check the health and organization quality of memories
+     */
+    healthCheck(params: HealthCheckParams): Promise<MemoryHealth>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIlD,qBAAa,wBAAwB;IACnC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,qBAAqB,CAAsB;gBAEvC,MAAM,EAAE,wBAAwB;IAkB5C;;OAEG;IACI,aAAa,IAAI,UAAU;IAIlC;;OAEG;IACU,aAAa,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,WAAW,EAAE,CAAC;IAwBzB;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAgB9E;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAgB3E;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAgB5E;;OAEG;IACG,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgBjF;;OAEG;IACG,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC;IAgB7E;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC;CAepE"}

package/dist/core/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SDK-specific error classes
+ */
+export declare class MemoryIntelligenceError extends Error {
+    constructor(message: string);
+}
+export declare class ConfigurationError extends MemoryIntelligenceError {
+    constructor(message: string);
+}
+export declare class MemoryNotFoundError extends MemoryIntelligenceError {
+    constructor(memoryId: string);
+}
+export declare class DatabaseError extends MemoryIntelligenceError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+export declare class EmbeddingError extends MemoryIntelligenceError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+export declare class ValidationError extends MemoryIntelligenceError {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,uBAAuB;gBACjD,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,mBAAoB,SAAQ,uBAAuB;gBAClD,QAAQ,EAAE,MAAM;CAI7B;AAED,qBAAa,aAAc,SAAQ,uBAAuB;IACpB,aAAa,CAAC,EAAE,KAAK;gBAA7C,OAAO,EAAE,MAAM,EAAS,aAAa,CAAC,EAAE,KAAK,YAAA;CAI1D;AAED,qBAAa,cAAe,SAAQ,uBAAuB;IACrB,aAAa,CAAC,EAAE,KAAK;gBAA7C,OAAO,EAAE,MAAM,EAAS,aAAa,CAAC,EAAE,KAAK,YAAA;CAI1D;AAED,qBAAa,eAAgB,SAAQ,uBAAuB;gBAC9C,OAAO,EAAE,MAAM;CAI5B"}