Admin & governance

What makes Engram enterprise-grade rather than a prompt dump: every memory has a lifecycle, history is append-only, permissions are enforced in the query, and every governance action leaves an audit trail. This page is the admin's operating manual.

Members, teams & roles#

Two role systems compose, and it helps to keep them straight:

• Workspace roles — owner / admin / member. Owners and admins bypass folder grants entirely (still audited). The first user on a fresh deployment becomes owner.
• Folder roles — viewer / contributor / manager per grant, controlling read / capture-and-edit / approve-and-manage within that subtree (see Core concepts).

Every member starts from the workspace default: all members → contributor @ root — a flat team works with zero configuration. Explicit grants union with that baseline, so placing someone on a team widens their access; restricting a folder is how you narrow it. Placing a member on a team from the canvas provisions their team-folder grant automatically.

Grants & restricted folders#

• Grants are additive: principal × folder × role, covering the subtree. There are no deny rules — the model stays auditable because you only ever reason about what was granted.
• Restricted folders are the boundary primitive. Flag /departments/hr or /projects/secret-x restricted and grants from above stop flowing in; access requires a grant at or below the restricted folder. Members' private folders under /people use exactly this mechanism.
• Classification is the second lock. Members default to a confidential clearance ceiling; restricted-classified content requires an explicit grant. Set classifications on sensitive memories and the clearance check applies everywhere, on top of paths.

Role mappings — your role model, translated#

When client applications call the API on behalf of their users, the subject's external roles (whatever your company already uses — employee, dept:sales, executive) translate through the workspace's role mapping table into Engram grants. A typical enterprise matrix:

Because it's data, any client's role model maps the same way — no code per client. Mapped grants are always intersected with the calling token's own scopes, so a compromised or over-eager client backend still can't escalate past its token.

Token hygiene#

• Integration tokens are never managers — mint them scoped to the narrowest folders that work, and cap classification.
• Personal tokens track their owner's live role: demoting or removing the member depowers the token on its very next call. No re-mint needed.
• Secrets are shown once at mint and stored hashed; lastUsedAt is tracked — revoke anything that's gone quiet.

Running the approval flow#

The lifecycle (draft → reviewed → approved → deprecated) and the AI-write invariant are covered in Core concepts; the day-to-day surface is the review queue. Operating notes for admins:

• Distribute managers. Approval rights are per-folder — give each team a manager on its own subtree instead of routing everything through admins.
• Trusted-corpus imports are the one carve-out. A connector marked importAs: approved lands content pre-approved with the configuring admin recorded as approver. Reserve it for corpora that are already governed elsewhere.
• Staleness rules flag approved content untouched past a threshold (e.g. 180 days) into a review filter, and deprecating a node cascades a warning to memories that cite it.

The audit trail#

Governance actions are reconstructable end-to-end from layered records:

• Who knew what — usage events (view, copy, answer-cited) per memory per actor.
• Who changed what — the append-only version chain itself: author type (human, Gardener, agent), author id, timestamps, change notes.
• Who approved what — approver and time on every version.
• Where it came from — provenance back to raw captures, original bytes retained.
• What AI did — every agent job with token usage and cost.

Over all of that sits the unified audit event log — one row per governance mutation (memory.approve, grant.added, member.role_changed, token.minted, …) — browsable in the control plane, with CSV export for compliance requests.

Privacy settings#

• Query logging — full, anonymized (default: query text kept for gap detection, asker identity hashed), or off. Raw query text is scrubbable by retention policy.
• Personal folders — members' connected-account imports live in restricted folders only they hold grants on.