Frequently asked questions
Tier isolation and how HUPI actually works.
Straight answers, verified against the code — not the original aspirational design.
General
What is HUPI?
A memory layer that sits between you and any AI language model. Normally an AI’s memory resets the moment your conversation ends. HUPI durably records every conversation, distills it into searchable, fact-checked summaries overnight, and automatically re-injects relevant facts into future conversations — with any AI vendor, not just one.
Is HUPI open source?
Tiers 1 and 2 — the gateway, retrieval, consolidation, encryption, admin tooling, everything most people run — yes, MIT licensed, free forever. The full source, including the schema migrations and every doc referenced on this page, is on GitHub. Tier 3 (team/shared-workspace support) is a separate, commercially-licensed extension — see "Is Tier 3 free too?" below.
What LLM providers does it support?
Any OpenAI-API-compatible provider (OpenAI, Azure OpenAI, Groq, OpenRouter, local Ollama/vLLM) through one adapter, plus a dedicated adapter for Anthropic’s native API. Memory is stored as plain decrypted text and metadata, not tied to any one vendor’s format — switching providers is a config change, not a re-index.
How is this different from a vendor’s built-in memory feature?
It runs on your own infrastructure and your own Postgres, works with any vendor rather than locking you into one, fact-checks every memory against its source before trusting it (see "What is grounding?" below), and gives you an actual audit trail — for any past response, you can ask exactly what was remembered and from where, and get a real answer instead of a guess.
Can I use HUPI directly inside my editor?
Yes, two ways. The HUPI VS Code extension gives you a chat sidebar, inline edit, @hupi in VS Code's own Chat view, and inline completions, all backed by your own gateway — install it today on Windows, macOS, or Linux. For a more built-in experience, HUPI Code is a HUPI-native fork of VS Code with that same experience bundled in from first launch, no install step — signed/notarized macOS and Linux downloads are already live, Windows ships through the Microsoft Store. As far as we're aware, no other memory product on the comparison page puts itself this directly inside your editor — they're a library you call from your own code or a separate hosted service, not something that lives where you're actually writing.
Tiers & isolation
What are Tier 1, 2, and 3?
Tier 1 (Personal) is one person, self-hosted, no auth required. Tier 2 (Professional Single) is architecturally identical to Tier 1, running the exact same free software — the difference is purely operational (IT-managed rather than self-managed). Tier 3 (Professional Shared) adds real multi-user identity: teams, per-team shared workspaces, and authentication — while keeping every member’s personal memory private. Unlike Tiers 1/2, Tier 3 is a separate, commercially-licensed extension, not part of the free build — see "Is Tier 3 free too?" below. See the docs page for setup.
Is Tier 3 free too?
No. Tiers 1 and 2 (this whole repo) are MIT-licensed and free forever. Tier 3 — real end-user/team authentication and the shared-workspace routes — is developed in a separate, privately-held repo (hupi-t3) under a commercial license, priced per member per month: $50/member (10-seat minimum) for teams under 10, $40/member (rounded up to the next 10 seats, capped at 200) for 10-200 members, and a custom quote above that. It's a real, if small, technical split, not just a paywalled config flag: build the public repo alone and Tier 3's code isn't even compiled in — HUPI_REQUIRE_AUTH=true without a Tier 3 license fails immediately at startup with a clear error rather than silently doing nothing. See the pricing table or contact us directly.
Does Tier 3 support SSO / Azure AD / OIDC login?
Yes. Tier 3 can authenticate users via any standards-compliant OpenID Connect provider — Azure AD/Entra ID, Okta, Auth0, Google Workspace — instead of (or alongside) hupi-admin-provisioned API keys. Team membership comes from the provider itself (Azure AD App Roles by default), so adding someone to a team in your existing directory is enough; there's no separate hupi-admin step to keep in sync. It's a second way to authenticate a request, not a replacement — API keys keep working unchanged. See OIDC.md for the setup walkthrough.
Which identity providers does HUPI’s OpenID Connect (OIDC) support actually work with?
Any provider that speaks standard OpenID Connect and publishes a .well-known/openid-configuration discovery document — that's the whole integration surface, so it isn't a per-vendor integration list. Built and tested against Azure AD/Entra ID specifically (including live end-to-end sign-in testing, not just unit tests), but nothing is hardcoded to it: Okta, Auth0, Google Workspace, and any other compliant IdP work the same way, configured entirely through environment variables — no code change required to switch providers.
Does the HUPI VS Code extension support SSO sign-in too?
Yes. Alongside pasting an API key, the extension has a HUPI: Sign In command that runs a real OpenID Connect login: it opens your system browser at your identity provider's actual login page (Authorization Code + PKCE, the same standard flow tools like the Azure CLI and GitHub CLI use) and listens for the redirect on a local port — your credentials never pass through the extension itself. See VSCODE_EXTENSION.md for setup.
How does team-based isolation actually work — is it just application code trusting itself?
No — it’s enforced twice, independently. Scope filtering is built into every query the application makes, so even a leaked API key only lets an attacker act as the user it belongs to. Separately, Postgres row-level security enforces the same boundary at the database layer: even if a future application bug forgot to filter a query correctly, the database itself refuses to return rows outside the requesting session’s declared scope. This has been verified with tests that deliberately try to break it — including a raw query that explicitly asks for one team’s data while the database session is scoped to a different team, which correctly returns zero rows.
Can one team see another team’s data?
No. Every team’s data is additionally encrypted with its own separate key — someone with raw access to the encrypted database contents can’t read any team’s data without that specific team’s key, so a compromised key exposes only that one team, not the whole deployment.
Does my personal communication style follow me into a team workspace?
Yes, deliberately. Your self_model (communication style and standing preferences) always anchors to you personally and gets applied in every conversation, including team ones — the AI doesn’t suddenly talk like a committee just because the facts it’s drawing on are shared. Everything else — the actual facts being searched — is scoped to whichever workspace the conversation is happening in, and a private fact you’ve shared elsewhere never leaks into a team’s shared memory.
What happens if an API key leaks, or someone gets direct database access?
Scope filtering limits a leaked key to that one user’s private memory and whatever teams they belong to — nothing else. Row-level security is a second, independent backstop at the database layer. Per-team encryption keys mean raw database access alone isn’t enough to read anything. And an insert-only audit log records every write, retrieval, and admin action, attributed to a named operator rather than a shared credential — so even a compromised application credential can’t erase its own trail.
How HUPI works
What is consolidation?
A scheduled overnight job (not part of the live chat path) that reads a day’s conversations, asks an AI to distill them into a handful of concrete, cited facts, and updates the standing knowledge-graph entities those facts touch. Consolidation is what actually gets searched later — individual raw conversation turns are a fallback, not the primary retrieval path.
What is grounding, and why does it matter?
An automatic, independent fact-check consolidation runs on every summary before trusting it: a second AI call verifies each claimed fact actually appears in the source conversation, separate from whichever call generated the summary in the first place. Anything it can’t verify is flagged and excluded from future recall rather than silently accepted — the system is built to be honest about what it doesn’t know rather than confidently making things up about your own history.
Is search only semantic (vector-based)?
No — vector (semantic) search runs alongside BM25, a decades-old exact-term keyword-ranking algorithm, because the two cover different failure modes. Semantic search finds a meaning-close match even with no shared words; keyword search catches a specific name, ID, or acronym that a long, multi-topic summary’s embedding can dilute or miss. Keyword search also reaches raw conversation turns that were never important enough to get vector-embedded in the first place — a real capability gain, not just a backup path. Because every stored field is encrypted at rest, there’s no database index for keyword search to use the way ordinary full-text search would — it decrypts and scores your own history live at query time instead — so an installing admin can turn it off with a single environment variable (HUPI_ENABLE_KEYWORD_SEARCH) on the rare deployment where that live-scoring cost actually matters.
What is the retrieval gate (skipped / partial / full)?
A record of how confidently memory was pulled into a given turn, logged on every single conversation. skipped means a cheap local pre-check found no signal worth searching for at all — no vector search, keyword search, or entity lookup even ran (e.g. "what’s 2+2?"). partial means a search did run but nothing cleared the confidence threshold. full means at least one match — an exact entity match, a high-similarity vector hit, or a keyword (BM25) hit — cleared it, and that’s the content actually handed to the model.
Does every message trigger a full memory search?
No — that’s the point of the retrieval gate’s first stage. A cheap, local, no-LLM-call check decides whether a message looks worth searching for at all (a known entity name, decision/preference language, a question referencing something earlier). Generic or impersonal requests skip retrieval entirely rather than paying for a search that was never going to find anything relevant.
How do corrections work — can a wrong memory actually be fixed?
Yes. Nothing is ever silently edited in place — a correction writes a brand-new version of the summary that supersedes the old one, with the reason for the change recorded, and re-runs the same independent grounding check against it before accepting it. From that point on, retrieval only ever surfaces the corrected version, but the wrong one — and why it was wrong — stays in the historical record rather than disappearing, which is itself useful signal for improving the fact-check over time.
Setup & operations
How do I install it?
./install.sh handles Postgres, schema migrations, and provider config for you — see the docs page for the full quick-install and manual setup steps.
Can I switch which AI vendor I use later?
Yes — memory is stored as plain decrypted text and metadata, not tied to any one vendor’s response format. Switching is a config change to providers.yaml, plus a one-time re-embed if you also change embedding models (existing vector search results would otherwise be comparing embeddings from two different models).
Can I use any embedding model?
Almost any, including local ones — every embedding is stored in a fixed-width column, and the database rejects anything of a different length outright, so HUPI checks this the moment it starts up and adapts automatically. A model whose native output is already the right size (OpenAI’s older ada-002, for example) works as-is. A model with a smaller native output — true of most local/offline embedding models — gets mathematically padded up to size, which is exact, not a quality tradeoff. A model with a larger native output gets asked to shrink it, if it supports that (OpenAI’s newer text-embedding-3-small/-large do). The only real dead end is a larger-output model with no such option, which gets rejected at startup with a clear error rather than silently corrupting search results later. After switching to a model that does pass, run the bundled re-embed tool once per scope to bring existing memories onto the new model.
Is my data encrypted?
Yes, at rest — every episode and summary is stored encrypted by default. In Tier 3, each team additionally gets its own separate encryption key, so a compromised key only exposes that one team’s data.
What does it cost to run, beyond LLM API usage?
Just your own Postgres (with pgvector) and wherever you run the gateway binary — there’s no HUPI-side hosting fee since it’s self-hosted, and Tiers 1/2 are free and open source. (Tier 3 has a separate commercial license fee — see "Is Tier 3 free too?" above.) The main recurring LLM cost beyond normal chat usage is the nightly consolidation pass and its independent grounding check, which roughly doubles the number of consolidation calls — accepted deliberately, since the alternative is a memory system that can drift from the truth with no way to detect it.
Didn't find your question? The full scenario-by-scenario walkthrough is in BUSINESS_PROCESS.md.