OpenParable
Skip to content
← Back to skills

Yopedia

Productivity
yopedia

Yopedia is an Agent Skill for productivity published in the yologdev/yoyo-evolve repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Save research and reflections into (and recall from) your personal knowledge vault (yopedia) — your second brain

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/yologdev/yoyo-evolve/blob/HEAD/skills/yopedia/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/yopedia, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Yopedia — your second brain

Yopedia (https://yopedia.yolog.dev) is your personal, persistent knowledge vault. Use it to save what you learn (so it doesn't evaporate after a session) and to recall what you already know (so you build on yourself instead of re-treading the same ground).

Setup (from env)

BASE=https://yopedia.yolog.dev
AGENT_ID="${YOPEDIA_AGENT_TOKEN%%.*}"     # the token text before the dot, e.g. alice--yoyo
VAULT="$YOPEDIA_VAULT_ID"        # which vault to file into — passed on every ingest

If $YOPEDIA_AGENT_TOKEN or $YOPEDIA_VAULT_ID is unset, your second brain isn't wired up yet — skip ingestion/recall silently and carry on. A yopedia call must never fail your actual work.

Recall FIRST

Before researching a topic, check what you already know and build on it. Lead with keyword search — it's your workhorse and needs no auth header (it still uses your agent-id, so the Setup skip-guard applies). Recall is agent-scoped, so it spans all your vaults (an evolve session recalls your dream-research notes too).

# 1. Keyword search (no auth) — YOUR MAIN RECALL.
#    Matches your term against note titles + bodies (stemmed word-family, NOT semantic),
#    so search the REAL terms of your topic — names, features, concepts — and try a
#    couple of phrasings if the first comes back empty:
curl -sS "$BASE/api/wiki/search?q=<keyword>&scope=agent:$AGENT_ID"

# 2. Whole index (no auth) — scan every note title you have, to see what's there at all:
curl -sS "$BASE/api/agents/$AGENT_ID/context"

# 3. Natural-language question (NEEDS your agent token) — a synthesized answer, not a list.
#    /api/query is authenticated; send the same token you ingest with. (Unconfirmed that the
#    Bearer token fully satisfies its gate — it rejected an unauthenticated call. If #3 errors,
#    just fall back to #1/#2.) Use when you want a digested answer rather than raw matches:
curl -sS -X POST "$BASE/api/query" \
  -H "Authorization: Bearer $YOPEDIA_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d "{\"question\":\"What have I learned about <topic>?\",\"scope\":\"agent:$AGENT_ID\"}"

Ingest a source (whenever something genuinely informs you)

Ingest is fire-and-forget: the POST is queued and processed in the background, so it returns almost immediately. Don't wait for or parse a slug — just fire it and move on. (A non-2xx response means it failed; log it and skip.)

From a URL (no quoting worries — inline is fine):

curl -sS -X POST "$BASE/api/agents/$AGENT_ID/ingest" \
  -H "Authorization: Bearer $YOPEDIA_AGENT_TOKEN" -H "Content-Type: application/json" \
  -d "{\"url\":\"https://example.com/paper\",\"vaultId\":\"$VAULT\"}"
# → {queued: true, jobId} (queued; processed in the background — no slug to wait on)

From your own notes — build the JSON with python3 (text has quotes/newlines; hand-concatenated JSON breaks → 400):

python3 -c "import json,os,datetime; print(json.dumps({
  'title': 'Proprioception in software systems — ' + datetime.date.today().isoformat(),
  'text':  'What it said, why it matters, and the source URL(s).',
  'vaultId': os.environ['YOPEDIA_VAULT_ID']}))" \
| curl -sS -X POST "$BASE/api/agents/$AGENT_ID/ingest" \
    -H "Authorization: Bearer $YOPEDIA_AGENT_TOKEN" -H "Content-Type: application/json" --data @-

Ingest a report (a synthesis worth keeping)

Same python3→curl pattern, with a dated report title:

python3 -c "import json,os,datetime; print(json.dumps({
  'title': 'Research — <topic> (' + datetime.date.today().isoformat() + ')',
  'text':  '<what I explored / key findings / open questions / sources>',
  'vaultId': os.environ['YOPEDIA_VAULT_ID']}))" \
| curl -sS -X POST "$BASE/api/agents/$AGENT_ID/ingest" \
    -H "Authorization: Bearer $YOPEDIA_AGENT_TOKEN" -H "Content-Type: application/json" --data @-

Rules

  • Recall before you research; ingest after you learn. That's the loop.
  • Recall is keyword search, not semantic — search the literal terms of your topic (names, features, concepts), and try a couple of phrasings before concluding you know nothing.
  • Give every note a clear, dated title — recall and dedup work better.
  • Re-posting is safe — the server dedups when it processes the queue (the immediate response won't include a dedup flag).
  • Ingest is async/fire-and-forget: a note you save this cycle becomes recallable once the queue processes it (usually by your next cycle), not the instant you POST it.
  • Always build text/report bodies with python3 -c (quotes/newlines break naive strings).
  • Your notes are private agent-knowledge; the vault is your organizing lens.
  • Never fail your task over yopedia. If a key is unset or a call errors, log it and move on. Responses: 2xx → {queued:true, jobId} (queued for background processing) · 401 bad/missing token · 403 token is for another agent · 400 no url/text/vault · 500 retry.