ultan-search

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.