basic-memory

Grep

grep

Read-only

Search note content in a project to find matching notes by keywords, or rank results by meaning and show surrounding line context.

Instructions

Search note content in one project and return matching notes. Not a regex: pattern is matched as full-text keywords by default, and a pattern found in no note returns no results. semantic=True ranks by meaning instead (hybrid semantic plus full-text, when semantic search is enabled). Add context_lines to get case-insensitive matching lines with surrounding context and line numbers. Requires 'project' when several projects are addressable.

Input Schema

Name	Required	Description
`page`	No	Page number (1-indexed).
`pattern`	Yes	Text to search for.
`project`	No	Project name. Required when more than one project is addressable.
`semantic`	No	Rank by meaning with hybrid semantic plus full-text retrieval instead of the default keyword matching. Cannot be combined with context_lines.
`page_size`	No	Results per page (maximum 100 in line-scanning mode).
`project_id`	No	Project external_id (UUID); takes precedence over `project`.
`max_matches`	No	Maximum matching lines to show per candidate in line mode (1-100, default 10). Omitted matches carry next_match_line for a targeted read_note or cat read. Edits between calls can shift line positions.
`context_lines`	No	Return compact literal match windows with 0-10 surrounding lines (not with semantic=True). Case-insensitive substrings, coordinates including frontmatter, overlapping windows merged. Scans current content of this indexed candidate page; pagination/totals count candidates, not exact matches.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.24.1Oct 23, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and destructiveHint=false, so the safety bar is low. The description adds genuine behavioral context beyond annotations: empty-match returns no results, case-insensitive matching, and the reason to add context_lines. It doesn't discuss pagination behavior, but the added matching semantics are valuable.

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?

Front-loads the core purpose and then layers mode details efficiently. Sentences each carry information, though the density around semantic/context_lines is slightly tight.

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?

Output schema exists, so return values needn't be explained, and annotations cover the safety profile. The description covers matching modes and the project prerequisite, leaving only minor gaps like pagination behavior for an 8-param tool.

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%, so baseline is 3. The description adds real meaning beyond the schema for `pattern` (full-text keywords, not regex) and reinforces the semantic vs context_lines tradeoff and the project requirement, which the schema alone states more tersely.

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?

States a specific verb and resource ('Search note content in one project and return matching notes') and clarifies the matching mechanism ('Not a regex... full-text keywords by default'). It distinguishes itself from regex search by mechanism, though it doesn't name the competing sibling tools (search_notes, search) explicitly.

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?

Gives clear conditions for the semantic mode ('semantic=True ranks by meaning instead') and for context_lines ('Add context_lines to get...'), plus the 'Requires project when several projects are addressable' prerequisite. It lacks explicit 'use X instead of grep' routing to siblings, so not a full 5.

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