Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@andrebuzeli/advanced-sqlite-memory-bank) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Advanced SQLite Memory Bank MCP v1.9.0

🚀 HIGH PERFORMANCE AI AGENT MEMORY SYSTEM 10 specialized tools for comprehensive project management and AI context handling

🌟 Features

🧠 10 Specialized Tools

Tool	Purpose	Key Features
Task Manager	Hierarchical task management	3-level hierarchy, batch operations, time tracking
Memory Manager	AI-optimized memory storage	Semantic search, vector embeddings, auto-clustering
Plan Manager	Strategic planning	Goal tracking, milestone management, progress monitoring
Change History	Complete audit trail	Precise timestamps, comprehensive metadata, advanced querying
Remember Tool	Unified search & retrieval	Cross-entity search, bookmarking, recent activity
Reasoning Tool	Advanced coding analysis	Debug step-by-step, architecture reasoning, code review
Code Snippet Manager	Reusable code storage	Usage tracking, categorization, batch operations
AI Context Manager	Conversation context	Decision logging, pattern analysis, insight generation
Goal Manager	Long-term objectives	Progress tracking, milestone management, analytics
Search Manager	Intelligent search	Global, semantic, fuzzy search with learning

⚡ High Performance Features

🚀 SQLite Optimized - High-performance database operations with connection pooling
📦 Protocol Buffers - Efficient data serialization and storage
⚡ Batch Operations - Multiple CRUD operations in single API calls
🔍 Semantic Search - AI-powered content discovery with vector embeddings
🧠 Vector Embeddings - Advanced similarity matching and clustering
💾 Intelligent Caching - Smart data caching for optimal performance
🔄 Real-time Sync - Automatic synchronization across entities
🎨 Formatação Padronizada - Respostas sempre legíveis em Markdown estruturado

🔗 Comprehensive Linking System

graph TD
    A[Memory] <--> B[Task]
    A <--> C[Plan]
    A <--> D[Goal]
    B <--> C
    B <--> D
    C <--> D
    
    A --> E[Search Manager]
    B --> E
    C --> E
    D --> E
    
    E --> F[Remember Tool]
    E --> G[Analytics]

Relationship Types:

implements - Memory implements Task
supports - Memory supports Plan
contains - Plan contains Task
belongs_to - Task belongs to Plan
depends_on - Task depends on another Task
achieves - Task achieves Goal

🏗️ Architecture

graph TB
    subgraph "MCP Server"
        A[SQLite Manager] --> B[Cache Manager]
        A --> C[Semantic Engine]
        B --> D[Task Manager]
        B --> E[Memory Manager]
        B --> F[Plan Manager]
        C --> G[Search Manager]
        C --> H[Remember Tool]
        D --> I[Reasoning Tool]
        E --> J[Code Snippet Manager]
        F --> K[AI Context Manager]
        G --> L[Goal Manager]
    end
    
    subgraph "Database Layer"
        M[(SQLite Database)]
        N[Vector Store]
        O[Protocol Buffers]
    end
    
    A --> M
    C --> N
    A --> O

📦 Installation

Prerequisites

Node.js 18+
TypeScript 4.5+
SQLite3

Install from NPM

npm install @andrebuzeli/advanced-sqlite-memory-bank

Install from Source

git clone https://github.com/Andre-Buzeli/advanced-sqlite-memory-bank.git
cd advanced-sqlite-memory-bank
npm install
npm run build

🚀 Quick Start

Basic Setup

import { SQLiteMemoryBank } from '@andrebuzeli/advanced-sqlite-memory-bank';

// Initialize the MCP server
const server = new SQLiteMemoryBank();
await server.start();

// Your project path (project name extracted automatically)
const projectPath = "/path/to/your/project";

MCP Configuration

Add to your mcp.json:

{
  "mcpServers": {
    "advanced-sqlite-memory-bank": {
      "command": "npx",
      "args": ["@andrebuzeli/advanced-sqlite-memory-bank"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

🛠️ Tools Overview

📋 Task Manager

// Create hierarchical tasks
const task = await taskManager.create(
  projectPath, 
  "Implement Authentication", 
  "User login and registration system",
  1, // level (1-3)
  null, // parentId
  8, // priority (1-10)
  ["backend", "security"] // tags
);

// Batch operations
const tasks = await taskManager.batchCreate(projectPath, [
  { title: "Setup Database", level: 1, priority: 9, tags: ["database"] },
  { title: "Create API", level: 1, priority: 8, tags: ["api"] }
]);

// Update status with error handling
await taskManager.updateStatus(projectPath, taskId, "error", "API endpoint not responding");

🧠 Memory Manager

// Create AI-optimized memories
const memory = await memoryManager.create(
  projectPath,
  "Architecture Decisions",
  "System architecture choices",
  "Using React + Node.js + PostgreSQL with Redis cache",
  9, // importance (1-10)
  ["architecture", "tech-stack"]
);

// Semantic search
const results = await memoryManager.semanticSearch(
  projectPath, 
  "database performance optimization", 
  5
);

// Auto-cluster similar memories
const clusters = await memoryManager.autoCluster(projectPath, 0.7);

📊 Plan Manager

// Create strategic plans
const plan = await planManager.create(
  projectPath,
  "Q1 2024 Roadmap",
  "First quarter development goals",
  9, // priority
  ["roadmap", "2024", "q1"]
);

// Link plans and tasks
await planManager.linkToTask(projectPath, planId, taskId, "contains");
await planManager.linkPlans(projectPath, sourcePlanId, targetPlanId, "depends_on");

📝 Change History

// Record any change with precise timestamps
const change = await changeHistory.recordChange(
  projectPath,
  "update", // changeType
  "task", // entityType
  "modified", // action
  "Updated task priority and added deadline",
  {
    entityId: "T-123456",
    importance: 7,
    tags: ["priority", "deadline"],
    sessionId: "session-001",
    beforeValue: { priority: 5 },
    afterValue: { priority: 8, deadline: "2024-12-31" }
  }
);

// Get complete audit trail
const history = await changeHistory.getHistory(
  projectPath,
  {
    changeType: "update",
    entityType: "task",
    dateFrom: new Date("2024-01-01"),
    limit: 50
  }
);

// Get statistics and analytics
const stats = await changeHistory.getStatistics(projectPath, {
  startDate: new Date("2024-01-01"),
  endDate: new Date("2024-12-31")
});

console.log(`Total changes: ${stats.total_changes}`);
console.log(`Unique change types: ${stats.unique_change_types}`);

// Search through change history
const searchResults = await changeHistory.searchHistory(
  projectPath,
  "authentication", // search term
  { limit: 20 }
);

// Export history for analysis
const exportedData = await changeHistory.exportHistory(
  projectPath,
  { entityType: "task" },
  "json" // or "csv"
);

Key Features:

Precise Timestamps: UTC and local time with millisecond precision
Comprehensive Metadata: Before/after values, user info, session tracking
Advanced Filtering: By type, entity, file, session, date ranges
Full Text Search: Search through descriptions and metadata
Statistics & Analytics: Activity summaries, change frequency analysis
Batch Operations: Record multiple changes efficiently
Export Capabilities: JSON/CSV export for external analysis
Automatic Cleanup: Remove old history to manage database size

🔍 Remember Tool

// Unified search across all entities
const results = await rememberTool.search(
  projectPath,
  "authentication",
  "all", // search all types
  10 // max results
);

// Bookmark important items
await rememberTool.bookmarkItem(
  projectPath,
  "T-123456",
  "task",
  "critical",
  "High priority authentication task"
);

// Get recent activity
const activity = await rememberTool.recentActivity(
  projectPath,
  10, // limit
  ["task", "memory", "plan"], // types
  "days" // time window
);

🤖 Reasoning Tool

// Analyze code for issues
const analysis = await reasoningTool.analyzeCode(
  projectPath,
  `async function processPayment(amount, cardToken) {
    const payment = await stripe.charges.create({
      amount: amount * 100,
      currency: 'usd',
      source: cardToken
    });
    return payment;
  }`,
  "javascript",
  "Review security vulnerabilities"
);

// Debug step-by-step
const debug = await reasoningTool.debugStepByStep(
  projectPath,
  "const user = null; console.log(user.name);",
  "TypeError: Cannot read property 'name' of null",
  "javascript"
);

// Architecture reasoning
const architecture = await reasoningTool.architectureReasoning(
  projectPath,
  "E-commerce platform",
  ["scalability", "performance", "security"],
  ["budget constraints", "small team"]
);

🔗 Entity Linking System

Create Links Between Entities

// Memory ↔ Task
await memoryManager.linkToTask(projectPath, "Architecture", "T-123", "implements");

// Memory ↔ Plan  
await memoryManager.linkToPlan(projectPath, "Architecture", "P-456", "supports");

// Task ↔ Plan
await taskManager.linkToPlan(projectPath, "T-123", "P-456", "belongs_to");

// Goal ↔ Plan
await goalManager.linkToPlan(projectPath, "G-789", "P-456", "achieves");

// Goal ↔ Task
await goalManager.linkToTask(projectPath, "G-789", "T-123", "requires");

Query Links

// Get all links for a memory
const memoryLinks = await memoryManager.getMemoryLinks(projectPath, "Architecture");

// Get all links for a plan
const planLinks = await planManager.getPlanLinks(projectPath, "P-456");

// Get all links for a goal
const goalLinks = await goalManager.getGoalLinks(projectPath, "G-789");

📊 Batch Operations

All manager tools support efficient batch operations:

Task Manager Batch Operations

// Batch create tasks
const tasks = await taskManager.batchCreate(projectPath, [
  { title: "Task 1", description: "Description 1", level: 1, priority: 8, tags: ["urgent"] },
  { title: "Task 2", description: "Description 2", level: 1, priority: 6, tags: ["normal"] }
]);

// Batch update tasks
await taskManager.batchUpdate(projectPath, [
  { taskId: "T-123", updates: { priority: 9, status: "in-progress" } },
  { taskId: "T-456", updates: { description: "Updated description" } }
]);

// Batch delete tasks
await taskManager.batchDelete(projectPath, ["T-123", "T-456"]);

// Batch status update
await taskManager.batchStatusUpdate(projectPath, [
  { taskId: "T-123", status: "complete" },
  { taskId: "T-456", status: "error", errorReason: "API timeout" }
]);

Memory Manager Batch Operations

// Batch create memories
const memories = await memoryManager.batchCreate(projectPath, [
  { topicName: "Bug Report", content: "Login issue in Safari", importance: 8, tags: ["bug"] },
  { topicName: "Feature Request", content: "Add dark mode", importance: 6, tags: ["feature"] }
]);

Plan Manager Batch Operations

// Batch create plans
const plans = await planManager.batchCreate(projectPath, [
  { name: "Q1 Goals", description: "First quarter objectives", priority: 9, tags: ["quarterly"] },
  { name: "Technical Debt", description: "Address technical debt", priority: 7, tags: ["maintenance"] }
]);

🔍 Advanced Search

Global Search

// Search across all entities
const results = await searchManager.globalSearch(
  projectPath,
  "authentication",
  10 // max results
);

Semantic Search

// AI-powered semantic search
const semanticResults = await searchManager.semanticSearch(
  projectPath,
  "user login security",
  5
);

Type-Specific Search

// Search only in tasks
const taskResults = await searchManager.searchByType(
  projectPath,
  "bug fix",
  "task",
  10
);

// Search only in memories
const memoryResults = await searchManager.searchByType(
  projectPath,
  "architecture",
  "memory",
  5
);

Fuzzy Search

// Search with typo tolerance
const fuzzyResults = await searchManager.fuzzySearch(
  projectPath,
  "autentication", // typo in "authentication"
  5
);

🧠 AI Context Management

Save Conversation Context

await aiContextManager.saveConversationContext(
  projectPath,
  "conv-123",
  "technical",
  "Discussion about implementing Redis cache for session management",
  { topic: "caching", complexity: "medium" },
  ["cache", "redis", "sessions"],
  8 // importance
);

Log Decisions

await aiContextManager.logDecision(
  projectPath,
  "architecture",
  "Choose Redis over Memcached for caching",
  ["Redis", "Memcached", "In-memory cache"],
  "Redis offers better data structures and persistence",
  "Improved performance and data durability",
  "Performance improved by 40%",
  9 // confidence level
);

Generate Insights

const insights = await aiContextManager.generateInsights(
  projectPath,
  "decision",
  "performance",
  0.8, // min confidence
  true // include actionable items
);

📈 Analytics & Insights

Goal Analytics

const goalAnalytics = await goalManager.goalAnalytics(projectPath);
// Returns: total goals, completion rate, category distribution, etc.

Search Analytics

const searchAnalytics = await searchManager.searchAnalytics(projectPath);
// Returns: popular queries, search trends, result effectiveness

Code Snippet Usage Analysis

const snippetAnalytics = await codeSnippetManager.analyzeSnippetUsage(
  projectPath,
  "language", // group by language
  true, // include trends
  0, // min usage threshold
  "json" // export format
);

⚡ Performance Features

Database Optimization

Connection Pooling - Efficient database connections
Query Optimization - Indexed queries for fast retrieval
Batch Operations - Reduced database round trips
Caching Layer - Intelligent data caching

Memory Management

Vector Embeddings - Fast semantic similarity search
Auto-clustering - Automatic grouping of similar content
Memory Decay - Automatic importance adjustment
Cleanup - Orphaned data removal

Search Performance

FTS5 Integration - Full-text search capabilities
Semantic Indexing - Vector-based similarity search
Fuzzy Matching - Typo-tolerant search
Result Caching - Frequently accessed results cached

📝 Complete Examples

Full Project Workflow

// 1. Create a comprehensive project plan
const plan = await planManager.create(
  projectPath, 
  "E-commerce Platform", 
  "Build a modern e-commerce platform with React, Node.js, and PostgreSQL",
  9, 
  ["ecommerce", "web", "fullstack"]
);

// 2. Create tasks with hierarchy
const tasks = await taskManager.batchCreate(projectPath, [
  { title: "Backend Development", level: 1, priority: 9, tags: ["backend"] },
  { title: "Database Setup", level: 2, parentId: "T-001", priority: 9, tags: ["database"] },
  { title: "API Development", level: 2, parentId: "T-001", priority: 8, tags: ["api"] },
  { title: "Frontend Development", level: 1, priority: 8, tags: ["frontend"] },
  { title: "React Components", level: 2, parentId: "T-004", priority: 7, tags: ["react"] }
]);

// 3. Create memories for knowledge management
const memories = await memoryManager.batchCreate(projectPath, [
  { 
    topicName: "Architecture", 
    content: "Microservices architecture with React frontend, Node.js API, PostgreSQL database, Redis cache",
    importance: 9, 
    tags: ["architecture", "microservices"] 
  },
  { 
    topicName: "Database Schema", 
    content: "Users, Products, Orders, Cart tables with proper indexing",
    importance: 8, 
    tags: ["database", "schema"] 
  },
  { 
    topicName: "Known Issues", 
    content: "Cart persistence issue in Safari, payment gateway timeout",
    importance: 7, 
    tags: ["bugs", "critical"] 
  }
]);

// 4. Create goals for tracking
const goal = await goalManager.create(
  projectPath,
  "Launch MVP",
  "Launch minimum viable product by end of Q1",
  "Business",
  9,
  "2024-03-31",
  0,
  ["Backend Complete", "Frontend Complete", "Testing", "Deployment"],
  8,
  "Market validation",
  "Revenue generation"
);

// 5. Link everything together
await planManager.linkToTask(projectPath, plan.id, tasks[0].id, "contains");
await memoryManager.linkToTask(projectPath, "Architecture", tasks[0].id, "implements");
await memoryManager.linkToPlan(projectPath, "Architecture", plan.id, "supports");
await goalManager.linkToPlan(projectPath, goal.id, plan.id, "achieves");

// 6. Track progress
await taskManager.updateStatus(projectPath, tasks[0].id, "in-progress");
await goalManager.trackProgress(projectPath, goal.id, 25);

// 7. Search and analyze
const searchResults = await searchManager.globalSearch(projectPath, "database", 10);
const relatedMemories = await memoryManager.findRelated(projectPath, "Architecture", 5);
const goalProgress = await goalManager.evaluateProgress(projectPath, goal.id);

AI-Assisted Development

// Use reasoning tool for code analysis
const codeAnalysis = await reasoningTool.analyzeCode(
  projectPath,
  `function calculateTotal(items) {
    let total = 0;
    for (let i = 0; i < items.length; i++) {
      total += items[i].price * items[i].quantity;
    }
    return total;
  }`,
  "javascript",
  "Optimize for performance and add error handling"
);

// Debug issues step by step
const debugAnalysis = await reasoningTool.debugStepByStep(
  projectPath,
  "const user = getUserById(null);",
  "TypeError: Cannot read property 'id' of null",
  "javascript"
);

// Get architecture recommendations
const archRecommendations = await reasoningTool.architectureReasoning(
  projectPath,
  "High-traffic e-commerce API",
  ["scalability", "performance", "reliability"],
  ["budget constraints", "small team", "tight deadline"]
);

🔧 Configuration

Environment Variables

# Optional: Custom database path
export MEMORY_BANK_DB_PATH="/custom/path/to/database"

# Optional: Cache size limit
export MEMORY_BANK_CACHE_SIZE="100MB"

# Optional: Enable debug logging
export MEMORY_BANK_DEBUG="true"

MCP Server Configuration

{
  "mcpServers": {
    "advanced-sqlite-memory-bank": {
      "command": "npx",
      "args": ["@andrebuzeli/advanced-sqlite-memory-bank"],
      "env": {
        "NODE_ENV": "production",
        "MEMORY_BANK_DEBUG": "false"
      }
    }
  }
}

Database Schema

The system automatically creates optimized SQLite tables:

memories - AI-optimized memory storage
tasks - Hierarchical task management
plans - Strategic planning data
goals - Long-term objectives
*_links - Cross-entity relationships
*_analytics - Usage and performance data

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/Andre-Buzeli/advanced-sqlite-memory-bank.git
cd advanced-sqlite-memory-bank
npm install
npm run dev

Running Tests

npm test
npm run test:coverage

Code Style

TypeScript strict mode
ESLint configuration
Prettier formatting
Conventional commits

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links & Resources

Repositories

GitHub: https://github.com/Andre-Buzeli/advanced-sqlite-memory-bank
Gitea: http://nas-ubuntu:3000/andrebuzeli/advanced-sqlite-memory-bank

Package Managers

NPM: https://www.npmjs.com/package/@andrebuzeli/advanced-sqlite-memory-bank

Documentation

API Reference: docs/API.md
Architecture Guide: docs/ARCHITECTURE.md
Performance Guide: docs/PERFORMANCE.md

Community

Issues: GitHub Issues
Discussions: GitHub Discussions
Discord: AI Development Community

📞 Support

Documentation: Check the docs folder
Issues: Open a GitHub Issue
Discussions: Join GitHub Discussions
Email: andrebuzeli@gmail.com

Made with ❤️ for the AI community

Empowering AI agents with intelligent memory and context management