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.

---

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.
- **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.
• 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.