quickmemo-mcp
QuickMemo MCP is a lightweight, locally-persisted scratchpad server that lets an AI assistant save, organize, search, and remove context memos.
Save memos (
add_memo): store a title, content, optionalcategory(defaults togeneral), and optionaltagslist.List memos (
list_memos): browse everything stored, optionally filtered bycategoryortag.Retrieve one memo (
get_memo): fetch a memo's full content and metadata bymemo_id.Search (
search_memos): keyword lookup across titles, content, tags, and categories.Delete one memo (
delete_memo): remove a specific memo bymemo_id.Clear everything (
clear_memos): wipe the entire memo store (destructive, no parameters).All tools take simple string/list arguments and return a text
result, making them easy for an LLM to call in sequence.Data lives in local JSON storage, so memos persist across sessions for scratchpad, handover, and note-taking workflows.
QuickMemo MCP Server πβ‘
QuickMemo MCP is a sleek, minimalistic, and unique Model Context Protocol (MCP) server that provides AI assistants with a fast, structured scratchpad and context memo engine.
Built cleanly using the official Python MCP SDK, QuickMemo showcases all three core MCP primitivesβTools, Resources, and Promptsβin an elegant, zero-bloat codebase.
π Key Highlights
β‘ Minimalist & Zero-Bloat: Under 150 lines of clean, readable Python code.
π― All 3 MCP Primitives:
Tools: Save, list, search, filter, retrieve, and delete context memos.
Resources: Real-time markdown digest (
memo://all) and dynamic telemetry (memo://stats).Prompts: Ready-to-use prompt templates for note reviews and daily standup generation.
π Zero Configuration Required: Instant out-of-the-box local persistent JSON storage (
~/.quickmemo/memos.json).π Marketplace & Registry Ready: Preconfigured with
smithery.yamlandDockerfilefor one-click deployment to Smithery and Glama.π Universal Compatibility: Works seamlessly with Claude Desktop, Cursor, Antigravity IDE, Windsurf, and custom MCP clients.
Related MCP server: mindmap-mcp-server
π Project Structure
quickmemo-mcp/
βββ docs/ # Learning documentation & reports
β βββ EXISTING_MCP_EXPERIENCE.md # Hands-on write-up evaluating Context7 & Playwright
β βββ MCP_FUNDAMENTALS.md # Complete MCP protocol & architecture guide
βββ src/
β βββ quickmemo/ # MCP Server package (<150 LOC)
β βββ __init__.py # Package exports
β βββ __main__.py # Executable entrypoint
β βββ server.py # Core server (Tools, Resources, Prompts)
βββ tests/
β βββ demo_client.py # Live interactive demonstration script
β βββ test_server.py # Pytest unit & integration test suite
βββ Dockerfile # Containerized deployment manifest
βββ LICENSE # MIT License
βββ pyproject.toml # Package configuration & dependencies
βββ README.md # Quickstart & user documentation
βββ smithery.yaml # Smithery registry manifestπ Architecture Overview
+-------------------------------------------------------------------------------+
| MCP CLIENT |
| (Claude Desktop / Cursor IDE / Antigravity / Custom AI) |
+-------------------------------------------------------------------------------+
β²
β JSON-RPC 2.0 (stdio)
βΌ
+-------------------------------------------------------------------------------+
| QUICKMEMO MCP SERVER |
| |
| [TOOLS] [RESOURCES] [PROMPTS] |
| β’ add_memo β’ memo://all (Digest) β’ review_notes |
| β’ list_memos β’ memo://stats (JSON) β’ daily_standup |
| β’ search_memos |
| β’ get_memo / delete_memo |
+-------------------------------------------------------------------------------+
β
βΌ
Local JSON Storage Engine
(~/.quickmemo/memos.json)π οΈ MCP Primitives Catalog
1. Tools (Model-Controlled Functions)
Tool Name | Parameters | Description |
|
| Saves a new memo or snippet with optional category and tags. |
|
| Lists saved memos with optional category and tag filtering. |
|
| Retrieves full content and metadata for a specific memo. |
|
| Performs keyword search across title, content, tags, and category. |
|
| Deletes a memo by ID. |
| None | Empties the memo store. |
2. Resources (Dynamic Context Streams)
Resource URI | MIME Type | Description |
|
| Formatted dynamic markdown digest of all stored memos. |
|
| Real-time statistics (total memos, categories breakdown, tag distribution). |
3. Prompts (Pre-Engineered Workflow Templates)
Prompt Name | Arguments | Description |
|
| Synthesizes saved memos into key takeaways and an actionable checklist. |
| None | Converts recent memos into a standard 3-part daily standup report. |
π‘ AI Assistant Workflows & Use Cases
π§ Multi-Step Code Refactoring Scratchpad:
The LLM stores tentative architecture decisions and checklist items as memos (
category: "refactor").Allows long-horizon task continuity without overflowing working memory.
π Session Handover & Context Preservation:
Before ending a chat session, ask the AI: "Save a summary memo of today's progress and active blockers."
Start the next session with "Retrieve memos tagged 'blockers' to resume work."
π Real-Time Daily Standup Generation:
Trigger the
daily_standupprompt to instantly consolidate team notes, bug findings, and feature progress into a formatted report.
π Quickstart & Installation
Option 1: Local Setup with uv (Recommended)
# Clone the repository
git clone https://github.com/Abdullah-Zafarr/quickmemo-mcp.git
cd quickmemo-mcp
# Install dependencies and package in editable mode
uv pip install -e .
# Run test suite
uv run pytest -v
# Run the interactive demo
uv run python tests/demo_client.pyOption 2: Running Directly via CLI
# Run server over stdio
quickmemoπ Client Configuration
Claude Desktop
Add QuickMemo to your claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"quickmemo": {
"command": "uvx",
"args": ["--from", "quickmemo", "quickmemo"]
}
}
}Cursor IDE
Add to .cursor/mcp.json in your workspace:
{
"mcpServers": {
"quickmemo": {
"command": "quickmemo"
}
}
}Antigravity IDE
Add to your project's .agents/mcp_config.json or global MCP settings:
{
"mcpServers": {
"quickmemo": {
"command": "quickmemo"
}
}
}Windsurf & VS Code (Roo Code / Continue)
Add QuickMemo under your MCP server settings:
{
"mcpServers": {
"quickmemo": {
"command": "uv",
"args": ["run", "quickmemo"]
}
}
}βοΈ Deploying to Smithery / Glama
This repository is pre-configured for the Smithery registry with smithery.yaml and Dockerfile.
Install via Smithery CLI
npx -y @smithery/cli install quickmemo --client claudeManual Registry Deployment
Push your repository to GitHub.
Visit Smithery.ai and sign in.
Import your GitHub repository. Smithery automatically detects
smithery.yamland deploys your MCP server.
π§ͺ Testing
Run the automated test suite:
uv run pytest -vOutput:
tests/test_server.py::TestMemoStore::test_add_and_get PASSED [ 12%]
tests/test_server.py::TestMemoStore::test_list_and_filter PASSED [ 25%]
tests/test_server.py::TestMemoStore::test_search PASSED [ 37%]
tests/test_server.py::TestMemoStore::test_delete_and_clear PASSED [ 50%]
tests/test_server.py::TestServerTools::test_tool_workflow PASSED [ 62%]
tests/test_server.py::TestServerTools::test_clear_memos_tool PASSED [ 75%]
tests/test_server.py::TestServerResourcesAndPrompts::test_resources PASSED [ 87%]
tests/test_server.py::TestServerResourcesAndPrompts::test_prompts PASSED [100%]
============================== 8 passed in 1.10s ==============================βοΈ Environment Configuration & Storage Customization
By default, QuickMemo persists memos at ~/.quickmemo/memos.json. You can customize the storage path by setting the QUICKMEMO_STORAGE environment variable:
# Custom storage path example
export QUICKMEMO_STORAGE="/path/to/my_custom_memos.json"
quickmemoβ Troubleshooting & FAQs
Server not connecting in Claude Desktop or Cursor?
Ensure
uvorquickmemois available in your system'sPATH.Check that the path to
quickmemois executable and python version >= 3.10 is installed.
Where are my memos stored?
Run the
memo://statsresource in your client to view the exact activestorage_path.
How to run tests locally?
Execute
uv run pytest -vfrom the repository root to verify all 8 unit & integration tests pass.
π Deliverables & Learning Documentation
π Existing MCP Hands-On Evaluation:
docs/EXISTING_MCP_EXPERIENCE.mdπ MCP Architecture & Fundamentals Guide:
docs/MCP_FUNDAMENTALS.mdπ» Interactive Live Demo Script:
tests/demo_client.pyβοΈ Smithery Configuration:
smithery.yaml
π License
MIT License Β© 2026 QuickMemo MCP Contributors.
Available Tools
6 toolsadd_memoA
Save a new context memo, snippet, or idea with optional category and tags.
Inputs: title (required), content (required), tags, category. Returns: result
clear_memosA
Clear all stored memos (use with caution).
Inputs: no named parameters. Returns: result
delete_memoA
Delete a specific memo by ID.
Inputs: memo_id (required). Returns: result
get_memoA
Retrieve the full details and content of a specific memo by ID.
Inputs: memo_id (required). Returns: result
list_memosA
List saved memos with optional category and tag filtering.
Inputs: tag, category. Returns: result
search_memosA
Search memos by keyword across title, content, tags, and category.
Inputs: query (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: create, list, get, search, delete, and clear. No two tools overlap in functionality, so an agent can easily select the correct one.
All tool names follow the verb_noun pattern consistently (add_memo, list_memos, get_memo, search_memos, delete_memo, clear_memos). The naming is uniformly snake_case with clear verbs and a common noun.
Six tools is well-scoped for a memo management server. Each tool covers a core operation without being excessive or too sparse.
The tool surface covers create, read (list/get/search), and delete (single and all). The only noticeable gap is the lack of an update or edit operation, which could be a minor limitation but does not interrupt the main workflow.
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yoβ¦
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Shared memory for your AI tools: tasks, notes and context every tool can read and write over MCP.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
AlicenseAqualityDmaintenanceAn open-source server implementing the Model Context Protocol (MCP) that enables capturing insights from AI sessions and transforming them into persistent, searchable knowledge accessible across tools.79Business Source 1.1- AlicenseAqualityCmaintenanceA local-first MCP server for shared memory across AI tools, enabling context capture and resume across sessions.2663 npm6Apache 2.0
- FlicenseAqualityDmaintenanceA lightweight, intelligent note-organizing server that acts as an AI-powered personal memory vault for capturing, organizing, and retrieving insights using FastMCP and SQLite.82-
- AlicenseNot gradedqualityBmaintenanceA high-performance personal Model Context Protocol (MCP) server built with the FastMCP Python framework.MIT