A personal second-brain application built with Phoenix 1.8 + LiveView. It stores your knowledge as typed pages (notes, concepts, entities, references, goals, plans, todos, queries, projects) and links them with relations, forming a queryable knowledge graph.

Includes a full markdown editor (TipTap WYSIWYG), three autonomous agents — curator, link_gardener, and graph_rag, an MCP endpoint for AI agent integration (with per-user token auth and context scoping), and a REST API.

SKILL.md — Agent operating manual for the Dran MCP server: tools, agent rules, page types, recipes, and pitfalls. If you're building an AI agent that connects to Dran via MCP, start there.

Dran is a networked knowledge base for a single human. It captures notes and structured knowledge, then connects them with semantic and explicit relations so you (and AI agents) can traverse, summarize, and answer questions against a live graph — not a pile of isolated files.

• 9 page types with type-specific metadata — note, concept, entity, reference, project, goal, plan, todo, query
• Markdown editor — TipTap WYSIWYG with bidirectional markdown, tables, code blocks, mermaid diagrams, and file embeds ![[slug]]
• Autonomous agents — background ReAct agents (curator, link_gardener) that plan, act, and log every step
• Knowledge graph — visual graph at /graph with pan/zoom and 3D view, built from explicit and semantic relations; every page detail surfaces a per-page subgraph
• Bidirectional semantic relations — PageAugmenter creates semantic links after every capture, with an adaptive cosine-distance threshold tunable in settings
• Multi-user auth with Google OAuth — per-user accounts, per-user API tokens, and context membership control
• Per-context page type disabling — restrict which page types are available in a given context
• Version history with diff — every edit saves the previous body to page_versions
• Activity feed — real-time log of all brain actions in a dedicated LiveView
• Hybrid search — unified search picks full-text, fuzzy, semantic or hybrid with RRF fusion and an optional PageRank authority boost
• Runtime settings — tune the brain without a redeploy via an admin-only /settings page organized in tabs
• MCP server — 18 tools for AI agents to search, read, create, update, delete, relate, lint, and manage the graph (see SKILL.md)
• Full context export — export an entire context (pages, relations, versions, uploads) as a JSON backup

• Elixir 1.15+ and OTP 26+ — managed via mise (see mise.toml)
• PostgreSQL 14+ (with pg_trgm, uuid-ossp, and pgvector extensions)
• Node.js 18+ (for asset building)

# 1. Clone and enter the project
git clone git@github.com:alvarolizama/dran.git
cd dran

# 2. Copy the env template and edit values
cp .env.example .env
$EDITOR .env    # set SECRET_KEY_BASE, admin credentials, etc.

# 3. Install deps, create the DB, run migrations, build assets, and seed
mix setup

mise auto-loads .env: If you use mise, the .env file is loaded automatically via mise.toml (_.file = ".env"). No need to source .env manually. Otherwise use direnv allow or export the vars in your shell.

mix setup runs: mix deps.get → mix ecto.create → mix ecto.migrate → mix assets.setup → mix assets.build → mix seed (creates the default context from DRAN_CONTEXT_SLUG / DRAN_CONTEXT_NAME).

mix phx.server

Visit localhost:4000. You'll be redirected to login.

Dran supports two ways to log in: Google OAuth (recommended) and legacy credentials.

Every user is a row in the users table with email, name, google_id, avatar_url, is_admin, and a single api_token. A user can access only the contexts assigned to them (via the user_contexts join table). Admins can access everything and are the only role that sees Settings.

On a fresh install (empty users table), any visit redirects to /setup, which asks for an email + password and creates the initial admin account. Once a user exists, /setup closes itself and normal login takes over. There are no env-var web credentials — users are managed in Settings → Users.

Google login appears on the login page only when GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET are set. On first login a user is auto-created only if their email domain is in GOOGLE_OAUTH_ALLOWED_DOMAINS (fail-closed). Admin promotion is manual (Settings → Users).

