Skip to main content
Glama
rwnalds

Engram

by rwnalds
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Engram is a self-hosted MCP server + dashboard that gives Claude Code, Cursor, Hermes, and any Model Context Protocol agent shared, long-term memory they read and write — over a plain, git-backed folder of markdown you own. Built for the case a single agent's memory never hits: a team running several agents against one brain.

Autonomous agents forget everything between sessions — and worse, they can't tell what they remember is still true. An agent pulls an old README, a retired price, an API doc you changed months ago, and quotes it with full confidence, because keyword and vector search both rank by resemblance, not truth. Engram makes "is this still true" a first-class, written property: mark a fact superseded or expired and search withholds it — and tells the agent what it skipped and why. Per-agent read/write tokens and a git audit trail of who-wrote-what keep it sane when the writers are a fleet, not just you.

Unlike a headless memory store, you can watch it happen. A fast dashboard lets you search your brain, see exactly what every agent and teammate changed (with per-file diffs), jump back into recent notes, and curate it all — while agents read and write the same vault over one MCP endpoint. No database: your .md files are the source of truth, git is the durable store, and an in-memory index powers full-text search + a wikilink knowledge graph.

Deploy on Railway Deploy to Render

CI License: MIT Docker

Opinionated about how it stores memory — git-backed markdown, no database, agents write (not just read), self-hosted. Unopinionated about what you keep in it — any markdown vault, any folder structure, any MCP client. Point it at a fresh repo or your existing Obsidian vault: no import step, no lock-in.

What it's for · How it compares · Features · Works with · Quick start · MCP tools · Deploy · FAQ · Contributing

What it's for

  • Shared memory for a team running multiple agents — one vault, many agents reading and writing concurrently, with per-agent read/write tokens and a git audit trail of who changed what.

  • Memory that knows what's still true — retire a price, a term, or a changed API doc and your agents stop quoting it; they're told what they skipped and why. The failure a single agent's memory never fixes.

  • Long-term memory for Claude Code and other coding agents — stop re-explaining your project every session.

  • A self-hosted, Obsidian-compatible second brain exposed over MCP — your notes, your server, your git repo.

  • Memory you can see, not a black box — a dashboard to search, watch (with diffs), and curate what your agents remember.

  • Markdown RAG without the vector database — full-text search + a link graph over human-readable files.

Related MCP server: mem-universe

How it compares

Most agent memory is built to answer "what did I store about this?" Engram is built to answer "what is still true about this?" — a different question, and the one that bites when an agent quotes a price you retired months ago.

Engram

Vector-store memory(mem0, Zep, …)

Markdown memory(Basic Memory, …)

Plain RAG over docs

Storage

markdown files, git is the database

embeddings in a vector DB

markdown files

embeddings in a vector DB

Ranking

relevance × authority

similarity

relevance

similarity

Knows a fact is retired

✅ superseded_by + valid_until, enforced at search

—

—

—

Explains what it withheld

✅ excluded[] with a reason per note

—

—

—

Retire + replace atomically

✅ brain_supersede, one commit

—

—

—

Refuses contradicting writes

✅ at write time, not read time

—

—

n/a (read-only)

Audit trail

✅ git, per-write attribution, per-file diffs

varies

git, if you commit

—

Per-agent access control

✅ read / write token scopes

varies

—

—

Human UI

✅ dashboard, search, diffs, graph

varies

—

—

Runs on

your box, one container

mostly hosted SaaS

your box

your box

The row that matters is the third one. Similarity search cannot tell a contradiction from a duplicate — a retired price and a live one are textually identical, so the retired one often outranks the live one by being longer and more detailed. That can't be fixed at read time, which is why Engram writes the retirement down when it happens.

Categories, not feature-by-feature audits of specific products, and accurate to the best of my knowledge as of July 2026. If something here misrepresents a tool you maintain, open a PR — I'll fix it.

