Skip to content

docs: Update docs #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pringled merged 3 commits into from
Apr 14, 2026
Merged

docs: Update docs #6

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
22593da
Trim README to bare minimum
Pringled Apr 14, 2026
9def45a
Remove search mode options from docs
Pringled Apr 14, 2026
921611e
Use 'result' instead of 'r' in README example
Pringled Apr 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 5 additions & 27 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,38 +11,16 @@ pip install semble
## Python API

```python
from semble import SearchMode, SembleIndex
from semble import SembleIndex

index = SembleIndex.from_path("./my-project")

# Hybrid search (semantic + BM25, default)
results = index.search("how does authentication work?", top_k=5)
for r in results:
print(r.chunk.location, f"score={r.score:.3f}")
print(r.chunk.content[:200])

# Keyword-only
results = index.search("JWT token", mode=SearchMode.BM25)
```

## Search modes

| Mode | Description |
|------|-------------|
| `hybrid` | Semantic + BM25, normalized and combined (default) |
| `semantic` | Embedding similarity only |
| `bm25` | Keyword search only |

## Disk embedding cache

Embeddings are cached to `~/.cache/semble` by default so re-indexing unchanged files is instant. When using a custom encoder, pass `model_name` to enable caching:

```python
index = SembleIndex.from_path("./my-project", model=my_model, model_name="my-org/my-model")
for result in results:
print(result.chunk.location, f"score={result.score:.3f}")
print(result.chunk.content[:200])
```

Only embeddings are cached; BM25 and the ANNS index are always rebuilt fresh.

## MCP server

Semble can run as an MCP server so agents (Claude Code, Cursor, etc.) can search your codebase directly.
Expand All @@ -63,5 +41,5 @@ This indexes the directory at startup and exposes two tools:

| Tool | Description |
|------|-------------|
| `search` | Search with a natural-language or code query. Supports `hybrid` (default), `semantic`, and `bm25` modes. |
| `search` | Search your codebase with a natural-language or code query. |
| `find_related` | Given a file path and line number, return chunks semantically similar to the code at that location. |