Memory System

Remember decisions, preferences, and error patterns across sessions. No more context loss.

The Problem

Every time you start a new AI coding session, you lose context:

• Decisions you've made about architecture
• Your coding preferences and style
• Error patterns you've encountered and fixed
• Research you've done on APIs and libraries

You end up re-explaining the same things, re-discovering the same patterns. That's wasted time and cognitive overhead.

The Solution

Sugar Memory persists this knowledge and makes it searchable. Store memories with sugar remember, search with sugar recall, and integrate with Claude Code via MCP server.

Installation

# Install with memory support (enables semantic search)
pipx install 'sugarai[memory]'

# Or all features
pipx install 'sugarai[all]'

Memory works without these dependencies (using keyword search), but semantic search requires sentence-transformers.

Quick Start

# Store a preference
sugar remember "Always use async/await, never callbacks" --type preference

# Store a decision
sugar remember "Chose JWT with RS256 for auth tokens" --type decision

# Search memories
sugar recall "authentication"

# List all memories
sugar memories

Memory Types

Sugar organizes memories into six categories:

CLI Commands

sugar remember

Store a new memory with optional metadata:

# Basic preference
sugar remember "Use 4-space indentation for Python"

# Decision with tags
sugar remember "Chose Redis for session storage" --type decision --tags "architecture,redis"

# Research with expiration
sugar remember "Stripe API rate limit is 100/sec" --type research --ttl 90d

# File context
sugar remember "handles OAuth callback flow" --type file_context --file src/auth/callback.py

# High importance
sugar remember "NEVER use eval() for security reasons" --type preference --importance 2.0

Options

• --type TYPE - Memory type (default: decision)
• --tags TEXT - Comma-separated tags
• --file PATH - Associate with a file
• --ttl TEXT - Time to live: 30d, 90d, 1y, never
• --importance FLOAT - Importance score 0.0-2.0

sugar recall

Search memories with semantic or keyword matching:

# Basic search
sugar recall "authentication"

# Filter by type
sugar recall "database errors" --type error_pattern

# JSON output for scripting
sugar recall "stripe" --format json

# Full details
sugar recall "architecture decisions" --format full --limit 5

Options

• --type TYPE - Filter by memory type
• --limit INT - Maximum results (default: 10)
• --format FORMAT - Output: table, json, full

Other Commands

• sugar memories - List all memories with filtering
• sugar forget <id> - Delete a memory
• sugar export-context - Export for Claude Code hook
• sugar memory-stats - Show statistics

Claude Code Integration

Sugar Memory integrates with Claude Code in two ways:

1. MCP Server (Recommended)

Give Claude Code full access to your memory:

# One command to add
claude mcp add sugar -- sugar mcp memory

Or add manually to ~/.claude.json:

{
  "mcpServers": {
    "sugar": {
      "type": "stdio",
      "command": "sugar",
      "args": ["mcp", "memory"]
    }
  }
}

MCP Tools Available

2. SessionStart Hook

Auto-inject context at the start of every Claude Code session:

Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "sugar export-context"
      }]
    }]
  }
}

Semantic vs Keyword Search

Sugar supports two search modes:

Semantic Search (Recommended)

Uses AI embeddings to find conceptually similar memories:

• "auth issues" finds memories about "authentication", "login", "JWT"
• Understands synonyms and related concepts
• Requires sentence-transformers package

Keyword Search (Fallback)

Uses SQLite FTS5 for text matching:

• Fast and lightweight
• No additional dependencies
• Matches exact words/phrases

Sugar automatically uses semantic search when available, falling back to keyword search otherwise.

What to Remember

Good Memories

• Architecture decisions and their rationale
• Coding conventions specific to the project
• Error patterns you've debugged
• API quirks and workarounds
• File/module responsibilities

Less Useful

• Generic programming knowledge (Claude already knows)
• Highly volatile information
• Large code blocks (use file context instead)

Storage

Memories are stored per-project in .sugar/memory.db:

.sugar/
├── config.yaml
├── sugar.db      # Task queue
└── memory.db     # Memory database

Backup & Export

# Export all memories to JSON
sugar memories --format json > memories-backup.json

# Copy database directly
cp .sugar/memory.db memory-backup.db

Learn More

• CLI Reference - Complete command documentation
• GitHub Repository - Source code and issues