Features

  • MCP server — 15 brain_* tools over one bearer-authenticated HTTP endpoint (POST /api/mcp, streamable HTTP JSON-RPC). Connect any MCP client to a single URL. Per-agent token scopes: a read-only token never even sees the write tools.

  • Human dashboard — a search-first home, file tree, note viewer with Obsidian callouts, wikilinks, and backlinks, Preview / Edit / Split editor with autosave, ⌘K search + in-page keyboard navigation, "jump back in" recents, and a force-directed knowledge graph.

  • Authority-aware search — ranking knows relevance, not truth, so a superseded note repeats your query words as often as the live one. Every hit carries an authority (authoritative → current → provisional → superseded → archived) derived from the note's folder and frontmatter — so your agents quote the locked doc, not the dead one. Markdown RAG that won't hand back yesterday's answer.

  • Temporal validity + explainable rejection — mark a fact superseded_by another note or give it a valid_until date, and search withholds it by default (even if it's locked) — then hands the agent an excluded list of what it skipped, each with a reason ("expired 2026-06-01"). One atomic brain_supersede retires the old fact and links the new one in a single commit, so add-and-retire can't drift apart. This is the difference between an agent that remembers and one that knows what's still true.

  • Write-time contradiction guards — authority ranking fixes reading; these stop the vault accepting the contradiction in the first place. Engram refuses to create a second live note on a subject a live note already covers (the acme-pricing-2026.md-beside-acme-pricing.md bug) and points the agent at brain_supersede instead; refuses to overwrite a note the caller hasn't read; and warns when a status: isn't a word the ranking model knows, so a typo can't silently strip a note's authority.

  • Audit trail + access control — every write is attributed in git to the token or human that made it, with expandable per-file diffs in the activity feed. Give an agent a read-only token and it never even sees the write tools; a write token can create, edit, move, and archive.

  • The Curator (optional) — Engram's built-in agent harness over your vault. Chat with your notes (grounded answers, wikilink citations). Or hand brain_capture a rough dump — a meeting note, a voice transcript — and an agentic loop searches what already exists, then files, merges, or archives and returns a manifest of what it touched. It reads before it overwrites and never deletes. Opus / Sonnet / Haiku, your key.

  • Markdown-native — plain .md + YAML frontmatter + [[wikilinks]]. Drop in an existing Obsidian vault and it just works.

  • Git-backed — optional auto commit + push of every change. Full history, no lock-in, your data lives in your repo.

  • No database — files are the source of truth; an in-memory MiniSearch index + a ported wikilink graph power search and backlinks. Nothing to provision.

  • Multi-workspace — connect multiple vault repos (URL + token or GitHub OAuth), rename, switch the active one, or remove them — all from the UI.

  • Self-hosted — one Docker container. Railway / Render / Fly / any host with a volume. Not serverless (it needs a persistent volume, a file watcher, and a long-running index).

  • Team auth — Google SSO + email allowlist for the dashboard; per-agent bearer tokens — or OAuth for Claude.ai custom connectors — for MCP, created/revoked in the UI. Secrets encrypted at rest.

  • Runtime config — toggle git-sync and the Curator right from the home; manage commit author, keys, and OAuth in Settings — no redeploy.

Works with

Any client that speaks the Model Context Protocol — one endpoint, bearer-token auth. Most-used first:

  • Claude Code — Anthropic's agentic coding CLI

  • Codex — OpenAI's coding agent (CLI + IDE)

  • Hermes — always-on autonomous agent runtime

  • openclaw — open-source coding agent

  • Cursor — AI code editor

  • Cline — VS Code agent

  • Windsurf — agentic IDE

  • Claude Desktop — Anthropic's desktop app

  • …and any other MCP client — Continue, Goose, Zed, Amp, and the rest

If it speaks MCP, it can read and write Engram as shared memory.

Quick start

Want to poke at it first? There's a live demo — open, no signup, resets a few times a day. Break it all you like.

bun install
bun dev            # http://localhost:3000 — runs against ./sample-vault

Point it at your own vault:

VAULT_DIR=/path/to/your/obsidian-or-markdown/vault bun dev

Two ways to run it

  • Hosted mode (team): the dashboard + HTTP MCP server above — self-host it once, many agents and teammates connect over POST /api/mcp. This is the main mode.

  • Local mode (stdio): a plain stdio MCP server over a folder, no HTTP/auth/git — for a single machine, Claude Desktop / Cursor, or a registry's Docker introspection:

    bun run mcp:stdio /path/to/your/vault      # defaults to ./sample-vault

    Same brain_* tools. Built from Dockerfile.mcp.

Each mode ships as its own image, and they are not interchangeable:

Image

Mode

Use it for

ghcr.io/rwnalds/engram-app

HTTP — dashboard + /api/mcp

Railway, Render, Fly, any host. This is the one you deploy.

ghcr.io/rwnalds/engram

stdio — JSON-RPC on stdin/stdout

Claude Desktop, Cursor, MCP registries. Never opens a port.

Deploying the stdio image as a web service is the one mistake worth calling out: it can only 502, because there is nothing listening. It now refuses to start on a PaaS and tells you this instead.

MCP tools

Agents only ever see the active vault — no repo, workspace, or GitHub tools are exposed. A read-scope token sees only the read tools. brain_capture appears only when the Curator is full.

Tools

Read

brain_search · brain_read · brain_list · brain_recent · brain_tree · brain_backlinks · brain_graph · brain_schema

Write (needs a write-scope token)

brain_write · brain_edit · brain_append · brain_move · brain_supersede · brain_create_folder · brain_delete

Connect an agent (the dashboard → Connect page shows the exact command + token):

claude mcp add --transport http engram https://<host>/api/mcp \
  --header "Authorization: Bearer <token>"

Deploy

Runs anywhere you can run a Docker container with a persistent volume — Railway, Render, Fly, or your own box. Serverless (Vercel) won't work: Engram holds a volume, a file watcher, and an in-memory index that a serverless function can't keep alive.

  1. Deploy this repo (root Dockerfile), mount a volume at /data, set ENGRAM_DATA_DIR=/data.

  2. Connect your vault repo(s) in the dashboard (Workspaces) — by URL + token, or GitHub OAuth.

  3. Sign in with Google, create MCP tokens on the Connect page, point your agents at the URL.

Most runtime config (git-sync, AI capture, GitHub OAuth, app name) is editable in the Settings page — only auth/infra bootstrap vars live on the host. Full setup: DEPLOY.md.

  • Railway: New Project → Deploy from GitHub repo → add a Volume at /data.

  • Render: one-click via the bundled render.yaml (Docker + a /data disk).

Deploying from a prebuilt image instead of the repo? Use ghcr.io/rwnalds/engram-app:latest — not engram:latest, which is the stdio server and cannot answer HTTP. Set the healthcheck to /api/health.

FAQ

How do I give Claude Code long-term memory? Deploy Engram, connect a markdown vault, and claude mcp add the endpoint. The brain_* tools let Claude Code search, read, and write persistent notes across sessions.

Can multiple AI agents share one knowledge base? Yes. Every agent points at the same MCP URL and reads/writes the same active vault — that's the point. Give each agent its own bearer token, read or write — a read-only token can't mutate your notes.

How do I stop an agent from quoting outdated facts? Retire the fact and search stops surfacing it. When a value changes, call brain_supersede(old, new) — one atomic commit marks the old note superseded_by the new one, and it's withheld from search by default (even if it's locked). Or set valid_until: 2026-12-31 on a note and it self-expires. Retired matches don't vanish silently: brain_search returns them in an excluded list with a reason ("expired 2026-06-01"), so the agent can say what it ignored and why instead of quoting it.

