Telys — on-device memory

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.

Build per-partition IVF indexes and calibrate nprobe to a recall floor — approximate search for partitions that have outgrown exact scans. Maintenance sibling of telys_compact (physically reclaim space from deletes) and telys_tune (plan and optionally apply tuning automatically). Required: collection. Optional: min_rows (default 20000; only partitions with at least this many rows get an IVF index — smaller ones keep exact scans) 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. Collections created through MCP are lexical-capable, so this works out of the box after ingestion. This builds the lexical BM25 index; telys_build_ivf builds the IVF vector index. 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.

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. Alternatives: telys_delete to remove rows, telys_tune for index tuning. Required: collection. Repeating with no pending changes is a no-op. Fails when the collection does not exist.

Return the live row count (post-tombstone) for a collection — cardinality only, optionally where-scoped. Siblings: telys_stats for aggregate stats (partition key, live id count, runtime index counters); telys_ids to enumerate the ids themselves. Required: collection — the name of an existing collection in the active store; the call fails when it does not exist (write first via telys_add or telys_create_collection). Optional: where — a single-key equality filter (one key only); more than one key fails.

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). Collections created through MCP are automatically text-retaining and lexical-capable: stored text is returned by telys_get and telys_search, and telys_build_lexical / telys_search_lexical work out of the box. 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.

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.

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. For memory rows created through MCP, the stored raw text is also returned. 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, or return stored text for memory rows). Unknown ids come back as found:false, not an error; fails only when the collection does not exist.

Return the live (non-tombstoned) external ids in a collection, optionally scoped by a where filter — enumeration without ranking. Siblings: telys_search returns ranked hits with scores for a query; telys_count returns just the cardinality. Required: collection. Optional: where — a single-key equality filter such as scope=project:acme (one key only). Result: the full id list in a single response (no pagination); the order is the engine's internal row order — neither sorted nor insertion order — so sort client-side when a stable display order matters. Fails when the collection does not exist or when `where` carries more than one key.

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. Routing: telys_repo_search queries the index; telys_add/telys_upsert store manual memories. Returns status (built/refreshed/hit), repo_id, and file/chunk counts. 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.

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.

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.

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, text). Use to recall stored notes/facts/decisions before answering. The raw text is included for memory rows created through MCP, so agents can read what they stored without a separate telys_get. Choose this embedding-ranked path when wording varies; choose telys_search_lexical when exact terms and BM25 scoring matter. 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.

On-device BM25 lexical (keyword) search — exact-term matching for identifiers and rare tokens where semantic search is fuzzy. Sibling: use telys_search for embedding-ranked (vector) retrieval; this tool is the BM25 path, no embedding involved. Collections created through MCP are lexical-capable; run telys_build_lexical once after bulk ingestion, then telys_search_lexical returns hits including the stored text. 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.

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. Siblings: telys_list_collections enumerates collections; telys_count returns cardinality only. Required: collection. 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. Sibling: telys_build_ivf builds the IVF index directly; this tool plans and optionally applies tuning. Applying (dry_run=false) sets the default target recall + exact↔quantized crossover and IVF-builds oversized partitions (already-built ones are skipped) — instant settings plus a faiss-requiring build that grows with partition size, applied live in-process (this handler does not persist to disk) and not atomically, so a mid-apply failure can leave earlier settings in place. Verify the after-state with telys_stats. Required: collection. Optional: dry_run (plan-only vs apply; values on the parameter). Fails when the collection does not exist.

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.

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.

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.