The legacy DRAN_API_TOKEN is treated as an admin token (full access) and continues to work for MCP/REST.

Each user has one api_token (shown/managed in Settings → Users) used for the API and MCP. A token grants access only to the contexts assigned to that user:

• MCP returns 401 for an invalid/missing token, and 403 when a user's token tries to access a context they're not assigned to.
• Set context on a request to target a specific context; otherwise it falls back to the user's first assigned context.

See .env.example for the full annotated list. Key variables:

* Web login is created via the first-run /setup flow (no env credentials). DRAN_API_TOKEN is only needed for API/MCP access without per-user tokens. Never use the dev default (dran-token) in production.

Dran is designed to run in multiple network configurations simultaneously:

Why BUILD-time for force_ssl? Phoenix's force_ssl is compile-time (marked via compile_env). Runtime config cannot toggle it — it must be baked into the release. This is why the Dockerfile has ARG DISABLE_FORCE_SSL and config/prod.exs checks the env var at build time.

Database SSL: Managed databases (AlloyDB, Cloud SQL) require SSL but use self-signed certificates. Dran defaults to ssl: true with verify: :verify_none (encrypted but not verified). Set ECTO_SSL=false for local dev or ECTO_SSL_VERIFY=true for strict verification against the system CA bundle.

Session cookies: In production, SESSION_SIGNING_SALT and SESSION_ENCRYPTION_SALT are required — the app refuses to boot without them. Generate with mix phx.gen.secret 32. SESSION_COOKIE_SECURE=true forces HTTPS-only cookies.

Google OAuth + VPN: When running over VPN without HTTPS, set GOOGLE_OAUTH_REDIRECT_URI explicitly to your public HTTPS URL. Google requires HTTPS redirect URIs (except localhost). Example: GOOGLE_OAUTH_REDIRECT_URI=https://dran.example.com/auth/google/callback.

Dran can talk to an OpenAI-compatible inference server to add embeddings, reranking, and chat to the second brain.

How it's used: unified/semantic search (embeddings in pgvector), reranking of candidates, and automatic semantic relations (PageAugmenter). The models are selectable per-purpose at runtime in Settings → Models. The current local server typically exposes Qwen3-Embedding, Qwen3-Reranker, and a chat model — verify at runtime with GET /v1/models.

Only admins see Settings (/settings, and /settings/:tab). It's organized in tabs:

Context CRUD and user/context membership management all live in Settings now — there is no standalone /contexts page.

Each context can disable any subset of page types via contexts.disabled_page_types (an array). Disabling a type:

• Hides it from the web sidebar (no kanban/todos/projects/goals/plans/notes/concepts/entities/references links for that type)
• Excludes it from list_pages on the MCP server
• Rejects creation via web or MCP with the error page type 'X' is disabled in context 'Y'

Manage disabling in Settings → Contexts → "Page types" modal per context.

Every piece of knowledge is a page with a page_type. Some types have a kind sub-type (in meta.kind):

Page links use three independent, orthogonal meta slugs — meta.project_slug, meta.goal_slug, meta.plan_slug — each optionally materializing its own part_of relation. There is no rigid hierarchy; every page is an orphan by default.

Pages track who created and owns them; todos carry an assignee (free-form string, e.g. alvaro for a human, hermes for an agent) so you can delegate between humans and AI agents. Filter in the kanban or via dran_list_pages with assignee ("none" for unassigned).

• ![[slug]] — embed a file (renders as image/video/audio/PDF)
• ![[slug|Alt Text]] — embed with alt text

Embeds auto-create embeds relations. Plain [[slug]] wikilinks are no longer supported — link pages explicitly with dran_create_relation or let PageAugmenter create semantic relations.

Relations are directed (source → target) and typed:

