Stickygon by Axefield - MCP Server

Stickygon - Agnostic Persistent Memory System

A sophisticated Model Context Protocol (MCP) server that provides advanced long-term memory capabilities for LLM hosts like Claude Desktop and Cursor. Stickygon is designed to be domain-agnostic, giving AI systems genuine persistent memory with adaptive learning, pattern recognition, and intelligent context management.

🏗️ Core Architecture

Purpose

This server implements domain-agnostic persistent memory for AI systems, allowing them to remember patterns, successful strategies, and learn from outcomes over time. It's designed to provide genuine long-term memory capabilities with semantic understanding, adaptive learning, and intelligent context management.

Technology Stack

TypeScript with ES2022 modules
SQLite (better-sqlite3) for local-first storage with automatic migrations
Vector Similarity Search (vectorlite) for optimized vector operations
MCP SDK for protocol implementation
OpenAI embeddings (with fallback hash-based embeddings)
K-means clustering for memory consolidation
Adaptive ranking algorithms for outcome-based learning
Custom feature extraction (domain-agnostic)
Pattern mining for procedural rule generation

🧠 Memory System Features

Memory Types

The system supports three types of memories:

Episodic: Specific events/experiences
Semantic: General knowledge/facts
Procedural: Rules and procedures

Memory Properties

Each memory includes:

Text content and tags for organization
Importance score (0-1) for prioritization
Confidence level (0-1) for reliability
Embedding vector for semantic search
Usage tracking and decay rates
Pin status for quick access
Expiration dates for temporary memories
Session tracking for context
Belief promotion (semantic facts)
Merging provenance (tracks consolidated memories)

🛠️ Available Tools (19 Total)

Core Memory Operations (6)

memorize - Store new memories with text, tags, importance, type, source, confidence, and custom features
recall - Retrieve memories by query or get recent ones (with smart ranking)
search - Semantic search through stored memories using embeddings
update - Modify existing memory text and regenerate embeddings
forget - Delete a memory by ID
pin - Pin/unpin memories for quick access

Advanced Memory Management (4)

consolidate - Cluster memories using K-means → produce semantic beliefs
extract_rules - Pattern mine executions vs outcomes → emit IF/THEN procedural rules
summarize_day - Create daily summaries with activities, outcomes, key executions
decay - Maintain memory scores and delete/archive stale items
reflect - Write distilled lessons and update procedural rules

Context & Learning (4)

context_broker - Returns exact memory sets for planning/execution/review tasks
grade_context - Provide feedback on context helpfulness for adaptive ranking
label_outcome - Label execution outcomes with success metrics and efficiency
why_this_context - Explain why specific memories were chosen for context

Session & Organization (3)

pin_set - Create curated memory sets for quick access
session_start - Start sessions with goals and tags
session_end - End sessions with summaries and review

Adaptive Learning (3)

track_context_outcome - Track context effectiveness for learning
get_performance_metrics - Get adaptive ranker performance and weights
retrain_ranker - Manually trigger ranker weight retraining

Vector Search (1)

vss_status - Get VSS status and performance metrics

🔍 Smart Search & Ranking

Vector Similarity Search (VSS)

Stickygon now includes optimized vector search using the vectorlite extension:

Native SQLite integration with virtual tables
HNSW algorithm for fast approximate nearest neighbor search
Metadata filtering - combine vector similarity with SQL filters
Automatic fallback to cosine similarity if VSS unavailable
Performance monitoring and status reporting

Adaptive Hybrid Scoring Algorithm

The ranking system combines multiple factors with automatic learning:

60% - Semantic similarity (optimized VSS or cosine similarity)
20% - Recency (exponential decay with ~20.8 day half-life)
15% - Importance score
5% - Usage boost (capped at 0.2)
+0.3 - Pin boost for pinned memories
+0.1 - Helpful boost (user feedback)
Dynamic - Outcome-based boost (learns from results)

Search Capabilities

