Semantic + lexical search over a Telys memory collection: the server embeds query with its built-in on-device embedder and returns the best-matching live rows as hits (id, score, metadata). Use to recall stored notes/facts/decisions before answering. Required: collection, query. Optional: top_k (default 5) and where — a single-key equality filter such as scope=project:acme (one key only; MCP-created collections are partitioned by scope). Fails (isError) when the collection does not exist — write first via telys_add or telys_create_collection — or when where carries more than one key.

Add text documents to a Telys memory collection: each text is embedded on-device, inserted as a new row, and persisted; the collection is auto-created (partition_by='scope') when absent. Use to store new memories. Required: collection, texts. Optional: ids (one per text; auto-generated when omitted — an id that already exists raises a conflict, so use telys_upsert to replace) and metadata (one object per text; set a scope value to route partitions and enable where-filtering later). Fails on empty texts, ids/texts length mismatch, or duplicate ids. NOT idempotent: omitted ids are freshly generated per call, so a repeat call inserts additional new rows.

Create a named Telys memory collection in the active store, wired to the built-in embedder. Optional — telys_add auto-creates on first write — but use it to fix the name and partition key up front. Required: name. Optional: partition_by (default 'scope'; a single metadata key name — compose compound keys into one string yourself). The new collection is built but NOT persisted, so telys_list_collections shows it only after a mutating tool (telys_add, telys_upsert, …) writes to it. Repeating with the same name returns the existing collection unchanged.

List the Telys memory collections saved in the active store ($TELYS_MEMORY_PATH, default ~/.telys/memory). Use to discover what exists before searching or writing. Takes no arguments and returns sorted names; an empty store yields an empty list, not an error. Collections created but never written to by a mutating tool do not appear — if names you expect are missing, check the client points at the right store.

Report stats for one Telys memory collection: name, partition key name, and live external-id count, plus runtime-provided counters (row counts, dimension, index state) that vary by runtime version. Use to confirm a collection exists and gauge its size. Required: collection. Fails when the collection does not exist.

Add-or-replace text rows by external id: new ids are inserted; existing ids are re-embedded and replaced as a versioned update (never a duplicate physical row), then persisted. Use when the caller owns the ids and a repeated call must converge instead of conflicting — this is the idempotent write path. Required: collection, texts, ids (explicit JSON null is treated as omitted = plain telys_add with generated ids). Optional: metadata (one object per text) and partition_by (default 'scope'; the collection is auto-created when absent). Fails on ids/texts length mismatch.

Replace the vectors/metadata of EXISTING ids by re-embedding new texts, then persist. Use for deliberate corrections to known rows. Required: collection, texts, ids — strict by contract: missing or null ids fail with 'update requires ids' (use telys_upsert to insert-or-replace instead). Optional: metadata (one object per text; the collection's partition key is defaulted when omitted). Fails when the collection does not exist or on ids/texts length mismatch.

Tombstone rows by external id so they no longer appear in queries or id listings; the store is persisted and the space is physically reclaimed later by telys_compact. Use to forget memories. Required: collection, ids. Repeating the same delete is a no-op. Fails when the collection does not exist.

Return the live (non-tombstoned) external ids in a collection, optionally scoped by a where filter. Use to enumerate what is stored before a bulk update or delete. Required: collection. Optional: where — a single-key equality filter such as scope=project:acme (one key only). Fails when the collection does not exist or when where carries more than one key.

Return the live row count (post-tombstone) for a collection, optionally where-scoped. Use for a cheap size check without pulling the full id list. Required: collection. Optional: where — a single-key equality filter (one key only). Fails when the collection does not exist or when where carries more than one key.

Exact row lookup by external id — no similarity search. Returns one entry per requested id with a found flag plus stored metadata; for auto-indexed repo rows the exact source slice is re-read from disk via the row's path + line range. Use to fetch known rows or read the code behind a telys_repo_search hit. Required: collection, ids. Optional: with_metadata (default true) and with_text (default true; re-read the source slice for repo-index rows). Unknown ids come back as found:false, not an error; fails only when the collection does not exist.

On-device BM25 lexical (keyword) search — exact-term matching for identifiers and rare tokens where semantic search is fuzzy. Requires the collection to have been created with lexical=True AND telys_build_lexical to have run, otherwise the call fails. Required: collection, query. Optional: top_k (default 5), where (single-key equality filter), explain (default false; include per-hit score explanations). Fails when the collection does not exist or the lexical index was never built.

Flush tombstones and merge the delta segment into the base layout, physically reclaiming space from deleted/updated rows; the store is persisted. Use after large delete or update batches. Required: collection. Repeating with no pending changes is a no-op. Fails when the collection does not exist.

Build per-partition IVF indexes and calibrate nprobe to a recall floor — speeds up search on large partitions (small partitions already use exact scans). Run once a partition grows large. Required: collection. Optional: min_rows (default 20000; partitions below this stay exact) and target_recall (default 0.98). Fails when the collection does not exist; needs the optional faiss dependency — the error names the fix (pipx: pipx inject telys faiss-cpu; venv: pip install faiss-cpu).

Fit the BM25 lexical index over the collection's retained tokens and persist it; the collection must have been created with lexical=True. Run after bulk ingestion and before telys_search_lexical. Required: collection. Optional: k1 (default 1.8; term-frequency saturation) and b (default 1.0; document-length normalization). Fails when the collection does not exist.

Produce a TuningPlan for a collection via its Tuner, and optionally apply it. Use to inspect or apply index/maintenance recommendations. Required: collection. Optional: dry_run — true never applies (plan only), false always applies, omit for the tuner default. Fails when the collection does not exist.

Walk a repo directory — respecting .gitignore on git checkouts, else skipping common build/dep dirs; binaries and symlinks escaping the root are refused — chunk every text file, and ingest the chunks into a collection for telys_repo_search. Incremental: re-calls re-fingerprint each file (size, mtime), re-embed only changed files, tombstone removed ones, and no-op fast when nothing changed. All arguments optional: path (repo root; default: the server workspace, else CWD), collection (default 'repo_symbols'), mode ('windowed' default or 'file'), window_lines (48), window_overlap_lines (8), max_file_bytes / max_files / max_seconds (0 = unlimited), force (default false; rebuild every file). Fails when path is not a directory or the collection already exists with a partition key other than repo_id.

Search the auto-indexed repo collection (default 'repo_symbols') with the on-device embedder. Every call first re-runs the incremental telys_index_repo against the server workspace — cheap on no-change — so hits are always fresh, and each hit carries the exact source slice re-read from disk. Use for 'map this codebase and search it' workflows. Required: query. Optional: top_k (default 5) and path_hint (exact repo-relative path to scope the search). Fails when no workspace is configured — set TELYS_MCP_WORKSPACE, launch telys mcp --workspace <dir>, or call telys_index_repo with an explicit path first. Note: the freshness re-index writes to the store, so this is not a read-only tool.

Report the server's configured workspace: resolved path, repo_id, the auto-index collection name, tracked file count, and whether the fingerprint cache is persisted across restarts. Use to verify which repo telys_repo_search will index before calling it. Takes no arguments; the workspace fields are null when no workspace is configured — that is a report, not an error.