Your first context filesystem.

1. Start the runtime

The runtime is one background process per machine. Every other component runs inside it.

$ clio_run start

Leave it running in its own terminal, or add & to run it in the background. It is ready when the log shows the client transport. Its port is the base RPC port, 9413, plus 3:

IpcManager: TCP ROUTER transport bound on <address>:9416
Viz: dashboard listening at http://127.0.0.1:8080

In another terminal, clio_run status prints RUNNING, STOPPED (clean), or STOPPED (stale artifacts) when a crashed runtime left files behind.

The runtime reads ~/.clio/clio.yaml. To use a different file, set CLIO_SERVER_CONF before you start it:

$ export CLIO_SERVER_CONF=$HOME/my-clio.yaml
$ clio_run start --disk /scratch/$USER/clio   # keep persistent state on scratch

2. Mount the filesystem

$ mkdir -p ~/clio-mnt
$ CLIO_WITH_RUNTIME=0 clio_cte_fuse ~/clio-mnt -f

CLIO_WITH_RUNTIME=0 tells the FUSE daemon to attach to the runtime you started. Without it, the daemon starts a private runtime of its own, and nothing else can see your files. -f keeps the daemon in the foreground; leave it running.

On Windows, mount a drive letter: clio_cte_fuse Z: -f. On macOS, see FUSE on macOS.

3. Use it like a directory

$ mkdir -p ~/clio-mnt/notes
$ cp report-2024.md field-log.txt ~/clio-mnt/notes/
$ ls -l ~/clio-mnt/notes
$ grep -i "sea ice" ~/clio-mnt/notes/*

Writes go through to the runtime as they happen, so file sizes are exact as soon as write() returns. Each file is stored as 1 MiB pages placed on the fastest tier with room. A copy goes to the persistent disk tier, and the index picks up the text.

Open http://127.0.0.1:8080 and look at Pools → clio_cte_core. The tier roster shows the bytes you just wrote. The dashboard tutorial walks through every page.

4. Find files from Python

Keyword search is served by the indexer pool (564.0). Point the client at it, then search the files you copied in:

import os
os.environ["CLIO_WITH_RUNTIME"] = "0"     # attach to the running runtime
os.environ["CLIO_CTE_POOL"] = "564.0"     # search lives in the indexer

import clio_cte_core_ext as cte

cte.clio_init(cte.RuntimeMode.kClient, False)
cte.initialize_cte("", cte.PoolQuery.Dynamic())
client = cte.get_cte_client()

# Each file is a tag named by its path. Map tag ids back to paths.
paths = {}
for name in client.TagQuery(".*notes/.*", 0):
    tid = cte.Tag(name).GetTagId()
    paths[(tid.major_, tid.minor_)] = name

for hit in client.SemanticSearch(".*notes/.*", "[0-9]+", "sea ice extent", 5):
    if hit.score > 0:                      # 0 means no query word appears
        print(f"{hit.score:6.2f}  {paths.get((hit.tag_id.major_, hit.tag_id.minor_))}")

Results are ranked by BM25 relevance. Each hit is one 1 MiB page of a file, and hit.blob_name is the page number. The blob pattern [0-9]+ limits the search to pages; each file also has a small attribute blob named ~i. Every page that matches the patterns is ranked, so pages without any query word come back with a score of 0. Query files from Python covers name and time queries, reading the bytes back, and the higher-level clio_cee API.

5. Stop cleanly

$ fusermount3 -u ~/clio-mnt     # Linux. macOS: umount ~/clio-mnt
$ clio_run stop

clio_run stop drains in-flight work for up to five seconds by default. Use --grace-period <ms> to change that, or --force to stop immediately.

Your files survive the stop. clio_run start recovers them from the metadata log, so start again and mount the same directory to see the same files. To begin from an empty store instead, use clio_run start --fresh, which discards this node's persistent state.

Troubleshooting