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.