Database

AgentCore runs on PostgreSQL 16 with the pgvector extension for vector similarity search. The schema is managed by Prisma 6 and lives in prisma/schema.prisma.

Setup

# Start PostgreSQL
docker compose up -d postgres

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Visual database browser
npm run db:studio

Models Overview

The schema contains 26 models organized into these domains.

RBAC & Organization

Model	Purpose	Key fields
SystemRole	Custom and built-in RBAC roles	name, slug, isSystem, allDepartments, departmentIds, permissions
Department	Tenant/department boundary for most data	name, slug, color, description, settings, isArchived
User	Authenticated users and HR state	email, name, phone, passwordHash, legacy role, roleId, departmentId, avatarUrl, tokenVersion, permission and department overrides
PasswordResetToken	Password reset flow	userId, token, expiresAt, usedAt

User.role keeps the legacy enum (admin, approver, dept_head, employee) for compatibility. Current authorization uses SystemRole plus per-user extraPermissions, revokedPermissions, extraDepartmentIds, and revokedDepartmentIds.

Knowledge Base

Model	Purpose	Key fields
KnowledgeBase	Department-owned document collection	departmentId, name, description, config
Document	Source document or generated output file	knowledgeBaseId, title, type, originalUrl, status, metadata
Chunk	Searchable text chunk	documentId, content, embedding, syntheticQuestions, metadata
ChunkQuestion	Synthetic Q&A retrieval path	chunkId, question, embedding

Chunk.embedding and ChunkQuestion.embedding are vector(1536) columns and must match the configured embedding model dimensions.

Conversations & Namespaces

Model	Purpose	Key fields
Namespace	Department-specific assistant config	name, departmentId, systemPrompt, persona, config
NamespacePlugin	Enabled integration plugins per namespace	namespaceId, pluginId, config, enabled
Conversation	User conversation thread	userId, channel, status, metadata, namespaceId
Message	Conversation message	conversationId, role, content, sources
PiiRedactionMap	Reversible PII placeholders for conversations	conversationId, placeholder, entityType, encryptedValue

Namespaces scope persona, trust matrix, adapter config, plugins, conversations, document templates, and agent tasks.

Approvals & Intents

Model	Purpose	Key fields
Approval	HITL approval workflow	messageId, approverId, status, editedContent, approverNotes, escalatedToId, escalationReason, intentName
IntentTrust	Trust matrix for autonomous sends	namespaceId, intentName, successfulCount, threshold, isAutonomous, samplingRate
IntentExample	Labeled phrases for vector intent classification	namespaceId, intentName, phrase, embedding, metadata

Document Generation

Model	Purpose	Key fields
Template	Legacy file-backed templates	name, departmentId, filePath, variables
DocumentTemplate	API-managed Handlebars templates	namespaceId, departmentId, name, description, category, templateBody, variables, outputFormat, createdBy
DocumentGeneration	Render history and generated output	templateId, userId, input, output, outputFileId, status, error

Generated files can be saved back into Document through outputFileId, which lets generated documents participate in normal knowledge-base workflows.

Employee Memory & Agent Execution

Model	Purpose	Key fields
EmployeeProfile	Extracted user memory/profile	userId, summary, currentProjects, preferences, frequentIntents, accessLevel, profileVersion, lastExtractedAt
AgentTask	Agent-runner task record	namespaceId, conversationId, messageId, adapterType, status, token/cost/duration fields, metadata, timestamps
AgentToolCall	Step-level agent execution trace	agentTaskId, stepName, status, inputData, outputData, durationMs, errorMessage

Observability & Notifications

Model	Purpose	Key fields
AuditLog	Business and security audit trail	userId, action, entityType, entityId, changes, ipAddress, userAgent
AgentRun	Langfuse/OpenAI trace summary	traceId, conversationId, provider, model, token/cost/latency fields, status
RetrievalHit	RAG retrieval evidence for a trace	agentRunId, chunkId, documentId, rank, score, rerankScore
Notification	User notification center	userId, type, title, body, entityType, entityId, readAt

Enums

Role:                admin | approver | dept_head | employee
DocumentType:        pdf | docx | txt | url | image
DocumentStatus:      pending | processing | ready | failed
ConversationChannel: web | whatsapp | telegram | slack | email
ConversationStatus:  active | closed | escalated | awaiting_approval
MessageRole:         user | assistant | system
ApprovalStatus:      pending | approved | rejected | edited | escalated
AgentTaskStatus:     queued | running | done | failed | timeout

Operational Notes

• Department isolation goes through a direct departmentId or a related Namespace, User, or KnowledgeBase record.
• Users and departments use soft deactivation (isActive = false, isArchived = true).
• JWT invalidation uses User.tokenVersion. Password resets, logout-all, department transfers, and deactivation increment it.
• Document uploads and generated outputs both use Document. Generated outputs carry metadata.source = "document_generation".

Migrations

Migrations are in prisma/migrations/.

npx prisma migrate dev --name <migration_name>

For production deployment:

npx prisma migrate deploy