daruma
Daruma is a local-first, context-aware MCP server for storing and retrieving lessons learned during development, helping AI agents and developers capture and reuse knowledge.
Resolve workspace context (
get_current_context): Given an absolute directory path, identify the repository name, monorepo component, and active technology stack — the "coordinates" of your current workspace.Store lessons (
store_lesson): Save a titled, markdown-formatted lesson tied to a directory context, with a configurable scope (component,repository, orglobal) and optional tags (e.g.,concurrency, mutex).List relevant lessons (
list_context_lessons): Retrieve a prioritized index of lessons applicable to your current directory, automatically aggregating across component, repository, technology, and global layers.Read a specific lesson (
read_lesson): Fetch the full content of a single lesson by its unique ID, useful after identifying a relevant title from the list.Search by tag (
search_lessons_by_tag): Perform a global tag-based search across all repositories and components to find lessons matching keywords likecss,security, orconcurrency.Review recent merged changes (
get_recent_merged_changes): Retrieve recent commits or merges authored by you in a given directory, supporting both Git and Jujutsu (jj) workflows, to extract patterns from historical work.
Allows retrieval of repository context from Git, including remote URLs and recent merged changes, to coordinate lessons learned with the project's Git history.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@daruma list lessons for this project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Daruma (だるま) 🏮
Daruma is a lightweight, local-first, context-aware Model Context Protocol (MCP) server and interactive CLI designed to help developers and AI coding agents store and retrieve lessons learned during development.
Unlike heavy vector databases that suffer from high noise and concurrency locking, Daruma utilizes SQLite in WAL (Write-Ahead Logging) mode for bulletproof concurrent reads and writes, paired with precise hierarchical and technology-based filtering to eliminate context bloat.
The Big Picture (How it works)
When you or an AI agent perform work inside a directory, Daruma resolves the context into four distinct layers:
📁 Your Project Subdirectory
├── 1. Component Layer (e.g., "backend/auth" parsed from go.mod / package.json)
├── 2. Repository Layer (parsed from Git remote or Jujutsu remote)
├── 3. Technology Layer (auto-detected, e.g., "go", "rust", "python", "typescript")
└── 4. Global Layer ("global" software engineering rules)Daruma queries these specific coordinates and returns a lightweight list of lesson titles. The agent only reads full lesson contents when explicitly relevant, keeping your prompt context clean and concise.
Related MCP server: Lessons Learned MCP Server
Installation & Setup
Daruma is managed using uv.
1. Local Setup
Clone this repository and sync dependencies:
cd daruma
uv sync2. Database Location
The database is fully self-contained and XDG-compliant, residing at:
~/.local/share/daruma/daruma.db
MCP Registration & Integration
Daruma is primarily designed to run in the background as an autonomous, contextual expertise cache for your AI assistants. To link Daruma to your AI assistant (e.g., Claude Desktop, Cursor, Gemini), register the server in your MCP config file:
{
"mcpServers": {
"daruma": {
"command": "uv",
"args": ["--directory", "/path/to/daruma", "run", "daruma-server"]
}
}
}Activating AI Agent Initiative (Proactive Mode)
To make AI coding assistants (like Gemini, Claude, or Cursor) proactively search and store lessons on their own initiative, you can append the following paragraph directly to your client-wide global instructions file (e.g., ~/.config/ai/custom_instructions.md):
## Project Daruma Initiative
- **Session Start**: At the start of every session, before editing or writing any code, you MUST proactively query the Daruma MCP server using the `list_context_lessons` tool, passing the absolute path of your current workspace directory as the `directory` argument, to check for existing contextual rules, architectural patterns, or historical gotchas relevant to the current workspace context.
- **Upvote Relevant Lessons**: After reading a lesson via the `read_lesson` tool, you must evaluate if the information within that lesson is indeed relevant/useful to your current activity, plan, or codebase modifications. If it is relevant, you MUST call the `upvote_lesson` tool to increment its upvoted counter.
- **Session End (CRITICAL EXECUTION FLOW)**: Before you conclude your final response on any task, milestone, or request (i.e., before writing your final summary or stopping tool calls), you MUST evaluate your edits. If you solved a challenging bug, refactored duplicated code (e.g. following DRY principles), or learned an engineering lesson, you MUST call the `store_lesson` tool to save it *before* outputting your final text response. Do NOT end your turn or present your final summary to the user until these lessons are successfully committed to the database.Registered Tools
get_current_context: Resolves(repo, component, tech).store_lesson: Saves a new lesson learned.list_context_lessons: Pulls prioritized index of applicable lessons.read_lesson: Fetches a single full lesson.upvote_lesson: Upvotes a specific lesson by its unique ID.search_lessons_by_tag: Searches for lessons globally matching a specific tag (e.g.css,concurrency), crossing project boundaries.get_recent_merged_changes: Retrieves authored merges (from Git or Jujutsu) to extract patterns from.
The Interactive CLI (daruma) (Inspect & Debug)
Daruma provides a built-in CLI primarily intended for developers to inspect, debug, and manually manage the database. While the AI assistant automatically handles CRUD operations in the background, you can use the CLI to view stored lessons, manually seed new ones, or correct/delete existing records.
Commands
1. List Lessons (Inspect Cache)
List all cached lessons matching your current directory context, or search globally across all projects using a tag query:
# List lessons matching active directory context
uv run daruma-cli list
# Search globally across all repos for lessons tagged with 'css'
uv run daruma-cli list --tag css
# or using the short flag
uv run daruma-cli list -t css2. View a Lesson
uv run daruma-cli view <lesson_id>3. Edit an Existing Lesson
Spins up your $EDITOR (respecting $EDITOR, e.g., nvim or nano) to modify a lesson in place:
uv run daruma-cli edit <lesson_id>4. Delete a Lesson
uv run daruma-cli delete <lesson_id>5. Rename a Repository Coordinate
Rename all references to an old repository remote or folder coordinate across the entire database:
uv run daruma-cli rename-repo <old_repo> <new_repo>6. Add a Lesson Manually
Launches your preferred editor with a pre-populated template:
# Add a lesson for the current directory component
uv run daruma-cli add
# Add a global lesson
uv run daruma-cli add --global
# Add a lesson with specific technology override
uv run daruma-cli add --tech rustDatabase Migrations
Daruma uses a lightweight, self-contained schema migration system based on SQLite's built-in PRAGMA user_version.
On startup, the server automatically reads PRAGMA user_version, identifies outstanding schema updates, runs them sequentially, and increments the database version in place. Your existing data is never deleted or overwritten during schema upgrades.
Development & Maintenance
This repository enforces strict dynamic documentation alignment.
Available Tools
6 toolsget_current_contextA
Resolves the repository name, monorepo component, and active technology stack for a given directory path.
Use this to determine the exact coordinates of your current workspace.
Parameters:
- directory: The absolute path of the current workspace directory (REQUIRED).
Inputs: directory (required).
get_recent_merged_changesA
Retrieves recent committed/merged changes made by you in this project.
Use this to pull historical code patterns, review modifications, and study successful merges.
Works seamlessly in standard Git checkouts and Jujutsu (jj) co-located checkouts.
Parameters:
- directory: The absolute path of the current workspace directory (REQUIRED).
- count: The number of recent changes to retrieve (default: 10).
Inputs: directory (required), count.
list_context_lessonsB
Retrieves titles and metadata of applicable lessons matching your current context.
This automatically searches and aggregates Component, Repo, Tech-specific, and Global layers,
sorted by architectural priority.
Parameters:
- directory: The absolute path of the current workspace directory (REQUIRED).
Inputs: directory (required).
read_lessonA
Retrieves the full content of a specific lesson by its unique ID.
Use this once you see a relevant title in list_context_lessons to read its full guidelines.
Inputs: lesson_id (required).
search_lessons_by_tagB
Searches for lessons globally matching a specific tag (e.g., 'security', 'css', 'concurrency'), regardless of repository or component context boundaries.
Inputs: tag (required).
store_lessonB
Stores a learned lesson based on the current directory context.
Parameters:
- directory: The absolute path of the current workspace directory (REQUIRED).
- title: Descriptive title of the lesson
- content: Full lesson body (markdown format)
- scope: Can be 'component' (folder-level), 'repository' (project-wide), or 'global' (cross-project rules)
- tags: Optional comma-separated categories (e.g. "concurrency, mutex")
Inputs: title (required), content (required), directory (required), tags, +1 more. 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: workspace context, recent changes, lesson listing, reading, searching, and storing. No two tools could be confused even with less-than-perfect descriptions.
All tools use consistent verb_noun patterns with underscores (e.g., get_current_context, list_context_lessons, store_lesson). No mixing of cases or styles.
Six tools is well-scoped for the server's domain of context-aware lesson management. Each tool earns its place without being excessive or insufficient.
Covers core CRUD for lessons (create via store_lesson, read via list/read/search) but lacks update and delete operations. Context and history tools are read-only, which is acceptable, but lesson lifecycle is incomplete.
Maintenance
Related MCP Connectors
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.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenancePersistent memory for AI coding agents. Enables agents to save and recall decisions, patterns, bugs, and context across sessions via an MCP server with local SQLite storage.24 npm2MIT
- FlicenseNot gradedqualityCmaintenanceCentral MCP server for storing and querying lessons learned and project-specific implementation details, compatible with MCP-capable AI clients like Cursor, Claude Code, and Google Antigravity.-
- AlicenseNot gradedqualityCmaintenanceA tiny local MCP memory server that stores lessons learned and resurfaces them before your AI agent repeats the same mistake. It provides tools for adding, searching, listing, forgetting, and inspecting lessons via MCP stdio.MIT
- AlicenseAqualityCmaintenanceGives coding assistants a local-first SQLite store for project and global lessons with evidence, immutable replacements, retrieval tracking, and agent feedback, searched by keyword out of the box or by optional local semantic search. It runs over MCP stdio with launch-bound workspace scopes and write permissions disabled by default, so assistants can save, supersede, archive, retrieve, and rate memories entirely on the local machine.6MIT