roboticforce · cdnsteve · Jan 21, 2026 · Jan 21, 2026 · Jan 21, 2026 · Jan 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,92 @@ All notable changes to the Sugar autonomous development system will be documente
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.5.0] - Unreleased
+
+### 🧠 MINOR RELEASE: Memory System
+
+Sugar now has persistent semantic memory! Remember decisions, preferences, error patterns, and more across sessions. Integrates with Claude Code via MCP server for seamless context sharing.
+
+### Added
+
+#### Memory System (`sugar/memory/`)
+- **MemoryStore**: SQLite-backed storage with vector search support
+  - Semantic search using sentence-transformers embeddings
+  - FTS5 keyword search fallback when embeddings unavailable
+  - sqlite-vec integration for fast vector similarity
+- **Memory Types**: Six memory categories for different kinds of information
+  - `decision` - Architectural and implementation decisions
+  - `preference` - User coding preferences (permanent)
+  - `file_context` - What files do what
+  - `error_pattern` - Bug patterns and their fixes
+  - `research` - API docs, library findings
+  - `outcome` - Task outcomes and learnings
+- **MemoryRetriever**: Context formatting for prompt injection
+- **Embedder**: SentenceTransformer embeddings with graceful fallback
+
+#### New CLI Commands
+- `sugar remember "content"` - Store a memory with type, tags, TTL, importance
+- `sugar recall "query"` - Search memories with semantic/keyword matching
+- `sugar memories` - List memories with filtering by type, age
+- `sugar forget <id>` - Delete a memory by ID
+- `sugar export-context` - Export memories for Claude Code SessionStart hook
+- `sugar memory-stats` - Show memory system statistics
+- `sugar mcp memory` - Run MCP server for Claude Code integration
+
+#### MCP Server for Claude Code
+- **search_memory** - Semantic search over project memories
+- **store_learning** - Store new observations/decisions from Claude
+- **get_project_context** - Organized project context summary
+- **recall** - Formatted markdown context for prompts
+- **list_recent_memories** - List with type filtering
+- **Resources**: `sugar://project/context`, `sugar://preferences`
+
+#### Claude Code Integration
+- **SessionStart Hook**: Auto-inject context via `sugar export-context`
+- **MCP Server**: Full memory access via `claude mcp add sugar -- sugar mcp memory`
+- **Bidirectional**: Claude can both read and write memories
+
+### Configuration
+
+New optional dependency group:
+```bash
+pip install 'sugarai[memory]'   # Enables semantic search
+pip install 'sugarai[all]'      # All features
+```
+
+Memory works without dependencies (uses FTS5 keyword search), but semantic search requires:
+- `sentence-transformers>=2.2.0`
+- `sqlite-vec>=0.1.0`
+
+### Usage Examples
+
+```bash
+# Store memories
+sugar remember "Always use async/await, never callbacks" --type preference
+sugar remember "Auth tokens expire after 15 minutes" --type research --ttl 90d
+sugar remember "payment_processor.py handles Stripe webhooks" --type file_context
+
+# Search memories
+sugar recall "how do we handle authentication"
+sugar recall "database errors" --type error_pattern --limit 5
+
+# Claude Code integration
+claude mcp add sugar -- sugar mcp memory
+```
+
+### Documentation
+- New [Memory System Guide](docs/user/memory.md)
+- Updated README with memory commands and MCP integration
+- Updated CLI reference with all memory commands
+
+### Technical Details
+- 24 new tests for memory module
+- Full backwards compatibility - memory is opt-in
+- Database stored at `.sugar/memory.db` per project
+- Embeddings use all-MiniLM-L6-v2 (384 dimensions)
+
+---
+
 ## [3.4.4] - 2026-01-10
 
 ### 🔄 MINOR RELEASE: Agent-Agnostic Rebranding