What stops an agent just adding a second, contradicting note? Engram refuses the write. Told "the price is now X", an agent that can't overwrite a note it never read will happily add acme-pricing-2026.md next to acme-pricing.md — nothing is corrupted, and you now have two live notes disagreeing about one number. That write is rejected with a pointer to brain_supersede, which retires the old note and adds the new one in a single commit. Pass allow_conflict: true when both notes genuinely belong.

How do I know what an agent changed? Every write is committed to git attributed to the token or human behind it, and the dashboard's activity feed shows per-file diffs — a built-in audit trail for autonomous agents.

Does it work with my Obsidian vault? Yes. It reads plain markdown with frontmatter and [[wikilinks]], and renders Obsidian-style callouts and backlinks. No import step.

Do I need a vector database? No. Engram uses full-text search (MiniSearch) plus a wikilink graph over human-readable markdown — no embeddings service, no vector store to run.

Can I chat with my notes? Yes — enable the optional Curator, a chat agent that searches and reads your vault to answer with wikilink citations (Opus / Sonnet / Haiku). It's read-only in chat, so it helps you think without changing anything, and it runs on your own Anthropic key.

Can I see what my agents changed? Yes — the Activity view reads your vault's git history and shows every change (agents and teammates alike), expandable to per-file diffs. Since it's just git, you get the full audit trail for free.

