@lanonasis/mem-intel-sdk

Memory Intelligence SDK 🧠✨

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.

// 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

# 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:

npm install react @tanstack/react-query

For Vue applications:

npm install vue

For MCP Server:

npm install @modelcontextprotocol/sdk

Quick Start

Basic Usage

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

import { NodeMemoryIntelligenceClient } from "@lanonasis/mem-intel-sdk/node";

// Automatically reads LANONASIS_API_KEY from environment
const client = NodeMemoryIntelligenceClient.fromEnv();

React Integration

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

<script setup>
import { usePatternAnalysis } from "@lanonasis/mem-intel-sdk/vue";

const { data, loading, execute } = usePatternAnalysis();

onMounted(() => {
  execute({ userId: "user-123", timeRangeDays: 30 });
});
</script>

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

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

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

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

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

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

// 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)

// 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

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 <div>Finding relevant memories...</div>;

  return (
    <div>
      <h2>{data?.personalization?.greeting}</h2>
      {data?.predictions.map(pred => (
        <div key={pred.id} onClick={() => recordFeedback({
          memoryId: pred.id,
          userId,
          useful: true,
          action: "clicked"
        })}>
          <span className="confidence">{pred.confidence}%</span>
          <h3>{pred.title}</h3>
          <p>{pred.reason}</p>
        </div>
      ))}
    </div>
  );
}

Scoring Algorithm

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:

# 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:

# Required - Same as your @lanonasis/mcp-core
ONASIS_SUPABASE_URL=https://<project-ref>.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)

# Development
npm run dev

# Production
npm start

HTTP Mode

# 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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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:

{
  "mcpServers": {
    "lanonasis-core": {
      "command": "node",
      "args": ["/path/to/mcp-core/dist/index.js"],
      "env": {
        "ONASIS_SUPABASE_URL=https://<project-ref>.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://<project-ref>.supabase.co
        "ONASIS_SUPABASE_SERVICE_KEY=REDACTED_SUPABASE_SERVICE_ROLE_KEY
        "OPENAI_API_KEY=REDACTED_OPENAI_API_KEY
      }
    }
  }
}

Testing with MCP Inspector

npx @modelcontextprotocol/inspector dist/index.js

Response Formats

All tools support both markdown (human-readable) and json (machine-readable) formats:

// 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:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error analyzing patterns: Database connection failed. Try checking your ONASIS_SUPABASE_URL=https://<project-ref>.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

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

# 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:

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:

# 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)

-- 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 for details.

Built with care by the LanOnasis team.

We believe AI should anticipate your needs, not just respond to commands.

GitHub | npm | Changelog