Docs / Concepts

Scopes - org / user / project

Hydrate stores facts at three scope levels. Retrieval is the union across them, so a query in a specific project gets org-wide policy + your personal preferences + project-specific facts, all at once.

The three scopes

org (Enterprise) - policy that applies to everyone in your company. Examples: "team uses British English", "approved deps: react 18, tailwind 4, stripe", "deploys via promotion gate, never direct push".
user - your cross-project preferences. Examples: "prefers terse responses", "senior Go engineer, new to React", "avoid emojis in code comments".
project - specific to this codebase. Examples: "pricing tiers are Free / Pro / Team", "uses pnpm not npm", "docs live at /docs".

Retrieval

SELECT * FROM facts
 WHERE user_id = $1
   AND (scope = 'user'
        OR (scope = 'project' AND project_id = $2)
        OR (scope = 'org' AND org_id = $3))
   AND status = 'active'
 ORDER BY recency_score DESC

The union is the fallback semantics. There's no inheritance or override logic at retrieval - all three scopes are simultaneously in play, ranked by recency and strength.

Classification

Every extracted fact goes through a heuristic classifier before it's stored. Rules, in order:

org - mentions of "team", "our company", "org policy", or references to multiple users
project - "this project", "this codebase", "we're building", references to files in cwd
user - everything else

You can re-classify a fact manually:

hydrate facts promote fact_7f3a --to=user
hydrate facts promote fact_c482 --to=project

Isolation

Project scoping is what stops facts from one project contaminating another. Before scope hierarchy landed, Hydrate sometimes injected "dark mode is already implemented" from an old project into a new one - and the model believed it. This is now prevented at the database level.