Is my data locked in? No. It's just .md files in a git repo you own. Turn Engram off and you still have every note and its full history.

Where does it run / is it self-hosted? You host it. One Docker container on Railway / Render / Fly / any VM with a volume. Your keys, your data.

Contributing

Issues and PRs welcome — especially where the validity model breaks against a vault shaped differently from mine.

bun install && bun dev
bun test          # the ranking/authority suite, incl. the stale-truth fixtures

If Engram is useful to you, starring the repo genuinely helps other people find it.

Stack

Next.js 16 (App Router) · React 19 · TypeScript · Tailwind v4 · shadcn/ui · bun · MiniSearch · d3-force · MCP SDK. MIT licensed.

Keywords: MCP server · Model Context Protocol · second brain for AI agents · agent memory · long-term memory for Claude Code · shared memory for AI agents · self-hosted knowledge base · Obsidian-compatible · markdown · knowledge graph · wikilinks · PKM · Zettelkasten · git-backed notes · Hermes agent memory · Cursor memory · RAG without a vector database · chat with your markdown notes · git-backed agent activity feed · audit trail for AI agents · authority-aware search · read-only vs write MCP tokens · agent access control · self-organizing notes · agentic note capture · AI that files your notes · temporal validity · stale memory · agents quoting outdated facts · supersede · note expiry · shared memory for a team of agents · Basic Memory alternative · mem0 alternative.

Available Tools

16 tools
brain_appendA

Append text to a note (creates it if missing).

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesvault-relative path
textYestext to append

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility for behavioral disclosure. It discloses the creation-on-missing behavior, which is key. However, it does not mention safety (e.g., non-destructive nature), return values, or any side effects. The disclosure is minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that immediately states the verb and resource, with parenthetical clarification. No wasted words; highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no output schema), the description covers the core behavior. However, it omits return value, formatting expectations, and any constraints (e.g., file size). Adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters are documented in the schema. The description adds no additional semantic meaning beyond what the schema provides (e.g., path format or text handling). Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'append' and the resource 'note', and adds the important qualifier that it creates the note if missing. This distinguishes it from sibling tools like 'brain_write' (which likely overwrites) and 'brain_edit' (which may modify existing content).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used for appending text, but provides no guidance on when to use alternatives (e.g., brain_write, brain_edit) or when not to use this tool. No explicit context for choosing this over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_captureA

Hand over a ROUGH note / brain-dump and let the vault file it. An agent loop reads SCHEMA.md, searches for what already exists, then deliberately creates a new note, appends to a matching one, or archives what this supersedes — and returns a manifest of every path it touched. It reads a note before overwriting it, and never deletes. Use when you have unstructured input and don't want to choose the path yourself; use brain_write when you do.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesthe rough note / brain dump to file

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description takes full responsibility for behavior. It discloses the internal workflow (reads SCHEMA.md, searches, decides), safety guarantees (reads before overwriting, never deletes), and returns a manifest of touched paths. This is thorough and clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the first states the core action, the second details the process and safety, and the third gives usage guidance. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having only one parameter, no annotations, and no output schema, the description provides sufficient context: how it decides, what it returns, its safety behavior, and when to use it. The description compensates for all missing structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of the parameter with a description ('the rough note / brain dump to file'). The description adds no new semantic details about the parameter beyond restating the same idea, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear purpose: hand over a rough note and the tool files it, deciding between creating new, appending, or archiving. It distinguishes from siblings by explicitly comparing with brain_write, making the tool's unique role clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: use when you have unstructured input and don't want to choose the path yourself, use brain_write when you do. This directly tells the agent when to choose this tool over an alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_create_folderA

Create a new folder in the vault (with a .gitkeep).

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesfolder path

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden. It discloses that a '.gitkeep' file is added, which is a useful behavioral detail. However, it does not mention what happens if the path already exists, permission requirements, or error handling, leaving gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently conveys the necessary information without wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one param, no output schema), the description is fairly complete. It includes the .gitkeep detail which is contextually relevant. However, it could mention whether creation is recursive or if the operation is idempotent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage with a description for the single parameter 'path'. The tool description does not add extra semantics beyond the schema, so baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Create' and the resource 'a new folder in the vault', distinguishing it from siblings like brain_delete or brain_write. It also includes a specific detail about '.gitkeep' which adds precision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives such as brain_write or brain_capture. The description implies it's for folder creation but lacks context about prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_deleteA

