CLI Reference

The mx CLI provides token-efficient access to your knowledge base.

Search Commands

mx search

Search the knowledge base with hybrid keyword + semantic search.

mx search "query"                    # Hybrid search
mx search "docker" --tags=infra      # Filter by tag
mx search "api" --mode=semantic      # Semantic only
mx search "api" --mode=keyword       # Keyword only
mx search "query" --limit=20         # More results
mx search "query" --min-score=0.5    # Only confident results
mx search "query" --content          # Include full content
mx search "query" --strict           # No semantic fallback
mx search "query" --scope=project    # Project KB only
mx search "query" --include-neighbors
mx search "query" --include-neighbors --neighbor-depth=2
mx search "query" --terse            # Paths only
mx search "query" --full-titles      # Show untruncated titles
mx search "query" --json             # JSON output

Options:

--tag, --tags: Filter by tags (comma-separated)
--mode: Search mode (hybrid, keyword, semantic)
--limit, -n: Maximum results (default: 10)
--min-score: Minimum score threshold (0.0-1.0)
--content: Include full document content in results (replaces snippet)
--strict: Disable semantic fallback
--terse: Output paths only
--full-titles: Show full titles without truncation
--scope: Limit to KB scope (project or user)
--include-neighbors: Include semantic links + typed relations + wikilinks
--neighbor-depth: Neighbor traversal depth (default: 1)
--json: JSON output

Content Flag Behavior:

When --content is used:

JSON output: Returns content field with full document text instead of snippet
Table output: Shows the standard results table followed by a content section displaying full text for each result

Without --content, only a brief snippet is shown (default behavior).

Notes:

Query cannot be empty. An error is returned for empty or whitespace-only queries.

Understanding Search Scores

All search scores are normalized to 0.0-1.0 (higher = better match).

Score Range	Confidence	Interpretation
>= 0.7	High	Strong keyword or semantic match. Trust this result.
0.4 - 0.7	Moderate	Partial match. Worth reviewing but may be tangential.
< 0.4	Weak	Tangential relevance only. May be noise.

How scores are calculated:

Hybrid mode (default): Combines keyword and semantic search using Reciprocal Rank Fusion (RRF). Results appearing in both rankings score higher.
Keyword mode: BM25 text matching. Exact term matches matter most.
Semantic mode: Cosine similarity of embeddings. Conceptual meaning matters more than exact words.

Score adjustments:

After initial ranking, scores receive context-aware boosts:

Tag match: +0.05 per matching tag (e.g., searching "python" boosts entries tagged "python")
Project context: +0.15 if entry's source_project matches your current project
Boost paths: +0.12 if entry matches patterns in boost_paths in your .kbconfig

Scores are re-normalized to 0-1 after boosts, so the top result is always 1.0.

Recommended thresholds:

# High-confidence results only (for automated workflows)
mx search "deployment" --min-score=0.7

# Moderate confidence (good default for exploration)
mx search "deployment" --min-score=0.4

# All results (when you want broad coverage)
mx search "deployment"

mx history

View and re-run past searches.

mx history                  # Show last 10 searches
mx history -n 20            # Show last 20
mx history --rerun 1        # Re-run most recent
mx history --clear          # Clear history

Read Commands

mx get

Read a knowledge base entry.

mx get tooling/my-entry.md            # Full entry by path
mx get tooling/my-entry.md --metadata # Metadata only
mx get tooling/my-entry.md --json     # JSON output
mx get --title="Docker Guide"         # Get by title
mx get --title "Python Tooling"       # Get by title (alt form)

Options:

--title: Get entry by title instead of path (case-insensitive)
--metadata, -m: Show only metadata
--json: JSON output

Title Lookup Behavior:

If one match found: returns that entry
If multiple matches: shows error with candidate paths
If no match: shows error with similar title suggestions

mx list

List entries with optional filters.

mx list                        # All entries
mx list --tags=infrastructure  # Filter by tag
mx list --category=tooling     # Filter by category
mx list --limit=50             # More results
mx list --full-titles          # Show untruncated titles
mx list --scope=project        # Project KB only

mx categories

List available top-level categories (directories) in the KB.

mx categories
mx categories --scope=project
mx categories --json

mx tree

Display directory structure.

mx tree                    # Full tree
mx tree tooling            # Specific path
mx tree --depth=2          # Limit depth
mx tree --scope=project    # Project KB only

Write Commands

mx add

