This server provides tools for maintaining and querying a local Markdown/Obsidian vault as agent memory.
Check index health and stale notes, and rebuild the index incrementally or fully.
List notes by tag/folder and read notes or their outlines.
Run hybrid semantic/keyword search and find related notes via semantics and wiki-links.
Inspect backlinks, outbound links, broken links, hub notes, and orphan notes.
Create and patch notes with metadata, tags, aliases, descriptions, retraction/supersedes fields, and automatic index refresh.
Allows agents to use an Obsidian vault as long-term memory, providing tools to semantically search, read, write, and maintain Markdown notes, including backlinks, graph overview, broken links, and vault health metrics.
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., "@cog-brain search my vault for RAG evaluation notes and show backlinks"
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.
Your notes. Your agents. One memory.
Keep decisions, sources and next steps in Markdown. Let your coding agents bring that knowledge into your work, so the next session can pick up where you left off.
cog-brain connects a personal knowledge base to your coding agents. You read and edit the notes in Obsidian or your editor; agents search them, save useful findings and maintain a short handoff for each project.
Get started · Daily workflow · Integrations · Reference
Continue a project. Bring its goal, constraints and next action into a new session, including when you switch agents.
Remember the reason. Keep the decision, the evidence and the conditions under which it applies, alongside links to the original sources.
Capture without organizing first. Save an idea or a link in today's daily note. Turn it into lasting knowledge when it proves useful.
Keep corrections visible. Withdrawn claims remain searchable with a warning and a link to their replacement.
The working loop is small: recall context, do the work, save what you verified, leave a useful next step.
Related MCP server: Brainstem
You'll need macOS or Linux, Python 3.12+, uv, and an existing folder of Markdown notes. Obsidian is optional. The default search engine runs locally without Docker or an embedding service.
uv tool install git+https://github.com/cog-sh/cog-brainPoint it at your existing vault and build the local index:
cog-brain setup --vault ~/Notes
cog-brain doctorSetup saves the vault and backend to ~/.config/cog-brain/config.toml, preserving
other settings and backing up changes. SQLite is the default: no Docker, account
or model download. Replace ~/Notes with your folder of notes.
Choose your client (the integration table lists all options):
cog-brain install --harness codex --mode code
# Other examples:
cog-brain install --harness claude-code --mode code
cog-brain install --harness opencode --mode codeRestart the client and enable its hooks if prompted. In Codex, open /hooks
and approve the new cog-brain handlers. A managed instruction provides CLI recall
while those hooks await review.
Installation adds a skill and the client's hooks, extension or instructions.
It backs up changes, preserves unrelated settings and disables only the existing
cog-brain MCP entry. Use --keep-mcp to retain it. Add --scope project to install
in the current repository (required for VS Code).
Open a repository in your agent and ask:
Create a cog-brain project card for this repository. Link it to a relevant existing note. Record the goal, current state, constraints and next step.
That card binds the repository to its memory. Future tasks can retrieve the card and relevant notes automatically. If a project has no card, cog-brain reports that explicitly.
Try it with an ordinary question:
Where should we pick up on this project?
When | What you do | What the agent keeps |
Start a session | Describe the task | The project card and relevant evidence in context |
Find something interesting | “Capture this link for later” | Raw material in |
Settle a decision | “Save why we chose this” | A linked note with the reason, scope and verification |
Finish or switch projects | “Update the handoff” | Current state, checks, blockers and the next action |
Once a week, review the captures worth developing and the projects still active. Daily notes stay out of ordinary knowledge retrieval, so an unprocessed thought doesn't become a confirmed fact just because it was saved.
You can keep using your existing vault. New knowledge notes use a short description and a link to an existing note; project cards stay brief enough to read at the start of a session.
See the note formats and writing guide for the conventions shared by you and your agents.
Client ( | How memory reaches the agent |
Codex ( | Session/prompt hooks; AGENTS fallback; hook approval required |
Oh My Pi ( | Native extensions before work and after compaction |
Claude Code ( | SessionStart and UserPromptSubmit hooks; CLAUDE.md fallback |
Gemini CLI ( | SessionStart and BeforeAgent hooks; GEMINI.md fallback |
Cursor ( | SessionStart hook; project rule for task-time recall |
OpenCode ( | Native context hook; V2 default, |
Copilot CLI ( | Instructions ask the agent to recall through its executor |
VS Code Copilot ( | Repository instructions and skill; project scope only |
Windsurf ( | Global/project rules ask the agent to recall through its executor |
Other MCP clients | Optional MCP adapter |
All code integrations use the existing executor and local runtime. Hook-based clients can receive a bounded project packet before answering; instruction-based clients depend on the agent following the recall rule. Cursor's startup hook loads context once per session; its prompt-validation hook cannot inject context. Client permissions and hook support still apply.
For marketplace installation and /brain-* commands, see
cog-brain-plugins.
Code Mode means an agent can search, read several notes and filter the results inside one program. Only what the program returns needs to enter the model's context. MCP remains available for clients that use it.
For example, inside a Python environment with cog-brain installed:
import json
from cog_brain import Brain
brain = Brain()
found = brain.search("why did we choose this database?", project="my-project", limit=4)
notes = [
brain.read(hit["file_path"], max_chars=1200)
for hit in found["hits"][:2]
]
print(json.dumps({"notes": notes, "warnings": found["warnings"]}, ensure_ascii=False))Replace my-project with your project card's identifier. See the
API and integration reference for setup details and commands.
The vault is the source of truth. Notes remain ordinary Markdown with YAML
properties and [[wiki-links]]. The search index can be rebuilt from those files.
cog-brain preserves existing YAML fields and comments when editing notes. Writes are atomic, concurrent appends are serialized, and replacing a note's body through the Python API requires the revision you read. Indexing failures are reported separately from a successful note save.
You can edit in Obsidian or another editor. External editors do not participate in cog-brain's locks; detected conflicts require a fresh read. Malformed YAML is reported instead of silently rewritten.
Files and indexes live locally by default. Retrieved notes become part of the context sent to your chosen agent's model provider. With vector search enabled, embedding requests go to the endpoint you configure.
Engine | Best starting point for | What it needs |
SQLite — default | Local keyword search with a persistent index | No background services |
Markdown | Searching directly from the vault without a persistent index | No background services |
Qdrant | Hybrid semantic and keyword search | Qdrant and an embedding endpoint |
Automatic lifecycle context uses local keyword search even when Qdrant is your configured engine, so it doesn't wait for the vector services to start.
After editing notes outside cog-brain, run cog-brain reindex. During a longer
editing session, cog-brain-index --watch keeps the index updated.
cog-brain setup --backend qdrant --vault ~/Notes --dry-run
cog-brain setup --backend qdrant --vault ~/NotesSetup reuses healthy Qdrant/Ollama endpoints. If either service is missing locally, it needs a running Docker installation and starts only that service. It downloads the embedding model when needed, checks its 1024-dimensional output and collection compatibility, then saves the backend and indexes your vault. The first run needs internet, disk space and time.
Managed services bind to 127.0.0.1, restart with Docker and keep data in named
volumes. Setup never deletes a container, volume or collection. You can return to
service-free search with cog-brain setup --backend sqlite; vector data stays in
place. See bootstrap details.
cog-brain is an early release. Local API, note safety and integration behavior have isolated regression coverage. Autonomous CLI recall has also been checked in a live Codex session. Additional client adapters and service bootstrap have isolated regression coverage; complete live LLM workflows across every client and fresh Docker downloads are not yet validated.
Automatic recall requires a bound project card and an enabled client integration. The agent saves decisions and handoffs through the API; hooks do not archive every conversation or turn every answer into a note.
MIT licensed. Built by cog-sh.
Who links to this note (inbound) and where this note points (outbound, with resolution).
Frontmatter links count: moc: "[[Rust MOC]]" is a real reference.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does add useful behavioral context: outbound links are returned 'with resolution' and frontmatter links count as real references (with a concrete example). That is genuinely non-obvious. But it says nothing about pagination/limiting behavior or the cost of the operation.
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, front-loaded sentences with the core purpose stated first and a clarifying edge-case note second. Minimal waste, though the second sentence is a somewhat disjoint detail.
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. Given no annotations and 0% schema coverage, the definition still leaves the `k` parameter, pagination, and when-to-use-versus-siblings unaddressed, making it adequate but incomplete.
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 2 parameters. The description never mentions `k` (the result limit) or clarifies `file_path`; only 'this note' loosely implies the target. With zero coverage in the schema, the description should compensate but does not.
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 purpose: it returns inbound links (who links to this note) and outbound links (where the note points). This clearly distinguishes it as a link-relationship tool versus a content reader. However, it does not explicitly differentiate itself from closely-related siblings like broken_links, find_related, or graph_overview.
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 clarifies scope and what the tool returns, so usage is implied, but there is no explicit when-to-use guidance and no named alternatives among the many link/graph-related siblings (broken_links, find_related, graph_overview). The agent must infer when this is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wiki-links that resolve to no existing note (by stem or title), grouped by source note.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does disclose one behavioral trait beyond the schema: results are grouped by source note, which tells the agent the return shape. However, it says nothing about the index dependency (index_now exists as a sibling, implying staleness is possible) or the read-only/rate-limit profile.
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 dense sentence with no wasted words, front-loading the defining characteristic (links that resolve to nothing) and the grouping in one clause.
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, and the grouping is stated. Still missing for a link-integrity tool are the index-freshness caveat and the semantics/scope of limit, leaving an agent to guess about result truncation.
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 the description never mentions the sole parameter. It is unclear whether limit caps broken links, source notes, or groups, nor what the default 200 means in context — the description does not compensate for the schema gap.
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 names a specific resource and scope: wiki-links that fail to resolve, resolved by stem or title. It is a noun phrase with no verb, but the intent (find broken links) is unambiguous and clearly distinct from the broader backlinks and graph_overview siblings.
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?
Usage is implied by the resource itself — an agent looking for dangling wiki-links would pick this up — but there is no explicit when-to-use statement, no mention of prerequisites such as a fresh index, and no comparison against the overlapping backlinks tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Knowledge-graph overview: hub notes (most outgoing wiki-links — MOC candidates) and orphans (no links at all).
| Name | Required | Description | Default |
|---|---|---|---|
| k | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 clarify what the operation yields by defining 'hub' and 'orphan' semantically. However, it says nothing about read-only behavior, cost, whether the graph is computed live, or pagination/limits on the returned results.
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, dense sentence that front-loads the resource and immediately defines both returned categories. There is no filler and nothing that could be cut without losing meaning.
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?
Because an output schema exists, return values need not be described, and the qualitative category definitions are helpful. But the unexplained k parameter and the complete absence of usage guidance leave real gaps for an agent deciding whether and how to call this.
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 parameter 'k', and the description never mentions it. An agent cannot tell from either source whether k controls the number of hubs, orphans, or both, nor how it interacts with the default of 15.
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 names the specific resource (knowledge graph) and precisely defines its two output categories: hubs as notes with the most outgoing wiki-links and orphans as notes with no links. That makes it distinguishable in spirit from backlinks or broken_links, though it never names those siblings explicitly.
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 statement of when to call this versus siblings like backlinks, broken_links, or list_notes, and no exclusions or prerequisites. The agent must infer the use case from the subject matter alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the vault indexer now (incremental; full=True re-embeds everything).
Concurrent runs are safe: the indexer holds a lock and a second run exits immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| full | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden and does disclose meaningful behavior: the lock-based concurrency model and that a competing run exits immediately, plus the fact that 'full=True' re-embeds everything (a costly, potentially long operation). It omits expected duration, whether the call blocks the caller, and any permission requirements.
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, no filler. The primary action is front-loaded and the concurrency caveat follows, so the most important information comes first.
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, and the mutation/concurrency behavior is covered. What remains thin for a state-mutating indexer is the absence of any note on typical runtime, resource cost, or whether the caller is blocked while indexing runs.
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% and the 'full' property has no description, so the description must compensate — and it does, explaining that the default is incremental while 'full=True' re-embeds everything. Minor gap: no detail on cost/runtime tradeoffs of full mode.
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: 'Run the vault indexer now', with an explicit scope modifier ('incremental' by default). No sibling tool (vault_status, list_notes, semantic_search, etc.) performs indexing, so an agent can route to it unambiguously.
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?
Implies use when the index needs refreshing, and the 'full=True' note hints at the choice between incremental and full runs. However, it never states when an agent should trigger re-indexing versus relying on existing state, nor any prerequisites before calling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cheap inventory of notes: file_path, title, type, status, tags. Filter by tag or folder prefix.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| limit | No | ||
| folder | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does disclose that this is a lightweight listing returning only metadata fields (implying no note bodies), but says nothing about permissions, pagination beyond the schema default, or whether results are ordered or truncated. Partial disclosure only.
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 terse sentences, front-loaded with what the tool returns, then how to filter. Every clause 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 need not be fully specified, and the description still summarizes them. For a simple zero-required-parameter read tool this is nearly sufficient; only the 'limit' behavior and result ordering are left to inference.
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 covers two of three parameters ('tag', 'folder prefix'), and 'prefix' adds matching semantics beyond the schema, which is genuinely useful. However, the 'limit' parameter is left unexplained 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?
The description names a specific action and resource ('inventory of notes') and enumerates the fields returned (file_path, title, type, status, tags), which tells an agent this is a metadata-only listing rather than a content read. It stops short of naming a sibling such as read_note or semantic_search explicitly, so it is clear but not fully differentiated.
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 word 'cheap' implicitly signals when to prefer this over heavier tools like semantic_search or read_note, but there is no explicit when-to-use or when-not-to-use statement and no named alternative. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Headings of a note with their levels — cheap context before reading the whole thing.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that this is a lightweight/cheap read that returns only headings rather than full content, but says nothing about failure modes (missing file), permissions, or size 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?
A single front-loaded clause: what it returns, then why it is worth calling. 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?
An output schema exists, so return-value detail is not required, and the description still summarizes the shape (headings + levels). For a one-parameter read tool this is essentially complete; only path-format guidance is 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 coverage is 0% for the single file_path parameter, so the description must compensate. 'of a note' weakly implies the path is a note identifier, but format/source (vault-relative vs absolute) is left entirely unstated.
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 precisely what is returned: a note's headings with their levels. Implicitly distinguishes itself from read_note via 'cheap context before reading the whole thing,' though it never names the sibling explicitly.
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?
'before reading the whole thing' implies the workflow position relative to read_note/read tools, giving usable but inferred guidance. There is no explicit when-not-to-use or named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the full text of a vault note by its relative path (path from semantic_search/list_notes).
max_chars bounds the result for a large note; the truncation is marked explicitly.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| max_chars | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does disclose real behavior — max_chars bounds output and truncation is explicitly marked — which is genuinely useful. It omits, however, what happens on a missing/invalid path or non-text file, and gives no hint about encoding or result metadata, leaving notable gaps for a read operation.
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 purpose, then the one behavioral nuance that matters (truncation). Nothing redundant or padded.
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 documented, and the description covers the path source and truncation behavior. The main residual gap is error/missing-file behavior, which keeps it from a 5 for a tool with zero annotation coverage.
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, and it largely does: max_chars is explained (bounds the result, truncation is marked) and file_path is defined as a relative path sourced from semantic_search/list_notes. What's missing is what the path is relative to (vault root) and any default/limit semantics for max_chars beyond null.
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 (vault note) plus the lookup key (relative path), which cleanly separates it from write_note, update_note, and the snippet-returning semantic_search. An agent can tell what this returns (full text) versus a listing or search tool.
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 parenthetical '(path from semantic_search/list_notes)' tells the agent the intended workflow: obtain a path from a search or listing tool, then read here. It gives clear context but names no explicit exclusion or alternative condition, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hybrid (dense+BM25, RRF) semantic search over the Obsidian vault. Returns chunks with file_path citations.
chunks_per_note raises how many chunks one long note may contribute (default 1, the previous
behaviour). Every result carries index_stale: how many notes changed since the last index —
0 means the results are current, -1 means the index has never run. Trust accordingly.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | ||
| tag | No | ||
| query | Yes | ||
| folder | No | ||
| chunks_per_note | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 well: it discloses the retrieval method (dense+BM25 fused with RRF), the return content (chunks with citations), and, notably, the semantics of the `index_stale` result field (0 = current, -1 = never run) so the agent can gauge trust. It stops short of 5 only because it omits things like result freshness implications of running a search against a stale index or whether an indexing step is required first.
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?
Front-loaded with the core capability, then a short paragraph on the one non-obvious parameter and the staleness signal. Every sentence earns its place; minor verbosity in the parenthetical '(default 1, the previous behaviour)'.
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, yet the description usefully clarifies the subtle `index_stale` field. However, for a 5-parameter tool with 0% schema coverage it leaves `k`, `tag`, and `folder` entirely unexplained, which is a real gap 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 description coverage is 0% across 5 parameters. The description explains `chunks_per_note` well and implies `query`, but `k`, `tag`, and `folder` receive no meaning, syntax, or filtering guidance in either the schema or the description, leaving half the surface undocumented.
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?
Names a specific verb+resource: hybrid (dense+BM25, RRF) semantic search over the Obsidian vault, and states the return shape (chunks with file_path citations). It does not explicitly differentiate itself from near siblings like find_related or list_notes, so it stops 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 when-to-use guidance and no routing to alternatives such as find_related, read_note, or a keyword search. The reader must infer that this is the tool for semantic retrieval over the vault, and nothing tells them when a different sibling is preferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Patch an existing note in place: frontmatter fields and/or body, bumping updated.
Only the arguments you pass are changed. content replaces the body, or appends to it with
append=True. The result is re-checked for at least one resolvable [[wiki-link]].
| Name | Required | Description | Default |
|---|---|---|---|
| moc | No | ||
| tags | No | ||
| type | No | ||
| title | No | ||
| append | No | ||
| status | No | ||
| aliases | No | ||
| content | No | ||
| file_path | Yes | ||
| retracted | No | ||
| auto_index | No | ||
| supersedes | No | ||
| description | No | ||
| superseded_by | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does add real value: partial-patch semantics ('Only the arguments you pass are changed'), the `updated` bump, and a validation constraint (at least one resolvable [[wiki-link]] must remain). However, it omits auth/permission needs, what happens on a nonexistent file, and the effect of auto_index/retracted, leaving meaningful gaps for a 14-param mutation.
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?
Three tight sentences, front-loaded with the core action and constraint; each sentence conveys distinct information about mutation scope, body handling, and validation. 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?
For a 14-parameter, unannotated mutation with 0% schema coverage, the description leaves most parameters and failure modes undocumented, even though the presence of an output schema excuses it from explaining return values. It is not complete enough for an agent to invoke confidently across the full parameter set.
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 for 14 undocumented parameters. It only clarifies `content` (replaces body) and `append` (appends instead), plus a vague reference to 'frontmatter fields'; the remaining ~11 params (moc, tags, type, title, status, aliases, auto_index, supersedes, etc.) get no semantic help from either source.
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 ('Patch an existing note in place') and clarifies that it touches frontmatter fields and/or body while bumping `updated`. This makes the patch-vs-full-write distinction against write_note inferable, though the sibling is never named explicitly.
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 explains mechanics but never states when to choose update_note over write_note or other siblings, nor any prerequisites (e.g. the note must already exist). No when/when-not guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index health: notes on disk vs indexed, when the index last ran, and which notes changed since.
Call this before trusting a search result: after a write the index is refreshed automatically, but a manual file edit from outside this server leaves it stale.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 usefully discloses the index-refresh behavior (writes auto-refresh, external edits leave it stale), which is genuine context beyond the tool's output. It does not state read-only/safety profile or any permission/rate constraints, keeping it out of 5 territory.
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?
Front-loaded with the core definition ('Index health: ...') followed by tightly relevant usage context. Two short blocks with no padding, though the second paragraph blends usage guidance with behavioral detail.
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 no elaboration, and with zero parameters the schema gap is nil. The description supplies purpose and the key staleness caveat, making it complete enough to call 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 tool takes zero parameters, so the schema cannot carry semantic weight; baseline is 4. Nothing in the description misrepresents the empty argument set.
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 resource and scope: reports index health, specifically notes on disk vs indexed, last run time, and which notes changed. This clearly distinguishes it from search/read siblings, though it does not name a specific sibling it differs from (e.g. index_now) to reach 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?
Gives an explicit condition for use: 'Call this before trusting a search result,' tied to the trigger of an external manual file edit leaving the index stale. Lacks an explicit pointer to the remediation sibling (index_now) for when the index is stale, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new vault note. Flat vault: file_path is kebab-case EN in the vault root.
description is required (one sentence — it is the RAG chunk title) and moc takes either
Rust MOC or [[Rust MOC]]. The body must link at least one EXISTING note; links that do
not resolve yet are reported back rather than rejected, so a hub may be written before its
spokes. The index is refreshed automatically (set auto_index=False to batch).
| Name | Required | Description | Default |
|---|---|---|---|
| moc | No | ||
| tags | No | ||
| type | No | zettel | |
| title | Yes | ||
| status | No | seedling | |
| aliases | No | ||
| content | Yes | ||
| file_path | Yes | ||
| retracted | No | ||
| auto_index | No | ||
| supersedes | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses that unresolved links are reported rather than rejected and that the index refreshes automatically, which is non-obvious context. But it omits a critical write-tool behavior: what happens if file_path already exists (overwrite vs. error), and any permission/conflict semantics.
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?
Front-loaded with the core purpose, then layered with format and behavioral detail; every sentence carries information and nothing is padded. The one blemish is the misplaced '`description` is required' claim, which is both incorrect against the schema and interrupts the otherwise tight structure.
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 12-parameter mutation tool with 0% schema coverage and no annotations, the description covers the trickiest params and two key behaviors, which is meaningful. But it leaves most parameters undocumented and never resolves the overwrite/conflict question, so an agent could still call it incorrectly. The existing output schema relieves the description of return-value duty.
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, and it does add real meaning for a few params (file_path kebab-case EN in vault root, moc accepts 'Rust MOC' or '[[Rust MOC]]', auto_index batching). However, 8 of 12 params (tags, type, status, aliases, retracted, supersedes, content, title) get no semantic treatment. It also asserts 'description is required' while the schema marks it optional with default null — a factual conflict.
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 first sentence gives a specific verb+resource: 'Create a new vault note.' The word 'new' distinguishes it implicitly from the sibling update_note, but that contrast is never made explicit. An agent can identify the operation, but the sibling differentiation is left to inference.
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 supplies workflow context (a hub may be written before its spokes, use auto_index=False to batch) which implies how the tool fits into a flow. However, it never states when to reach for write_note versus update_note, nor any prerequisites such as whether the target file must not already exist. Usage is implied, not directed.
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.0backlinksbroken_linksfind_relatedgraph_overviewindex_nowlist_notesoutlineread_notesemantic_searchupdate_notevault_statuswrite_noteScored across 12 tools
Each tool targets a distinct action or resource: status, inventory, outline, full read, search, related notes, backlinks, broken links, graph overview, create, update, and index. Overlaps are minimal and descriptions clearly differentiate.
Some tools use verb_noun (list_notes, read_note, write_note, update_note, find_related), while others are noun phrases (vault_status, semantic_search, backlinks, broken_links, graph_overview). The mix is readable but not a consistent pattern.
12 tools is well within the typical 3-15 range and each tool has a clear, non-redundant purpose for managing an Obsidian vault.
The surface covers create, read, update, search, linking, and indexing, but lacks a delete_note operation and any move/rename capability. These are notable gaps for full vault lifecycle management.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
A second brain for your AI agent. Shared memory for your team's AI agents, plus public and private knowledge bases — works with ChatGPT, Claude, Cursor and any MCP client.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
