Admin Guide

This guide is for the admin — the domain expert responsible for defining the policy layer that governs how Memintel operates. You do not need to be a software developer, but you do need to know your domain well: what signals matter, what thresholds are meaningful, and what should happen when something is detected.

---

The Two Config Files

Memintel uses two configuration files. Understanding which file does what — and who is responsible for each — is the most important thing to grasp before starting.

memintel_config.yaml — Infrastructure Config

Who owns this: your data engineer.

This file contains the technical plumbing — database connections, Redis, LLM provider, data connectors, and primitive-to-data-source mappings. You do not edit this file. Your data engineer sets it up once during deployment and maintains it.

# memintel_config.yaml — your data engineer's file
database:
  url: ${DATABASE_URL}

cache:
  url: ${REDIS_URL}

llm:
  provider: anthropic
  api_key: ${ANTHROPIC_API_KEY}
  model: claude-sonnet-4-6

  # On-premise alternative:
  # provider: openai_compatible
  # base_url: https://llm.internal.yourcompany.com/v1
  # model: llama3.1:70b
  # timeout_seconds: 60
  # ssl_verify: false


connectors:
  postgres.analytics:
    type: postgres
    host: ${ANALYTICS_DB_HOST}
    database: analytics
    user: ${ANALYTICS_DB_USER}
    password: ${ANALYTICS_DB_PASSWORD}

primitives:
  account.active_user_rate_30d:
    connector: postgres.analytics
    query: >
      SELECT (active_users::float / total_seats)
      FROM account_metrics
      WHERE account_id = :entity_id
      AND recorded_at <= :as_of
      ORDER BY recorded_at DESC LIMIT 1

memintel_guardrails.yaml — Policy Config (Seed and Fallback)

Who owns this: you, the admin.

This file defines the initial guardrails policy — which evaluation strategies are permitted, what parameter ranges are acceptable, how severity language maps to numeric thresholds.

For most deployments, you will manage guardrails via the API instead — which is simpler, takes effect immediately, and requires no server restart. The file is used as a seed on first deployment and as a fallback. Once you post guardrails via the API, the API version always takes precedence over the file.

# memintel_guardrails.yaml — your file as admin
strategy_registry:
  - threshold
  - percentile
  - z_score
  - change
  - equals

type_strategy_map:
  float:       [threshold, percentile, z_score, change]
  int:         [threshold, percentile, change]
  categorical: [equals]
  # Note: boolean type has no supported strategies.
  # Use categorical with labels: ['true', 'false'] instead.

parameter_priors:
  account.active_user_rate_30d:
    low_severity:    { value: 0.60 }
    medium_severity: { value: 0.45 }
    high_severity:   { value: 0.30 }

bias_rules:
  significant: medium_severity
  urgent:      high_severity
  early:       low_severity

---

How Configuration Works

Different parts of the system are managed in different ways:

What	How it is managed	Who does it
Connectors	memintel_config.yaml	Data engineer
Primitive data sources	memintel_config.yaml (connector mapping + query)	Data engineer
Primitive type schema	POST /registry/definitions (API call)	Data engineer
Conditions / Concepts	Compiled automatically from user intent	Memintel compiler
Tasks	POST /tasks (API call)	Users
Application context	POST /context (API call)	Admin
Guardrails	POST /guardrails (API) or memintel_guardrails.yaml (file)	Admin

Primitives require two steps

A primitive needs both a config file entry (so the runtime knows where to fetch its value) and an API registration (so the compiler knows its type). See Step 1 — Primitives for details.

As admin, your configuration work happens in two places:

1. memintel_guardrails.yaml — the policy file you own and edit
2. POST /context — the API call you make to define domain context

---

The Admin Setup Flow

Step 1 — Infrastructure (Data Engineer)

Before the server can start, all of the following must be in place:

1. Install PostgreSQL and create the database

createdb memintel

2. Run database migrations

alembic upgrade head

This creates all tables Memintel needs. Run this once after install and again after any update that includes new migration files.

3. Install and start Redis

Redis must be running and reachable before the server starts.

4. Set all required environment variables

The server will not boot without these:

Variable	Purpose
DATABASE_URL	PostgreSQL connection URL
REDIS_URL	Redis connection URL
MEMINTEL_ELEVATED_KEY	Secret key for privileged API endpoints
ANTHROPIC_API_KEY	Anthropic API key for the LLM pipeline
MEMINTEL_CONFIG_PATH	Path to memintel_config.yaml

