AI Agent System Architecture

Comprehensive guide to the three-tier AI agent system (Cursor, Platform, Space)

🧠 AI Agent System Architecture

Session: 6/6.8
Last Updated: December 2024
Status: Production-Ready Foundation

Overview

GoGrab Space implements a three-tier AI agent architecture designed for:

Developer productivity (Cursor Agents)
Platform learning (Platform Intelligence)
User assistance (Space Assistants)

Each tier serves a distinct purpose with appropriate isolation and knowledge management.

📊 Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                         AI AGENT ARCHITECTURE                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐  │
│  │   CURSOR AGENTS     │  │ PLATFORM INTELLIGENCE│  │  SPACE ASSISTANTS  │  │
│  │   (Developer-Facing)│  │   (Background)       │  │   (User-Facing)    │  │
│  ├─────────────────────┤  ├─────────────────────┤  ├─────────────────────┤  │
│  │ • Architecture      │  │ • Pattern Learning  │  │ • Widget Help      │  │
│  │ • Angular           │  │ • Widget Analysis   │  │ • Theme Selection  │  │
│  │ • Backend           │  │ • Theme Patterns    │  │ • Flow Building    │  │
│  │ • Testing           │  │ • Module Discovery  │  │ • Configuration    │  │
│  │ • Documentation     │  │ • Flow Optimization │  │ • Personalization  │  │
│  └─────────┬───────────┘  └─────────┬───────────┘  └─────────┬───────────┘  │
│            │                        │                        │              │
│            └────────────────────────┼────────────────────────┘              │
│                                     │                                        │
│  ┌──────────────────────────────────▼───────────────────────────────────┐   │
│  │                    HYBRID STORAGE LAYER                               │   │
│  ├───────────────────────────────────────────────────────────────────────┤   │
│  │                                                                        │   │
│  │  Layer 1: autoFlashState (IndexedDB)                                  │   │
│  │  ├── Speed: < 1ms (instant)                                           │   │
│  │  ├── Scope: Per-browser, real-time                                    │   │
│  │  └── Use: UI state, offline-first                                     │   │
│  │                                                                        │   │
│  │  Layer 2: MongoDB Atlas (Cloud)                                       │   │
│  │  ├── Speed: ~50ms                                                     │   │
│  │  ├── Scope: Multi-developer, shared                                   │   │
│  │  └── Use: Vector search, team sync                                    │   │
│  │                                                                        │   │
│  │  Layer 3: docs/data/*.json (Git-tracked)                             │   │
│  │  ├── Speed: N/A (backup)                                              │   │
│  │  ├── Scope: Repository history                                        │   │
│  │  └── Use: Auditability, fallback                                      │   │
│  │                                                                        │   │
│  └───────────────────────────────────────────────────────────────────────┘   │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

🤖 Tier 1: Cursor Agents (Developer-Facing)

Purpose

Help developers write code faster and better by learning from decisions made in the IDE.

Agent Specializations

Agent ID	Responsibility	Knowledge Domain
`cursor-orchestrator`	Routes tasks to specialized agents	All domains
`cursor-architecture`	SOLID, patterns, system design	Architecture decisions
`cursor-angular`	Components, signals, RxJS	Frontend patterns
`cursor-backend`	NestJS, MongoDB, APIs	Backend patterns
`cursor-testing`	Vitest, Playwright, TDD	Testing patterns
`cursor-documentation`	Markdown, ADRs, APIs	Documentation patterns

How It Works

// MCP Server receives decision from Cursor
{
  type: "implementation",
  question: "How to handle component state?",
  options: ["Signals", "RxJS BehaviorSubject", "NGXS"],
  chosen: "Signals",
  reasoning: "Angular 20 best practice, simpler than RxJS for local state",
  confidence: 0.9,
  agentId: "cursor-angular-agent"
}

Knowledge Flow

Developer Action (Cursor IDE)
        ↓
MCP Server logs decision
        ↓
Decision stored in development-memory.json
        ↓
Synced to MongoDB (agent_decisions collection)
        ↓
Patterns mined periodically
        ↓
Future pre-flight retrieves relevant patterns

Configuration

// MCP configuration in .cursor/mcp.json
{
  "mcpServers": {
    "development-ai": {
      "command": "node",
      "args": ["tools/mcp-development-ai/dist/server.js"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceRoot}",
        "ENABLE_VECTOR_MEMORY": "true"
      }
    }
  }
}

💡 Tier 2: Platform Intelligence (Background Learning)

Purpose

Automatically learn patterns from how the platform is used to improve suggestions and automation.

Agent Specializations

Agent ID	Responsibility	Learns From
`platform-pattern`	Extract reusable patterns	Successful implementations
`platform-widget`	Widget best practices	Widget deployments
`platform-theme`	Theme combinations	Theme usage analytics
`platform-module`	Module structures	Module integrations
`platform-flow`	Logic flow patterns	Flow executions

How It Works

// Platform observes widget deployment
@Injectable()
export class PlatformWidgetAgent extends BasePlatformAgent {
  
  observe(event: WidgetDeploymentEvent): void {
    if (event.success && event.metrics.userSatisfaction > 4.0) {
      this.learnPattern({
        context: event.widgetType,
        configuration: event.config,
        performance: event.metrics
      });
    }
  }
}

Pattern Extraction

// Automatically mined pattern
{
  id: "pattern-virtual-scroll-large-data",
  name: "Virtual Scroll for Large Datasets",
  context: "DataTable with >1000 rows",
  recommendation: "Enable virtual scroll with rowHeight=48",
  reasoning: "Reduces DOM nodes, improves FPS by 300%",
  supportCount: 15,
  successRate: 0.95,
  techTags: ["angular", "performance", "data-table"],
  agentTypes: ["platform-widget", "cursor-angular"]
}

Knowledge Isolation

Global Scope: Learns from all tenants
Anonymized: No tenant-specific data stored
Aggregated: Patterns require multiple occurrences

🚀 Tier 3: Space Assistants (User-Facing)

Purpose

Help end-users build their spaces through natural language and contextual suggestions.

Capabilities

Capability	Description
Widget Help	Create, configure, and customize widgets
Theme Selection	Suggest themes based on preferences
Flow Building	Guide users through flow creation
Module Configuration	Help configure module settings
Troubleshooting	Diagnose and fix issues

How It Works

// User asks for help
"How do I add a chart to my dashboard?"

// Space Assistant responds with context
{
  context: "dashboard-page",
  tenantId: "tenant-123",
  response: "I'll help you add a chart! Based on your data...",
  actions: [
    { type: "suggest-widget", widget: "bar-chart" },
    { type: "open-config", panel: "widget-settings" }
  ]
}

Tenant Isolation

// Each tenant has completely isolated knowledge
export class SpaceAssistantService {
  private knowledgeByTenant = new Map<string, TenantKnowledge>();
  
  getAssistant(tenantId: string): SpaceAssistant {
    // Strict isolation - cannot access other tenants
    return new SpaceAssistant(this.knowledgeByTenant.get(tenantId));
  }
}

Security Model

✅ Can access: Own tenant's data, spaces, configurations
❌ Cannot access: Other tenants, core code, system settings
✅ Can modify: User's widgets, themes, flows
❌ Cannot modify: Platform code, other users' data

💾 Hybrid Storage System

Overview

The AgentMemoryStorageService provides three-layer persistence:

import { AgentMemoryStorageService } from '@libs-ai/agent-orchestrator';

@Injectable()
export class MyService {
  private memory = inject(AgentMemoryStorageService);
  
  // Real-time session tracking
  currentSession = this.memory.sessionDisplay; // "6/6.8"
  
  // Store decisions by agent type
  this.memory.storeDecision({
    id: 'dec-123',
    type: 'implementation',
    question: 'How to handle X?',
    chosen: 'Use Y',
    reasoning: 'Because Z',
    confidence: 0.9,
    agentType: 'cursor-angular',
    timestamp: new Date().toISOString()
  });
  
  // Sync to cloud
  this.memory.fullSyncToMongo();
}

Storage Locations

Location	Purpose	Format
`IndexedDB`	Real-time local	autoFlashState
`MongoDB Atlas`	Cloud sync	Documents
`docs/sessionID.json`	Session tracking	JSON
`docs/data/*.json`	Git-tracked backup	JSON
`.cursor/ai-memory/`	MCP memory	JSON

Session Management

// Session increments with progress
6.0 → 6.1 → 6.2 → ... → 6.8 → 6.9 → 7.0

// Increment session ID
memory.incrementSessionID(); // 6.8 → 6.9

// Start new major session
memory.startNewSession(); // 6.x → 7.0

🎛️ Knowledge Control

Clearing Agent Knowledge

// Clear a specific agent's learned patterns
memory.clearAgentKnowledge('cursor-angular');

// Remove a specific decision
memory.removeDecision('decision-id-123');

// Deprecate a pattern
memory.updatePatternStatus('pattern-id', 'deprecated');

Knowledge Summary

const summary = memory.getKnowledgeSummary();
// {
//   'cursor-angular': { decisions: 45, patterns: 12 },
//   'cursor-backend': { decisions: 23, patterns: 8 },
//   'platform-widget': { decisions: 15, patterns: 5 }
// }

🔌 API Endpoints

Backend Endpoints (NestJS)

Endpoint	Method	Purpose
`/api/ai-agents/session/current`	GET	Get current session info
`/api/ai-agents/session/increment`	POST	Increment session ID
`/api/ai-agents/session/sync`	POST	Sync session from frontend
`/api/ai-agents/sync/full`	POST	Full MCP → MongoDB sync
`/api/ai-agents/sync/full-frontend`	POST	Full frontend → MongoDB sync
`/api/ai-agents/sync/pull-all`	GET	Pull all data for frontend
`/api/ai-agents/patterns/mine`	POST	Mine patterns from decisions
`/api/ai-agents/storage/stats`	GET	Get comprehensive stats

📁 File Structure

libs/libs-ai/
├── agent-orchestrator/         # Core orchestration
│   └── services/
│       ├── agent-api.service.ts
│       ├── agent-memory-storage.service.ts  # Hybrid storage
│       └── agent-platform-learning.service.ts
├── agent-mind/                 # Visualization components
│   └── components/
│       ├── agent-mind-container/
│       ├── knowledge-browser/
│       └── memory-clusters/
├── platform-intelligence/      # Platform learning agents
│   └── agents/
│       ├── base-platform-agent.ts
│       ├── platform-pattern-agent.ts
│       └── platform-widget-agent.ts
├── vitto-hub/            # User-facing assistant
│   └── components/
│       └── ai-panel/
└── gograb-ai/                  # Dashboard & UI
    └── components/
        ├── ai-dashboard/
        └── ai-agents-dashboard/

🔄 Data Flow Summary

                    ┌─────────────┐
                    │   Cursor    │
                    │     IDE     │
                    └──────┬──────┘
                           │ MCP Protocol
                           ▼
                    ┌─────────────┐
                    │ MCP Server  │
                    │ (Node.js)   │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
    ┌────────────┐  ┌────────────┐  ┌────────────┐
    │ Local File │  │  Backend   │  │  User Home │
    │ (workspace)│  │   API      │  │   Backup   │
    └─────┬──────┘  └─────┬──────┘  └────────────┘
          │               │
          │               ▼
          │        ┌────────────┐
          └───────►│  MongoDB   │◄─────── Frontend
                   │   Atlas    │         (autoFlash)
                   └─────┬──────┘
                         │
                         ▼
                   ┌────────────┐
                   │ docs/data/ │
                   │ (git sync) │
                   └────────────┘

🚀 Getting Started

1. Enable MCP in Cursor

Ensure .cursor/mcp.json is configured with the development-ai server.

2. Use the Memory Service

import { AgentMemoryStorageService } from '@libs-ai/agent-orchestrator';

export class MyComponent {
  private memory = inject(AgentMemoryStorageService);
}

3. Log Decisions

Use the MCP log_decision tool or the memory service's storeDecision method.

4. Sync Data

Click "Full Sync" in the AI Dashboard or call memory.fullSyncToMongo().

📈 Metrics & Monitoring

Dashboard Location

http://localhost:5701/ai/dashboard

Key Metrics

Total decisions per agent
Pattern count and success rates
Sync status (MongoDB connected)
Session progression

🔐 Security Considerations

Tenant Isolation: Space Assistants are strictly isolated per tenant
Data Anonymization: Platform Intelligence anonymizes patterns
Access Control: Backend validates tenant context
Sensitive Data: Reasoning can be redacted in exports

📚 Related Documentation

CLAUDE.md - Main AI instructions
AGENTS.md - Agent-specific rules
session-6 - Current session context
MCP Server - MCP implementation

Last updated: Session 6/6.8