halofy README

The project's README from github.com/halofyai/halofy. As one markdown file: README.md.

Halofy

The open access and governance layer for AI agents across your organization.
Give every agent the right organizational context through one identity and policy model, with provenance, audit, and signed erasure.

Get started Architecture Build a driver Discussions

CI AGPL-3.0-or-later Node 22 Offline ready No telemetry

As AI spreads across an organization, every agent needs access to shared context without becoming its own identity system, policy engine, or audit silo. Halofy sits between organizational knowledge and the agents that use it. It resolves identity, enforces access, governs change, records every outcome, and makes erasure independently verifiable.

Underneath that governance boundary, Halofy maintains durable context and keeps retrieval replaceable. The result is infrastructure you can inspect, self-host, run offline, and connect to any agent over MCP or HTTP.

Why Halofy

Organization-wide access Governed context Open infrastructure
Agents, applications, and operators use the same server-resolved identity, namespace ACL, roles, and policy boundary over MCP or HTTP. Every change follows one auditable path with provenance, supersedence, append-only history, and signed erasure. Postgres remains the authority while retrieval engines plug in through an ACL-scoped, read-only driver interface.

What ships in this repository

Quickstart

Run the complete offline story

git clone https://github.com/halofyai/halofy.git
cd halofy/kernel
npm ci
npm run demo

No API key. No database server. No model download. No network call. The demo boots the real kernel on embedded PGlite, then exercises pinning, assembly, writes, hybrid search, an L3 context fault, audit, import, fragmentation, and signed erasure.

== T0 ·· boot in-memory, pin the refund policy, assemble the working set
booted: embedder=hash(dim=256) llm=stub

== T3 ·· mem_fault - page missing context in from L3
fault: hit=true source=L3 injected=2

== T7 ·· mem.forget - erase the customer and mint a signed certificate
certificate 01... verifyCertificate === true
after forget: mem_search surfaces 0 matching facts

demo complete - kernel closed.

Then prove the kernel and its retrieval boundary:

npm test
npx tsx src/cli.ts conformance baseline

The current standalone verification passes 2,678 tests across 205 files and all 6/6 driver-conformance checks. Timings and generated identifiers vary by machine; the behavior does not.

Start the API and control room

cd kernel
npm run serve

Open http://localhost:8787/console/login. For a durable self-hosted deployment with Postgres, generated keys, and Docker Compose, follow the self-hosting guide.

Connect an agent over MCP

cd kernel
npx tsx src/cli.ts keygen org/support/agent-1 user:dana owner
HALOMEM_API_KEY=hm_... npm run mcp

The API key resolves the namespace, actor, and role server-side. MCP tool schemas do not accept caller-asserted identity fields.

Architecture

The important boundaries

  1. Identity is server-owned. Namespace, actor, role, and source scope come from the credential, never from a request body.
  2. Access is organization-wide and policy-bound. The same ACL and role decisions apply across agents, applications, operators, MCP, and HTTP.
  3. Changes are governed. Corrections close the prior fact's validity interval and link the replacement. They do not overwrite history.
  4. Reads are delegated. A retriever sees only an ACL-scoped ScopedView and can return references only. It cannot write or reach audit/storage modules.
  5. Postgres is the authority. Context, embeddings, policy, provenance, tombstones, and audit live together. PGlite embeds the same model for local development and tests.
  6. Every outcome audits. Success, denial, miss, brownout, and error paths all append an event.

Read the architecture guide for the syscall pipeline, ACL examples, SQL, tiering, brownout behavior, and a per-directory source map.

Security model

The core namespace rule is deliberately small: a caller in namespace N sees rows belonging to N or an exact /-split ancestor of N. Siblings and descendants remain invisible unless an explicit, audited administration path allows a subtree operation.

caller: org/support/agent-1

org                          visible     ancestor
org/support                  visible     ancestor
org/support/agent-1          visible     self
org/support/agent-2          hidden      sibling
org/support/agent-1/scratch  hidden      descendant
org/sales                    hidden      sibling

The query layer enforces this rule with exact ancestor matching. Retrieval drivers do not reimplement it; they receive an already-scoped view. See the threat model for the known partial controls and adversarial cases, and the architecture guide for the worked ACL queries.

Open by design

The standalone build is not a trial:

Property Standalone behavior
Licence/activation No licence key, edition flag, activation, or entitlement check
Packaging quota None; the public QuotaPort defaults to UNMETERED
Capacity controls Operator-owned policy rate limits and model-budget brownout only
Telemetry None; no usage beacon or Halofy phone-home
Models Offline deterministic defaults; optional direct Anthropic, OpenAI-compatible, OpenAI embedding, and Azure OpenAI configuration
Database Embedded PGlite by default; regular Postgres/pgvector for durable deployments
Export Open schema, export, manifest, and erasure paths

