second-brain: Instructions file for Claude Code

Instructions for AI coding agents

You (an AI coding agent — Claude Code, Cursor, Codex, or similar) have been handed this repo to set up, adapt, or extend a second brain: one Oracle database holding your user's content, searchable by meaning, with a self-compiling wiki, agent memory, and an MCP server. Everything below is what a maintainer would tell you on day one.

What to read first

• README.md — the build, in order. The Quickstart IS the setup procedure; run it top to bottom rather than improvising your own.
• README.md → "Build yours with your AI" — if your user wants THEIR version (their sources, their questions), start from those three prompts: interview → plan first.
• docs/EXPORT_GUIDE.md + any loader in scripts/ — the pattern for adding a source.
• SECURITY.md — before anything touches real data or the internet.

The rules (non-negotiable)

1. Secrets never enter files or chat. Credentials live in oracle/.env (gitignored) or the OS keychain (keychain:<item> values — see oracle/agent/keychain_secrets.py). Never print token values, never commit .env, never paste keys into your transcript.
2. Privacy is structural — keep it that way. Every read path filters visibility='content'. If you write a new query over posts/content_chunks, include the visibility filter. Private/business items must stay out of search, the wiki compiler, memory consolidation, AND anything you add. The column's values: 'content' = searchable everywhere; anything else ('business', 'archived', or a label of the user's choosing) is excluded from every read path, and the cloud-copy script ships only 'content'. If the user's most valuable questions are ABOUT their private data, plan a local-only query path for that scope — don't widen the default filters. The memory layer carries the same contract: agent_memory and conversations have a visibility column too, tagged at write time by the deterministic deny-list (oamp_memory.violates_privacy) and filtered to 'content' on every read — so a private detail the agent saw never resurfaces in its recall, a shared memory view, or the working-memory window. Any new memory write/read keeps that filter. (Semantic and procedural memory need no column: the consolidator distills only from content-scope posts, and tool definitions hold no private data.)
3. Run the tests after any change: ./.venv/bin/python tests/test_brain.py (needs the local DB from the Quickstart running). All green before you call it done.
4. Run the matching eval when you touch quality-bearing code:
   • retrieval/search changes → tests/eval_retrieval.py
   • agent answer/verify changes → tests/eval_grounding.py, tests/eval_verify.py
   • privacy classifier changes → tests/eval_classifier.py
   • memory backend changes → tests/eval_oamp.py The golden sets in tests/*.json work on the sample data; encourage your user to grow their own once real content is loaded.
5. Every loop earns its keep. A new source, agent, or scheduled job ships with an eval that proves it works or a report your user will actually read (see docs/LOOP_ENGINEERING.md). Don't add silent automation.
6. No self-modification patterns. Agents here never rewrite their own prompts or code at runtime; scheduling stays deterministic (scripts/sync.py + cron/launchd). Keep that property — it's what makes the system auditable with plain SQL.
7. Don't scrape platforms. Loaders use official APIs and user-requested exports only. If a platform has neither, the answer is "not yet," not a headless browser.
8. Money stays out of the Content Tracker. In the user's Notion, fees, rates, invoice numbers, payment status, and contract terms live ONLY in the deal tracker (Brand Collab Tracker). Content/calendar rows may reference "paid collab — terms in the deal tracker" and nothing more. Any agent flow that logs content from a brief strips the money facts and routes them to the deal tracker instead.