second-brain AGENTS.md

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.