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

Global Memory

By default, memories are stored per-project in .sugar/memory.db. Global memory uses ~/.sugar/memory.db instead - a single store shared across every project on your machine.

Use global memory for knowledge that applies everywhere: deployment conventions, personal coding standards, cross-team guidelines. Use project memory for decisions specific to one codebase.

# Store a global guideline (available in every project)
sugar remember --global "Title tags under 60 chars for SEO" --type guideline

# Store a global decision
sugar remember --global "Always use Kamal for deploys" --type decision

# Recall from any project (searches both local + global)
sugar recall "deployment"

# View stats for both stores
sugar memory-stats

The --global flag works on all memory commands:

• sugar remember --global "..." - write to global store
• sugar memories --global - list only global memories
• sugar forget --global <id> - delete from global store

sugar recall searches both stores by default. Project results are ranked first, but global guidelines are always surfaced. See Search Strategy for details.

Memory Types

Sugar organizes memories into seven 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 dynamic code execution for security reasons" --type preference --importance 2.0

Options

• --type TYPE - Memory type (default: decision)
• --global - Write to global store at ~/.sugar/memory.db
• --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
• --global - Search only the global store
• --local - Search only the project store

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

MCP Resources

• sugar://memory/context - Current project memory context
• sugar://global/guidelines - All global guideline memories, formatted for injection into system prompts

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"
      }]
    }]
  }
}

How Search Works

Sugar runs a three-tier search engine. Everything runs locally - no external API calls.

1. Semantic Search (Best Results)

Uses sentence-transformers (all-MiniLM-L6-v2, 384-dimension vectors) with sqlite-vec for vector similarity.

• "auth issues" finds memories about "authentication", "login", "JWT"
• Understands synonyms and related concepts
• Downloads a ~90MB model on first use
• Install: pipx install 'sugarai[memory]'

2. FTS5 Keyword Search (Fallback)

SQLite full-text search with stemming and prefix matching. Used automatically when sentence-transformers is not installed.

• Fast and lightweight, no additional dependencies
• Matches words with basic stemming (e.g., "deploys" matches "deployment")
• OR-based multi-word queries for better recall

3. LIKE Search (Last Resort)

Simple substring matching. Used only if FTS5 queries fail (rare edge cases).

Sugar automatically uses the best available method. You get useful results regardless of which search tier is active - semantic just gives better conceptual matching.

Search Strategy

When you run sugar recall without a scope flag, Sugar queries both the project store and the global store and merges the results with a defined priority order:

1. Project results first - local context is most specific to what you're working on and ranks highest.
2. Global guidelines reserved - a fixed number of slots are always reserved for global guideline memories, so they surface even when project results are plentiful.
3. Remaining global results - any remaining slots are filled with other global memories ranked by relevance.
4. Automatic deduplication - if the same content exists in both stores, only the project-scoped copy is returned.

This means your global guidelines are always visible without crowding out project-specific decisions. You can override the behavior with --local or --global to restrict the search to one store.

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

Sugar maintains two separate memory databases:

Project store

Lives inside the project directory. Committed to version control at your discretion.

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

Global store

Lives in your home directory. Shared across all projects on the machine.

~/.sugar/
└── memory.db     # Global memory database

Backup & Export

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

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

# Copy databases directly
cp .sugar/memory.db project-memory-backup.db
cp ~/.sugar/memory.db global-memory-backup.db

Learn More

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