AIMem - Intelligent Memory Management for AI Conversations

AIMem is a Model Context Protocol (MCP) server that provides intelligent memory management for AI conversations, featuring advanced session management, project-aware context storage, and performance monitoring.

🚀 Key Features

Intelligent Session Management

• Project-Aware Sessions: Automatically detects projects and creates persistent sessions
• Deterministic Session IDs: Consistent session IDs based on project characteristics
• Session Hierarchy: Support for main, feature, debug, and experiment sessions
• Legacy Migration: Seamlessly migrates from old session formats
• Multi-Project Support: Handle multiple projects with isolated contexts

Advanced Project Detection

• Git Repository Detection: Automatic Git project recognition
• Workspace Markers: Detects Node.js, Go, Python, Rust, and other project types
• Language & Framework Detection: Intelligent detection of programming languages and frameworks
• Caching: Efficient project detection with smart caching

Performance Monitoring & Debugging

• Real-time Metrics: Track system, session, and operation-level performance
• Memory Usage Tracking: Monitor context memory consumption
• Request Analytics: Latency, error rates, and throughput metrics
• Debug Tools: Comprehensive session state debugging

Enhanced Storage

• Dual Storage: SQLite and Redis support with automatic failover
• Schema Evolution: New project and session tables with foreign key relationships
• Context Relationships: Advanced context linking and retrieval

🛠️ Installation & Setup

Prerequisites

• Go 1.19+
• SQLite 3+ or Redis 6+

Installation

# Clone the repository
git clone https://github.com/yourusername/aimem.git
cd aimem

# Build the server
go build -o aimem cmd/main.go

# Run with default configuration
./aimem

Configuration

Create a config.yaml file:

# Storage configuration
database: "sqlite"  # or "redis"

sqlite:
  database_path: "~/.aimem/aimem.db"
  max_connections: 10
  max_idle_connections: 5
  connection_max_lifetime: 60

redis:
  host: "localhost:6379"
  password: ""
  db: 0
  pool_size: 10

# Memory management
memory:
  max_session_size: "100MB"
  chunk_size: 2048
  max_chunks_per_query: 20
  ttl_default: 24h

# Embedding configuration
embedding:
  model: "sentence-transformers/all-MiniLM-L6-v2"
  cache_size: 1000
  batch_size: 32

# Performance settings
performance:
  compression_enabled: true
  async_processing: true
  cache_embeddings: true
  enable_metrics: true
  metrics_interval: 30s

# Session Manager
session_manager:
  enable_auto_detection: true
  enable_legacy_migration: true
  default_session_type: "main"
  session_cache_size: 100
  session_timeout: 24h
  max_sessions_per_project: 10
  enable_session_hierarchy: true
  auto_cleanup_inactive: true
  inactive_threshold: 168h  # 1 week

# Project Detector
project_detector:
  enable_caching: true
  cache_timeout: 10m
  max_cache_size: 1000
  deep_scan_enabled: true
  git_detection_enabled: true
  workspace_detection_enabled: true
  language_detection_enabled: true
  custom_workspace_markers: []
  ignore_patterns:
    - "node_modules"
    - ".git"
    - "vendor"
    - "target"
    - "build"
    - "dist"

# MCP settings
mcp:
  server_name: "AIMem"
  version: "2.0.0"
  description: "Intelligent Memory Management for AI Conversations"

🎯 Usage

Basic Usage with Claude Desktop

1. Add AIMem to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "aimem": {
      "command": "/path/to/aimem",
      "args": []
    }
  }
}

2. Restart Claude Desktop

3. AIMem tools will be automatically available

Available MCP Tools

Intelligent Session Management

get_or_create_project_session

Automatically creates or retrieves a project-aware session based on working directory.

{
  "working_dir": "/path/to/your/project"  // Optional, defaults to current directory
}

resolve_session

Intelligently resolves session ID, path, or legacy ID to active session.

{
  "session_id_or_path": "session-id-or-/path/to/project"
}

get_session_info

Get detailed information about a session including project metadata.

{
  "session_id": "your-session-id"
}

list_project_sessions

List all sessions for a specific project.

