SuperAPI AI Directory

lov-ataru-search

General & other

View repository

Updated 10-16 00:01

About this skill

lov-ataru-search — Recall context from local memory

Find past records relevant to the current question in the local existing AI session history, and return two directly usable things: ranked hits with stable identifiers (Project / Session / Message), and a passage of original text around a hit. Index construction and repair belong to lov-ataru-indexing。

Triggers

Activate when

  • "How did I fix this error last time?"
  • "Find the record where session recovery was discussed."
  • Help me recall what was decided about this module in an earlier session.

Do not activate when

  • The user wants to "rebuild the index" or asks "is the index broken" — leave it to lov-ataru-indexing。
  • The user wants to find a symbol or file in the current codebase — use ordinary grep and file search, that is code retrieval not session memory retrieval.

User Profile (cross-session)

skill.yaml Declaration user-profile/v1. At the start of each run, read the shared user, brand, workspace, preferences, and this Skill's skills.lov-ataru-search namespace.

There are two records worth keeping long-term:records.ataru_bin(the path to the Ataru executable available on this machine) and records.default_level(the user's preferred retrieval granularity). When the user directly states such values, use scripts/profile_store.py record to write them back and report the saved path. One-off inputs such as search terms and project IDs are not written to the Profile. For the full contract see references/user-profile.md。

Skill Group Composition

See references/skill-composition.md. This source is an independent Single Skill, and with lov-ataru-indexing there is only an artifact-level handoff (index status).

Workflow (MANDATORY)

You MUST follow these steps in order.

Step 0: Resolve the binary, then confirm the index

export SKILL_DIR="$HOME/.claude/skills/lov-ataru-search"
python3 "$SKILL_DIR/scripts/ataru_recall.py" index-status

The resolution order is --bin → ATARU_BIN → PATH → installed App bundle → local dev build found by searching upward from the current directory, running --versiononce on each candidate. Old versions below 0.41.3 do not recognize the index subcommand, and will treat it as a desktop launch parameteropening a windowand never return.

search itself will first confirm the index. When the index is not ready, it fails with ATARU_INDEX_NOT_READY or ATARU_INDEX_BUILDING and points to lov-ataru-indexing,will notreturn zero results— "not found" and "index not built" must be two distinguishable answers. This Skill does not build the index for the user.

Step 1: Choose the level before querying

level One hit represents When to use
turn A single message Default. To pinpoint a specific sentence, a specific error, or a specific decision
run One round of user request to answer To see the full context of one exchange
session An entire session To find "which session was discussing this"
project A project To find out which project this topic mainly occurred in
python3 "$SKILL_DIR/scripts/ataru_recall.py" search "会话恢复方案" --level turn --limit 10

When restricting to a project, use the equals form, because the project ID itself starts with a hyphen:

python3 "$SKILL_DIR/scripts/ataru_recall.py" search "索引没有更新" \
  --level session --project-id=-Users-me-projects-app

In a hit, projectId / sessionId / messageId / lineNumber is a stable identifier and can be fed directly to the next step.snippet is truncated to 600 characters by default; add --full。

Command-line retrieval only uses keyword mode:mode and requestedMode will both be keyword, semanticAvailable is usually false. Do not promise the user that the command line can get semantic or hybrid ranking, and do not assert "this is not in the history" just because keywords did not hit—try synonyms and a different level.

On a real corpus of tens of thousands of sessions, one turn-level retrieval takes on the order of tens of seconds. Do not lower it for the sake of "failing fast" --timeout。

Step 2: Read the original transcript around a hit

Ranking hits are only enough to locate, not enough to make a judgment. Once you have a candidate, read a passage of the original text around it:

python3 "$SKILL_DIR/scripts/ataru_recall.py" read \
  --project-id=-Users-me-projects-app \
  --session-id=<session uuid> \
  --around=<message uuid or line number> \
  --window 6

--window is the number of messages to keep on each side,--message-chars controls truncation of a single body (default 2000). When --around is not passed, return the last --window messages of the session. When the given --around cannot be found in that session, the script reports ATARU_MESSAGE_NOT_FOUND rather than silently returning some other position.

Step 3: Answer with citations, not with impressions

The answer must include things that can be traced back to the source: the session title, the timestamp, and when necessary the sessionId. Truncated body text must be stated as truncated. If retrieval does not hit, say it did not hit, and state which terms and which level were used — do not use speculation from the current context to fill in historical gaps.

Dependencies

  • Python 3.8+ (standard library only)
  • Ataru 0.41.3 or a newer version installed locally, with the index ready

General feedback loop

When a user raises revision feedback during a Skill-driven task, before continuing the current artifact you must execute:

  1. First determine whether the feedback is task-specific(this time only) or reusable(reusable across tasks).
  2. task-specific only modifies the current task, not the Skill.
  3. reusable first determine the scope: for domain rules, first update the corresponding canonical Skill; for rules that apply to all Skills, first update the shared specification.
  4. After completing the rule update, versioning, lint, and distribution verification, then apply the changes to the current task.
  5. reusable the modification invalidates previous "confirm," "continue," and "send it" responses; after completing the current artifact modification and reading it back, you must stop and wait for the user's next instruction, and must not automatically proceed to publishing, committing, or other external writes.