Timeln

Whoami

Confirm the current Timeln token and return the user's email + plan.

Get Recent Docs

Get the user's recent documents.

Search Documents

List the user's documents with pagination.

Get Document

Fetch a single document by id.

Ingest Text

Ingest plain text into the user's Timeln knowledge graph.

Ingest Url

Ingest a public URL — backend fetches and processes it.

Query Knowledge

Ask a natural-language question over the user's knowledge graph + documents. Also answers questions about the user's own recent activity, e.g. "what was I researching two days ago?" or "what did I work on this week?" — route such temporal/self questions here.

Get Topic Entities

Return entities and their sources related to a topic or keyword. Uses the entity-extraction analytics endpoint to surface what is connected to a given concept in the user's graph. Useful for MECE gap analysis (which nodes cluster around a topic, which are isolated).

Graph Stats

Size snapshot of the user's knowledge graph — node count, relationship count, label list, relationship-type list. Use this when the user asks "how big is my graph", "how many notes/entities do I have", "what's in my knowledge base", or as a first step before any graph-analysis workflow to confirm the graph is populated. Cheap — single fast call. NOT for content search (use `graph_hybrid_search` or `query_knowledge`) and NOT for schema details like property keys (use `graph_schema`).

Graph Schema

Full structural schema of the graph — every node label, relationship type, property key, and index. Use this BEFORE composing a custom `graph_cypher` query so you know which labels and properties actually exist (e.g. is it `Entity` or `__Entity__`, does `created_at` exist, is there a vector index?). Also useful when the user asks "what kinds of things are in my graph" or "what can I filter by". NOT for counts (use `graph_stats`) and NOT for actual content (use search tools).

Graph Top Entities

Most-important entities in the user's graph, ranked by a graph-centrality algorithm. Use when the user asks "what are my top concepts", "what topics am I most into", "what's central to my thinking", "find the most influential ideas", or wants a high-level overview of what their knowledge base orbits around.

Graph Communities

Auto-discover topic clusters via label-propagation community detection. Returns the list of communities (clusters) with a sample of entity names and size for each, largest first. Use when the user asks "what are my main topic areas", "cluster my knowledge", "what are my reading themes", "auto-organize my notes", or wants to see the natural neighborhoods in their graph without supplying tags. Each community can be treated as a candidate auto-tag or folder.

Graph Neighborhood

Pull the local subgraph (nodes + edges) around one entity, expanding outward N hops via BFS. Use when the user picks a single entity/concept and wants to see "what's around X", "what connects to X", or wants a graph-visualization payload focused on one node.

Graph Similar Entities

Find entities STRUCTURALLY similar to a given one — entities that share neighbors in the graph. Use when the user asks "what's similar to X", "what entities behave like X", "what could substitute for X", "what other concepts play the same role as X". This is STRUCTURAL similarity (overlap of graph neighbors), not SEMANTIC similarity (text/embedding meaning). For semantic similarity use `graph_hybrid_search`. For LIKELY-MISSING links (link prediction) pick `adamic_adar`.

Graph Paths

Find the K shortest paths in the graph between two specific entities. Use when the user asks "how is A related to B", "what's the connection between A and B", "trace the link from A to B", "do A and B have anything in common in my notes". Returns full path objects (nodes + relationships). If the user wants a human-readable narration of the connection ("explain how A relates to B"), prefer `graph_explain` — it returns ordered name lists better-suited for prose.

Graph Explain

Explain the connection between two entities as ordered name-chains, ready for prose narration. Use when the user asks "explain how X connects to Y" or "why are X and Y in the same graph". Returns each path as a list of entity NAMES (e.g. ["X", "Z", "Y"]) plus a weight — easier for an LLM to narrate than raw path objects. Prefer this over `graph_paths` when the goal is a written explanation. Use `graph_paths` when the goal is rendering a graph visualization or doing further structural analysis.

Graph Hybrid Search

SEMANTIC + KEYWORD search for ENTITIES in the user's graph (vector embeddings ∪ fulltext). Use when the user types a freeform query or topic and you need to locate the matching entity ids — e.g. "find anything about transformers", "look up notes on Kubernetes", "what do I have on Stoicism". Each hit is tagged with its source ('vector', 'fulltext', or 'both'); the entity ids returned feed naturally into the other graph_* tools. Difference from `query_knowledge`: this returns RAW entity hits and

Graph Related Documents

Documents that share entities with a given document, ranked by overlap (with sample shared entities). Use when the user is viewing a specific document and asks "what else should I read", "more like this", "related notes", "what other documents touch the same ideas". Returns each candidate document plus the entities it shares with the source — built-in "why is this related?" explanation.

Graph Recommendations

Recommend entities personalized to a seed set — BFS-weighted personalized-PageRank approximation. Use when the user wants "recommendations based on these topics", "what should I explore next given that I care about X, Y, Z", "suggest concepts adjacent to my current focus". Seeds bias the recommendations: pass in entities the user has starred, recently read about, or explicitly named.

Graph Trending

Entities most mentioned across documents the user added in the last N days — what's "hot" lately. Use for "what's trending in my notes", "what have I been reading about this week/month", "what topics are heating up", or to power a weekly digest. Strictly time-windowed: relies on Document.created_at, so older but still-influential entities will NOT show (use `graph_top_entities` for that).

Graph Cypher

ESCAPE HATCH — run arbitrary READ-ONLY openCypher against the user's FalkorDB graph. Use ONLY when no other graph_* tool fits — e.g. multi-step aggregations, custom filters on specific properties, calling FalkorDB algorithms not exposed by a dedicated tool (algo.WCC, algo.MSF, algo.SSpaths, etc.), or one-off analytics. Prefer the dedicated tools first; they are faster to compose and have richer descriptions for the user. BEFORE writing a query, call `graph_schema` to confirm label/property nam