feat(mcp): add bounded line reads and literal grep context (#1502)

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/cli/commands/posix.py

@@ -332,6 +332,31 @@ def _plain_find_fields(result: dict[str, Any]) -> None:
         print(f"{row.get('file_path', '')}\t{fields_json}")
 
 
+def _display_grep_lines(result: dict[str, Any], *, plain: bool) -> None:
+    """Print bounded windows without reintroducing the search response's full body."""
+    output: list[str] = [f"Search candidates: page {result['current_page']}"]
+    for row in result["results"]:
+        path = row["file_path"]
+        output.append(f"{path}: {row['match_count']} matching line(s)")
+        for window in row["windows"]:
+            for number, line in zip(
+                range(window["start_line"], window["end_line"] + 1),
+                window["content"].split("\n"),
+                strict=True,
+            ):
+                marker = ":" if number in window["match_lines"] else "-"
+                output.append(f"{path}{marker}{number}{marker}{line}")
+        if row["next_match_line"] is not None:
+            output.append(f"… more matches; read {path} at line {row['next_match_line']}")
+    if result["has_more"]:
+        output.append(f"… more candidates; use --page {result['current_page'] + 1}")
+    text = "\n".join(output)
+    if plain:
+        print(text)
+    else:
+        console.print(Text(text))
+
+
 # --- tail rendering ---
 # tail's row shape ({type, title, permalink, file_path, created_at}) differs
 # from recent-activity's payload, so it gets its own small renderers rather
@@ -622,6 +647,22 @@ def grep(
             "--literal", "-F", help="Literal full-text matching instead of semantic search"
         ),
     ] = False,
+    context_lines: Annotated[
+        Optional[int],
+        typer.Option(
+            "-C",
+            "--context-lines",
+            min=0,
+            max=10,
+            help="Compact literal line matches with surrounding context (requires -F)",
+        ),
+    ] = None,
+    max_matches: Annotated[
+        int,
+        typer.Option(
+            "--max-matches", min=1, max=100, help="Matching lines per candidate in context mode"
+        ),
+    ] = 10,
     page: Annotated[int, typer.Option("--page", help="Page number (1-indexed)")] = 1,
     page_size: Annotated[int, typer.Option("--page-size", help="Results per page")] = 10,
     json_output: JsonOption = False,
