meivo.Discuss your project

Reference

Core API keys & offline use

Direct core-engine API keys, offline operation, and the controls required for a sealed deployment.

Security, access, and audit evidence

This page describes the direct gm-server boundary: bearer keys, network exposure, offline preparation, and memory-integrity signals.

The packaged enterprise product normally puts its built-in gateway in front of the memory framework. That gateway adds local/LDAP identity, roles, ACL resolution, guardrails, encrypted provider configuration, and the audit management UI. A direct REST or HTTP MCP call to the engine does not automatically inherit those controls.

Enterprise gateway controls

Route end users through the enterprise gateway. It resolves live user identity, roles, and source grants on each request. Administrators can grant source access to the workspace, individual users, or groups. Unlabelled content is denied; connectors must not broaden supplied ACLs. Source-system permission changes are not automatically synchronized by every connector.

The gateway validates retrieved chunks against active document versions and the current caller's permissions before using them as model context. Fact and graph retrieval lanes are disabled for ACL-filtered end-user requests until derived knowledge has equivalent authorization. Direct engine keys remain privileged.

Chat preparation, model execution, configured input/context/output policy, persistence, and final authorization auditing run in the control plane. An answer is returned only after that flow succeeds. Policy mode is an operator choice; monitoring and disabled modes do not provide blocking enforcement. Provider keys remain server-side by default. Parsing, payloads, provider calls, and per-user search/chat request budgets have explicit resource limits.

Evidence your team can verify

Audit events use an HMAC chain. New schema-2 events also authenticate event identity, trace IDs, and signing-key versions. Exports can be verified offline and sealed by an independent evidence custodian with an Ed25519 key; recipients can verify the sealed file with the separately trusted public key. Sealing is an explicit operational step, not an automatic property of every downloaded file.

AWS Object Lock and Google Cloud locked-retention checkpoint configurations support evidence retention when deployed and configured. Signed records support an audit process; they do not grant a compliance certification. OIDC/SCIM, KMS envelope custody, and broader engine read-audit guarantees remain roadmap items. Review the direct-engine boundary and limitations below.

Direct-engine bearer keys

gm-server loads GM_API_KEYS at startup and compares the incoming Authorization: Bearer <key> value with configured keys using a constant-time comparison.

  • With GM_API_KEYS unset, authentication is off. The safe default bind is loopback.
  • A non-loopback bind without keys is refused unless the operator explicitly sets GM_ALLOW_INSECURE=true.
  • Every /v1 route requires a key when keys are configured except GET /v1/healthz and GET /v1/readyz.
  • Streamable HTTP MCP at /mcp uses the same bearer middleware.
  • Stdio MCP is a local child process and is protected by the host process, filesystem, and OS-user boundary rather than HTTP bearer middleware.

Keys can be named for audit attribution:

GM_API_KEYS=ingestion-worker:secret-one,internal-agent:secret-two \
  gm-server serve --host 0.0.0.0

The value after the first colon is the secret sent by the client:

curl -sS https://memory.example.internal/v1/stats \
  -H 'Authorization: Bearer secret-two'

Creating and rotating keys

Any high-entropy secret works. For example:

openssl rand -hex 32

Store keys in the customer's secret manager rather than source control or a container image. Key changes require a server restart.

For a rolling rotation:

  1. Add the new named key while retaining the old one, then restart.
  2. Move the trusted client to the new key.
  3. Remove the old key and restart again.

Use one named key per internal service where practical. A valid engine key is still broad: it can read and write every engine space, so do not distribute engine keys to end users.

Offline preparation

The default local embedder needs to obtain BGE-small-en-v1.5 before first use. Prepare a disconnected target from a connected build or staging environment:

gm-server warmup --data-dir /opt/greatmemory/data

Transfer /opt/greatmemory/data/models/ through the customer's approved media and integrity-verification process, then start the target with that same data directory:

GM_DATA_DIR=/opt/greatmemory/data \
GM_AUDIT_MODE=standalone \
gm-server serve

Storage and hybrid retrieval can run with GM_LLM=none. For local fact extraction and reflection, point GM_LLM at a customer-operated local endpoint such as Ollama. Any container images, operating-system packages, local LLM weights, certificate revocation policy, and updates must also be staged for the offline environment.

The core engine does not require a public licence service, telemetry service, or update service to answer requests. It can still make network calls when:

  • the fastembed model is missing and must be downloaded;
  • an operator configures an HTTP embedder or LLM;
  • integrated audit delivery points to the enterprise gateway.

Offline-ready software is not the same as a sealed network. The enterprise gateway's local-only provider checks are application-level defense in depth. A genuinely air-gapped deployment also needs customer-enforced firewall, DNS, routing, proxy, update, removable-media, and supply-chain controls.

Memory integrity and trust

Stored memory can carry false claims or prompt-injection text. Meivo assigns a trust score to memory and search results using provenance. With trust gating enabled, known prompt-injection-like patterns are also detected:

  • suspicious content receives a lower score;
  • it remains stored for investigation;
  • it is not promoted into structured graph facts;
  • the consuming application receives retrieved content as data, with provenance.

This is a heuristic control, not a proof that content is safe or true. Novel attacks and ordinary misinformation can pass pattern checks. Combine it with source allow-lists, permission-aware ingestion, gateway guardrails, model instructions, output validation, and human review.

Audit behavior at the engine boundary

In integrated mode, mutating actions are placed in a durable outbox and reconciled to the gateway's tamper-evident audit chain. Search/context read events use a bounded asynchronous queue so audit delivery does not add a hard dependency to the read response. Under sustained overload, read events can be dropped.

Monitor:

  • audit_backlog_count;
  • audit_backlog_oldest_age_secs;
  • audit_read_tier_dropped_count;

through GET /v1/stats.

GM_AUDIT_MODE=standalone writes engine audit events to local logs and does not provide the packaged gateway's hash-chain, checkpoint, export, or review workflow.

Current direct-engine limitations

  • API-key secrets are retained in process memory and originate in environment or TOML configuration; they are not stored as password-style hashes.
  • API keys have no built-in expiry, per-route scope, per-space scope, or hot reload.
  • space is a namespace, not an authorisation boundary for a direct engine key.
  • The engine speaks HTTP; terminate TLS at a trusted reverse proxy or load balancer.
  • Trust scoring and pattern checks are defense in depth, not content certification.
  • A delete call removes active document/chunk retrieval but is not, on its own, proof of erasure from fact history, audit evidence, exports, or backups.

Use the built-in enterprise gateway for user-facing access rather than trying to turn shared engine keys into an end-user identity system.

Production checklist

  • Route users and business applications through the enterprise gateway.
  • Keep gm-server on a private network and issue named keys only to trusted internal services.
  • Terminate TLS and apply network allow-lists.
  • Set exact GM_CORS_ORIGINS; CORS is a browser control, not API authorisation.
  • Store and rotate secrets through the customer's secret manager.
  • Monitor health, readiness, RSS, and audit pipeline counters.
  • Validate backup restoration and retention separately from live-data deletion.
  • For offline deployments, test startup and representative inference after external egress is blocked.