• related — generic connection (create manually)
• part_of — hierarchy (A is part of B)
• supersedes — replacement (A replaces/obsoletes B)
• contradicts — conflict (A contradicts B)
• embeds — source embeds target (auto-created from ![[slug]])
• semantic — auto-created by PageAugmenter when pages are semantically similar

For explicit typed relations, use the MCP dran_create_relation tool or POST /api/relations.

Dran can delegate longer tasks to autonomous ReAct agents. There are three agent types:

• Start a session with dran_start_agent and poll with dran_get_agent_session.
• Agents run asynchronously, persist every step, and broadcast live updates to the UI.

Quantum scheduled crons: curator_daily (daily 06:00) runs the curator agent on the default context; pagerank_nightly (daily 03:00) recomputes weighted PageRank and detects communities via Label Propagation (persisted to meta.pagerank / meta.community_id); community_summaries_nightly (daily 03:30) generates LLM summaries for each detected community.

Dran exposes an MCP (Model Context Protocol) endpoint at POST /api/mcp using the Streamable HTTP transport (MCP spec 2025-03-26). This lets any MCP-compatible client — Claude Desktop, Hermes Agent, custom scripts — use Dran as a knowledge tool.

The server returns an mcp-session-id header on initialize; include it in subsequent requests of the same session.

{
  "mcpServers": {
    "dran": {
      "url": "http://localhost:4000/api/mcp",
      "headers": { "Authorization": "Bearer <your-api-token>" }
    }
  }
}

curl -X POST http://localhost:4000/api/mcp \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

For the full operational guide — all tools, resources, prompts, recipes, and pitfalls — see SKILL.md. The available MCP tools are:

dran_search · dran_get_page · dran_list_pages · dran_get_links · dran_create_page · dran_update_page · dran_delete_page · dran_create_todo · dran_update_todo · dran_create_relation · dran_delete_relation · dran_rename_slug · dran_reaugment_page · dran_get_stats · dran_lint_brain · dran_start_agent · dran_get_agent_session

All API endpoints require a bearer token: Authorization: Bearer <user-api-token>. Scoped to the user's assigned contexts (pass ?context=<slug>). Notable routes:

mix ecto.create    # create the database
mix ecto.migrate   # run migrations
mix seed           # create the default context (idempotent)
mix ecto.reset     # drop + create + migrate + seed (destructive)

Dran ships as a standard Elixir release with helpers in rel/overlays/bin/:

Build with:

mix local.hex --force && mix local.rebar --force
MIX_ENV=prod mix deps.get --only prod
MIX_ENV=prod mix compile
MIX_ENV=prod mix assets.deploy
MIX_ENV=prod mix release

The release lives in _build/prod/rel/dran/ and is self-contained — copy it to the target machine or build a container image. The repo also ships a multi-stage Dockerfile (with an entrypoint that runs pending migrations before boot). Coolify/Railpack/Nixpacks auto-detect the Elixir app; set the env vars above (Runtime env vars only — never bake secrets into a Dockerfile) and start command bin/server.

Platform env vars: See the main env vars table above — PHX_PORT, PHX_SCHEME, UPLOADS_DIR, UPLOADS_MAX_SIZE, ECTO_IPV6, DNS_CLUSTER_QUERY, DISABLE_FORCE_SSL (build-time). Runtime env vars only — never bake secrets into a Dockerfile.

curl -fsSL https://dran.example.com/health

• Phoenix 1.8 with LiveView
• TipTap v3 markdown editor with @tiptap/markdown for bidirectional markdown
• MDEx (comrak) for server-side markdown rendering with GFM + sanitization
• MCP (Model Context Protocol) for AI agent integration
• Quantum (~> 3.5) — cron scheduler for the curator (daily), pagerank_nightly (03:00), and community_summaries_nightly (03:30) jobs
• Tailwind CSS v4 + daisyUI for styling

Before committing, always run:

mix precommit

This runs compile --warnings-as-errors, deps.unlock --unused, format, and test. Fix any issues it reports before pushing.

MIT