@@ -635,6 +676,7 @@ def grep(
 
     Examples:
 
+    bm grep -F "retry" -C 3 --plain
     bm grep "auth token rotation"
     bm grep -F "BASIC_MEMORY_FORCE_LOCAL"
     bm grep "deploy checklist" --page-size 20 --json
@@ -652,6 +694,8 @@ def grep(
                 mcp_grep(
                     pattern,
                     literal=literal,
+                    context_lines=context_lines,
+                    max_matches=max_matches,
                     page=page,
                     page_size=page_size,
                     project=project,
@@ -662,6 +706,8 @@ def grep(
         mode = _resolve_output_mode(json_output, plain)
         if mode == "json":
             _print_json(result)
+        elif context_lines is not None:
+            _display_grep_lines(result, plain=mode == "plain")
         elif mode == "plain":
             _plain_search_results(result, query=pattern)
         else:

src/basic_memory/cli/commands/tool.py

@@ -699,6 +699,14 @@ def write_note(
 @tool_app.command()
 def read_note(
     identifier: str,
+    start_line: Annotated[
+        Optional[int],
+        typer.Option(min=1, help="First document line, including frontmatter (1-based)"),
+    ] = None,
+    end_line: Annotated[
+        Optional[int],
+        typer.Option(min=1, help="Last document line, inclusive; omitted reads to EOF"),
+    ] = None,
     include_frontmatter: bool = typer.Option(
         False,
         "--frontmatter",
@@ -740,6 +748,7 @@ def read_note(
     bm tool read-note my-note --frontmatter
     bm tool read-note my-note --plain
     bm tool read-note my-note --json
+    bm tool read-note my-note --start-line 120 --end-line 180 --plain
     """
     # Deferred: loading the MCP tool stack at module import slows CLI startup (#886).
     from basic_memory.mcp.tools import read_note as mcp_read_note
@@ -756,6 +765,8 @@ def read_note(
                     project_id=project_id,
                     include_frontmatter=include_frontmatter,
                     output_format="json",
+                    start_line=start_line,
+                    end_line=end_line,
                 )
             )
 
@@ -776,6 +787,19 @@ def read_note(
         mode = _resolve_output_mode(json_output, plain)
         if mode == "json" or isinstance(result, str):
             _print_json(result)
+        elif "start_line" in result:
+            from basic_memory.markdown.line_scanning import format_line_read
+
+            text = format_line_read(
+                result["content"],
+                start_line=result["start_line"],
+                end_line=result["end_line"],
+                total_lines=result["total_lines"],
+            )
+            if mode == "plain":
+                print(text)
+            else:
+                console.print(Text(text))
         elif mode == "plain":
             _plain_read_note(result, include_frontmatter=include_frontmatter)
         else:

src/basic_memory/man/man1/grep(1).md

@@ -17,6 +17,7 @@ generated: hand
 
 ```
 bm grep PATTERN [-F | --literal] [--page N] [--page-size N]
+        [-C N | --context-lines N] [--max-matches N]
         [--json | --plain] [--project NAME | --project-id UUID]
         [--local | --cloud]
 ```
@@ -29,14 +30,31 @@ matching, like real grep's fixed-strings flag. Results carry title, score,
 permalink, and the matched snippet; on a TTY they render as a table, and
 `--json` (or piped output) emits the search response with pagination.
 
+With `-F -C N`, return compact literal match windows instead. The full-text index
+selects a page of candidate notes, then their current content is checked for
+case-insensitive literal substrings. Matching line numbers include frontmatter
+and can be passed directly to `read_note(start_line=..., end_line=...)` or
+`bm cat ... --lines N-M`. Overlapping context windows merge to avoid repeated text.
+The full body and search excerpt are omitted in this mode, including JSON output.
+
+This is not an exhaustive filesystem grep: index tokenization, stemming, or edits
+can produce a candidate with zero literal matches, or omit a substring-only match.
+Pagination and totals refer to search candidates, not exact matching notes or lines.
+Each candidate reports `match_count`, `total_lines`, `windows`, and `next_match_line`
+(the first omitted matching line, or null). Use the latter for a targeted note read.
+Line positions can change if the note is edited between calls.
+
 ## OPTIONS
 
 - **-F, --literal** — literal full-text matching instead of semantic search
+- **-C, --context-lines** — opt into line scanning with 0-10 lines around each match; requires -F
+- **--max-matches** — matching lines to show per candidate in line mode, 1-100 (default 10)
 - **--page, --page-size** — result pagination (defaults 1 and 10)
 
 ## EXAMPLES
 
 ```
+bm grep -F "retry" -C 3 --max-matches 5 --plain
 bm grep "auth token rotation"
 bm grep -F "BASIC_MEMORY_FORCE_LOCAL"
 bm grep "deploy checklist" --json | jq '.results[].permalink'

src/basic_memory/man/man3/read-note(3).md

@@ -21,14 +21,15 @@ MCP:
 
 ```
 read_note(identifier, project=None, project_id=None, page=1, page_size=10,
-          output_format="text", include_frontmatter=False)
+          output_format="text", include_frontmatter=False, start_line=None,
+          end_line=None)
 ```
 
 CLI:
 
 ```
 bm tool read-note IDENTIFIER [--project NAME | --project-id UUID]
-                  [--page N] [--page-size N] [--frontmatter]
+                  [--start-line N] [--end-line N] [--frontmatter]
                   [--local | --cloud]
 ```
 
@@ -53,10 +54,12 @@ Accepted identifier forms (all verified):
 - **identifier** (string, required) — The title or permalink of the note to read. Can be a full memory:// URL, a permalink, a title, or search text. From the CLI this is a positional argument, not a flag.
 - **project** (string | null, optional, default: None) — Project name to read from. Optional - server will resolve using the hierarchy above. If unknown, use list_memory_projects() to discover available projects.
 - **project_id** (string | null, optional, default: None) — Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects().
-- **page** (integer, optional, default: 1) — Page of fallback-search results to use when the identifier does not resolve to a note directly (default: 1). A direct or exact-title match always returns the full note content — page/page_size never chunk the note itself, and the title-match lookup pages through fixed-size pages of title results until an exact match is found or results are exhausted, regardless of page or page_size. Aliases: page_number.
+- **page** (integer, optional, default: 1) — Page of fallback-search results to use when the identifier does not resolve to a note directly (default: 1). A direct or exact-title match returns the note content — page/page_size never chunk the note itself, and the title-match lookup pages through fixed-size pages of title results until an exact match is found or results are exhausted, regardless of page or page_size. Aliases: page_number.
 - **page_size** (integer, optional, default: 10) — Number of fallback-search results per page (default: 10). When no match is found, this caps how many related-note suggestions are listed. Aliases: limit, per_page.
 - **output_format** (string, optional, default: "text") — "text" returns markdown content or guidance text. "json" returns a structured object with title/permalink/file_path/content/frontmatter.
-- **include_frontmatter** (boolean, optional, default: False) — When output_format="json", whether content should include the opening YAML frontmatter block; the parsed frontmatter object is returned either way. The CLI flag is --frontmatter (--include-frontmatter is a deprecated alias).
+- **include_frontmatter** (boolean, optional, default: False) — For unsliced JSON reads, include opening YAML in content; parsed frontmatter is returned either way. Explicit line ranges are never stripped. CLI: --frontmatter (--include-frontmatter is a deprecated alias).
+- **start_line** (integer | null, optional, default: None) — First document line to read (1-based, inclusive). Defaults to 1 when only end_line is given. Line scans count the full Markdown, including frontmatter, matching cat's default line coordinates.
+- **end_line** (integer | null, optional, default: None) — Last document line to read (inclusive); omitted means EOF. Out-of-file ranges return empty content; invalid/reversed ranges fail. With either bound, text output is numbered and JSON carries coordinates, has_more, and next_start_line/next_end_line. include_frontmatter does not strip an explicitly addressed range. Edits between calls may shift lines.
 
 ## MCP USAGE
 
@@ -76,6 +79,27 @@ bm tool read-note "playground/demo-cli-stdin" --project manual
 #          "frontmatter": {...}}
 ```
 
+## LINE SCANNING
+
+Pass `start_line` and/or `end_line` to read a 1-based inclusive range. An omitted
+start means line 1; an omitted end means EOF. Coordinates count the full Markdown,
+including frontmatter, regardless of `include_frontmatter`. They match literal
+grep context and `cat` with its default `include_frontmatter=True`. Cat's explicit
+`include_frontmatter=False` line reads remain body-relative.
+
+Text scans show numbered lines and the next bounded range. JSON scans return
+`content`, `start_line`, `end_line`, `total_lines`, `has_more`, `next_start_line`,
+and `next_end_line`; both next bounds are null at EOF. End bounds clamp to EOF;
+a start beyond EOF returns empty content with `end_line < start_line`. Empty
+notes have zero total lines. Bounds below 1 and reversed ranges are errors.
+Line endings normalize to LF, with CR/LF/CRLF counted consistently. A trailing
+newline does not create an extra line. Lines may move after an intervening edit.
+
+```
+read_note("runbook", start_line=120, end_line=180)
+bm tool read-note runbook --start-line 120 --end-line 180 --plain
+```
+
 ## EXAMPLES
 
 A miss returns suggestions, not an error (run against the dev project):
@@ -89,8 +113,8 @@ read_note("xyzzy definitely missing note", project="dev")
 
 ## GOTCHAS
 
-- [gotcha] Text mode always includes frontmatter; include_frontmatter only controls the json content field #output
-- [gotcha] page/page_size never chunk the note — an exact match returns the full note regardless; they only page the miss-suggestion listing #pagination
+- [gotcha] Unsliced text mode includes frontmatter; include_frontmatter controls unsliced JSON content #output
+- [gotcha] page/page_size never chunk the note — use start_line/end_line for within-note scanning; page/page_size only page the miss-suggestion listing #pagination
 - [gotcha] The CLI identifier is a positional argument, unlike write-note where everything is a flag #cli-parity
 - [gotcha] Exact-title lookup walks its own fixed-size internal pages, so a tiny page_size cannot displace an exact match out of the lookup window #pagination
 

src/basic_memory/markdown/line_scanning.py

@@ -0,0 +1,84 @@
+"""Bounded literal-match windows over the same document lines as note slices."""
+
+from dataclasses import dataclass
+
+from basic_memory.markdown.sections import document_lines
+
+
+@dataclass(frozen=True)
+class MatchWindow:
+    start_line: int
+    end_line: int
+    match_lines: list[int]
+    content: str
+
+
+@dataclass(frozen=True)
+class LiteralLineScan:
+    total_lines: int
+    match_count: int
+    windows: list[MatchWindow]
+    next_match_line: int | None
+
+
+def scan_literal_lines(
+    content: str, pattern: str, *, context_lines: int, max_matches: int
+) -> LiteralLineScan:
+    """Find case-insensitive literal substrings; merge overlapping context windows.
+
+    Count all matching lines, but return context for only the first max_matches.
+    The next omitted match points to a useful follow-up read without copying the
+    rest of the note into the response. Inputs are validated by the tool boundary.
+    """
+    lines = document_lines(content)
+    needle = pattern.casefold()
+    matches = [number for number, line in enumerate(lines, 1) if needle in line.casefold()]
+    ranges: list[tuple[int, int, list[int]]] = []
+    for number in matches[:max_matches]:
+        first = max(1, number - context_lines)
+        last = min(len(lines), number + context_lines)
+        if ranges and first <= ranges[-1][1] + 1:
+            previous_first, previous_last, previous_matches = ranges.pop()
+            ranges.append((previous_first, max(previous_last, last), [*previous_matches, number]))
+        else:
+            ranges.append((first, last, [number]))
+    return LiteralLineScan(
+        total_lines=len(lines),
+        match_count=len(matches),
+        windows=[
+            MatchWindow(first, last, numbers, "\n".join(lines[first - 1 : last]))
+            for first, last, numbers in ranges
+        ],
+        next_match_line=matches[max_matches] if len(matches) > max_matches else None,
+    )
+
+
+def format_line_read(
+    content: str,
+    *,
+    start_line: int,
+    end_line: int,
+    total_lines: int,
+) -> str:
+    """Render a slice with copyable coordinates and a bounded continuation hint."""
+    header = f"Lines {start_line}-{end_line} of {total_lines} (document, including frontmatter)"
+    # The slice has no terminal newline. Splitting on '\n' preserves a final
+    # blank selected line; the coordinate range distinguishes it from EOF.
+    numbered = (
+        "\n".join(
+            f"{number}: {line}"
+            for number, line in zip(
+                range(start_line, end_line + 1), content.split("\n"), strict=True
+            )
+        )
+        if end_line >= start_line
+        else ""
+    )
+    if end_line < total_lines:
+        width = end_line - start_line + 1
+        header += (
+            f"; next: start_line={end_line + 1}, end_line={min(total_lines, end_line + width)}"
+        )
+    else:
+        header += "; EOF"
+    return f"{header}\n{numbered}" if numbered else header

src/basic_memory/markdown/sections.py

@@ -50,6 +50,18 @@ def _ends_with_terminator(text: str) -> bool:
     return text.endswith(("\n", "\r"))
 
 
+def document_lines(text: str) -> list[str]:
+    """Count physical Markdown lines, without a phantom line after a final newline.
+
+    Unlike str.splitlines(), Unicode separators inside prose do not move the
+    coordinates away from those used by the section and line-range reader.
+    """
+    if not text:
+        return []
+    lines = _split_lines(text)
+    return lines[:-1] if _ends_with_terminator(text) else lines
+
+
 @dataclass(frozen=True, slots=True)
 class MarkdownSection:
     """One heading-bounded span of a note body, addressed by its heading path.