Plus any connector-specific variables referenced in your config file, for example ANALYTICS_DB_HOST, ANALYTICS_DB_USER, ANALYTICS_DB_PASSWORD.

5. Create memintel_config.yaml

Contains database, cache, LLM provider, and connector configuration. See the example in The Two Config Files above.

6. Create memintel_guardrails.yaml

Contains the initial guardrails policy — strategy registry, type-strategy map, parameter priors, and bias rules. This file is loaded as the seed policy on first boot. See Step 3B — Guardrails via File for the full format.

---

Step 2 — Start the Server

Once all prerequisites are in place, start the server:

uvicorn app.main:app --host 0.0.0.0 --port 8000

On startup, Memintel:

• Connects to PostgreSQL — fails immediately if not reachable
• Connects to Redis — fails immediately if not reachable
• Loads memintel_config.yaml — fails immediately if missing or invalid
• Loads memintel_guardrails.yaml as the seed policy

If any of these fail, the server exits with a startup_failed error in the logs. Fix the underlying issue and restart.

---

Step 3 — Register Primitives (Data Engineer)

With the server running, the data engineer registers each primitive's type schema via the API:

curl -X POST https://api.memsdl.ai/v1/registry/definitions   -H "X-Elevated-Key: your-elevated-key"   -H "Content-Type: application/json"   -d '{"primitive_id": "account.active_user_rate_30d", "type": "float", "namespace": "org", "missing_data_policy": "null"}'

See Step 1 — Primitives for the full guide.

---

Step 4 — Set Application Context (Admin)

Post your domain context so the LLM compiler understands your business:

curl -X POST https://api.memsdl.ai/v1/context   -H "X-API-Key: your-api-key"   -H "Content-Type: application/json"   -d '{"context": "SaaS platform monitoring customer health and churn risk..."}'

See Step 2 — Application Context for the full guide.

---

Step 5 — Post Guardrails (Admin)

Refine the policy beyond the seed file by posting guardrails via the API:

curl -X POST https://api.memsdl.ai/v1/guardrails   -H "X-Elevated-Key: your-elevated-key"   -H "Content-Type: application/json"   -d '{...}'

tip

The API version always takes precedence over the seed file. Use the API unless you need to set guardrails before the server is running for the first time.

See Step 3A — Guardrails via API for the full guide.

---

Step 6 — Register Actions (Admin)

Define what happens when a condition fires — Slack alerts, emails, webhooks:

curl -X POST https://api.memsdl.ai/v1/actions \
  -H "X-Elevated-Key: your-elevated-key" \
  -H "Content-Type: application/json" \
  -d '{
    "action_id": "slack_cs_team",
    "version": "v1",
    "config": { "type": "notification", "channel": "slack-cs-alerts" },
    "trigger": { "fire_on": "true", "condition_id": "cond_churn_risk", "condition_version": "v1" },
    "namespace": "org"
  }'

See Step 4 — Actions for the full guide.

---

File Locations and Security

Both config files live on the server, outside the Git repository, and are excluded from version control via .gitignore. They are never committed to Git.

File / Store	Location	In Git?	Restart needed?
memintel_config.yaml	/etc/memintel/memintel_config.yaml	Never	Yes
memintel_guardrails.yaml	/etc/memintel/memintel_guardrails.yaml	Never	Yes (file changes only)
Guardrails via API	Stored in PostgreSQL database	N/A	No
Primitive type registry	Stored in PostgreSQL database	N/A	No

The elevated key (MEMINTEL_ELEVATED_KEY) is required to post guardrails and register primitives via API — treat it with the same care as database credentials.

The path to memintel_config.yaml is set by the MEMINTEL_CONFIG_PATH environment variable on the server. The path to memintel_guardrails.yaml is declared inside memintel_config.yaml under guardrails_path.

warning

Never send these files by email or store them in a shared document. They contain references to credentials. Ask your data engineer for secure access to edit them on the server directly.

---

Pages in This Guide

• Self-Hosting — deploy Memintel to a production server
• Local Setup — run Memintel on your local machine
• Step 1 — Primitives — define signal vocabulary (config + API registry)
• Step 2 — Application Context — domain briefing via API call
• Step 3A — Guardrails via API — recommended: manage guardrails without a server restart
• Step 3B — Guardrails via File — advanced: edit memintel_guardrails.yaml directly
• Step 4 — Actions — configure alert delivery
• Calibration — improve conditions over time with feedback
• Governance — traceability, audit trails, and regulatory readiness

---

Ready to Start?

→ Self-Hosting