{
  "project_id": "project-hash-id",
  "include_inactive": false
}

create_feature_session

Create a feature-specific session branched from main session.

{
  "parent_session_id": "main-session-id",
  "feature_name": "user-authentication"
}

discover_related_sessions

Find existing sessions related to current project for consolidation.

{
  "working_dir": "/path/to/project"
}

Context Management

store_context

Store conversation context with intelligent processing.

{
  "session_id": "session-id",
  "content": "Your context content here",
  "importance": "high",  // "low", "medium", "high"
  "silent": true
}

context_aware_retrieve

Retrieve relevant context with task-aware intelligence.

{
  "session_id": "session-id",
  "current_task": "Debug authentication issue",
  "task_type": "debugging",  // "analysis", "development", "debugging", etc.
  "auto_expand": true,
  "max_chunks": 10,
  "context_depth": 2,
  "max_response_tokens": 20000
}

retrieve_context

Basic semantic search for context retrieval.

{
  "session_id": "session-id",
  "query": "authentication error handling",
  "max_chunks": 5
}

Performance & Debugging

get_performance_metrics

Get system performance metrics and statistics.

{
  "metric_type": "system",  // "system", "session", "operation", "all"
  "session_id": "session-id"  // Required for session metrics
}

debug_session_state

Get detailed debugging information about session state.

{
  "session_id": "session-id",
  "include_memory": true,
  "include_chunks": false
}

Memory Management

smart_memory_manager

Optimize memory based on session phase with intelligent strategies.

{
  "session_id": "session-id",
  "session_phase": "development",  // "analysis", "development", "testing", "deployment"
  "memory_strategy": "balanced",   // "aggressive", "balanced", "conservative"
  "preserve_important": true
}

summarize_session

Get comprehensive session overview including statistics.

{
  "session_id": "session-id"
}

cleanup_session

Clean old or low-relevance context using configurable strategies.

{
  "session_id": "session-id",
  "strategy": "relevance"  // "ttl", "lru", "relevance"
}

Project Analysis

auto_store_project

Automatically analyze and store project context.

{
  "session_id": "session-id",
  "project_path": "/path/to/project",
  "focus_areas": ["architecture", "api", "database"],
  "importance_threshold": "medium",
  "silent": true
}

🏗️ Architecture

System Components

┌─────────────────────────────────────────────────────────────┐
│                        AIMem Server                         │
├─────────────────┬──────────────────┬─────────────────────────┤
│ MCP Protocol    │ Session Manager  │ Project Detector        │
│ - Tools/List    │ - Auto Detection │ - Git Recognition       │
│ - Tools/Call    │ - Legacy Migration│ - Workspace Detection   │
│ - Initialize    │ - Session Types  │ - Language Detection    │
├─────────────────┼──────────────────┼─────────────────────────┤
│ Performance     │ Storage Layer    │ Context Processing      │
│ - Metrics       │ - SQLite/Redis   │ - Embedding Service     │
│ - Monitoring    │ - Schema         │ - Chunking Service      │
│ - Debug Tools   │ - Relationships  │ - Summarization        │
└─────────────────┴──────────────────┴─────────────────────────┘

Database Schema

Projects Table

CREATE TABLE projects (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    canonical_path TEXT NOT NULL,
    type TEXT NOT NULL,
    git_root TEXT,
    git_remote TEXT,
    language TEXT,
    framework TEXT,
    workspace_markers TEXT, -- JSON array
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_active DATETIME DEFAULT CURRENT_TIMESTAMP,
    status TEXT DEFAULT 'active',
    metadata TEXT -- JSON object
);

Sessions Table

CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    project_id TEXT,
    name TEXT NOT NULL,
    type TEXT NOT NULL DEFAULT 'main',
    parent_session_id TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_active DATETIME DEFAULT CURRENT_TIMESTAMP,
    status TEXT DEFAULT 'active',
    working_dir TEXT,
    metadata TEXT, -- JSON object
    FOREIGN KEY (project_id) REFERENCES projects(id),
    FOREIGN KEY (parent_session_id) REFERENCES sessions(id)
);

Context Chunks Table