diff --git a/README.md b/README.md
@@ -54,6 +54,16 @@ uv pip install sugarai
 pipx install 'sugarai[github]'
 ```
 
+**With memory system (semantic search):**
+```bash
+pipx install 'sugarai[memory]'
+```
+
+**All features:**
+```bash
+pipx install 'sugarai[all]'
+```
+
 </details>
 
 ## Quick Start
@@ -203,7 +213,13 @@ With pipx, Sugar's dependencies don't conflict with your project's dependencies.
 - Self-correcting loops until tests pass
 - Prevents single-shot failures
 
-**Full docs:** [docs/ralph-wiggum.md](docs/ralph-wiggum.md)
+**Memory System** *(New in 3.5)*
+- Persistent semantic memory across sessions
+- Remember decisions, preferences, error patterns
+- Claude Code integration via MCP server
+- `sugar remember` / `sugar recall` commands
+
+**Full docs:** [docs/ralph-wiggum.md](docs/ralph-wiggum.md) | [Memory System](docs/user/memory.md)
 
 ## Configuration
 
@@ -254,7 +270,28 @@ Claude: "I'll create a Sugar task for the test fixes."
 
 ### MCP Server Integration
 
-Sugar provides an MCP server for Goose, Claude Desktop, and other MCP clients.
+Sugar provides MCP servers for Goose, Claude Code, Claude Desktop, and other MCP clients.
+
+**Using with Claude Code (Memory):**
+```bash
+# Add Sugar memory to Claude Code
+claude mcp add sugar -- sugar mcp memory
+```
+
+Or add to `~/.claude.json`:
+```json
+{
+  "mcpServers": {
+    "sugar": {
+      "type": "stdio",
+      "command": "sugar",
+      "args": ["mcp", "memory"]
+    }
+  }
+}
+```
+
+This gives Claude Code access to your project's memory - decisions, preferences, error patterns, and more.
 
 **Using with Goose:**
 ```bash
@@ -279,6 +316,32 @@ goose configure
 }
 ```
 
+### Memory System
+
+Sugar's memory system provides persistent context across sessions:
+
+```bash
+# Store memories
+sugar remember "Always use async/await, never callbacks" --type preference
+sugar remember "Auth tokens expire after 15 minutes" --type research --ttl 90d
+
+# Search memories
+sugar recall "how do we handle authentication"
+sugar recall "error patterns" --type error_pattern
+
+# List and manage
+sugar memories --type decision --since 7d
+sugar forget abc123 --force
+sugar memory-stats
+
+# Export for Claude Code SessionStart hook
+sugar export-context
+```
+
+**Memory types:** `decision`, `preference`, `file_context`, `error_pattern`, `research`, `outcome`
+
+**Full docs:** [Memory System Guide](docs/user/memory.md)
+
 ## Advanced Usage
 
 **Task Orchestration**
@@ -342,6 +405,7 @@ sugar run --once                        # Test single cycle
 
 - [Quick Start](docs/user/quick-start.md)
 - [CLI Reference](docs/user/cli-reference.md)
+- [Memory System](docs/user/memory.md) *(New)*
 - [Task Orchestration](docs/task_orchestration.md)
 - [Ralph Wiggum](docs/ralph-wiggum.md)
 - [GitHub Integration](docs/user/github-integration.md)
@@ -376,6 +440,6 @@ pytest tests/ -v
 
 ---
 
-**Sugar v3.4** - The autonomous layer for AI coding agents
+**Sugar v3.5** - The autonomous layer for AI coding agents
 
 > ⚠️ Sugar is provided "AS IS" without warranty. Review all AI-generated code before use.
diff --git a/docs/README.md b/docs/README.md
@@ -11,6 +11,7 @@ Documentation for developers who want to **use** Sugar in their projects:
 - **[Quick Start Guide](user/quick-start.md)** - Get up and running in 5 minutes
 - **[Execution Context](user/execution-context.md)** - Where and how to run Sugar correctly
 - **[CLI Reference](user/cli-reference.md)** - All Sugar commands and options
+- **[Memory System](user/memory.md)** - Persistent semantic memory for coding sessions *(New)*
 - **[GitHub Integration](user/github-integration.md)** - Connect Sugar to GitHub issues and PRs
 - **[Examples](user/examples.md)** - Real-world usage examples
 - **[Configuration Best Practices](user/configuration-best-practices.md)** - Essential config patterns and exclusions