Create a new entry.

mx add --title="My Entry" --tags="foo,bar" --category=tooling --content="..."
mx add --title="..." --tags="..." --category=... --file=content.md
cat content.md | mx add --title="..." --tags="..." --category=... --stdin

Required:

--title: Entry title
--tag, --tags: Tags (comma-separated)

Category behavior:

--category: Optional target directory.
If omitted and .kbconfig sets primary, primary is used.
If omitted and no primary is set, mx add writes to KB root (.) and warns by default. Tip: Use mx categories to discover available categories.
Silence the warning with:
- .kbconfig: warn_on_implicit_category: false

Common options:

--scope: Target KB scope (project or user)
--semantic-links: Set semantic links as JSON array

mx replace

Replace content or metadata in an existing entry.

mx replace path/entry.md --tags="new,tags"
mx replace path/entry.md --content="New content"
mx replace path/entry.md --file=new-content.md

Note: For appending content, use mx append. For surgical edits, use mx patch.

mx patch

Surgical find-replace edits.

mx patch path/entry.md --find="old text" --replace="new text"
mx patch path/entry.md --find="TODO" --replace="DONE" --replace-all
mx patch path/entry.md --find="..." --replace="..." --dry-run

Intent Detection: If you use flags that suggest a different command (e.g., --content without --find), the CLI will suggest the correct command:

$ mx patch entry.md --content='new stuff'
Error: --find is required for find-replace operations.

Did you mean:
  - To append content:  mx append 'Title' --content='...'
  - To replace text:    mx patch entry.md --find 'x' --replace 'y'
  - To overwrite entry: mx replace entry.md --content='...'

mx append

Append content to existing entry by title, or create new if not found.

mx append "Daily Log" --content="Session summary"
mx append "API Docs" --file=api.md --tags="api,docs"
mx append "Debug Log" --content="..." --no-create  # Error if not found
cat notes.md | mx append "Meeting Notes" --stdin --tags="meetings"

mx delete

Delete an entry.

mx delete path/entry.md
mx delete path/entry.md --force  # Delete even with backlinks

mx quick-add

Quickly add content with auto-generated metadata.

mx quick-add --stdin              # Paste content, auto-generate all
mx quick-add -f notes.md          # From file with auto metadata
mx quick-add --content "..." --confirm  # Auto-confirm creation
echo "..." | mx quick-add --stdin --json

mx ingest

Ingest a markdown file into the KB, adding frontmatter if missing.

mx ingest notes.md                          # Auto-detect title/tags
mx ingest draft.md --title="My Entry"       # Override title
mx ingest doc.md --tags="api,docs"          # Set tags
mx ingest doc.md --directory="guides"       # Place in guides/
mx ingest doc.md --scope=project            # Project KB only
mx ingest doc.md --dry-run                  # Preview changes

Analysis Commands

mx health

Audit KB for problems.

mx health
mx health --json

Checks for:

Orphaned entries (no backlinks)
Broken links
Stale content (>90 days)
Missing frontmatter

Orphans are entries with no incoming links (no [[wikilinks]] or typed relations pointing at them). This is normal in new KBs.

Quick fixes:

Add an index/hub entry that links to everything important.
Add at least one link from an existing entry to each orphan.
Use mx suggest-links path/to/entry.md to find candidates to connect.

mx relations-lint

Warn on unknown or inconsistent typed relation types (non-blocking by default).

mx relations-lint
mx relations-lint --json
mx relations-lint --strict   # Exit non-zero if issues found

Use mx relations-lint to align relation types with the canonical taxonomy.

mx hubs

Show most connected entries.

mx hubs
mx hubs --limit=5

mx suggest-links

Find semantically related entries.

mx suggest-links path/entry.md
mx suggest-links path/entry.md --limit=10

mx tags

List all tags with counts.

mx tags
mx tags --min-count=3

Browse Commands

mx info

Show KB configuration and stats.

mx info
mx info --json

Alias: mx config

mx whats-new

Show recently modified entries.

mx whats-new                      # Last 30 days
mx whats-new --days=7             # Last week
mx whats-new --scope=project      # Project KB only
mx whats-new --limit=20           # More results

Project Setup Commands

mx init

Initialize a knowledge base (project or user scope).

mx init                    # Project KB in ./kb/
mx init --user             # User KB in ~/.memex/kb/
mx init --path docs/kb     # Custom location
mx init --force            # Reinitialize existing
mx init --json             # JSON output