Delete a note (recoverable via git history). Prefer brain_move into an archive folder — deleting destroys the reasoning trail, archiving only removes it from search. Delete when the note is wrong or duplicated, archive when it is merely no longer true.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesvault-relative path

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that deletion is recoverable via git history, that it destroys the reasoning trail, and contrasts with archiving's effect on search. It does not mention permissions or side effects on linked notes, but for a simple delete operation this is substantial transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the primary action, then concise guidance. Every clause earns its place, with no fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter, no output schema), and the description covers the purpose, recoverability, and decision framework for use verses archiving. It is complete enough for an agent to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the 'path' parameter already described as 'vault-relative path'. The description does not add any additional parameter semantics, but there is no need to compensate given the schema's clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Delete a note', a specific verb and resource, and immediately distinguishes itself from brain_move by stating the preferred alternative. It clearly identifies the tool's core function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Prefer brain_move into an archive folder' and gives precise criteria: 'Delete when the note is wrong or duplicated, archive when it is merely no longer true.' This directly addresses when to use this tool vs alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_editA

Overwrite a note. Pass content (full raw markdown incl. frontmatter) — read first with brain_read, then write the whole file back. Also accepts body (+ optional frontmatter) like brain_write.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNomarkdown body (alternative to content; pair with `frontmatter`)
pathYesvault-relative path
contentNofull raw markdown incl. frontmatter
overwriteNoconfirm you mean to replace an existing note with much shorter content (default false)
frontmatterNoYAML frontmatter object (with `body`)
allow_conflictNoconfirm a near-duplicate of a live note is deliberate — prefer brain_supersede (default false)

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description effectively discloses the destructive 'overwrite' behavior and the need for confirmation via the overwrite and allow_conflict fields. It reveals the read-then-write pattern, adding context that the schema alone does not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences that front-load the purpose ('Overwrite a note') and efficiently cover the two usage modes and workflow. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and no output schema, the description covers the essential behaviors: overwrite, read-first workflow, and conflict handling. It omits details on return values, but given no output schema, this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds meaning by explaining that `content` is the full raw markdown from brain_read and that `body`+`frontmatter` follow the brain_write pattern. This clarifies the dual parameter modes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Overwrite a note' as the core purpose, with specific verb and resource. It distinguishes from siblings by noting it combines reading and writing, and references alternatives like brain_supersede for near-duplicates.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit workflow guidance: read first with brain_read, then write the whole file back. It also contrasts with brain_supersede for conflict scenarios. However, it does not explicitly state when to use this tool over brain_write or brain_append beyond the overwrite context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_graphC

The knowledge graph (nodes + edges from wikilinks and related:). Optional folder filter.

ParametersJSON Schema
NameRequiredDescriptionDefault
folderNooptional folder filter

TDQS

C2.9/5.0
Behavior2/5

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 discloses it is a knowledge graph (likely read-only) but does not mention performance, limitations, output format, or what 'related:' means. Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise at one sentence, front-loaded with the key concept. However, it may be too brief for such a complex tool, but still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema and a single optional parameter. The description fails to explain what nodes and edges look like, how the folder filter works, or what 'related:' entails. Incomplete for a graph-building tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one optional folder filter. The description repeats 'optional folder filter' without adding any meaning beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns a knowledge graph with nodes and edges from wikilinks and related, which is a specific verb+resource. However, it does not explicitly distinguish from sibling tools like brain_tree or brain_list, which might also deal with connections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (e.g., brain_tree, brain_search). Agent must infer from the concept of 'knowledge graph' without explicit context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_listA

List every note with metadata (path, title, folder, type, tags, status, authority). Use to discover what exists. authority tells you which notes are source-of-truth and which are history.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

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 discloses that the tool lists all notes with metadata and explains the authority field, but does not mention potential limitations like pagination, rate limits, or performance characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise: two sentences that front-load the essential information. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, no output schema, and a simple purpose (list all notes), the description is fairly complete. It explains the key metadata and usage. Minor gaps are acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters (input schema is empty). Baseline for 0 parameters is 4, and the description does not need to add parameter information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists every note with specific metadata fields (path, title, folder, type, tags, status, authority), and highlights the authority field's significance. It distinguishes from siblings like brain_search and brain_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says 'Use to discover what exists,' providing clear context for use. It does not explicitly mention when not to use it or compare to all siblings, but the context is sufficient for basic guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_moveA

