Skip to content

CLAUDE.md

Latest commit

 

History

History
49 lines (36 loc) · 2.95 KB

CLAUDE.md

File metadata and controls

49 lines (36 loc) · 2.95 KB
Raw

CLAUDE.md — Agent Instructions for Open Brain

This file helps AI coding tools (Claude Code, Codex, Cursor, etc.) work effectively in this repo.

What This Repo Is

Open Brain is a persistent AI memory system — one database (Supabase + pgvector), one MCP protocol, any AI client. This repo contains the extensions, recipes, schemas, dashboards, integrations, and skills that the community builds on top of the core Open Brain setup.

License: FSL-1.1-MIT. No commercial derivative works. Keep this in mind when generating code or suggesting dependencies.

Repo Structure

extensions/     — Curated, ordered learning path (6 builds). Do NOT add without maintainer approval.
primitives/     — Reusable concept guides (must be referenced by 2+ extensions). Curated.
recipes/        — Standalone capability builds. Open for community contributions.
schemas/        — Database table extensions. Open.
dashboards/     — Frontend templates (Vercel/Netlify). Open.
integrations/   — MCP extensions, webhooks, capture sources. Open.
skills/         — Reusable AI client skills and prompt packs. Open.
docs/           — Setup guides, FAQ, companion prompts.
resources/      — Official companion files and packaged exports.

Every contribution lives in its own subfolder under the right category and must include README.md + metadata.json.

Guard Rails

  • Never modify the core thoughts table structure. Adding columns is fine; altering or dropping existing ones is not.
  • No credentials, API keys, or secrets in any file. Use environment variables.
  • No binary blobs over 1MB. No .exe, .dmg, .zip, .tar.gz.
  • No DROP TABLE, DROP DATABASE, TRUNCATE, or unqualified DELETE FROM in SQL files.
  • MCP servers must be remote (Supabase Edge Functions), not local. Never use claude_desktop_config.json, StdioServerTransport, or local Node.js servers. All extensions deploy as Edge Functions and connect via Claude Desktop's custom connectors UI (Settings → Connectors → Add custom connector → paste URL). See docs/01-getting-started.md Step 7 for the pattern.

PR Standards

  • Title format: [category] Short description (e.g., [recipes] Email history import via Gmail API, [skills] Panning for Gold standalone skill pack)
  • Branch convention: contrib/<github-username>/<short-description>
  • Commit prefixes: [category] matching the contribution type
  • Every PR must pass the automated review checks in .github/workflows/ob1-review.yml before human review
  • See CONTRIBUTING.md for the full review process, metadata.json template, and README requirements

Key Files

  • CONTRIBUTING.md — Source of truth for contribution rules, metadata format, and the review process
  • .github/workflows/ob1-review.yml — Automated PR review
  • .github/metadata.schema.json — JSON schema for metadata.json validation
  • .github/PULL_REQUEST_TEMPLATE.md — PR description template
  • LICENSE.md — FSL-1.1-MIT terms