AI MEMORY + CONTROL PLANE SPEC (ONE-PAGE TEMPLATE)

Use this to force clarity before you ship an “assistant” that becomes a liability.

1) PRODUCT INTENT
- Primary jobs-to-be-done (max 3):
 1.
 2.
 3.
- Actions the AI is allowed to take (verbs only): e.g., draft, summarize, file ticket, open PR, run query, send email.
- Actions explicitly forbidden:

2) MEMORY CONTRACT (USER-FACING)
- What the system may remember long-term (structured fields):
 - Preferences (tone, format, timezone, default project, escalation rules)
 - Stable facts (role, team, region) — if applicable
- What the system must NOT store:
 - Secrets (API keys), credentials, payment info, regulated data classes you can’t retain
- Visibility:
 - Where can a user view memories?
 - How can a user edit or delete them?
- Retention:
 - Default retention policy for conversation logs
 - Retention for extracted memories

3) ORGANIZATIONAL KNOWLEDGE (RAG / RETRIEVAL)
- Approved sources (list systems): e.g., GitHub, Jira, Confluence, Google Drive, Slack.
- Indexing rules:
 - Tenant isolation approach:
 - Permission-aware retrieval approach:
 - How you handle versioning (doc timestamps, repo commits):
- Provenance requirement:
 - Every answer must include: doc ID/URL + timestamp OR ticket/PR reference.

4) TOOLING + PERMISSIONS (CONTROL PLANE)
- Tool allowlist (table): Tool | Who can use | Risk level | Requires approval (Y/N)
- Permission model:
 - RBAC roles:
 - Any ABAC conditions (project, environment, data classification):
- Secret handling:
 - Where secrets live (never in prompts):
 - How tools obtain auth (least privilege):

5) EXECUTION SAFETY
- High-risk actions that require human approval:
- Rate limits / blast radius:
 - Max actions per minute:
 - Max recipients / max query scope / deploy environment restrictions:
- Output validation:
 - Schema validation (what schemas exist):
 - Allowlists (domains, recipients, repos, environments):

6) AUDIT + DEBUG
- What gets logged for every run:
 - user ID, tenant ID, model used, retrieved sources, tool calls, approvals, final output
- Traceability requirement:
 - How an operator answers: “Why did it do that?” in under 5 minutes.

7) EVALUATION GATES (SHIP / NO SHIP)
- Offline eval set exists for:
 - Factuality against internal docs
 - Policy compliance (forbidden actions/data)
 - Tool correctness (args, recipients, environments)
- Release gates:
 - Must pass unit tests for schemas + permission checks
 - Must pass red-team prompts for injection attempts against your top 3 tools

Paste this into your repo as /docs/ai-control-plane.md and treat changes like API changes: reviewed, versioned, and tested.