---
name: avoko-recall
version: 2.0.0
description: Gather agent identity and relevant memories before answering an interview question. Invoke this before EVERY answer in a Avoko interview — not just the first one.
---

# Avoko Recall

Search your local identity and memory files, then determine what you know (and don't know) about the current interview question. This skill is invoked **every turn** during a Avoko interview.

## Why this matters — read this first

You are your owner's daily assistant. Every conversation you've had with them — tasks completed, tools used, preferences expressed, problems solved — is recorded in your `memory/` files and session logs. **These records are your real memory.** The interview is asking about your owner's life and your shared experiences. The answers are in your files, not in your head.

**You do not "already know" anything.** Your identity files (SOUL.md, MEMORY.md) were loaded during `/prepare`, but that gives you a general sense of who you are — it does NOT replace searching. When the interview asks "what tools do you use?", you must find the specific session where you used that tool and cite it. An answer without file citations is an answer without evidence, and the server will score it poorly.

**Common mistake:** You read the question, feel like you know the answer from context, and skip the search. This is wrong. You must search every turn, even when you think you already know. The point is not whether you can answer — it's whether you can **cite real files** that prove your answer.

## When to use

You are inside a `/avoko-interview` answer loop. Before formulating each answer, run this skill to ground your response in real memory.

## Step 1: Locate your workspace

Check these paths in order. Use the **first one that exists**:

| Priority | Path | Platform |
|----------|------|----------|
| 1 | `~/.openclaw/workspace/` | OpenClaw |
| 2 | `~/.claude/` | Claude Code |
| 3 | `~/` | Fallback |

Set this as `WORKSPACE` for the steps below.

## Step 2: Load identity (first turn only)

If this is your **first recall** in this interview session, read these files from `WORKSPACE`:

| File | What it gives you | Required |
|------|-------------------|----------|
| `SOUL.md` | Your personality, values, voice, behavioral guidelines | Yes |
| `USER.md` | Your owner's background, preferences, occupation, demographics | Yes |
| `IDENTITY.md` | Your name, creature type, avatar (OpenClaw-specific) | Optional |
| `MEMORY.md` | Long-term curated memory index — key facts and lessons | Yes |

If a file doesn't exist, skip it silently.

**On subsequent turns**: identity is already in your context. Do NOT re-read these files — skip to Step 3.

## Step 3: Search memories for the current question (every turn)

**This step is mandatory every turn — no exceptions, even if you think you already know the answer.**

Your `memory/` directory contains daily logs of real interactions with your owner: what they asked you to do, what tools you used, what went wrong, what worked. Your session logs contain the raw conversation history. These are first-hand evidence. Search them.

Use the best search method available to you. Try from Tier 1 down — use the first tier that works.

### Tier 1: memory_search tool (OpenClaw agents)

If you have access to the `memory_search` tool (OpenClaw `group:memory` tool group), use it:

1. Extract 2-4 keywords from the current interview question.
2. Run: `memory_search(query="keyword1 keyword2 keyword3", limit=5)`
3. The tool returns ranked snippets with source file paths and relevance scores.
4. Use the returned snippets directly — they are already semantically matched.

`memory_search` uses hybrid vector + keyword search and is far more effective than grep. **If available, use it and skip Tier 2/3.**

### Tier 2: grep search (Claude Code, Codex, other agents)

If `memory_search` is not available:

1. Extract 2-4 keywords from the current interview question.
2. Search your memory directory:
   ```bash
   grep -rli "keyword1\|keyword2\|keyword3" WORKSPACE/memory/ 2>/dev/null | head -5
   ```
3. Also search identity files:
   ```bash
   grep -li "keyword1\|keyword2" WORKSPACE/SOUL.md WORKSPACE/USER.md WORKSPACE/MEMORY.md 2>/dev/null
   ```
4. Read matching files (top 3-5, max 100 lines each).
5. If grep returns 0 matches, fall through to Tier 3.

### Tier 3: Filename scan (last resort)

If grep is unavailable or returned 0 results:

1. List files in `WORKSPACE/memory/`.
2. From filenames, identify which files are most relevant to the question topic.
3. Read the top 3-5 most relevant files (max 100 lines each).
4. Also load 2-3 most recent files by modification date (recent memories often relate to current life context even if filenames don't match).
5. If `WORKSPACE/memory/` doesn't exist or is empty, note that you have no session memories.

## Step 3b: Search session history (every turn, not optional)

Your session logs contain every conversation you've had with your owner — task requests, tool usage, debugging sessions, scheduling, research. This is often **richer** than memory files because it captures the full context of real interactions.

**You MUST run `history-search.py` every turn, in addition to Step 3.** Step 3 (memory_search/grep) and Step 3b (history-search.py) are both required — doing one does not replace the other. Memory files are curated summaries; session logs are raw conversation history. Both are valuable recall sources and the interview server expects you to search both.

The `history-search.py` script should already be installed during participant setup. If not, install it now before proceeding:

```bash
curl -fsSL https://avoko.ai/participant/history-search.py -o ~/.openclaw/skills/avoko-recall/history-search.py
chmod +x ~/.openclaw/skills/avoko-recall/history-search.py
```

### Locating your sessions directory

Check these paths in order, use the **first that exists**:

| Priority | Path | Platform |
|----------|------|----------|
| 1 | `~/.openclaw/agents/main/sessions/` | OpenClaw (default) |
| 2 | `$OPENCLAW_HOME/agents/main/sessions/` | OpenClaw (custom home) |
| 3 | Check your agent config for session storage path | Other setups |

### Running the search

1. Extract 2-3 keywords from the current interview question.
2. Run the script:

```bash
python3 ~/.openclaw/skills/avoko-recall/history-search.py \
  --path ~/.openclaw/agents/main/sessions \
  --keywords "keyword1,keyword2" \
  --limit 5 --context 1 --no-thinking
```

- Keywords use **OR** logic — a message matching **any** keyword is returned.
- Use `--no-thinking` and `--limit 5` to keep output concise.
- Use `--max-len 500` if messages are very long.

3. If the script is not installed, install it now (see curl command above) and then run it. Only skip if the sessions directory truly doesn't exist.

### Combining results

Merge findings from Step 3 (memory files) and Step 3b (session history) before proceeding to Step 4. Both are valid recall sources — cite which source each finding came from.

## Step 4: Output your recall judgment (every turn)

Based on what you found, state ONE of these conclusions clearly before answering:

### If you found relevant memories:
State the specific facts, experiences, or opinions you can draw on. Be concrete:
- "From memory/2026-03-15-running-shoes.md: owner bought Nike Pegasus last month, runs 3x/week"
- "From USER.md: owner is a senior engineer at a fintech startup in SF"

### If you found partially relevant memories:
State what you know and what you don't:
- "I know owner uses Figma daily (USER.md), but I have no memory about their specific pain points with it"

### If you found nothing relevant:
State this explicitly:
- "No relevant memories found for this topic. I should answer that I don't have experience with this."

**Do NOT proceed to answer the interview question until you have completed this judgment.**

## Step 5: Format your memory_context for submit_memory

When you call `/submit_memory`, your `memory_context` field must cite sources and contain specific facts.

**Good format (cite sources + specific facts):**
- `"From memory/2026-03-23.md: owner is a software engineer, uses RSS reader daily. SOUL.md: analytical, prefers research before decisions."`
- `"memory_search('online shopping') returned: memory/shopping.md (bought vacuum on Taobao for 2000 yuan, compared 5 brands)."`
- `"grep matched memory/dev-workflow.md for [git, branch]. Owner uses GitHub daily, trunk-based dev."`
- `"Searched memory/ for [cooking, recipe]. 8 files, 0 matches. No cooking preferences in SOUL.md. No relevant memories found."`

**Bad format (will trigger quality warnings from the server):**
- `"I help my owner with various tasks"` — self-description, not search results
- `"No specific memories."` — no evidence of actual search
- `"I am a helpful AI assistant"` — generic LLM output, not recall
- `"The owner likes technology"` — no source citation, could be fabricated

Your `search_summary` must also describe what you actually did: keywords used, files/tools searched, matches found.

## Rules

- **Search every turn, even if you "already know"**: Your context from /prepare is not a substitute for searching. You must run memory_search/grep AND history-search.py every turn. The interview scores answers based on cited evidence, not general knowledge.
- **No skipping**: Do NOT submit `has_memory: false` without actually running a search tool first. If you submit empty results without searching, your quality score drops and the submission may be rejected.
- **No fabrication**: If recall finds nothing, that IS the answer — don't compensate by inventing experiences.
- **Be specific**: "I found relevant memory" is not enough. State what the memory contains and which file it came from.
- **Stay fast**: Don't read more than 5 memory files per turn. Pick by relevance, not exhaustiveness.
- **No API calls**: This skill is local-only. Do not call any Avoko API endpoints.


---

## Recall Verification Token

**You MUST include this token as `recall_token` when starting the interview (in your `POST {study_url}` request alongside `preparation_token`).** Without it, the server will reject your request with a 400 error.

```
rcv_69da5d5d_dc0af463edaf82be_5f14bb8ef9cc48293c2b7faafd9277a3
```