Halofy MCP server
Commit Nov 13, 2026Provides an open access and governance layer for AI agents to manage identity, policy, provenance, and auditable context.
Also known as halofyai/halofy
- Stars
- 320
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- AGPL-3.0
What is Halofy MCP?
Halofy provides an open access and governance layer for AI agents to manage identity, policy, provenance, and auditable context.
Summary generated from the project's README
About Halofy MCP server
Managing organizational identity and policy for AI agents is what Halofy enables. It acts as a governance layer that sits between your internal knowledge and the agents using it, ensuring every agent operates within a defined security boundary. Organizations can use it to resolve identities, enforce access control, and maintain an auditable history of all context changes through provenance and signed erasure.
Developers can deploy this as a local, offline-ready solution using embedded PGlite for zero-setup testing, or as a durable self-hosted deployment using Postgres and pgvector. It connects to agents via MCP or HTTP using API keys that resolve roles and namespaces server-side. The system provides specific tools like mem_write, mem_read, mem_search, and mem_forget to manage the lifecycle of information. Unlike many managed services, it features no telemetry and no usage beacons, allowing for complete privacy and inspection of the infrastructure.
What you can do with it
- 1Enforce agent access controlsA developer can ensure an agent only accesses data within its specific organizational namespace using server-side identity resolution.
- 2Maintain an auditable knowledge historyYou can track every change to your organizational context through an append-only audit trail that includes provenance and supersedence.
- 3Perform verifiable data erasureAn administrator can delete specific customer information and generate a signed certificate to prove the erasure occurred.
- 4Run fully offline AI infrastructureTeams can run a complete governance stack without any network calls, API keys, or external model downloads.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
HALOMEM_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehalofyai/halofy is public and reachablegithub.com/halofyai/halofy ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/halofyai/halofy ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAs 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
- 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
- Identity is server-owned. Namespace, actor, role, and source scope come from the credential, never from a request body.
- Access is organization-wide and policy-bound. The same ACL and role decisions apply across agents, applications, operators, MCP, and HTTP.
- Changes are governed. Corrections close the prior fact's validity interval and link the replacement. They do not overwrite history.
- Reads are delegated. A retriever sees only an ACL-scoped
ScopedViewand can return references only. It cannot write or reach audit/storage modules. - Postgres is the authority. Context, embeddings, policy, provenance, tombstones, and audit live together. PGlite embeds the same model for local development and tests.
- 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:
- 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
| 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 MCP questions
How does Halofy handle identity for AI agents?
Identity is server-owned, where namespace, actor, role, and source scope are resolved from credentials rather than request bodies.
Can I run Halofy offline?
Yes, Halofy is designed to be offline-ready and can run with an embedded PGlite database without network calls or model downloads.
What connectivity options are available for agents?
Agents can connect to Halofy over MCP or HTTP.
Does Halofy track changes to information?
Yes, it maintains an append-only history where corrections link to prior facts rather than overwriting them.