Claude Desktop Instance
        ↓ (MCP Protocol)
┌─────────────────────────────────────────┐
│   Memory Engine MCP Server               │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ MCP Tool Layer                     │  │
│  │ (save, search, retrieve, optimize) │  │
│  └──────────────┬─────────────────────┘  │
│                 ↓                        │
│  ┌────────────────────────────────────┐  │
│  │ Prompt Builder & Optimizer         │  │
│  └──────────────┬─────────────────────┘  │
│                 ↓                        │
│  ┌────────────────────────────────────┐  │
│  │ Intelligent Retrieval Engine       │  │
│  │ (multi-factor ranking)             │  │
│  └──────────────┬─────────────────────┘  │
│                 ↓                        │
│  ┌────────────────────────────────────┐  │
│  │ Memory Layer System (L1-L4)        │  │
│  └──────────────┬─────────────────────┘  │
│                 ↓                        │
│  ┌────────────────────────────────────┐  │
│  │ SQLite Database (~/.cache/claude)  │  │
│  └────────────────────────────────────┘  │
└─────────────────────────────────────────┘

# Clone repository
git clone https://github.com/yourusername/claude-memory-engine.git
cd claude-memory-engine

# Install dependencies
npm install

# Build TypeScript
npm run build

# Initialize database
npm run init-db

# Start MCP server
npm start

{
  "mcpServers": {
    "claude-memory": {
      "command": "node",
      "args": ["/path/to/claude-memory-engine/dist/index.js"],
      "env": {
        "CLAUDE_MEMORY_BUDGET": "2000",
        "LOG_LEVEL": "info"
      }
    }
  }
}

/save_memory - Save facts/decisions/tasks explicitly
/search_memory - Search by keyword, entity, type
/retrieve_context - Get optimized context for request
/update_memory - Modify existing record
/delete_memory - Remove record
/optimize_prompt - Compress prompt within budget
/memory_stats - View memory metrics and recommendations
/explain_context - Show why a record was retrieved
/export_memory - Export to JSON/CSV/Markdown
/import_memory - Restore from export

# Database location
CLAUDE_MEMORY_DB=~/.cache/claude-memory/memory.db

# Token budget (1000-∞)
CLAUDE_MEMORY_BUDGET=2000

# Enable compression
CLAUDE_MEMORY_COMPRESSION=true

# Enable deduplication
CLAUDE_MEMORY_DEDUP=true

# Enable embeddings (requires model)
CLAUDE_MEMORY_EMBEDDINGS=false

# Auto cleanup interval (ms)
CLAUDE_MEMORY_CLEANUP_INTERVAL=3600000

# Log level
LOG_LEVEL=info

// Minimal mode (1000 tokens)
CLAUDE_MEMORY_BUDGET=1000
CLAUDE_MEMORY_COMPRESSION=true

// Balanced mode (2000 tokens) - Default
CLAUDE_MEMORY_BUDGET=2000

// Comprehensive mode (4000 tokens)
CLAUDE_MEMORY_BUDGET=4000

// No limit (not recommended)
CLAUDE_MEMORY_BUDGET=-1

User: "What was our database decision?"
Needed: Retrieve last 50 messages (~3000 tokens)
        Summarize into context (~1000 tokens overhead)
        Answer query (~500 tokens)
Total: ~4500 tokens

User: "What was our database decision?"
Needed: Search "decision" entity (~50ms)
        Find 2-3 relevant records (~100 tokens)
        Return with relationships (~200 tokens)
Total: ~300 tokens (93% reduction)

src/
  ├── index.ts                 # MCP server entry
  ├── config.ts               # Configuration
  ├── types.ts                # TypeScript types
  ├── database/
  │   ├── connection.ts       # SQLite management
  │   ├── schema.ts           # Database schema
  │   └── migrations.ts       # Schema versions
  ├── memory/
  │   ├── layers.ts           # L1-L4 layer system
  │   ├── retrieval.ts        # Search & ranking
  │   ├── extraction.ts       # Fact extraction
  │   └── deduplication.ts    # Merging logic
  ├── prompt/
  │   ├── builder.ts          # Prompt assembly
  │   ├── tokenizer.ts        # Token counting
  │   └── budget.ts           # Budget management
  ├── tools/
  │   ├── memory-tools.ts     # CRUD operations
  │   ├── retrieval-tools.ts  # Context retrieval
  │   └── optimization-tools.ts
  └── utils/
      ├── logger.ts           # Structured logging
      ├── ranking.ts          # Scoring engine
      ├── text-processing.ts  # NLP helpers
      └── tokenizer.ts        # Token counter

# All tests
npm test

# Watch mode
npm test:watch

# Coverage report
npm test:coverage

# Specific suite
npm test -- memory.test.ts

# Run performance benchmarks
npm run benchmark

# Profile specific operation
npm run benchmark -- --profile retrieval

# Development
npm run dev

# Production build
npm run build

# Type checking
npx tsc --noEmit

import { ExtractionEngine } from './memory/extraction';

const engine = new ExtractionEngine({
  minFactImportance: 5,
  extractCodeReferences: true,
  customPatterns: {
    'technology_stack': /stack:?\s*([^,\n]+)/gi,
    'api_endpoint': /endpoint:\s*([^\s]+)/gi,
  }
});

const result = engine.extract(claudeResponse);

import { EmbeddingModel } from './memory/embeddings';

const embedder = new EmbeddingModel('all-MiniLM-L6-v2');
await embedder.initialize();

// Embeddings automatically generated on save
const results = await retrievalEngine.semanticSearch(
  'database architecture',
  { useEmbeddings: true }
);

# Export all decisions to Markdown
curl -X POST http://localhost:3000/export \
  -d '{"format": "markdown", "type": "decision"}'

# Export facts as CSV
npm run export -- --type facts --format csv --output facts.csv

# Import from backup
npm run import -- --file backup.json --strategy merge

class DomainSpecificRetriever extends BaseRetriever {
  async retrieve(query: RetrievalQuery): Promise<RetrievalResult> {
    // Custom logic
  }
}

class CustomExtractor extends BaseExtractor {
  extractCustomType(text: string): CustomItem[] {
    // Domain-specific extraction
  }
}

class CrossEncoderReranker {
  rerank(items: RetrievalResult[]): RetrievalResult[] {
    // Use larger model for final ranking
  }
}

# Analyze memory distribution
npm run analyze

# Adjust retention policy in config.ts
# Increase MEMORY_RETENTION_POLICY archiveAfterDays
# Lower minFactImportance threshold

# Manually cleanup old records
curl -X POST http://localhost:3000/cleanup --data '{"olderThanDays": 60}'

# Check indexes are present
npm run analyze -- --indexes

# Consider enabling embeddings
CLAUDE_MEMORY_EMBEDDINGS=true npm start

# Reduce context budget
CLAUDE_MEMORY_BUDGET=1000 npm start

# Run VACUUM
npm run analyze -- --optimize

# Export important records, delete others
npm run export -- --type decision --output decisions.json

# Minimize mode
CLAUDE_MEMORY_BUDGET=1000
CLAUDE_MEMORY_COMPRESSION=true
CLAUDE_MEMORY_CLEANUP_INTERVAL=7200000  # 2 hours

# Maximum mode
CLAUDE_MEMORY_BUDGET=4000
CLAUDE_MEMORY_EMBEDDINGS=true
CLAUDE_MEMORY_DEDUP=true

git clone https://github.com/yourusername/claude-memory-engine.git
cd claude-memory-engine
npm install && npm run build && npm start