Normalize the CLI / MCP tool argument surface for v1.0

[groksrc]

Motivation

The MCP tools and the bm tool CLI expose the same operations with diverging argument names and shapes. Each divergence is individually defensible, but together they make the surface hard to predict — during a single manual QA session (June 11, the #962-#976 batch), a careful user writing CLI commands from the MCP signatures hit six mismatches in a row. Agents have the same failure mode in reverse: they learn one surface and transfer it to the other (the exact rationale behind #930's comma-split decision and #882's workspace-param parity).

Observed divergences (same session, current main)

Concept	MCP tool param	CLI flag/arg
Target folder	write_note(directory=...) (aliases: folder, dir, path)	--folder
Note type	write_note(note_type=...)	--type
Tags on write	tags (list or comma string)	--tags (repeatable)
Tags on search	tags	--tag (repeatable, singular)
Search query	search_notes(query=...)	positional QUERY
Type filter on search	note_types	--type
Context URL	build_context(url=...)	positional URL

Related shape quirk found in the same pass: a JSON-array string inside a list-typed param (--type '["note","task"]') silently matches nothing on both surfaces (parse_tags and parse_str_list are consistent with each other here, but the behavior surprises).

Proposal (v1.0 — the breaking-change window)

1. Pick one canonical noun per concept (e.g. decide folder vs directory, type vs note_type, singular vs plural for repeatable flags) and apply it to BOTH surfaces.
2. CLI flags mirror MCP param names wherever it doesn't fight CLI ergonomics; where positional args are kept (query, URL, identifier), make that choice consistent across subcommands.
3. Deprecation path before 1.0: accept old names as hidden aliases with a deprecation note, remove at v1.0.
4. Document the final surface in the man-pages work (Add man pages for bm CLI commands #610 / Create Unix-style Basic Memory manual pages as notes #952) — exact flag documentation is what those issues exist for, and they need a stable surface to document.

Non-goals

• No behavior changes to the underlying tools — naming/shape normalization only.
• Cloud CLI commands (bm cloud ...) are out of scope unless they share the same nouns.

Found during manual QA, same session as #972/#974/#975.

🤖 Generated with Claude Code

[claude]

Claude finished @groksrc's task in 2m 7s —— View job

---

Issue Triage

• Gather context and read issue
• Classify issue type, priority, component, complexity
• Check for duplicate issues
• Add appropriate labels
• Provide triage summary

---

Analysis

No duplicate found. This is a new, well-scoped proposal distinct from related issues (#930, #882, #952).

Labels added: enhancement

---

Classification

Dimension	Assessment
Type	Enhancement — naming/shape normalization, no behavior changes
Priority	Medium — important v1.0 polish, not a blocker; existing aliases mean no current breakage
Components	CLI (bm tool *) + MCP tools
Complexity	Complex — requires design decisions, coordinated changes across both surfaces, deprecation path, doc updates

---

Divergence Verification

I confirmed all 7 divergences against the current codebase:

Concept	MCP param	CLI flag	File locations
Target folder	directory (aliases: folder, dir, path)	--folder (mapped to directory=folder internally)	mcp/tools/write_note.py:36-38, cli/commands/tool.py:70
Note type	note_type	--type (mapped to note_type)	mcp/tools/write_note.py:43, cli/commands/tool.py:80-83
Tags on write	tags (list or comma string)	--tags (repeatable list)	mcp/tools/write_note.py:42, cli/commands/tool.py:77-79
Tags on search	tags	--tag (singular, repeatable)	mcp/tools/search.py, cli/commands/tool.py:520-521
Search query	query (named param)	positional QUERY	mcp/tools/search.py, cli/commands/tool.py
Type filter on search	note_types (plural)	--type (mapped to note_types)	mcp/tools/search.py, cli/commands/tool.py:528-530
Context URL	url (aliases: uri, memory_url)	positional URL	mcp/tools/build_context.py:137-139, cli/commands/tool.py

The note_type vs --type case is doubly confusing: on write-note --type maps to note_type, while on search-notes --type maps to note_types (plural). Same flag name, different semantics on different subcommands.

---

Proposal Evaluation

The issue's four-step plan is sound and well-ordered. Key decisions needed before implementation starts:

1. Canonical noun for folder/directory: The MCP tool already accepts folder as an alias (AliasChoices("directory", "folder", "dir", "path")). The path of least friction for v1.0 is declaring directory canonical on both surfaces (MCP already uses it in signatures; CLI would rename --folder → --directory with --folder as a deprecated alias). Alternatively, --folder is more ergonomic at the CLI and could be made canonical everywhere — that would require renaming the MCP param.

2. note_type vs type: note_type is unambiguous (avoids collision with Python's type builtin and makes the meaning explicit). Recommend note_type canonical on both surfaces; CLI --type becomes --note-type with --type as a deprecated alias.

3. note_types (search) vs note_type (write): Plural makes sense for a repeatable filter (note_types). The CLI --type on search-notes should become --note-type (repeatable, maps to note_types), matching the write side's new --note-type.

4. tags vs --tag (singular) on search: Recommend --tag (repeatable) on CLI matching tags on MCP — the singular CLI flag with plural MCP param is the standard Typer/Click pattern and is already used on write-note. No change needed here beyond documentation clarity.

5. Positional vs named for query/URL: Positional args are fine CLI ergonomics for required single values. The inconsistency here isn't the positional-vs-named shape but whether to document them as the canonical equivalent of the MCP param name. A note in the man pages (Create Unix-style Basic Memory manual pages as notes #952) that "CLI positional QUERY corresponds to MCP param query" is sufficient without changing the CLI shape.

---

Suggested implementation order

1. Design doc / ADR: decide canonical names (folder vs directory, type vs note_type) — can be done as a comment here
2. MCP side: write_note signature stays as-is; ensure aliases cover old names with deprecation warnings
3. CLI side: rename --folder → --directory (or the reverse), --type → --note-type, --tag (search) → keep as-is with doc note
4. Add deprecated_alias handling in Typer callbacks with console warnings
5. Update man-page content (Create Unix-style Basic Memory manual pages as notes #952) with the resolved canonical surface
6. Remove deprecated aliases at v1.0 cut

---

Relationship to open issues

• Create Unix-style Basic Memory manual pages as notes #952 (man pages): blocks on this being resolved — man pages need stable flag names
• write_note doesn't expose/document workspace targeting — agents can't disambiguate same-named projects across workspaces #882 (workspace param parity): same class of problem, could be batched into this work
• Decide comma-split behavior for note_types/entity_types/categories params in search_notes #930 (comma-split): already resolved; parse_tags and parse_str_list are consistent — no action needed here beyond documenting behavior
• Add man pages for bm CLI commands #610 (man pages upstream): same dependency as Create Unix-style Basic Memory manual pages as notes #952

[groksrc]

Additional datapoint from the #967 work: there is currently no general CLI-settings reference doc. docs/semantic-search.md documents only the search-related config fields; general CLI-behavior settings (e.g. write_note_overwrite_default, and now cli_output_style from #967) are documented solely via their config Field descriptions — discoverable in code and in the #963 diagnostics dump, but nowhere a user would browse.

When the surface gets normalized here, a docs/cli.md (or equivalent section in the #610/#952 man-pages work) would be the natural home for:

• the canonical flag/argument surface per bm tool command
• the output-mode story (--json / --plain / Rich default, and the cli_output_style config + BASIC_MEMORY_CLI_OUTPUT_STYLE env var)
• the remaining user-facing config fields that have no documentation home today

🤖 Generated with Claude Code