Provides a Dockerfile to build a single runtime image that includes both the backend and the UI; images are published to ghcr.io and can be run with Docker.
Configuration uses a .env file (copied from .env.example) to set environment variables such as VAULT_DIR.
The backend is built with FastAPI, exposing a REST API for notes, search, feedback, capture, request, audit, and health endpoints.
Changes to the vault and feedback queue are recorded in an append-only JSONL audit log, analogous to git history for auditing purposes.
The project is hosted on GitHub and uses GitHub Actions for CI and Docker image publishing, with images pushed to GitHub Container Registry (ghcr.io).
Stores each note as a Markdown file in a vault, with folders represented as real directories, supporting flat or nested structures.
The project uses pytest for testing, following a TDD approach with tests run via uv.
Implemented in Python 3.13, using uv for dependency management and packaging.
An information management system meant for AI. A fully fledged markdown vault
wiki: view it as a wiki in the web UI, CRUD any page, move notes, search by
name or content. One note = one .md file, folders = real folders, flat or
nested.
Think of it as a librarian: ask for information and it is presented when available; missing information is logged for future action so the librarian can retrieve it later. The feedback function is the improvement queue — corrections, missing-info notes, requests. In increments the librarian processes the capture queue (reviewed and double-checked) before updating the vault. All changes to the vault and the queue are audited (like git). Mutations flow through one audited service layer, exposed to agents via MCP.
src/mysharedbrain/ backend (uv · Python 3.13 · FastAPI · FastMCP)
vault.py CRUD + move + ripgrep search over markdown files
capture.py feedback queue (pending → applied/rejected)
audit.py append-only JSONL audit log (like git log)
service.py the librarian: single audited mutation path
app.py REST API + serves the UI
mcp.py MCP server (7 tools)
frontend/ decoupled static UI (no build; HTTP JSON only)
Dockerfile single runtime image (backend serves the UI)Related MCP server: Obsidian MCP
You need uv.
cp .env.example .env # set VAULT_DIR (default ./vault)
uv sync
uv run pytest src/tests/ -q # TDD: tests first, always green on main
uv run mysharedbrain # API + UI on http://localhost:8000
uv run mysharedbrain --mcp # MCP server over stdioTool | Description |
| Create note |
| Read note by id |
| Update note by id |
| Delete note by id |
| Move/rename note |
| Search names + content (ripgrep) |
| Correct info · flag missing info · file a request |
| Ask the librarian; misses are logged for future retrieval |
Add to an MCP client (stdio):
{ "mcpServers": { "mysharedbrain": {
"command": "uv", "args": ["run", "mysharedbrain", "--mcp"],
"cwd": "/path/to/mysharedbrain",
"env": { "VAULT_DIR": "/path/to/vault" }
} } }Notes POST/GET/PUT/DELETE /api/notes… (+ /move), GET /api/search?q=,
POST /api/feedback, GET /api/capture, POST /api/capture/{id}/review,
POST /api/request, GET /api/audit, GET /health.
docker build -t mysharedbrain .
docker run -p 8000:8000 -v mysharedbrain-data:/data/vault mysharedbrainImages are published to ghcr.io/hampusadamsson/mysharedbrain (sha-<sha>,
latest on main).
$VAULT_DIR/
<note-id>.md notes, flat or in real folders
.brain/
capture.jsonl feedback queue (JSONL, one entry per line)
audit.jsonl append-only change history (JSONL)Ask the librarian. Answered from the vault when possible, otherwise logged as missing information for future retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| question | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose one non-obvious trait: unanswered questions are 'logged as missing information for future retrieval', i.e. a write side effect. It does not say whether the call is read-only overall, whether the logging is visible to the caller, or anything about latency, auth, or rate limits.
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 sentences with no filler, and the core action ('Ask the librarian') is front-loaded before the behavioral clause. Nothing redundant, though the wording is slightly cryptic rather than maximally clear.
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?
An output schema exists, so return-value explanation is not required, and the description covers the basic request/response plus fallback behavior. However, with no annotations and no usage guidance, an agent still lacks clarity on the write side effect's implications and how this tool relates to search_notes.
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 description coverage is 0% for the single 'question' parameter, so the description should compensate but largely does not — no guidance on phrasing, length, or whether the question should be self-contained. It only implies the parameter is a natural-language question answered from the vault.
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 gives a concrete verb (ask) and names the domain (the librarian / the vault), and the second clause states exactly what the tool produces: an answer or a logged miss. It is distinguishable from the note CRUD siblings, though the 'librarian' metaphor leaves the backing service somewhat opaque.
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?
There is no when-to-use guidance and no comparison to search_notes, the obvious alternative for retrieving vault content. An agent must infer that ask_question is for open questions rather than lookups; nothing states that distinction or any prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new markdown note. Folders are created from the id path.
| Name | Required | Description | Default |
|---|---|---|---|
| content | No | ||
| note_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it discloses only one side effect: folders are auto-created from the id path. It says nothing about overwrite/conflict behavior when a note_id already exists, permissions, or reversibility, which matter for a mutation tool.
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 sentences, front-loaded with the core action and followed by the one non-obvious behavioral note. Every sentence earns its place with no filler.
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?
An output schema exists, so return values needn't be explained, and the tool is simple (2 params, 1 required). However, the absence of annotations means conflict/overwrite behavior and permission requirements are left undocumented.
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 description coverage is 0%, so the description must compensate. It adds meaning by implying note_id is a path structure (folders derived from it) and that content is markdown, but it doesn't clarify the id format, the empty-string content default, or required vs optional.
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 a specific verb and resource ('Create a new markdown note') which distinguishes it from read/update/delete/move/search siblings. It doesn't explicitly name a sibling it isn't, but the create semantics are unambiguous.
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?
There is no when-to-use guidance, no prerequisites, and no mention of when to prefer this over update_note or move_note. Usage is only implied by the verb 'Create'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a note by id.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden but says nothing about irreversibility, confirmation requirements, permission needs, or whether the deletion is soft or permanent. For a destructive operation this is a significant gap.
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?
A single short sentence that is front-loaded and wastes no words, but its brevity reflects under-specification rather than disciplined conciseness.
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?
An output schema exists so return values need not be explained, but for a destructive tool with zero annotations the description should at minimum warn about permanence or required permissions. It leaves an agent without the context needed to invoke safely.
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 description coverage is 0%, so the single required parameter note_id is undocumented in the schema. The phrase 'by id' only vaguely gestures at the parameter and adds no format, type, or sourcing guidance beyond the schema's own field name.
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 a specific verb and resource ('Delete a note'), which is unambiguous and distinguishably different from siblings like create_note, read_note, and update_note. However, it does not explicitly differentiate itself from potential alternative deletion paths or note-scoping concerns.
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 versus alternatives, no prerequisites, and no mention of consequences. The only implied usage is 'you have a note id and want it gone,' which the agent must infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queue feedback: correct info, flag missing info, or file a request.
kind is one of: correction | missing | request.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| kind | Yes | ||
| note_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. The word 'Queue' usefully implies asynchronous, non-blocking submission rather than an immediate answer, which is real behavioural signal. But it says nothing about who consumes the feedback, whether it is anonymous, whether it requires auth, or any rate limits.
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 lines with zero filler: the action and its three modes come first, then the enum constraint. Every sentence earns its place and nothing is buried.
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?
An output schema exists, so return values need not be explained. But for a 3-parameter tool with 0% schema coverage, only kind is really covered; note_id and body semantics, and the tool's relationship to ask_question, are missing.
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 description coverage is 0% and there are 3 parameters. The description usefully enumerates the allowed kind values (correction | missing | request), which the schema lacks as an enum, so it compensates for the most important parameter. It says nothing about body or about note_id, whose empty-string default and relationship to a note are left entirely opaque.
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 states a specific verb and resource ('Queue feedback') and breaks it into three concrete modes: correct info, flag missing info, file a request. That distinguishes it from the note CRUD siblings and from ask_question, though it never explicitly contrasts itself with ask_question, which is the closest functional neighbour.
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 three phrasings map intent to the kind values, which implicitly tells the agent which mode to pick. However, there is no guidance on when to use this tool versus ask_question, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move/rename a note.
| Name | Required | Description | Default |
|---|---|---|---|
| new_id | Yes | ||
| note_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It only restates the operation type and says nothing about what happens if new_id already exists (overwrite vs. error), whether the operation is reversible, or what permissions are required — critical for a mutation whose name implies destruction of the original identifier.
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?
A single short sentence with zero filler, front-loading the verb and resource. It is efficient, though the brevity reflects under-specification more than disciplined conciseness.
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?
The presence of an output schema relieves the description of explaining return values, but for an unannotated mutation tool with 0% parameter documentation and a name implying overwrite risk, the definition omits too much for an agent to call it safely.
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 description coverage is 0% and neither parameter is explained. The description hints that new_id is the rename target, but it does not clarify whether new_id is a new name, path, or identifier, nor what the distinction between the two required string params is.
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 a specific verb pair (move/rename) and the resource (a note), which is enough for an agent to identify the operation. It does not differentiate itself from siblings like update_note, which also modifies an existing note, but the core purpose is unambiguous.
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 when-to-use guidance, no prerequisites, and no mention of alternatives. An agent gets no signal on when to choose move_note over update_note or how it relates to delete_note/create_note workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a note by id.
| Name | Required | Description | Default |
|---|---|---|---|
| note_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does not state whether the note is returned whole or paginated, what happens on missing/invalid id, or any permission requirements. 'Read' implies non-mutating, but nothing is confirmed.
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?
One short sentence, front-loaded with the verb and resource, with no filler. It is appropriately sized for a simple one-parameter tool.
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?
With an output schema present, return format needn't be described. However, for a retrieval tool with no annotations and an undocumented parameter, the description is minimally adequate—it should at least clarify id format or error behavior.
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 single parameter note_id has no description in the schema (0% coverage), but the description's phrase 'by id' indicates the required identifier. Baseline for a short schema is limited, and it adds only minimal meaning beyond the parameter name.
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 a specific verb (read) and resource (note), plus the lookup key. It distinguishes from create/update/delete/move siblings by implication, but does not explicitly differentiate from search_notes, which also retrieves notes.
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 versus search_notes or the other note tools. An agent must infer that this is for direct retrieval by known id, but nothing is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search notes by name and content (ripgrep).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The parenthetical '(ripgrep)' hints that the query supports regex/substring matching, which is a useful but thin disclosure; nothing is said about case sensitivity, matching scope beyond name/content, or result ordering.
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?
A single front-loaded sentence with no wasted words. It is efficient, though arguably so terse that it under-delivers rather than being an example of well-structured completeness.
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?
An output schema exists, so return values need not be described. However, for a no-annotation search tool with 0% schema coverage, the description omits query matching semantics, the limit parameter, and any routing versus read_note, leaving it incomplete for correct invocation.
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%, so the description must compensate. It does clarify that the required 'query' parameter searches both name and content, which adds real meaning, but the 'limit' parameter (default 20) is never mentioned, leaving its behavior undocumented in both schema and description.
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 a specific verb and resource ('Search notes') and names the fields searched ('by name and content'), so an agent can distinguish it from mutation siblings like create_note/update_note. It does not explicitly contrast with read_note, which is the closest alternative, so it falls short of a 5.
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?
There is no explicit when-to-use guidance, no exclusions, and no named alternative such as read_note for retrieving a known note. The usage is only weakly implied by the word 'Search', so the agent must infer when this beats read_note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a note's content by id.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| note_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full behavioral burden. It implies a full overwrite ('replace'), which is useful, but doesn't state whether this requires the note to exist, what permissions are needed, or whether changes are reversible.
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?
A single nine-word sentence, front-loaded with the action and resource, with zero filler.
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?
With an output schema present, return-value explanation is not needed, but the description lacks any behavioral context (permissions, existence requirements, replacement semantics) and gives no usage guidance, making it thin for a mutation tool with no annotations.
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%, meaning the schema only defines types (note_id: string, content: string) without descriptive text. The description implies note_id identifies the target and content is the new value, but adds no format, length, or validation details beyond that. Baseline is 3 when schema coverage is low but the description maps parameters to their roles.
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 a specific verb (replace) and resource (note, by id), which clearly distinguishes it from siblings like create_note and delete_note. However, it doesn't explicitly contrast with create_note's use case or clarify the replace semantics versus an additive update.
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 when-to-use guidance, no prerequisites, no mention of alternatives like create_note if the note doesn't exist. The agent is left to infer the context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0ask_questioncreate_notedelete_notegive_feedbackmove_noteread_notesearch_notesupdate_noteScored across 8 tools
Core note CRUD tools are clearly distinct by action and resource, and search/move are well differentiated. Minor overlap exists between update_note and move_note, and between give_feedback and ask_question when logging missing information, but descriptions largely resolve this.
All tools follow a consistent snake_case verb_noun pattern: create_note, read_note, update_note, delete_note, move_note, search_notes, give_feedback, ask_question. The convention is predictable throughout.
Eight tools is well-scoped for a note vault with feedback and question support. Each tool has a clear, non-redundant purpose and the set is neither thin nor bloated.
The server covers full note lifecycle: create, read, update, delete, move/rename, and search, plus feedback and question channels. A list_notes or folder-listing operation is missing, but search may serve as a workaround for most discovery needs.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Shared project wiki for AI agents: read and write pages, next actions, and activity logs over MCP.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
