Dran

Dran — Tibetan for "remember". What one agent learns, none forget.

Shared memory & knowledge base for AI agents

The knowledge base and the memory your personal AI assistants share: one instance holding both the knowledge (a typed wiki graph) and the memory (trust-scored facts) that your agents read and write over the REST API or the Hermes plugin, and you browse as a wiki in the browser. You run it yourself, next to them.

• Knowledge — a typed graph of pages joined by typed relations. Four built-in page types (note, entity, concept, reference) plus custom types the instance declares; 13 relation types. TipTap markdown editor (tables, code blocks, mermaid, ![[slug]] embeds of your own pages, YouTube/Vimeo/map embeds) with version history and diff view. Hybrid search: full-text, fuzzy and semantic, fused.
• Memory — atomic facts with trust scores, deduplicated per owner: a re-stored fact returns the existing row; a near-duplicate (cosine 0.88–0.95) returns 409, never a silent merge. Feedback is asymmetric (+0.05 helpful / −0.10 unhelpful) and untouched facts decay. Facts auto-link to their closest pages at ingest.
• Work — goals (the WHAT, progress derived from their tasks), tasks (the board), plans (the HOW, an ordered checklist). The same rows whether your agent creates them by tool or you move them in the UI. dran_capture drops a quick task into your inbox goal.
• Services (your own apps) — connect your Gmail, calendar, GitHub, Slack… at /services; your agent runs them through 5 fixed tools. The tool catalog travels as data, and a service outside the owner's allowlist cannot even be listed.
• Automation — 3 background workers (curator, link_gardener, graph_rag) and 7 scheduled jobs, toggleable and runnable on demand.
• Visibility — every page, memory, collection, report, goal and plan is private (default), public, or shared with users and groups. A token reads exactly what its owner reads.

In the browser: wiki at /, goals /goals, board /tasks, plans /plans, memory /memory, 3D graph /graph, clusters /clusters, collections /collections, reports, /search, /activity, /journey, your connected apps /services, the skills the instance serves /skills; your account at /settings/account, the instance at /admin.

Requirements: Elixir 1.20+ / OTP 29, PostgreSQL 14+ with pgvector.

git clone git@github.com:alvarolizama/dran.git && cd dran
cp .env.example .env && $EDITOR .env     # SECRET_KEY_BASE, DATABASE_URL, BOTH salts
mix setup
mix phx.server                           # http://localhost:4000

First run redirects to /setup — whoever arrives first claims the instance as owner. Your API token lives in Settings → Account. Against a local Postgres without TLS, pass ECTO_SSL=false.

mix precommit closes the loop: compile --warnings-as-errors → deps.unlock --unused → format → deps.audit → sobelow → test.

Gives an agent the tools (dran_*, 46) and the memory provider (dran_memory_*, 4) — 50 in total, one token, one attribution, its owner's reach.

1. Token — copy your API token (Settings → Account) into the profile's .env as DRAN_API_KEY.

2. Install — symlink and enable:

   ln -sfn /path/to/dran/hermes_plugin/dran ~/.hermes/profiles/<profile>/plugins/dran

   # ~/.hermes/profiles/<profile>/config.yaml
   plugins:
     enabled:
       - dran
   memory:
     provider: dran

3. Configure — two surfaces that do not overlap: the plugin's card (Capabilities → Plugins → Dran → gear: instance, write destination, memory switch, 7 tool toggles, the two services budgets) and the memory panel (Settings → Memory & Context: only the recall knobs, writing $HERMES_HOME/dran/config.json). Per key, the JSON wins over the card. Restart the session and verify: ask it to "list my pages" (tools) and "what do you remember about…" (memory). The service timeouts are a ladder across both sides — the client's cap must stay above the instance's DRAN_COMPOSIO_* budgets; see Presupuestos de servicios.

Full detail: hermes_plugin/dran/README.md.

Nine skills are versioned with this repo: the loader router and the eight flows. They ship with the plugin — the files live in hermes_plugin/dran/skills/<slug>/SKILL.md and the plugin registers them locally (dran:loader, dran:knowledge-flow, …). An agent reads them with skill_view, with no network.

Dran serves only the workspace's skills. The nine suite slugs are reserved there (creating one is a 422), so nothing can shadow or duplicate them.

The prompt block points at both halves: the workspace catalog (a line per skill, q= search, bodies through dran_skills / dran_skill) and the suite, which the agent reads locally with skill_view("dran:loader").

Details: skills/README.md.

No soul.md line is needed: the block above already tells the agent that the suite exists and how to read it. Keep a line only in a profile where the block cannot warm at all — no memory.provider: dran, so nothing fetches the index at session start (see hermes_plugin/dran/README.md):

- **Dran skills** — before a task that may match a skill, list the workspace
  catalog with `dran_skills` (pass `q=` to search slug, name and description) and
  load the one that applies with `dran_skill`. The suite (`dran:loader` + the
  eight flows) ships with the plugin: read it locally with `skill_view`. The five
  tools are DEFERRED — reach them through `tool_search` with an English query.

One credential, no per-agent keys: the account's API token (Settings → Account), stored in the profile's .env as DRAN_API_KEY — the tools and the memory provider share it, and writes carry X-Hermes-Agent (the profile name).

Every variable, comment and safe default is in .env.example. Required in production: DATABASE_URL, SECRET_KEY_BASE, PHX_HOST, SESSION_SIGNING_SALT, SESSION_ENCRYPTION_SALT (the two salts must differ).

The ones that are Dran's:

Credentials are not env vars: account tokens in /settings/account, group tokens in /admin/groups, the legacy admin token in instance settings.

docker build -t dran .
docker run --rm -p 4000:4000 --env-file .env dran

• The container migrates before serving; a failed migration aborts the boot.
• The healthcheck is GET /health (touches no database) — point the proxy there, never at / (which redirects to /login).
• No account is seeded: the first visitor claims the instance at /setup — claim it right after the first deploy.
• force_ssl is compile-time: behind a VPN without TLS, build with --build-arg DISABLE_FORCE_SSL=1 and run with PHX_SCHEME=http.
• Mount a persistent volume at UPLOADS_DIR.
• DRAN_RESET=1 is destructive (drops the whole schema) and runs on every container start while set — unset it after the first boot.

• hermes_plugin/dran/README.md — the plugin: tools, config, and the surfaces it switches
• skills/README.md — the nine skills and how the plugin delivers them
• DESIGN.md — the UI standard

Released under the MIT License — Copyright (c) 2026 Álvaro Lizama. Covers the whole repository: the Elixir/Phoenix server, the Hermes plugin and the agent skills.