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 "Install 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., "@darumalist 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).
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as being read-only, side effects, or required permissions. A read operation is implied but not stated explicitly, leaving ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences plus a clear parameter bullet point. It is front-loaded with the main purpose, and every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter, no output schema, and no annotations, the description lacks details about the output format or possible errors. While the purpose is clear, the absence of return value information may hinder an agent's ability to use the result correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for its single parameter. The tool description adds meaning by specifying that the directory must be an absolute path and that it is required, compensating partially for the schema gap. However, no further details on format or constraints are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool resolves repository name, monorepo component, and technology stack for a directory path, which is a specific verb+resource. It distinguishes from sibling tools like get_recent_merged_changes or store_lesson by focusing on context resolution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use this to determine the exact coordinates of your current workspace,' providing a clear usage context. It does not mention when not to use or alternatives, but the context is clear and the tool's purpose is distinct from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| directory | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates a read-only operation ('Retrieves'), and mentions compatibility with Git and Jujutsu. No annotations provided, so description carries full burden; it adequately conveys safe, non-destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short paragraphs and a parameter list, no wasted words. Information is front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description could detail return format or sort order. However, for a simple retrieval tool with 2 params, it covers the essential: what, when, and parameters. Minor gap on output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description adds essential meaning: 'directory' is absolute path and required, 'count' is number of changes with default 10. Clearly explains each parameter beyond type info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb ('Retrieves') and specific resource ('recent committed/merged changes') with scope ('made by you in this project'). Differentiates from sibling tools which are about context and lessons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly lists use cases: 'pull historical code patterns, review modifications, and study successful merges.' No explicit when-not-to-use instructions, but context is clear given sibling tools have different purposes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only retrieval, automatic layering, and sorting, but lacks details on error behavior, caching, or side effects. With no annotations, more burden falls on the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise two-sentence description plus parameter list. No extraneous information; each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers what is returned and aggregation logic, but does not explain metadata fields or compare to sibling tools. Lacks detail on output structure since no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context for the directory parameter (absolute path, required), but does not explain format validation or example values. For a single parameter, this is adequate but not thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves titles and metadata of lessons matching context, distinguishing it from siblings that get context or search by tag. However, the notion of 'current context' is not precisely defined, leaving slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like search_lessons_by_tag or read_lesson. The description implies it's automatic but does not specify prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| lesson_id | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only says 'retrieves'. It does not disclose read-only nature, permissions, rate limits, or any side effects. This is minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no wasted words. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is adequate but not complete. It tells what it does and when to use, but omits return format and error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must add meaning. It clarifies that lesson_id is the unique ID and implies it comes from list_context_lessons. However, it adds no details about format or constraints beyond what the schema already shows.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the full content of a specific lesson by its unique ID. It differentiates from siblings by referencing list_context_lessons as a precursor and implying distinct use from search_lessons_by_tag and store_lesson.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this once you see a relevant title in list_context_lessons, providing clear context for when to invoke. It does not explicitly mention when not to use, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_lessons_by_tagB
Searches for lessons globally matching a specific tag (e.g., 'security', 'css', 'concurrency'), regardless of repository or component context boundaries.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It adds the global scope constraint but fails to disclose output format, error handling, or potential limits (e.g., case sensitivity, exact match). For a search tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the essential information: purpose, scope, and examples. Every word adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description should explain return values or behavior (e.g., list of lesson IDs, full lesson objects). It does not address pagination, sorting, or empty results. For a globally searching tool, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by providing examples of valid tags ('security', 'css', 'concurrency'). However, it does not specify constraints like case sensitivity, pattern matching, or required format. It adds some value but not full clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Searches), resource (lessons), criterion (by tag), and scope (globally, regardless of boundaries). It provides examples and distinguishes from context-bound tools like list_context_lessons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus siblings. It does not mention when not to use it, nor does it reference alternatives like list_context_lessons for context-specific searches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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")
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| scope | No | component | |
| title | Yes | ||
| content | Yes | ||
| directory | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only says 'stores' but lacks details on side effects, overwriting behavior, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concisely lists parameters in a clear block. No extraneous sentences, but could be more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes parameters adequately but omits return value or confirmation of success. With 5 parameters and no usage guidance, it feels minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description explains all 5 parameters with additional context (e.g., 'markdown format' for content, enum values for scope). Compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Stores a learned lesson' with a clear verb and resource. Differentiates from sibling read/search tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not explain prerequisites or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
6 tool updates
v0.1.0- First observed
get_current_context - First observed
get_recent_merged_changes - First observed
list_context_lessons - First observed
read_lesson - First observed
search_lessons_by_tag - First observed
store_lesson
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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Persistent memory for AI agents — log and recall conversation context over MCP.
- mcpOAuthai.butlerbrain
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
shared AI-context layer for teams — persistent memory your agents search and update over MCP
- memnodeOAuthdev.memnode
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenancePersistent 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.122MIT
- FlicenseNot gradedqualityBmaintenanceCentral 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 gradedqualityBmaintenanceA local MCP server that acts as long-term memory for AI coding assistants, storing lessons and patterns in a local SQLite database with optional hybrid vector search via Ollama.7MIT
- 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
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/r-darwish/daruma'
If you have feedback or need assistance with the MCP directory API, please join our Discord server