Culture Brain — العقل الثقافي الشخصي

A personal cultural intelligence for Movies, Jazz / Music and Video Games. Arabic-first conversation (Gulf dialect friendly), local-first data, provider-agnostic by design.

Culture Brain is not three trackers glued together. It is one system that learns one person's taste and context, discovers the relationships between everything they watch, listen to and play, and explains why it thinks something will be enjoyed — in Arabic.

              ┌──────────────────────────────────────────────┐
              │  Culture Brain   Taste · Context · Graph · AI │
              ├──────────────────────────────────────────────┤
              │  Personal Library  watched/played/rated      │
              ├──────────────────────────────────────────────┤
              │  Metadata Providers  TMDB · MusicBrainz ·     │
              │                      Discogs · IGDB · local   │
              ├──────────────────────────────────────────────┤
              │  Playback & Integrations  Spotify · Steam ·   │
              │                           Plex · Jellyfin     │
              └──────────────────────────────────────────────┘

Each layer only depends on the one below it, so replacing TMDB, Spotify or Steam means writing one adapter — never rebuilding the app.

Highlights

• Arabic-first chat that understands Gulf dialect and Arabic/English code-switching: «أبي فيلم noir الليلة بس ما يكون طويل» · «عطني jazz هادي وأنا قاعد أشتغل» · «شنو اللعبة اللي تنصحني أكملها من الـbacklog؟».
• Natural-language capture — «أمس شفت Heat، ممتاز، أعطيه 9 من 10. التصوير عجبني بس النهاية ما عجبتني.» updates the library, the taste profile, the context profile and the Culture Graph in one step.
• Taste Engine with confidence scores and evidence; nothing is ever a final fact.
• Context Engine for when and why: late-night jazz, weekend long films, short games when there is less than an hour. Only from what the user says or non-sensitive context.
• Culture Graph linking movies ↔ directors ↔ actors ↔ composers ↔ musicians ↔ albums ↔ genres ↔ games ↔ platforms ↔ eras ↔ moods — e.g. Miles Davis → John Coltrane → Cannonball Adderley → Bill Evans.
• Discovery slider: Safe ←→ Balanced ←→ Explore ←→ Wild, always with at least one intelligent reason.
• "ليش عجبني هذا؟" explanations built from the user's own history, with an explicit disclaimer that they are inferences.
• Memory timeline comparing taste across months and years.
• Local-first & private: SQLite on your machine; no network call unless you configure a provider explicitly. Never any DRM circumvention.
• Model of your choice: any OpenAI-compatible endpoint (OpenAI, Ollama, LM Studio, OpenRouter, vLLM…) is configured from الإعدادات → موديل الذكاء الاصطناعي, with a built-in connection test. With nothing configured, the deterministic Arabic engine answers entirely offline.

Quick start

npm ci                 # or: npm install
npm run build          # builds the server (dist/server) and the web app (dist/web)
npm run seed:demo      # optional: fill a realistic demo library (cinema + jazz + gaming)
npm start              # http://127.0.0.1:8787

# development
npm run dev:server     # API on :8787
npm run dev:web        # Vite dev server on :5173 (proxies /api)

Everything works with zero API keys: a curated offline catalog (jazz, cinema, games) keeps the product usable, and remote providers attach themselves when configured.

Copy .env.example to .env and fill only what you enable (TMDB, IGDB, MusicBrainz, Discogs, Spotify, Steam, Plex, Jellyfin, or any OpenAI-compatible LLM endpoint).

Scripts

Command	Purpose
npm run build	Build server + web into dist/
npm start	Serve API + built web app
npm test	Vitest suite (parsers, taste, graph, recommendations, HTTP API)
npm run typecheck	Strict TypeScript for server and web
npm run version:next	Show the next semantic version (dry run)
npm run version:bump -- --apply	Apply the version bump + changelog

Architecture

Detailed design lives in docs/ARCHITECTURE.md, the schema in docs/DATA-MODEL.md, the HTTP contract in docs/API.md and the delivery plan in docs/ROADMAP.md.

src/
  core/        taste · context · memory · graph · recommendation · Arabic NLP
  providers/   TMDB · MusicBrainz · Discogs · IGDB · offline local catalog
  integrations/Spotify · Steam · Plex · Jellyfin (isolated plugins)
  playback/    legal playback resolver with user-ordered preference
  server/      Fastify HTTP API
  web/         React + Vite dark "personal cultural library" UI (RTL)

CI/CD & versioning

Every change ships with a version bump whose size matches the size of the change, driven by Conventional Commits — see docs/VERSIONING.md.

• .forgejo/workflows/ci.yml — typecheck, tests, build on every pull request.
• .forgejo/workflows/release.yml — on every push to main: compute major|minor|patch, update package.json + CHANGELOG.md, tag vX.Y.Z, push, build the distribution tarball, publish a Forgejo release and prune old releases.

Commit	Bump
feat! / BREAKING CHANGE:	major
feat:	minor
fix:, perf:, docs:, chore:, …	patch

Privacy

Local-first by default. The SQLite database separates user library, AI memory, taste profile and graph/embeddings so each can be exported or deleted independently. No outbound request is made unless the corresponding provider or integration is explicitly configured.

License

MIT — see LICENSE.