Sugar — Claude Code MCP server: project memory
A local memory layer your coding agent reads and writes mid-session. Decisions, conventions and error patterns live in SQLite and come back on the next run.
claude mcp add --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env GITHUB_TOKEN=<GITHUB_TOKEN> --env SUGAR_DEFAULT_REPO=<SUGAR_DEFAULT_REPO> --transport stdio sugar -- uvx sugaraiWhat Sugar does
Sugar is an MCP server that lets your agent read and write memory during a session. Project entries sit in .sugar/memory.db, shared ones in ~/.sugar/memory.db. There are seven memory types: decision, preference, file_context, error_pattern, research, outcome, guideline. Some expire — error_pattern after 90 days, research after 60, outcome after 30.
Search is semantic: sentence-transformers with all-MiniLM-L6-v2, 384-dim vectors, plus sqlite-vec. Install the plain package and you fall back to SQLite FTS5 keyword matching. Nothing leaves your machine. Results come back project-first, with reserved slots so global guideline entries always surface, then deduplicated across both stores.
You can fill memory from the shell too: sugar remember "..." --type preference, sugar recall "authentication", sugar memories --global. The agent gets search_memory, store_learning, recall, get_project_context and list_recent_memories. Semantic search needs pipx install 'sugarai[memory]'; without it the server still runs, just on keywords.
What it helps with
- restore project context after the agent restarts
- record an architecture decision before it gets lost
- find old notes by meaning instead of exact wording
- keep coding standards across every project
- store a bug together with its fix
Example prompts for the agent
- Search memory for everything about authentication and show what we decided on JWT
- Remember this: when tests fail with import errors, check
__init__.pyexports first
How to install Sugar
Platform CLI
claude mcp add --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env GITHUB_TOKEN=<GITHUB_TOKEN> --env SUGAR_DEFAULT_REPO=<SUGAR_DEFAULT_REPO> --transport stdio sugar -- uvx sugaraiReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sugarai <command>
Platform CLI
codex mcp add sugar --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env GITHUB_TOKEN=<GITHUB_TOKEN> --env SUGAR_DEFAULT_REPO=<SUGAR_DEFAULT_REPO> -- uvx sugaraiReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sugarai <command>
Config file
{
"mcpServers": {
"sugar": {
"command": "uvx",
"args": [
"sugarai"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
"GITHUB_TOKEN": "<GITHUB_TOKEN>",
"SUGAR_DEFAULT_REPO": "<SUGAR_DEFAULT_REPO>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sugarai <command>
Config file
{
"servers": {
"sugar": {
"type": "stdio",
"command": "uvx",
"args": [
"sugarai"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
"GITHUB_TOKEN": "<GITHUB_TOKEN>",
"SUGAR_DEFAULT_REPO": "<SUGAR_DEFAULT_REPO>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sugarai <command>
Platform CLI
gemini mcp add -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e GITHUB_TOKEN=<GITHUB_TOKEN> -e SUGAR_DEFAULT_REPO=<SUGAR_DEFAULT_REPO> sugar uvx sugaraiReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sugarai <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Sugar
How do I install Sugar in Claude Code?
Install the package first: pipx install sugarai, or pipx install 'sugarai[memory]' for semantic search. Then connect the memory server with claude mcp add sugar -- sugar mcp memory.
What does Sugar do?
It keeps project context and shared guidelines in two SQLite databases and serves them to your agent over MCP. The agent searches before starting work and stores findings afterwards.
Does Sugar need API keys?
No. Storage and search run locally with no external calls. The ANTHROPIC_API_KEY, GITHUB_TOKEN and SUGAR_DEFAULT_REPO variables in the Codex, Cursor, GitHub Copilot and Gemini CLI setups belong to the optional task server.