Move or rename a note. This is how you retire something: when a note stops being true, move it to an archive folder (see brain_schema → conventions.ranking.archiveFolders) rather than deleting it. Archived notes are demoted in search and excluded by default, so they stop misleading agents while the reasoning trail survives. Leave a pointer in the replacement note saying what superseded what.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesnew path
fromYescurrent path

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It explains that archived notes are demoted in search and excluded by default, adding useful behavioral context beyond the basic move operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences effectively cover purpose, usage scenario, and a procedural detail (leaving a pointer) with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description adequately covers usage context and behavioral effects. It references conventions and distinguishes from alternatives, though it omits error handling or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter descriptions. The description adds context about archive folders but does not significantly enhance parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Move or rename a note' with a specific verb and resource, distinguishing it from sibling tools like brain_delete and brain_edit by emphasizing the archival use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes when to use this tool (for retiring notes that are no longer true) and provides guidance on using archive folders and leaving pointers, effectively differentiating from deletion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_readA

Read a note: full markdown (frontmatter + body), its authority, and its backlinks. Path is vault-relative, e.g. 'clients/mks/mks.md'.

Pass section to read just one heading's content instead of the whole file — cheaper on long documents. If the heading isn't found you get the list of available headings back.

Always check the returned authority before acting on the content: archived and superseded notes are history, not instructions.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesvault-relative path
sectionNooptional heading to extract, e.g. 'Pricing' — matches case-insensitively by prefix

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully handles behavioral transparency. It discloses the authority field can indicate 'archived' or 'superseded' notes, advising caution. It also explains the behavior when a section heading is not found (returns list of available headings), which is critical for agent decision-making.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three well-crafted sentences with no redundancy. The most critical information (what the tool does, path format, section usage, authority warning) is front-loaded and immediately actionable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description fully covers return values (markdown, authority, backlinks) and edge cases (missing section). Given the low parameter count (2) and 100% schema coverage, no additional information is needed for an agent to use this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds significant value: it clarifies path format with an example, explains that section matching is case-insensitive by prefix, and notes cost implications. This goes well beyond the schema's basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read a note' and specifies the exact content returned (full markdown, authority, backlinks). It distinguishes itself from siblings like brain_write and brain_edit by focusing on reading, and the section parameter usage is explicitly described, making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to check the returned 'authority' before acting, and explains when to use the section parameter (for cheaper reads on long documents). While it doesn't explicitly contrast with all siblings (e.g., brain_search, brain_list), it provides strong contextual guidance for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_recentA

Notes changed most recently, newest first. Use to catch up on what humans or other agents have done since you last looked.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNomax results (default 20)
sinceNooptional ISO date/time — only notes modified at or after this

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavior. It mentions the ordering ('newest first') and the 'since' parameter, but it does not state whether the tool is read-only, what the output format is, or any other behavioral traits. For a tool with no annotations, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two sentences: the first states what the tool does, and the second gives usage guidance. It is concise, front-loaded, and contains no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema and the tool is simple (2 optional parameters), the description is fairly complete. It explains the ordering, the purpose, and the usage. However, it lacks details about the output format, which might be important for an agent to process the results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already well-documented in the input schema. The description adds no additional semantic meaning beyond the schema's descriptions. The baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool retrieves notes changed most recently, sorted newest first. It uses a specific verb-resource ('notes changed most recently') and distinguishes itself from siblings like 'brain_search' and 'brain_list' by focusing on recent changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use to catch up on what humans or other agents have done since you last looked,' providing clear guidance on when to use the tool. It does not explicitly state when not to use it, but the context is strong enough for an agent to infer appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_schemaA

