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.

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

What ships in this repository

• One governed access surface over MCP and HTTP: mem_write, mem_read, mem_search,
  mem_assemble, mem_fault, mem_stats, mem_forget, policy, sharing,
  pinning, export, and manifest operations.
• Organization-wide identity and access control: credentials resolve actor,
  role, namespace, and source scope server-side before any read or write.
• A governed context lifecycle: provenance, entity resolution, exact and
  semantic dedupe, supersedence chains, and append-only audit.
• One organizational authority across two tiers: Postgres/pgvector for
  operational context and encrypted, Git-versioned knowledge for the cold tier.
  Embedded PGlite is the zero-setup local default.
• A frameworkless control room: access, teams, sources, policies, conflicts,
  retrieval quality, audit, alerts, skills, connected apps, and export.
• Four public connectors: filesystem, Postgres, Obsidian, and manual CSV
  import. All feed the same governed write path.
• A hermetic test lane: embedded PGlite, deterministic StubLlm,
  HashEmbedder, and zero network access.

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:

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:

• model routing, spend attribution, and gateway observability;
• billing, credit ledger, and hosted usage plans;
• operated Slack, Discord, WhatsApp, and Google Chat applications;
• the managed SaaS connector catalogue and its OAuth applications;
• federated live query across organizations;
• the tuned extraction prompt pack; and
• managed infrastructure, upgrades, backups, uptime, and support commitments.

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

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.