Release 3.5.0 - Memory System Improvements

.claude-plugin/README.md

@@ -165,7 +165,7 @@ sugar:
 
 - **Issues**: [GitHub Issues](https://github.com/roboticforce/sugar/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/roboticforce/sugar/discussions)
-- **Documentation**: [docs.roboticforce.io/sugar](https://docs.roboticforce.io/sugar)
+- **Documentation**: [sugar.roboticforce.io](https://sugar.roboticforce.io/)
 
 ## License
 

AGENTS.md

@@ -66,6 +66,55 @@ Sugar uses [PEP 440](https://peps.python.org/pep-0440/):
 
 Version is in `pyproject.toml` only. Bump dev number after merging PRs.
 
+## Release Process (IMPORTANT)
+
+Follow these steps exactly when releasing a new version:
+
+### 1. Create Release Branch (from develop)
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b release/X.Y.Z
+```
+
+### 2. Prepare Release
+- Update `pyproject.toml`: change `X.Y.Z.devN` → `X.Y.Z`
+- Add CHANGELOG.md entry for the release
+- Commit: `git commit -am "Prepare release vX.Y.Z"`
+
+### 3. Create PR to main
+```bash
+git push -u origin release/X.Y.Z
+gh pr create --base main --title "Release vX.Y.Z"
+```
+
+### 4. After PR Merge - IMMEDIATELY Tag
+```bash
+git checkout main
+git pull origin main
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+**The tag triggers the release workflow (GitHub Release + PyPI publish).**
+
+### 5. Sync develop with main
+```bash
+git checkout develop
+git pull origin develop
+git merge origin/main -m "Merge main vX.Y.Z into develop"
+```
+
+### 6. Bump develop to next dev version (via PR!)
+```bash
+git checkout -b chore/bump-version-X.Y.Z+1.dev0
+# Edit pyproject.toml: X.Y.Z → X.Y.Z+1.dev0
+git commit -am "Bump version to X.Y.Z+1.dev0 for development"
+git push -u origin chore/bump-version-X.Y.Z+1.dev0
+gh pr create --base develop --title "Bump version to X.Y.Z+1.dev0"
+```
+
+**NEVER push directly to develop or main - always use PRs!**
+
 ## Project Structure
 
 ```
@@ -138,6 +187,8 @@ sugar --version
 
 ## Testing
 
+Ensure you have activated the virtual environment (see Development Setup above) before running these commands.
+
 ```bash
 # Run all tests
 pytest

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

README.md

@@ -12,6 +12,7 @@ Sugar adds **autonomy and persistence** to your AI coding workflow. Instead of o
 
 - **Continuous execution** - Runs 24/7, working through your task queue
 - **Agent-agnostic** - Works with Claude Code, OpenCode, Aider, or any AI CLI
+- **Persistent memory** - Remember decisions, preferences, and patterns across sessions
 - **Delegate and forget** - Hand off tasks from any session
 - **Builds features** - Takes specs, implements, tests, commits working code
 - **Fixes bugs** - Reads error logs, investigates, implements fixes
@@ -54,6 +55,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
@@ -89,6 +100,31 @@ Sugar will:
 
 It keeps going until the queue is empty (or you stop it).
 
+## Memory System
+
+Sugar remembers what matters across sessions. No more re-explaining decisions or rediscovering patterns.
+
+**Saves tokens:** Memories are stored as compressed summaries (~90% smaller) and retrieved only when relevant. Real projects see **~89% token reduction per session** - that's ~$32 saved over 500 sessions.
+
+```bash
+# Store knowledge
+sugar remember "Always use async/await, never callbacks" --type preference
+sugar remember "JWT tokens use RS256, expire in 15 min" --type decision
+
+# Search memories
+sugar recall "authentication"
+
+# Claude Code integration - give Claude access to your project memory
+claude mcp add sugar -- sugar mcp memory
+
+# See your token savings
+python examples/token_savings_demo.py
+```
+
+**Memory types:** `decision`, `preference`, `file_context`, `error_pattern`, `research`, `outcome`
+
+**Full docs:** [Memory System Guide](docs/user/memory.md)
+
 **Delegate from Claude Code:**
 ```
 /sugar-task "Fix login timeout" --type bug_fix --urgent
@@ -177,6 +213,12 @@ With pipx, Sugar's dependencies don't conflict with your project's dependencies.
 
 ## Features
 
+**Memory System** *(New in 3.5)*
+- Persistent semantic memory across sessions
+- Remember decisions, preferences, error patterns
+- Claude Code integration via MCP server
+- Semantic search with `sugar recall`
+
 **Task Management**
 - Rich task context with priorities and metadata
 - Custom task types for your workflow
@@ -203,7 +245,7 @@ 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)
+**Full docs:** [Memory System](docs/user/memory.md) | [Ralph Wiggum](docs/ralph-wiggum.md)
 
 ## Configuration
 
@@ -254,7 +296,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 +342,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 +431,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 +466,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.

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