Engram — Admin Setup Guide

This guide walks through setting up Engram for your organization: creating a workspace, connecting sources, generating guidelines, and distributing them to your team's AI tools.

First-Time Setup

1. Create an Account

Open the Engram dashboard (http://localhost:3000 for self-hosted, or https://app.getengram.io for SaaS). Sign up with email (magic link) or via GitHub/Google OAuth.

2. Create a Workspace

After signing in, create your first workspace:

Name — your company or team name (e.g., "Acme Corp").
Slug — a URL-safe identifier used in API calls (e.g., acme). Cannot be changed later.

You are automatically assigned the owner role in the workspace you create.

3. Invite Team Members

Navigate to Settings > Members and invite colleagues by email. Assign each member a role:

Role	Permissions
Owner	Full control. Manage billing, delete workspace, transfer ownership.
Admin	Manage members, sources, repos, routing config, API keys. Run analysis and deployments.
Editor	Create and edit documents, domains, and guidelines. Confirm/dismiss topics. Run generation and validation.
Viewer	Read-only access to documents and the dashboard. Can use the CLI for context retrieval.

Recommended starting point: workspace creator as owner, engineering/platform leads as admins, domain specialists (design, marketing, security) as editors.

Connecting Sources

Sources are the raw material Engram uses to understand your company and generate guidelines. Connect them once — Engram ingests, analyzes, and extracts patterns. After initial setup, Engram becomes the primary editing surface for guidelines.

Navigate to Settings > Sources or use the CLI.

GitHub

Connect at the organization level to discover all repositories:

engram sources add github --org your-org

Engram scans repos for existing rules files (CLAUDE.md, .cursor/rules/, copilot-instructions.md, AGENTS.md), README files, package manifests, and code structure. This gives it a detailed understanding of your tech stack, patterns, and any existing AI conventions.

Authorization: GitHub OAuth flow (starts in the dashboard).

Notion

engram sources add notion

Engram accesses your Notion workspace via OAuth. It ingests pages and databases that contain company documentation — brand guidelines, design system docs, engineering standards, product specs.

Complete the OAuth authorization flow in the dashboard after running the CLI command.

Confluence

engram sources add confluence

Similar to Notion. Ingests Confluence spaces and pages. Useful for companies whose documentation lives in Atlassian.

Complete the OAuth authorization flow in the dashboard.

Website

engram sources add website https://www.example.com

Crawls key pages of your website. Engram uses this to extract brand voice, product positioning, messaging patterns, and visual identity cues — all from how your company actually presents itself.

Google Workspace

engram sources add google-workspace

Connects to Google Docs and Sheets. Useful for companies that maintain style guides, process docs, or runbooks in Google Drive.

Complete the OAuth authorization flow in the dashboard.

GitLab

engram sources add git_lab

Same as GitHub — scans repositories for tech stack, code patterns, and existing AI rules.

Bitbucket

engram sources add bitbucket

Same as GitHub/GitLab — supports Bitbucket Cloud repositories.

SharePoint

engram sources add share_point

Connects to SharePoint document libraries via OAuth. Common in Microsoft-oriented enterprises.

Syncing Sources

After connecting, trigger ingestion to fetch and index all source content:

# Sync all sources
engram sources sync

# Sync a specific source
engram sources sync --source src_abc123

Sync is an async operation. The dashboard shows progress in real time via the jobs panel.

Running Gap Analysis

Once sources are connected and synced, run a gap analysis. This is the core intelligence step — Engram analyzes all ingested content and produces a structured assessment.

engram analyze

Or from the dashboard: Analysis > Run New Analysis.

What Gap Analysis Produces

The analysis produces three buckets:

1. Can Create — Topics where Engram found enough source material to generate a guideline. This includes both explicit documentation (a brand guide in Notion) and implicit patterns (API naming conventions inferred from actual code across repos, brand voice extracted from website copy).

Each topic shows:

Title and suggested domain (e.g., "API Conventions" in Engineering)
Confidence score (how much source evidence exists)
Source evidence with excerpts
Whether the pattern is implicit (extracted from code/content) or explicit (from documentation)

2. Issues Found — Problems detected across your existing sources and rules:

Contradictions — conflicting conventions across repos (e.g., snake_case in one repo's CLAUDE.md, camelCase in another)
Divergence — code that has drifted from documented conventions
Quality — vague or unactionable existing rules
Staleness — outdated documentation

3. Missing Critical — Topics that Engram considers essential for your type of company but found no source material for. For example, a SaaS company without security policies, or a B2B company without sales methodology documentation. Engram can generate starter templates for these, but they require domain owner input to be useful.

Company Understanding

The analysis also produces a "company understanding" — a structured summary of what Engram learned about your organization: industry, product type, tech stack, team size. This informs which topics it considers critical.

Viewing Results

engram analyze --status
engram analyze --status --json  # machine-readable output

Reviewing Topics

After analysis, review the suggested topics and decide which ones to turn into guidelines.

List All Topics

engram topics list

Shows pending, confirmed, and dismissed topics.

Confirm a Topic

Confirming tells Engram you want a guideline generated for this topic:

engram topics confirm "API Conventions"

Dismiss a Topic

If a topic is not relevant or you prefer to handle it manually:

engram topics dismiss "Sales Methodology"

You can also confirm and dismiss topics in the dashboard with one click per topic.

Generating Guidelines

For each confirmed topic, generate a guideline document:

engram generate "API Conventions"

Generation is an async AI job. Engram:

Collects all source evidence mapped to the topic.
Extracts patterns (not copies content) — conventions, rules, principles.
Produces a structured guideline document with actionable items.
Tracks provenance — every statement links back to its source.
Sets the document status to needs-review (pending human review).

The generated document appears in your workspace under the suggested domain. Open it in the dashboard to review and edit.

Reviewing and Editing Guidelines

Generated documents start with status needs-review. The recommended workflow:

Review — read the generated content, check for accuracy.
Edit — refine wording, add missing context, remove irrelevant items. The dashboard provides a full markdown editor.
Approve — change status to active to include the document in compilations and context serving.

Document statuses:

Status	Meaning
`draft`	Work in progress. Not included in compilations.
`needs-review`	Awaiting human review (AI-generated or flagged by drift detection).
`active`	Approved and live. Included in compilations and context serving.
`deprecated`	Archived. No longer distributed.

All edits create a new version. Version history is immutable — you can restore any previous version at any time.

Configuring Compilation Targets

Compilation transforms your guidelines into the format each AI tool expects. Configure which targets each repository uses.

Supported Targets

Target	Output Files	How AI Tools Read Them
Claude Code	Root `CLAUDE.md` hub + `.claude/docs/engram/*.md` per document	AI reads the hub (~200 tokens), picks relevant docs per task.
Cursor	`.cursor/rules/engram-{slug}.mdc` with YAML frontmatter	Auto-applied by file glob matching.
GitHub Copilot	`.github/copilot-instructions.md`	Single merged file, condensed.
Windsurf	`.windsurf/rules/engram-{slug}.md`	Per-document rules.
AGENTS.md	`AGENTS.md`	Single merged file.

Coexistence with Existing Rules

Engram never overwrites manually maintained rules. It owns a clearly separated slice:

Claude Code: Engram manages ... sections in CLAUDE.md and the .claude/docs/engram/ subdirectory.
Cursor: Engram files are prefixed with engram- (e.g., engram-api-conventions.mdc). Manual rules are untouched.
Copilot / AGENTS.md: Engram appends an ... section. Content outside these markers is preserved.

Preview Compilation

See what the compiled output looks like before deploying:

engram compile                          # all targets
engram compile claude cursor            # specific targets

The dashboard also provides a live preview — edit a guideline and see the compiled output in real time (powered by the engram-core WASM module running in-browser).

Setting Up Routing

Routing controls which guidelines are included for each role. Configure routing in Settings > Routing or via the API.

Role-Based Paths

Define roles that map to subsets of your guidelines:

{
  "roles": ["backend", "frontend", "marketing", "design", "sales"],
  "roleMappings": {
    "backend": ["doc_api_conventions", "doc_architecture", "doc_security"],
    "frontend": ["doc_design_system", "doc_ux_writing", "doc_architecture"],
    "marketing": ["doc_brand_voice", "doc_product_positioning", "doc_writing_style"],
    "design": ["doc_design_system", "doc_brand_voice", "doc_visual_identity"],
    "sales": ["doc_sales_methodology", "doc_product_positioning", "doc_customer_comms"]
  }
}

When a CLI user or AI agent requests context with --role backend, they receive only the documents mapped to that role.

Always-Include Rules

Some guidelines apply to everyone regardless of role — company values, security policies, or brand principles. Add them to alwaysInclude:

{
  "alwaysInclude": ["doc_company_values", "doc_security_policies"]
}

These documents are prepended to every context response.

Reading Orders

Control the sequence in which documents appear for each role. Documents listed first are read first by the AI, so place the most important/foundational ones at the top:

{
  "readingOrders": {
    "backend": ["doc_architecture", "doc_api_conventions", "doc_security"],
    "marketing": ["doc_brand_voice", "doc_writing_style", "doc_product_positioning"]
  }
}

Deploying to Repos

Deployment compiles guidelines and pushes them to your connected repositories via the GitHub App.

Setting Up Repos

Navigate to Settings > Repos or use the API to register repositories:

URL — the repository URL (e.g., https://github.com/acme/backend).
Branch — target branch for PRs (default: main).
Compile targets — which output formats to generate for this repo (e.g., ["claude", "cursor"]).
Auto-merge — automatically merge the PR after creation (requires the GitHub App to have merge permissions).

GitHub App Setup

Install the Engram GitHub App on your organization. The App needs:

Read access to repository contents (to detect existing rules and drift).
Write access to pull requests and contents (to create branches and PRs).

When a guideline changes, Engram automatically:

Compiles the updated output for each target.
Creates a branch (engram/update-guidelines).
Opens a PR with the changes.
Optionally auto-merges if configured.

Manual Deploy

Trigger a deployment manually:

engram deploy                                      # all repos, all targets
engram deploy --repos repo_abc repo_def             # specific repos
engram deploy --targets claude cursor               # specific targets

The deploy job runs asynchronously. The CLI polls for completion and displays results, including PR numbers and URLs.

Managing API Keys

API keys authenticate CLI tools and AI agents against the Engram API. They are workspace-scoped — each key belongs to a single workspace.

Creating Keys

Navigate to Settings > API Keys in the dashboard, or use the API:

POST /api/v1/workspaces/{wid}/api-keys
Body: { "name": "CI pipeline" }

The full key (e.g., ek_abc123...) is returned once at creation time. Store it securely. Only the key prefix (ek_abc123) is stored for display.

Using Keys

Pass the API key as a Bearer token:

# CLI
engram init  # enter the key during setup

# Direct API
curl -H "Authorization: Bearer ek_abc123..." https://engram.example.com/api/v1/context?workspace=acme

Revoking Keys

Delete a key from Settings > API Keys or via the API. Revocation is immediate — all requests using that key will fail with 401 Unauthorized.

Validation

Validation checks the health of your guideline library. Run it periodically or after major changes.

engram validate                        # all checks
engram validate --checks freshness contradictions  # specific checks
engram validate --wait                 # wait for results
engram validate --wait --json          # machine-readable output

Available Checks

Check	What It Does
Freshness	Flags guidelines that haven't been updated within the staleness threshold (default: 90 days).
Contradictions	Detects conflicting advice across documents (e.g., two docs recommending different naming conventions).
Completeness	Identifies documents that are too short, lack examples, or have vague language.
Coverage	Finds topics referenced in one document but not covered by any other document.
Drift	Detects when a source has been updated more recently than the guideline derived from it.
Duplicates	Finds documents with significant content overlap that should be consolidated.

Health Score

Validation produces an overall health score (0-100) based on the number and severity of issues found. A score of 80+ indicates a healthy guideline library.

Dashboard View

The dashboard provides a visual validation report with direct links to affected documents for easy remediation.

Common Admin Workflows

Initial Onboarding (Day 1)

Create workspace and invite admins.
Connect sources: GitHub org, Notion/Confluence workspace, company website.
Sync all sources: engram sources sync
Run gap analysis: engram analyze
Review topics in the dashboard. Confirm the ones you want. Dismiss the rest.
Generate guidelines for confirmed topics: engram generate "Topic Name" (one per topic).
Assign domain owners (editors) — designers review design docs, engineers review API docs, etc.
Domain owners review and approve generated documents (set status to active).
Configure routing (roles, always-include, reading orders).
Set up repos with compile targets.
Deploy: engram deploy

Adding a New Repo

Register the repo in Settings > Repos with desired compile targets.
Install the GitHub App on the repo (if not already installed org-wide).
Deploy: engram deploy --repos repo_newid

Updating a Guideline

Edit the document in the dashboard.
The document auto-saves with a new version.
If the repo has auto-merge enabled, the updated guideline is deployed automatically.
Otherwise, a PR is created for review.

Periodic Maintenance

Run validation: engram validate --wait
Address any freshness, contradiction, or drift issues.
Re-sync sources if upstream docs have changed significantly: engram sources sync
Optionally re-run gap analysis to discover new topics: engram analyze