READ THIS FIRST, before searching or writing. Returns the vault's SCHEMA.md (folder taxonomy, frontmatter conventions, wikilink model, write protocol) AND a live description of this specific vault: its folders, the status: values actually in use, how search ranks notes by authority, and any integrity warnings. Vaults differ — never assume conventions, read them here.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: it returns schema, folders, status values, search ranking, and integrity warnings. It notes that vaults vary, adding context. It could mention that it is read-only and has no side effects, but the description is already informative.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences, front-loading the critical directive 'READ THIS FIRST.' Every sentence adds necessary context without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters and no output schema, the description is remarkably complete. It explains the tool's purpose, content, and the importance of reading it before other operations, covering all essential aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so no parameter details are needed. The description adds value by explaining what the tool returns, achieving baseline 4 for no parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns the vault's SCHEMA.md and a live description, acting as a meta-tool to be read first. It uses a specific verb ('READ') and resource ('schema'), distinguishing it from sibling tools that perform direct vault operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs 'READ THIS FIRST, before searching or writing,' providing clear timing of use. It explains what the tool returns and warns that vaults differ, implying the need to check conventions before other actions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_supersedeA

Retire a fact and replace it, atomically. When a fact changes (a price, a term, a decision), DON'T just add a new note — the old value keeps matching searches and gets quoted. brain_supersede(from, to) marks the old note superseded in place (body preserved) and links it to the new one, in a single commit, so add-and-retire can't drift apart. After this, search withholds the old note with the reason "superseded by ".

from = the note being retired; to = the note that replaces it. If to doesn't exist yet, pass body (its markdown) and it's created; otherwise write to first, then supersede. reason is recorded on the old note. Prefer this over brain_move for a value that changed (move is for relocation).

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesthe note that replaces it (vault-relative path)
bodyNooptional — markdown for `to` if it doesn't exist yet
fromYesthe note being retired (vault-relative path)
reasonNooptional — why it was retired, e.g. 'repriced Q3'

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description takes full responsibility for behavioral disclosure. It explains atomicity ('single commit'), preserves the old note ('body preserved'), and describes the post-operation effect ('search withholds the old note with the reason "superseded by <to>"'). It also notes the relationship between `from` and `to` and the conditional creation of `to`.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long (about 120 words) but every sentence adds value. It front-loads the core action and then explains use cases and parameters. It is well-structured with distinct sections (purpose, parameters, alternatives). It is not as concise as the two-sentence TDQS example, but the added detail is justified for a multi-step atomic operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, but the description covers the tool's side effects and behavior thoroughly. It explains what happens to the old note, how search behaves afterward, and how to handle the `to` note creation. Combined with the clear parameter semantics, it is complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers all four parameters with 100% coverage, so baseline is 3. The description adds meaning beyond the schema by explaining how `from` and `to` relate, the purpose of `body` as an alternative way to create `to`, and that `reason` is recorded on the old note. This extra context justifies a 4 but not a 5 since the schema already gives basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Retire a fact and replace it, atomically.' It uses a specific verb (supersede/retire) and identifies the resource (a fact/note). It explicitly distinguishes itself from a sibling tool: 'Prefer this over brain_move for a value that changed (move is for relocation).'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance: 'When a fact changes (a price, a term, a decision), DON'T just add a new note...' It also names an alternative (brain_move) and explains why to use this instead. It gives a clear workflow for both cases (to exists or not).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_treeA

Return the folder/file tree of the vault.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. It only says 'Return,' which implies read-only, but it does not explicitly confirm the absence of side effects, permissions, or other caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One concise, clear sentence with no filler. It is perfectly sized for the simplicity of the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool, this is nearly complete. It could add details about the tree structure (e.g., root, depth, whether empty folders are included), but the description is adequate for a simple vault tree.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the description does not need to add parameter semantics. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool returns the vault's folder/file tree. The term 'tree' distinguishes it from sibling tools like brain_list or brain_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this compared with brain_list, brain_schema, or brain_graph. The description only states what it does, not how to choose it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

brain_writeA

Create or overwrite a note. PREFER body (markdown, no frontmatter) + frontmatter (an object): the YAML is serialised for you and always parses. Hand-writing frontmatter into content risks invalid YAML — a note whose frontmatter fails to parse loses its status, tags and title on every read, so a note claiming status: locked would rank as an ordinary one. Such a write is REJECTED. Follow SCHEMA.md: kebab-case path, dated names for daily/decisions, frontmatter with title/type/tags/status. Path vault-relative (e.g. decisions/foo-2026-07-09.md).

