Telys — on-device memory

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/thyn-ai-telys

About

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 26, 2026.

Tools

9 read · 6 write · 2 delete · 2 not yet classified

Secrets

None asked for

Install scripts

None found

Runs as

Python package

Tools (19)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

• telys_add

  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 gene…

• telys_build_ivf

  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 fai…

• telys_build_lexical

  Fit the BM25 lexical index over the collection's retained tokens and persist it; the collection must have been created with lexical=True. 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.

• telys_compact

  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.

• telys_count

  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.

• telys_create_collection

  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.

• telys_delete

  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.

• telys_get

  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.

• telys_ids

  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 …

• telys_index_repo

  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; defa…

• telys_list_collections

  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.

• telys_repo_search

  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 pa…

• telys_search

  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. 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 coll…

• telys_search_lexical

  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. 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 bui…

• telys_stats

  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.

Signals

Stars

0

Forks

0

Open issues

0

Weekly downloads

90

Last commit

Oct 11, 2026 (18 days ago)

Last release

Oct 26, 2026 (3 days ago)

Last package publish

Sep 25, 2026 (1 month ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name

io.github.thyn-ai/telys

Version

0.1.14

Auth

No auth

Packages

pypi telys

License

Apache-2.0

Repository

github.com/thyn-ai/telys-sdk

Website

telys.ai

First seen

Oct 24, 2026

Last checked

Oct 26, 2026

Source

Official MCP Registrygithub-graphql