/ultan-search

name: ultan-search
description: Search and traverse the user's Ultan memory library (~/.agent-mem/knowledge/). Use whenever you see an Ultan wikilink in priming context (e.g. [[projects/foo/bar]]) and want to read it, OR when you want to find entries by topic. Accepts a wikilink/path (returns the entry plus directory context — siblings, subfolders, parent README) or a free-text query (returns top-K matches with snippets). Cheaper than multiple raw Read calls because it bundles content with the surrounding hierarchy in one shot. Use this in preference to Read for any path under ~/.agent-mem/knowledge/.

Ultan Search

Talks to the running `agent-mem-daemon` over its Unix socket and returns either a single entry (with browseable neighbours) or a ranked list of matches.

Usage

Invoke with **one argument** — the script auto-detects mode:

• **Wikilink or path** — `[[projects/agent-mem/concepts/README]]`, `projects/agent-mem/concepts/README`, `global/conventions/use-uv.md`, etc. → returns the entry's full content **plus** siblings, subfolders, and parent README excerpt so you can navigate to neighbours without a second call.
• **Free-text query** — `optimizer pruning`, `tier 3 interrupts`, `prefer python over javascript`, etc. → returns top-8 BM25-ranked entries with score + snippet.

Explicit prefixes win if auto-detection is wrong: `path:<x>` or `query:<x>`.

Running it

Run the `search.py` that sits in this skill's own directory (the directory containing this SKILL.md — shown in the skill listing):

python "<this-skill-dir>/search.py" "<wikilink-or-query>"

Use `Bash` to run this — the script writes the result as markdown to stdout. It is stdlib-only; any `python3` works.

When NOT to use this skill

• You want a **synthesised** answer fusing multiple entries — use `/ultan-advisor <question>` instead. The advisor runs Sonnet (deep search) + Opus (synthesis) to produce a single referenced answer; this skill is the raw-fetch primitive.
• The priming snippet you already received in `additionalContext` covers the question — don't drill down redundantly.
• You're trying to *write* to the library — use `/ultan <text>` or let the curator capture it from conversation; this skill is read-only.

Daemon dependency

This skill requires the agent-mem daemon to be running. If the socket isn't present at `${AGENT_MEM_HOME:-~/.agent-mem}/priming.sock`, the script prints a clear error. With the Ultan plugin installed the daemon lazy-starts on its own — retry after a turn or two; from source, start it with `uv run agent-mem-daemon -v`.