The permanent boundary is documented in OPEN-SOURCE-SCOPE.md. The practical feature matrix is in open build vs. managed service.

Deliberately commercial

Halofy's managed operations, not the access and governance boundary, fund the open kernel:

None of those components is required to run this repository. The connector framework, baseline model plumbing, governed context lifecycle, access control, console, self-host stack, and test suite are present and runnable.

Documentation

Guide Use it when you want to…
Getting started Go from clone to first key, write, search, MCP connection, and real model configuration
Architecture Trace requests, understand custody, or change the kernel
Driver kit Build and validate a retrieval cartridge
Self-hosting Run Postgres, Docker Compose, backups, restores, and upgrades
Threat model Review assets, boundaries, adversaries, and known partial controls
Open-source scope See what stays open and how that promise changes
Kernel reference Find scripts, source directories, environment variables, and development commands

The full index is in docs/README.md.

Contributing

Start with CONTRIBUTING.md. Security-sensitive changes to authentication, tenancy, ACLs, migrations, encryption, audit, erasure, or the write/retrieval boundary require adversarial review and regression coverage.

Security reports belong in the private channels described by SECURITY.md, not in public issues. Community expectations are in CODE_OF_CONDUCT.md.

License

The kernel and console are AGPL-3.0-or-later. Named client and extension subtrees are Apache-2.0 so they can be embedded without relicensing the host application. These include kernel/src/driver/, kernel/src/mcp/, and kernel/integrations/. See LICENSING.md and NOTICE for the authoritative file-by-file boundary.

The Halofy name is a trademark; neither software licence grants trademark rights. See TRADEMARK.md.

halofy (halofyai/halofy)

Searching Database…

319 ·GitHub
Halofy
Что это?Halofy — уровень доступа и управления, который стоит между знаниями организации и использующими их ИИ-агентами и ведает идентификацией, политиками, происхождением данных, аудитом и подписанным удалением.
Это библиотека для импорта или сервер, который я запускаю?Это самохостящийся сервер/ядро, доступный через MCP и HTTP, с административной консолью без фреймворка («control room») для доступа, команд, источников, политик и аудита.
Как это запустить?Запустите офлайн-демо на встроенной PGlite (не нужны API-ключ, сервер базы или сетевые вызовы), чтобы увидеть полный поток ядра, затем поднимите API и control room; для постоянного развёртывания следуйте руководству по самостоятельному развёртыванию с Postgres и Docker Compose.
Нужна ли база Postgres, чтобы попробовать?Нет — quickstart по умолчанию использует встроенную PGlite для локальной разработки и тестов без настройки; настоящий экземпляр Postgres/pgvector нужен только для постоянного развёртывания на своём сервере.
Чего нет в сборке с открытым кодом?Маршрутизация моделей и атрибуция расходов, биллинг, хостящиеся приложения Slack/Discord/WhatsApp/Google Chat, управляемый каталог SaaS-коннекторов, федеративные запросы между организациями и затюненный набор промптов для извлечения — это часть платного managed-сервиса, а не открытого ядра.
Как он решает, какие агенты какие данные видят?Каждый вызывающий на сервере сопоставляется с пространством имён (namespace), и правило доступа разрешает видеть строки только этого пространства или точного пути предка; соседние и дочерние пространства остаются невидимыми, пока явная аудитируемая админ-операция их не откроет.
С какими коннекторами он поставляется?Из коробки входят четыре публичных коннектора: filesystem, Postgres, Obsidian и ручной импорт CSV, и все они питают один и тот же контролируемый путь записи.
Как здесь работает удаление данных?Удаление криптографически подписано и проверяемо независимо, а не является простым стиранием, и обычные исправления закрывают интервал валидности прежнего факта и связывают замену, не перезаписывая историю.
Проект реально тестировался в таком масштабе?Автономная сборка сейчас проходит 2 678 тестов в 205 файлах и все 6 из 6 проверок соответствия драйверов, в герметичном контуре со встроенной PGlite, детерминированным заглушечным LLM и хэш-эмбеддером при полном отсутствии доступа к сети.
What are similar projects?bytebase, OpenMetadata, anythingmcp, casdoor, utopia, zilan, OpenLore, OpenBot
Which topics is it in?agent-governance, data-governance, identity-management, pgvector, access-control, multi-tenant, audit-log, multi-agent-systems, rbac, knowledge-management, context-engineering, enterprise
Creator
halofyai
Size
2.7 MB
Stars
319
Updated
CommitAug 24
Age
1mo
Commits · 90 Days