Skip to main content
Glama

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 sync

2. 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 css

2. 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 rust

Database 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.

IMPORTANT

If you modify the database schema, CLI flags, resolver directories, or underlying protocol specs, you are REQUIRED to immediately update both README.md and AGENTS.md.

Available Tools

6 tools
get_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

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent 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 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Central 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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
    • A
      license
      A
      quality
      C
      maintenance
      Gives 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.
      6
      MIT