Vector similarity search with VSS optimization
Semantic search using vector embeddings
Tag-based filtering with vector search
Session-based filtering with vector search
Time-based filtering (today's memories)
Hybrid filtering - combine vector similarity with metadata filters

📚 Context Resources

Available Resources

memory:today - All memories from today (pinned first)
memory:tag/{tag} - Memories under a specific tag

These resources can be pulled directly into the AI's context, making memories immediately available without tool calls.

🔌 Embedding System

Pluggable Providers

Primary: OpenAI text-embedding-3-small (1536 dimensions)
Fallback: Hash-based embeddings (256 dimensions) for offline use
Extensible: Easy to add local models or other providers

Smart Fallback

If no OpenAI API key is provided, the system uses a simple hash-based embedding that still enables basic semantic search.

🗄️ Storage Architecture

SQLite Database

Local-first storage with automatic indexing
JSON storage for complex fields (tags, embeddings, triggers)
Optimized indexes on creation time, tags, and session ID
Automatic schema management

🧮 Advanced Features

Adaptive Learning System

Outcome-based ranking - Memories that lead to wins get boosted
Multi-armed bandit - Learns optimal k values per task type
Weight adjustment - Automatically adjusts ranking weights based on performance
Context tracking - Tracks which memories were helpful for each execution

Memory Consolidation

K-means clustering to group similar memories
Automatic summarization of related memories
Belief promotion for consolidated knowledge
Provenance tracking for merged memories

Pattern Mining & Rules

Feature-based pattern detection from execution records
IF/THEN rule generation with confidence scores
Support threshold filtering (minimum occurrences)
Win-rate analysis for rule validation

Domain Feature Extraction

Custom Features: Any domain-specific features and indicators
Pattern Analysis: Trend analysis, pattern detection, confluence scoring
Performance Metrics: Success rates, efficiency calculations, outcome tracking
Context Analysis: Domain-specific context and regime detection
Setup Detection: Confluence scoring, setup identification
Custom Indicators: User-defined metrics and measurements

Memory Decay & Maintenance

Exponential decay based on age and usage
Automatic archiving of low-importance memories
Configurable decay parameters
Garbage collection for expired memories

Reflection System

Lesson extraction from experiences
Procedural rule creation and updates
Symbol-based organization of knowledge

Session Management

Goal-oriented sessions with symbol tracking
Clean session boundaries for organized memory
Session summaries for performance review

Quick Start

1. Install Dependencies

npm install

2. Build the Project

npm run build

3. Set Environment Variables (Optional)

For OpenAI embeddings (recommended):

# Windows PowerShell
$env:OPENAI_API_KEY="your-openai-api-key-here"

# Or create a .env file
OPENAI_API_KEY=your-openai-api-key-here

4. Set Up Vector Similarity Search (Optional but Recommended)

For optimal performance with large memory datasets, install the vectorlite extension:

# Check VSS status and get installation instructions
npm run setup-vss -- --install-instructions

# Test VSS functionality
npm run test-vss

5. Test the Server

npm start

Configuration

Claude Desktop

Add to your settings.json:

{
  "mcpServers": {
    "stickygon": {
      "command": "node",
      "args": ["C:/Users/p5_pa/Stickygon/dist/index.js"],
      "env": { "PCM_DB": "C:/Users/p5_pa/Stickygon/pcm.db" }
    }
  }
}

Cursor

Add to your Cursor settings:

{
  "mcpServers": {
    "stickygon": {
      "command": "node",
      "args": ["C:/Users/p5_pa/Stickygon/dist/index.js"]
    }
  }
}

🚀 Usage Examples

1. Store Memories with Features

// Store a project plan with features
memorize({
  text: "Project Alpha: React frontend with TypeScript, using Redux for state management",
  tags: ["project", "alpha", "react", "typescript", "redux"],
  importance: 0.9,
  type: "episodic",
  source: "plan",
  confidence: 0.8,
  features: {
    technology: "react",
    language: "typescript",
    stateManagement: "redux",
    priority: "high"
  }
})

2. Get Context for Tasks

// Get context for project planning
context_broker({
  task: "planning",
  tags: ["project", "alpha"],
  k: 5
})
// Returns: latest plan + last 3 executions + active beliefs + relevant rules + important memories

3. Track Execution Outcomes

// Label an execution outcome
label_outcome({
  execId: "exec-123",
  outcome: "success",
  score: 8.5,
  efficiency: 0.85,
  notes: "Completed ahead of schedule"
})

// Track context effectiveness
track_context_outcome({
  contextId: "ctx-456",
  outcome: "success",
  helpful: true
})

4. Extract Rules

// Mine patterns from executions
extract_rules({
  tag: "project",
  minSupport: 3
})
// Returns: IF technology=react & language=typescript THEN SUCCESS (confidence: 75%)

5. Daily Summary

// Get comprehensive daily summary
summarize_day({
  date: "2024-01-15",
  tags: ["project", "development"]
})
// Returns: executions, total score, success rate, key executions, rule breaches, new beliefs

6. Session Management

// Start a work session
session_start({
  goal: "Complete React component implementation",
  tags: ["project", "alpha", "react"]
})

// End session with summary
session_end({
  sessionId: "session-789",
  summary: "3 components completed, 2 bugs fixed, +8.5 score total"
})

7. Adaptive Learning

// Check VSS status and performance
vss_status()
// Returns: VSS availability, vector count, performance metrics, recommendations

// Get performance metrics
get_performance_metrics()
// Returns: success rate, context helpfulness, optimal k values per task

// Retrain ranker based on outcomes
retrain_ranker()
// Adjusts ranking weights based on recent performance

8. Memory Organization

// Create curated memory sets
pin_set({
  name: "React Best Practices",
  ids: ["mem-1", "mem-2", "mem-3"]
})

// Consolidate similar memories
consolidate({
  tag: "react",
  windowDays: 7
})
// Creates semantic beliefs from clustered memories

📁 Project Structure

src/
├── index.ts              # Main MCP server with all 18 tools and handlers
├── memory.ts             # SQLite storage layer with automatic migrations
├── ranker.ts             # Hybrid scoring algorithm for memory ranking
├── adaptive-ranker.ts    # Adaptive learning system with outcome tracking
├── providers/
│   └── embeddings.ts     # Pluggable embedding provider interface
└── types/
    └── kmeans-js.d.ts    # Type definitions for clustering library

🎯 Workflow Integration

Planning Phase

Get Context: Use context_broker to retrieve relevant memories
Review Rules: Check procedural rules from extract_rules
Store Plan: Use memorize to record your plan with features

Execution Phase

Track Execution: Use memorize with source: "execution" to log activities
Monitor Context: Use grade_context to rate memory helpfulness
Update Features: Use custom features for real-time analysis

Review Phase

Label Outcome: Use label_outcome to record execution results
Track Context: Use track_context_outcome for learning
Extract Lessons: Use reflect to create procedural rules
Daily Summary: Use summarize_day for performance review

Continuous Learning

Consolidate Memories: Use consolidate to create semantic beliefs
Mine Patterns: Use extract_rules to discover successful patterns
Retrain System: Use retrain_ranker to optimize memory selection
Monitor Performance: Use get_performance_metrics to track improvement

🎯 Key Strengths

Domain-Agnostic: Built to work with any domain or use case
Adaptive Learning: Automatically learns from outcomes and improves
Local-First: No external dependencies required for core functionality
Semantic Search: Advanced vector-based memory retrieval with context awareness
Smart Ranking: Multi-factor scoring with outcome-based learning
Pattern Recognition: Automatically discovers successful patterns and rules
Performance Tracking: Comprehensive metrics for continuous improvement
Production-Ready: Full error handling, type safety, and automatic migrations
Memory Management: Automatic decay, consolidation, and maintenance
Context Integration: Direct memory access via MCP resources

🚀 What Makes This Special

For Any Domain

Custom Features: Flexible feature extraction for any domain
Pattern Detection: Automatic pattern recognition and rule generation
Outcome Learning: System learns which memories lead to successful outcomes
Rule Mining: Discovers IF/THEN patterns from your execution history
Performance Analytics: Success scores, efficiency, and comprehensive tracking

For AI Systems

Adaptive Ranking: Automatically optimizes memory selection based on outcomes
Context Broker: Provides exactly the right memories for each task
Semantic Understanding: Advanced vector-based memory retrieval
Continuous Learning: Improves over time without manual intervention
Multi-Modal Memory: Episodic, semantic, and procedural memory types

For Developers

Extensible Architecture: Easy to add new features and domain-specific logic
Type Safety: Full TypeScript implementation with comprehensive types
Database Migrations: Automatic schema updates with backward compatibility
MCP Integration: Seamless integration with Claude Desktop and Cursor
Local-First: No cloud dependencies, complete data ownership

🔧 API Reference

Tools

memorize: Store new memories with text, tags, importance, and optional expiration
recall: Retrieve memories by query or get recent ones
search: Semantic search through stored memories
update: Modify existing memory text
forget: Delete a memory by ID
pin: Pin/unpin memories for quick access
decay: Maintain memory scores and delete/archive stale items
reflect: Write distilled lessons and update procedural rules

Resources

memory:today: All memories from today (pinned first)
memory:tag/{tag}: Memories under a specific tag

Prompts

summarize-selected: Compress multiple memories into bullet points

🏛️ Architecture

Storage: SQLite with automatic indexing and JSON field support
Embeddings: Pluggable providers (OpenAI, fallback hash-based)
Ranking: Hybrid scoring algorithm combining similarity, recency, importance, and usage
Transport: MCP stdio transport for easy integration
Memory Types: Episodic, semantic, and procedural memory support
Advanced Features: K-means clustering, memory decay, reflection system

🚀 Development

Build Commands

npm run build    # TypeScript compilation
npm run start    # Run compiled server
npm run dev      # Build and run

Adding New Embedding Providers

Extend the EmbeddingProvider.init() function in src/providers/embeddings.ts:

// Example: Add local model support
if (process.env.LOCAL_MODEL_PATH) {
  // Initialize local embedding model
  return new LocalEmbeddingProvider(process.env.LOCAL_MODEL_PATH);
}

Database Schema

The SQLite database uses the following schema:

CREATE TABLE memories (
  id TEXT PRIMARY KEY,
  text TEXT NOT NULL,
  tags TEXT NOT NULL,           -- JSON array
  importance REAL NOT NULL,
  pinned INTEGER NOT NULL,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL,
  expires_at INTEGER,
  session_id TEXT,
  embedding TEXT NOT NULL,      -- JSON array
  usage INTEGER NOT NULL,
  type TEXT NOT NULL,           -- episodic, semantic, procedural
  source TEXT NOT NULL,         -- plan, signal, execution, account
  confidence REAL NOT NULL,
  last_used INTEGER NOT NULL,
  decay REAL NOT NULL,
  belief INTEGER NOT NULL       -- promoted semantic fact
);

Memory Consolidation Algorithm

The system uses K-means clustering to consolidate similar memories:

Extract embeddings from memories within a time window
Cluster similar memories using K-means (default: 5 clusters)
Create semantic beliefs from cluster summaries
Update provenance to track merged memories
Promote to beliefs with higher confidence scores

Troubleshooting

Common Issues

SQLite errors: Ensure write permissions in the project directory
Build failures: Check TypeScript version compatibility
MCP connection issues: Verify the server path in your host configuration

Debug Mode

Set environment variable for verbose logging:

$env:DEBUG="mcp:*"
npm start

License

MIT License - see LICENSE file for details.