Sherlock's second brain
Investigation Cases: Create, retrieve, list, update, and delete cases; attach evidence; set status (open, in_progress, resolved, abandoned); promote resolved cases to validated knowledge base entries (fiches or skills).
Knowledge Base: Manage validated fiches and skills (list, read, write, delete).
Search: Perform hybrid semantic search (vector + lexical) across cases and knowledge base.
Index: Rebuild the search index from all source files.
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., "@Sherlock's second brain Search my knowledge base for insights on ChromaDB performance"
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.
sherlock-second-brain
Named after the famous detective of Baker Street who inspired this project: the same way, we run rigorous investigations (symptoms, clues, hypotheses, evidence, conclusion) to debug, analyze code, and remember what we learn across multiple projects.
MCP server + skill for Sherlock's second brain: validated knowledge lives in MD fiches and skills; everything not yet validated lives in cases (JSON investigation files for debugging and troubleshooting). Standalone notes worth remembering without an investigation live in memories (MD + YAML frontmatter). A resolved case is promoted into a fiche or a skill through the MCP; a memory can also be promoted into a fiche.
source of truth (files) derived index (rebuildable)
──────────────────────────────────── ────────────────────────────
<data_dir>/
cases/<case-id>/case.json ──→ vector/ (chromadb, gitignored)
cases/<case-id>/evidence/*.log hybrid search: vector (Chroma)
memories/<id>.md + lexical (RRF)
fiches/*.md
skills/<slug>/SKILL.mdStack
Python 3.12+,
uvFastMCP (stdio)
ChromaDB + fastembed (vector index, multilingual MiniLM-L12 model)
jsonschema (case validation)
jinja2 (rendering of promoted fiches / skills)
PyYAML (memory frontmatter)
Hexagonal architecture:
domain/(pure pydantic) ·application/(use cases + ports) ·adapters/(filesystem, chroma, lexical, hybrid RRF, MCP DTO, templates)
Related MCP server: brain-mcp
Installation (in a project)
uv init
uv add sherlock-second-brainOr from the repo:
cd sherlock-second-brain
uv syncTwo ways to run it
Your data (cases, fiches, skills, vector index) always lives on the machine where the server process runs. The server is local-first (stdio), so you choose where that machine is:
A. Self-hosted (data stays on your machine)
Install the package and run the stdio server locally — no third party ever touches
your data. Configure SHERLOCK_BRAIN_DATA_DIR to choose where the files live
(default ~/sherlock-second-brain-data).
B. Managed on Glama (opt-in)
Deploy your own instance on Glama's hosting from the Glama listing:
Glama builds the image, wraps the stdio transport into Streamable HTTP, and mounts
a persistent volume at /data. Set SHERLOCK_BRAIN_DATA_DIR=/data so your
knowledge survives redeploys. This is a paid managed option — the code itself is
free and open source (MIT).
Configuration
Variable | Role | Default |
| Root data directory (cases + memories + kb + vector) |
|
Wire the MCP server into opencode
Add to ~/.config/opencode/opencode.json:
{
"mcp": {
"sherlock-second-brain": {
"type": "local",
"command": ["/opt/sherlock-second-brain/.venv/bin/python", "-m", "sherlock_second_brain.server"],
"enabled": true,
"environment": {
"SHERLOCK_BRAIN_DATA_DIR": "/opt/infra/kb"
}
}
}
}Install the agent globally
The agent is versioned in this repo (agent/sherlock-second-brain.md). To make it
available to all opencode agents:
ln -s /opt/sherlock-second-brain/agent/sherlock-second-brain.md ~/.config/opencode/agent/sherlock-second-brain.mdOn another machine, clone the repo then create the same symlink pointing to the checkout. Restart opencode after installation.
MCP tools
Cases
Tool | Role |
| Create an investigation (unvalidated topic) |
| Read / list (status, tag filters) |
| Semantic search (cases + KB) |
| Add findings / steps / hypotheses / conclusion / hypothesis result |
| Attach evidence (log, output, note) |
| open / in_progress / resolved / abandoned |
| Delete a case and its evidence |
| Promote a resolved case → fiche or skill |
Memories
Tool | Role |
| Add a standalone note to remember (no case) |
| Read / list memories (tag filter) |
| Semantic search restricted to memories (hydrated) |
| Update summary / content / tags / references / source |
| Delete a memory |
| Promote a memory → validated fiche |
KB
Tool | Role |
| CRUD validated fiches |
| CRUD validated skills |
| Rebuild the vector index from source files |
Hybrid search
case_search (and memory_search) combines two engines via Reciprocal Rank
Fusion (adapters/hybrid.py) over four sources: fiches, cases,
skills and memories.
Vector (
adapters/chroma.py): multilingual embeddings (MiniLM-L12, ~0.22GB, French included), persistent collection invector/, rebuildable viaindex_rebuild.Lexical (
adapters/lexical.py): token overlap, zero dependency — a doc relevant for an exact term but missed by the vector engine still surfaces.
RRF fusion: score(d) = 1/(k + vector_rank) + 1/(k + lexical_rank), k = 60. The first index_rebuild downloads the model.
Memories
A memory is a low-friction capture ("remember that the NAS runs Fedora 44"), with
no case workflow. It is stored as memories/<id>.md with YAML frontmatter
(metadata) and a free-form markdown body. Memories are indexed on every mutation
(create included) so they are immediately searchable. A memory is not
validated; promote it with memory_promote once it becomes validated knowledge.
Case schema
Defined in
src/sherlock_second_brain/schema/case.schema.json
— source of truth, shipped inside the package. Every case written through the MCP
is validated against this schema (works from PyPI installs too).
Tests
uv run ruff check src/ tests/ # lint
uv run ty check # type checking
uv run pytest tests/ -v # testsAvailable Tools
14 toolscase_add_evidenceC
Attach a piece of evidence (log excerpt, output, note) to a case.
Inputs: case_id (required), content (required), summary (required), filename. Returns: object
case_createA
Create an investigation case. Use this when a topic is not yet validated.
tags and references are comma-separated strings.
Inputs: goal (required), title (required), tags, context, +1 more. Returns: object
case_getA
Read a case by its id (e.g. case-2026-08-07-001).
Inputs: case_id (required). Returns: object
case_listA
List cases, optionally filtered by status (open/in_progress/resolved/abandoned) and tag.
Inputs: tag, status. Returns: result
case_promoteA
Promote a resolved case into validated KB: target = fiche or skill.
Generates the MD/SKILL.md from the case, writes it to the KB and marks the case.
Inputs: target (required), case_id (required). Returns: object
case_searchB
Semantic search across cases and KB. Use this FIRST when debugging or planning.
Inputs: query (required), top_k. Returns: result
case_set_statusA
Change a case status: open / in_progress / resolved / abandoned.
Inputs: status (required), case_id (required). Returns: object
case_updateA
Append to a case.
fields supports:
finding(str): append to findingsstep_action(str): append a step (with optionalstep_result)step_result(str): result for the step being appendedconclusion(str): set conclusionhypothesis_statement/hypothesis_test: append a hypothesistags(list[str]) /references(list[str]): replace lists
Inputs: fields (required), case_id (required). Returns: object
fiche_listA
List validated fiches (slugs).
Inputs: no named parameters. Returns: result
fiche_readC
Read a validated fiche by slug.
Inputs: slug (required). Returns: result
fiche_writeA
Create or overwrite a fiche. Prefer case_promote for validated knowledge.
Inputs: slug (required), content (required). Returns: result
index_rebuildA
Rebuild the vector index from all source files. Returns doc count.
Inputs: no named parameters. Returns: object
skill_listB
List validated skills (slugs).
Inputs: no named parameters. Returns: result
skill_readA
Read a validated skill by slug.
Inputs: slug (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 14 tools
Tools are mostly distinct, but case_update and case_add_evidence both append to a case, and case_promote vs fiche_write both create fiches, which could cause some confusion. The descriptions clarify the intended use, but the boundaries are not perfectly sharp.
All tools follow a consistent pattern of domain prefix (case_, fiche_, skill_, index_) followed by an action verb (get, list, search, update, promote, etc.). The naming is uniform and predictable across the entire set.
14 tools is within the ideal range for a specialized knowledge management server. Each tool covers a distinct aspect of the workflow, and the count feels neither sparse nor bloated.
The case lifecycle is well covered (create, read, list, search, update, add evidence, set status, promote), and the fiche/skill read/list operations support retrieval. However, there are no delete operations for cases or knowledge artifacts, and skills lack a direct write/update tool, which are minor but notable gaps.
Maintenance
Related MCP Connectors
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
MCP server for querying Forkast documentation
KnowMan MCP server: search, ask, save and read your Knowledge Base from any MCP client.
Related MCP Servers
- FlicenseBqualityDmaintenanceAn MCP server that enables interaction with Markdown knowledge bases, allowing users to search and retrieve content by tags, text, URL, or date range from their local markdown files.791-
- AlicenseAqualityDmaintenanceAn MCP server for managing Obsidian-style note vaults, providing tools for full-text search, note creation, and backlink tracking. It enables users to navigate, structure, and update their personal knowledge base through natural language.9MIT
- FlicenseCqualityDmaintenanceGit-backed MCP server for creating and maintaining an Obsidian-style markdown knowledge base with full CRUD, search, and git sync.7-
- AlicenseBqualityDmaintenancePython MCP server for programmatic access to markdown-based knowledge vaults, enabling AI assistants to browse, read, search, update, and manage notes, tasks, and projects.481MIT