Options:

--path, -p: Custom location for local KB (default: kb/)
--user, -u: Create user KB at ~/.memex/kb/
--force, -f: Reinitialize existing KB
--json: JSON output

What gets created:

Project: kb/README.md and .kbconfig at the project root
User: ~/.memex/kb/README.md and ~/.memex/kb/.kbconfig

When to use:

Starting a new project that needs project-specific documentation
Creating a knowledge base that should be versioned with the code
Setting up for GitHub Pages publishing

mx context

Show or validate project KB configuration.

mx context                  # Show current config
mx context show             # Same as above
mx context validate         # Validate config paths
mx context validate --json  # JSON output

Note: .kbconfig is created by mx init.

Common next step: set a default write directory so you can omit --category in mx add:

# .kbconfig (project root)
primary: guides

Automation Commands

mx batch

Execute multiple KB operations in a single invocation.

mx batch << 'EOF'
add --title='Note 1' --tags='tag1' --category=tooling --content='Content'
search 'api'
EOF

Reads commands from stdin (or --file) and returns JSON results.

Templates

List or show available entry templates.

mx templates
mx templates show troubleshooting
mx templates --json

Publishing

mx publish

Generate static HTML site.

mx publish                           # Build to _site/
mx publish -o docs                   # Build to docs/
mx publish --base-url /my-kb         # For subdirectory hosting
mx publish --include-drafts          # Include draft entries

Maintenance

mx summarize

Generate descriptions for entries missing them.

mx summarize --dry-run         # Preview what would be generated
mx summarize                   # Generate and write descriptions
mx summarize --limit 5         # Process only 5 entries
mx summarize --json            # Output as JSON

mx reindex

Rebuild search indices.

mx reindex
mx reindex --json

mx eval

Evaluate search accuracy against a query dataset.

mx eval                              # Run eval/queries.json against current KB
mx eval --mode=keyword               # Keyword-only evaluation
mx eval --scope=project              # Project KB only
mx eval --json                       # JSON to stdout (includes meta)
mx eval --save                       # Also write eval/results/<timestamp>.json
mx eval --out /tmp/mx-eval.json      # Also write JSON artifact to a specific file

mx prime

Output agent workflow context (for hooks).

mx prime                    # Output onboarding + quick reference
mx prime --json             # JSON output

mx session-context

Output dynamic project-relevant context (for hooks).

mx session-context                   # Print session context
mx session-context --max-entries 4   # Limit relevant entries
mx session-context --install         # Update .claude/settings.json hook
mx session-context --install --install-path .claude/settings.local.json
mx session-context --json            # JSON output

mx schema

Output CLI schema with agent-friendly metadata for introspection.

mx schema                    # Full schema (JSON)
mx schema --command=patch    # Schema for specific command only
mx schema -c search          # Short form
mx schema --compact          # Minimal output (commands and options only)

Schema includes:

All commands with their arguments and options
Related commands (cross-references)
Common mistakes and how to avoid them
Example invocations
Recommended workflows

Use cases:

Agent introspection to understand available commands
Proactive error avoidance via common_mistakes field
Discovering related commands for a task
Understanding option types and defaults

Example output structure:

{
  "version": "0.2.0",
  "commands": {
    "patch": {
      "description": "Apply surgical find-replace edits",
      "options": [...],
      "related": ["update", "append"],
      "common_mistakes": {
        "--find without --replace": "Both are required"
      },
      "examples": ["mx patch path.md --find \"old\" --replace \"new\""]
    }
  },
  "workflows": {...}
}

Global Options

Global flags:

--version: Show the version and exit
--json-errors: Output errors as JSON (for programmatic use)
-q, --quiet: Suppress warnings, show only errors and essential output
--help: Show help

Per-command (when available):

--json: JSON output

CLI Reference

Search Commands

mx search

Understanding Search Scores

mx history

Read Commands

mx get

mx list

mx categories

mx tree

Write Commands

mx add

mx replace

mx patch

mx append

mx delete

mx quick-add

mx ingest

Analysis Commands

mx health

mx relations-lint

mx hubs

mx suggest-links

mx tags

Browse Commands

mx info

mx whats-new

Project Setup Commands

mx init

mx context

Automation Commands

mx batch

Templates

Publishing

mx publish

Maintenance

mx summarize

mx reindex

mx eval

mx prime

mx session-context

mx schema

Global Options

See Also