WHEN A FACT CHANGED, DON'T CREATE A DATED SIBLING. Writing acme-pricing-2026.md next to a live acme-pricing.md leaves two live notes disagreeing about one number, and the older one usually matches the query better — this is exactly how a retired price gets quoted. Such a write is REJECTED; use brain_supersede instead, which retires the old note and adds the new one in a single commit. allow_conflict: true overrides it when both notes genuinely belong.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNomarkdown body (pair with `frontmatter`)
pathYesvault-relative path, e.g. decisions/foo-2026-07-09.md
contentNofull raw markdown incl. frontmatter — alternative to body+frontmatter
overwriteNoconfirm you mean to replace an existing note with much shorter content (default false)
frontmatterNoYAML frontmatter object: title, type, tags, status, related, ...
allow_conflictNoconfirm a near-duplicate of a live note is deliberate — prefer brain_supersede (default false)

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description fully bears the burden. It discloses that writes with invalid frontmatter are rejected, and that writing a dated sibling for fact changes is rejected. It explains the reasoning behind rejections. Missing auth or rate limit info, but still strong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and then provides detailed usage guidance. It is structured clearly with paragraphs for different aspects. Could be slightly shorter, but every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description fully covers input semantics, constraints, rejection conditions, and sibling tool differentiation. No gaps remain for an AI agent to invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds significant meaning beyond schema: explains tradeoffs between body+frontmatter vs content, warns about YAML parsing risks, and clarifies when overwrite and allow_conflict flags are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create or overwrite a note' with specific verb and resource. It distinguishes from sibling tools like brain_supersede and brain_append by explaining when each is appropriate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to prefer body+frontmatter over raw content, when to use brain_supersede instead of writing a dated sibling, and how to use allow_conflict. It also references SCHEMA.md for naming conventions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.5
    • Addedbrain_capture
    • Addedbrain_delete
    • Addedbrain_supersede
    • Addedbrain_tree
  2. 6 tool updatesv0.1.2
    • Removedbrain_capture
    • Removedbrain_delete
    • Changedbrain_edit1 field changed
      • addedInput schema / properties / allow_conflict
        Added value: +{
+  "description": "confirm a near-duplicate of a live note is deliberate — prefer brain_supersede (default false)",
+  "type": "boolean"
+}
    • Removedbrain_supersede
    • Removedbrain_tree
    • Changedbrain_write1 field changed
      • addedInput schema / properties / allow_conflict
        Added value: +{
+  "description": "confirm a near-duplicate of a live note is deliberate — prefer brain_supersede (default false)",
+  "type": "boolean"
+}
  3. 16 tool updatesv0.1.0
    • First observedbrain_append
    • First observedbrain_backlinks
    • First observedbrain_capture
    • First observedbrain_create_folder
    • First observedbrain_delete
    • First observedbrain_edit
    • First observedbrain_graph
    • First observedbrain_list
    • First observedbrain_move
    • First observedbrain_read
    • First observedbrain_recent
    • First observedbrain_schema
    • First observedbrain_search
    • First observedbrain_supersede
    • First observedbrain_tree
    • First observedbrain_write
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation4/5

Most tools have clearly distinct purposes, but brain_write and brain_edit overlap significantly: both can create or overwrite a note, with the only differentiator being that edit also accepts raw markdown. Other potentially similar tools like brain_supersede vs brain_move and brain_backlinks vs brain_graph are well differentiated by their descriptions.

Naming Consistency4/5

All tool names share the consistent 'brain_' prefix and snake_case style, making them easy to group. However, the second element mixes verb forms (list, append, move, search, read, write, edit, supersede, capture, delete) with noun forms (schema, recent, tree, backlinks, graph), so the pattern is not purely verb_noun.

Tool Count4/5

At 16 tools, the set is slightly above the typical 3-15 range for a well-scoped server, but the rich feature set (CRUD, search, graph, lifecycle operations) justifies the count. Each tool earns its place, including the specialized supersede and capture tools.

Completeness5/5

The tool surface covers the full note lifecycle: create (brain_write, brain_capture), read (brain_read, brain_search, brain_list), update (brain_edit, brain_append, brain_supersede), delete (brain_delete), and organization (brain_move, brain_tree, brain_create_folder). Discovery is also complete with recent, backlinks, graph, and schema. No significant gaps are evident for a personal vault manager.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rwnalds/engram'

If you have feedback or need assistance with the MCP directory API, please join our Discord server