Telys — on-device memory

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.

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). 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.

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.

Takes no parameters.

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.

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 — 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.

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.

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.

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.

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.

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.

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.

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.

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.

Takes no parameters.