Read the contents of a text file.

Returns a JSON object with the file path, requested offset/limit, and the lines that were read. Large files are capped at MAX_FILE_SIZE bytes.

Args: path: Absolute or relative path to the file. offset: Number of lines to skip from the beginning. limit: Maximum number of lines to return (null = unlimited). encoding: Text encoding to use.

Returns: str: JSON string with keys 'success', 'path', 'offset', 'limit', 'total_lines', 'truncated', and 'content'.

Write text content to a file, optionally creating parent directories.

Args: path: Absolute or relative path to the file. content: Text content to write. encoding: Text encoding to use. append: If True, append to the file instead of overwriting. create_dirs: If True, create parent directories when they do not exist.

Returns: str: JSON string with keys 'success', 'path', 'bytes_written', and 'operation' ('append' or 'overwrite').

Execute a terminal command and return stdout, stderr, and exit code.

The command runs in a subprocess. By default it is executed through the system shell so that pipes, redirections, and environment variables work. Use caution with untrusted input to avoid command injection.

Args: command: Shell command to execute. working_directory: Working directory for the command. timeout: Maximum execution time in seconds. env: Additional environment variables to set or override. shell: Execute the command through the system shell.

Returns: str: JSON string with keys 'success', 'command', 'exit_code', 'stdout', 'stderr', and 'timed_out'.

Search the web using the specified search engine and return results.

Supported engines: duckduckgo (default), bing, google, baidu. Each result contains a title, URL, and short snippet. No API key is required.

Args: query: Search query string. engine: Search engine to use. num_results: Maximum number of results to return. region: Optional region/locale code for search results.

Returns: str: JSON string with keys 'success', 'query', 'engine', and 'results'.

Persist a key/value memory entry to disk for cross-session recall.

Each entry stores: key, value, category, tags, created_at, updated_at. Memory is kept in a JSON file and is safe to read concurrently.

Args: key: Unique identifier for the entry. value: Content to remember. category: Logical bucket for the entry. tags: Optional list of tags for retrieval filtering. overwrite: If False, fail when the key already exists.

Returns: str: JSON with keys 'success', 'key', 'category', 'tags', 'operation' ('created' or 'updated').

Load a single memory entry by key.

Args: key: Key of the memory entry to load.

Returns: str: JSON with keys 'success', 'key', and the full entry payload.

List memory entries, optionally filtered by category and/or tag.

Args: category: Only return entries in this category. tag: Only return entries carrying this tag. limit: Maximum number of entries to return.

Returns: str: JSON with keys 'success', 'count', and 'entries'.

Delete a single memory entry by key.

Args: key: Key of the memory entry to delete.

Returns: str: JSON with keys 'success', 'key', and 'deleted' (bool).

Search memory entries by substring or regex across key, value, and tags.

Args: query: Substring or regex to look for. use_regex: Treat the query as a regular expression. category: Restrict the search to a single category. limit: Maximum number of matches to return.

Returns: str: JSON with keys 'success', 'count', and 'matches'.

Discover and list skills available in the configured skills directory.

A skill is one of:

• <skills_dir>/<name>/main.py (or run.py) with a run(input, **kwargs) function

• <skills_dir>/<name>.py — Python skill

• <skills_dir>/<name>.sh — Shell skill

• <skills_dir>/<name>.md — Markdown skill (returns the file contents)

Args: skills_dir: Override the skills directory. pattern: Optional glob pattern to filter skill names.

Returns: str: JSON with keys 'success', 'skills_dir', 'count', and 'skills'.

Invoke a discovered skill by name and return its result.

Python skills are imported in-process and their run(input, **kwargs) function is called. Shell skills are executed via subprocess. Markdown skills simply return the file contents.

Args: name: Skill name. input: Primary input passed to the skill as the first argument. args: Additional keyword arguments forwarded to the skill. skills_dir: Override the skills directory. timeout: Maximum execution time in seconds.

Returns: str: JSON with keys 'success', 'name', 'type', 'stdout', 'stderr', 'exit_code', and 'timed_out'.