CREATE TABLE context_chunks (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    content TEXT NOT NULL,
    summary TEXT,
    embedding BLOB,
    relevance REAL DEFAULT 0.0,
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    ttl INTEGER,
    importance TEXT DEFAULT 'medium',
    metadata TEXT, -- JSON object
    FOREIGN KEY (session_id) REFERENCES sessions(id)
);

Session ID Generation

AIMem generates deterministic session IDs based on project characteristics:

1. Project Detection: Analyze working directory for Git, workspace markers, and language
2. ID Generation: Create hash from project identifier (Git remote URL or canonical path)
3. Session Types:
   • Main: {project-hash}-main
   • Feature: {project-hash}-feature-{uuid}
   • Debug: {project-hash}-debug-{uuid}
   • Experiment: {project-hash}-experiment-{uuid}

Performance Monitoring

The performance monitor tracks:

• System Metrics: Uptime, request count, error rates, latency
• Session Metrics: Per-session request counts, memory usage, activity
• Operation Metrics: Per-operation latency, error rates, throughput

🔧 Development

Building from Source

# Install dependencies
go mod download

# Run tests
go test ./...

# Build for production
go build -ldflags="-s -w" -o aimem cmd/main.go

Project Structure

aimem/
├── cmd/
│   └── main.go              # Application entry point
├── internal/
│   ├── analyzer/            # Project analysis
│   ├── chunker/            # Content chunking
│   ├── embedding/          # Embedding service
│   ├── logger/             # Logging utilities
│   ├── mcp/                # MCP protocol implementation
│   ├── performance/        # Performance monitoring
│   ├── project/            # Project detection
│   ├── server/             # Main server logic
│   ├── session/            # Session management
│   ├── storage/            # Storage backends
│   ├── summarizer/         # Content summarization
│   ├── types/              # Type definitions
│   └── utils/              # Utility functions
├── config.yaml             # Configuration file
├── go.mod
├── go.sum
└── README.md

🎨 Advanced Usage

Custom Project Detection

You can extend project detection by adding custom workspace markers:

project_detector:
  custom_workspace_markers:
    - "my-project.yaml"
    - "custom.config"

Session Hierarchies

Create sophisticated session hierarchies for complex projects:

main-session
├── feature/authentication
├── feature/user-management
├── debug/performance-issue
└── experiment/new-algorithm

Performance Optimization

Configure performance settings for your use case:

performance:
  # For high-throughput scenarios
  async_processing: true
  compression_enabled: true
  cache_embeddings: true
  
  # Monitor every 10 seconds
  metrics_interval: 10s

Memory Management Strategies

Choose appropriate memory management based on your workflow:

• Conservative: Minimal cleanup, preserves most context
• Balanced: Moderate cleanup based on relevance and age
• Aggressive: Aggressive cleanup to minimize memory usage

🐛 Troubleshooting

Common Issues

Session Not Found

Error: Session not found: xyz

Solution: Use resolve_session tool to migrate legacy sessions.

Project Detection Failed

Error: Failed to detect project

Solution: Ensure you're in a Git repository or have workspace markers (package.json, go.mod, etc.).

Memory Usage High

Warning: High memory usage detected

Solution: Use smart_memory_manager tool with appropriate strategy.

Debug Commands

Get detailed session state:

{
  "tool": "debug_session_state",
  "session_id": "your-session",
  "include_memory": true,
  "include_chunks": true
}

Check performance metrics:

{
  "tool": "get_performance_metrics",
  "metric_type": "all"
}

📊 Performance Benchmarks

Typical Performance

• Session Creation: ~5ms
• Context Storage: ~20ms (2KB chunk)
• Context Retrieval: ~15ms (5 chunks)
• Project Detection: ~10ms (cached), ~50ms (fresh)

Memory Usage

• Base Memory: ~50MB
• Per Session: ~1-5MB
• Per Chunk: ~2-10KB (depending on content)

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Model Context Protocol (MCP) specification
• Claude AI for inspiration and testing
• Go community for excellent libraries

AIMem v2.0.0 - Intelligent Memory Management for AI Conversations

For more information, visit our documentation or join our Discord community.