Domain Configuration

Domain configuration is how you teach Magneteco what matters for your application. Each app provides a configuration that defines:

Categories: Types of information to remember
Entity Types: Nouns in your domain (people, projects, accounts)
Relationship Types: How entities connect to each other
Relevance Rules: What to always/never remember

Configuration Schema

interface DomainConfig {
  // Required
  appId: string;
  description: string;
  categories: CategoryDefinition[];
  entityTypes: EntityTypeDefinition[];
  relationshipTypes: RelationshipDefinition[];

  // Optional
  relevanceRules?: RelevanceRule[];
  extractionPrompt?: string;
  summaryMaxLength?: number;
  embeddingModel?: string;
}

interface CategoryDefinition {
  name: string;           // Unique identifier (snake_case)
  description: string;    // What this category contains
  examples: string[];     // Few-shot examples for LLM
  priority?: number;      // Higher = loaded first in retrieval (default: 1)
  maxItems?: number;      // Max items before compression (default: 100)
}

interface EntityTypeDefinition {
  name: string;           // Entity type name (PascalCase)
  description: string;    // What this entity represents
  keyProperties: string[];// Properties to extract
  examples: string[];     // Example entity names
  identifiers?: string[]; // Properties that uniquely identify
}

interface RelationshipDefinition {
  name: string;           // Relationship name (UPPER_SNAKE_CASE)
  description: string;    // What this relationship means
  fromType: string;       // Source entity type
  toType: string;         // Target entity type
  examples: string[];     // Example relationships
  temporal?: boolean;     // Track validity period (default: false)
  exclusive?: boolean;    // Only one active at a time (default: false)
}

interface RelevanceRule {
  pattern: string;        // Regex pattern to match
  action: 'always_remember' | 'never_remember' | 'ask';
  category?: string;      // Force into specific category
}

Step-by-Step Guide

Step 1: Identify Categories

Think about what types of information your agent needs to remember:

categories: [
  {
    name: 'user_preferences',
    description: 'How the user likes to work, communicate, and receive information',
    examples: [
      'User prefers detailed explanations over summaries',
      'User likes code examples in Python',
      'User works best in the morning',
    ],
  },
  {
    name: 'project_context',
    description: 'Background on active projects and their goals',
    examples: [
      'Working on a React migration from Angular',
      'Project deadline is end of Q2',
      'Client is risk-averse about new technologies',
    ],
  },
]

Step 2: Identify Entity Types

What are the "nouns" in your domain that the user talks about?

entityTypes: [
  {
    name: 'Project',
    description: 'A work project or initiative',
    keyProperties: ['name', 'status', 'deadline', 'tech_stack'],
    examples: ['Website Redesign', 'Q4 Migration', 'Mobile App v2'],
  },
  {
    name: 'Person',
    description: 'A colleague, client, or stakeholder',
    keyProperties: ['name', 'role', 'organization', 'relationship'],
    examples: ['Jane from marketing', 'Bob the CTO', 'Client PM Sarah'],
  },
]

Step 3: Identify Relationships

How do your entities connect to each other?

relationshipTypes: [
  {
    name: 'WORKS_ON',
    description: 'Person is actively working on a project',
    fromType: 'Person',
    toType: 'Project',
    examples: ['Jane WORKS_ON Website Redesign'],
    temporal: true,      // Track when they started/stopped
    exclusive: false,    // Can work on multiple projects
  },
  {
    name: 'OWNS',
    description: 'Person is the owner/lead of a project',
    fromType: 'Person',
    toType: 'Project',
    examples: ['Bob OWNS Q4 Migration'],
    exclusive: true,     // Only one owner at a time
  },
]

Step 4: Define Relevance Rules

What should always or never be remembered?

relevanceRules: [
  // Security - never remember
  { pattern: 'password|secret|api[_-]?key|token', action: 'never_remember' },
  { pattern: 'ssn|social.security', action: 'never_remember' },

  // Important - always remember
  { pattern: 'deadline|due.date|milestone', action: 'always_remember' },
  { pattern: 'decision|decided|agreed', action: 'always_remember' },

  // Route to specific category
  { pattern: 'prefer|like|want|style', action: 'always_remember', category: 'user_preferences' },
]

Complete Example

export const tandaConfig: DomainConfig = {
  appId: 'tanda',
  description: 'AI assistant for SOW management and acceptance testing',

  categories: [
    {
      name: 'client_preferences',
      description: 'How clients prefer to work and communicate',
      examples: [
        'Acme Corp prefers Gherkin format for acceptance criteria',
        'Client stakeholder Jane prefers weekly status calls',
      ],
      priority: 2,
    },
    {
      name: 'project_context',
      description: 'Background on active projects',
      examples: [
        'NetSuite Migration is in Phase 2',
        'Project deadline is end of Q2 2024',
      ],
      priority: 2,
    },
    {
      name: 'risk_factors',
      description: 'Known risks, issues, and blockers',
      examples: [
        'Integration with legacy system is fragile',
        'Previous scope creep cost 3 weeks',
      ],
      priority: 2,
    },
  ],

  entityTypes: [
    {
      name: 'Client',
      description: 'A client organization',
      keyProperties: ['name', 'industry', 'size'],
      examples: ['Acme Corp', 'TechStart Inc'],
    },
    {
      name: 'Project',
      description: 'A project or engagement',
      keyProperties: ['name', 'status', 'deadline'],
      examples: ['NetSuite Migration', 'Q4 UAT'],
    },
    {
      name: 'Contact',
      description: 'A person at a client or on the team',
      keyProperties: ['name', 'role', 'organization'],
      examples: ['Jane Smith (Project Sponsor)'],
    },
  ],

  relationshipTypes: [
    {
      name: 'OWNS',
      fromType: 'Client',
      toType: 'Project',
      description: 'Client owns/sponsors a project',
      examples: ['Acme Corp OWNS NetSuite Migration'],
    },
    {
      name: 'STAKEHOLDER_OF',
      fromType: 'Contact',
      toType: 'Project',
      description: 'Contact is a stakeholder',
      examples: ['Jane Smith STAKEHOLDER_OF NetSuite Migration'],
      temporal: true,
    },
  ],

  relevanceRules: [
    { pattern: 'deadline|milestone', action: 'always_remember' },
    { pattern: 'risk|blocker|issue', action: 'always_remember' },
    { pattern: 'password|api[_-]?key', action: 'never_remember' },
  ],
};

Best Practices

Category Design

Be specific: "project_deadlines" is better than "project_info"
Use examples: More examples = better classification
Set priorities: What matters most when context is limited?
Limit count: 5-10 categories is ideal

Entity Design

Extract key properties: What do you need to know?
Use clear identifiers: How do you uniquely identify this entity?
Provide examples: Real examples help the LLM

Relationship Design

Be explicit about direction: "A OWNS B" not "RELATED_TO"
Mark temporal relationships: Track when things change
Mark exclusive relationships: Prevent duplicate active relationships

Relevance Rules

Start restrictive: Easier to add than remove
Be careful with patterns: Too broad = missed memories
Test thoroughly: Unexpected matches cause problems

Domain Configuration

On this page