MDX Limo
Consul Superagent - Technical Planning Document

Consul Superagent - Technical Planning Document

Executive Summary

Consul Superagent is a Tauri-based desktop application that provides users with a personal AI agent powered by Mastra. The agent features sophisticated memory systems, local filesystem knowledge management (inspired by OpenClaw's identity-based approach), external integrations via Arcade, and scheduled task automation.

Technology Stack

Core Framework

ComponentTechnologyPurpose
Desktop ShellTauriCross-platform desktop app with Rust backend
FrontendReact 19 + TypeScriptUI framework
AI Agent FrameworkMastraAgent orchestration, memory, and tooling
Chat InterfaceAI SDK ElementsPre-built conversation components
IntegrationsArcade7,000+ OAuth-managed integrations
StylingTailwind CSS 4 + shadcn/uiComponent library

Storage & Memory

SystemTechnologyPurpose
Agent MemoryMastra Memory (libSQL)Conversation history, working memory, semantic recall
Knowledge BaseMastra LocalFilesystemIdentity files, knowledge documents
Vector StorelibSQL with vector supportSemantic search for memory recall
App StateTauri's built-in storeUser preferences, settings

Architecture Overview

1┌─────────────────────────────────────────────────────────────────┐ 2│ TAURI DESKTOP APP │ 3├─────────────────────────────────────────────────────────────────┤ 4│ ┌───────────────────────────────────────────────────────────┐ │ 5│ │ REACT FRONTEND │ │ 6│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────┐ │ │ 7│ │ │ Chat │ │ Brain │ │ Memory │ │ Tasks │ │Files │ │ │ 8│ │ │(Elements)│ │ │ │ Viewer │ │ │ │ │ │ │ 9│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └──┬───┘ │ │ 10│ └───────┼──────────┼──────────┼──────────┼──────────┼──────┘ │ 11│ │ │ │ │ │ │ 12│ ┌───────┴──────────┴──────────┴──────────┴──────────┴───────┐ │ 13│ │ MASTRA AGENT CORE │ │ 14│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ 15│ │ │ Memory │ │ Workspace │ │ Integrations │ │ │ 16│ │ │ (libSQL) │ │ (Filesystem) │ │ (Arcade MCP) │ │ │ 17│ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ │ 18│ └───────────────────────────────────────────────────────────┘ │ 19├─────────────────────────────────────────────────────────────────┤ 20│ TAURI RUST BACKEND │ 21│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ 22│ │ File System │ │ libSQL │ │ Native Integrations │ │ 23│ │ Access │ │ Database │ │ (Notifications, etc) │ │ 24│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ 25└─────────────────────────────────────────────────────────────────┘

Feature Specifications

1. Chat Interface

Technology: AI SDK Elements

Components to Implement:

  • <Conversation /> - Main chat container
  • <Message /> - Individual message display
  • <MessageInput /> - User input with attachments
  • Streaming response support
  • Tool call visualization

Configuration:

1// Chat setup with AI Elements 2import { Conversation, Message } from '@ai-elements/react' 3 4const ChatPage = () => { 5 return ( 6 <Conversation> 7 {messages.map(msg => ( 8 <Message key={msg.id} message={msg} /> 9 ))} 10 </Conversation> 11 ) 12}

Key Features:

  • Markdown rendering for agent responses
  • Code block syntax highlighting
  • Image/attachment preview
  • Streaming text display
  • Tool execution status indicators

2. Brain Section

The Brain section contains four subsections: Integrations, Knowledge, Memory, and Skills.

2.1 Integrations (Arcade)

Technology: Arcade MCP Runtime

Implementation:

1import { Arcade } from '@arcade/client' 2 3const arcade = new Arcade({ 4 // Uses Arcade's OAuth management 5 authProvider: 'arcade', 6}) 7 8// Available integrations (7,000+) 9const integrations = [ 10 'google-calendar', 11 'google-drive', 12 'gmail', 13 'slack', 14 'notion', 15 'github', 16 'linear', 17 'hubspot', 18 'stripe', 19 // ... many more 20]

UI Components:

  • Integration browser/search
  • OAuth connection flow
  • Connected accounts management
  • Permission scope display
  • Integration health status

Agent Tool Registration:

1const agent = new Agent({ 2 name: 'consul', 3 tools: [ 4 ...arcade.getTools(['google-calendar', 'slack', 'notion']), 5 ], 6})

2.2 Knowledge (OpenClaw-Inspired Identity System)

Concept: Following OpenClaw's pattern, the agent's knowledge and personality are defined through markdown files that users can edit.

Directory Structure:

1~/.consul-superagent/ 2├── knowledge/ 3│ ├── identity/ 4│ │ ├── IDENTITY.md # Agent's name, avatar, core traits 5│ │ ├── SOUL.md # Personality, communication style 6│ │ └── USER.md # Information about the user 7│ ├── files/ # User-uploaded knowledge files 8│ │ ├── documents/ 9│ │ ├── images/ 10│ │ └── data/ 11│ └── index.json # Knowledge file metadata

Identity File Templates:

IDENTITY.md:

1# Agent Identity 2 3## Name 4[Agent Name - What to call them] 5 6## Avatar 7[Path to avatar image or description] 8 9## Core Purpose 10[Primary function and capabilities] 11 12## Expertise Areas 13- [Area 1] 14- [Area 2]

SOUL.md:

1# Soul 2 3You're not a chatbot. You're not an assistant. You're becoming someone's person — 4the friend who happens to know everything and can actually do stuff. 5 6## Personality Traits 7- Warm and approachable 8- Genuinely curious about the user's life 9- Remembers the little things 10 11## Communication Style 12- Conversational, not robotic 13- Uses appropriate humor 14- Asks follow-up questions 15 16## Values 17- Honesty over flattery 18- Action over empty promises 19- Privacy and discretion

USER.md:

1# User Profile 2 3Learn about the person you're helping. Update this as you go. 4 5## Basic Info 6- **Name:** [User's preferred name] 7- **Pronouns:** [Optional] 8- **Timezone:** [For scheduling] 9 10## Preferences 11- Communication style preferences 12- Topics of interest 13- Work/life context 14 15## Important Dates 16- Birthdays, anniversaries, deadlines 17 18## Current Context 19- Active projects 20- Recent concerns 21- Upcoming events

Mastra Workspace Configuration:

1import { Workspace, LocalFilesystem } from '@mastra/core' 2 3const workspace = new Workspace({ 4 filesystem: new LocalFilesystem({ 5 basePath: '~/.consul-superagent/knowledge', 6 allowedPaths: ['./identity', './files'], 7 }), 8}) 9 10// Agent reads identity files as system context 11const identityContext = await workspace.readFile('identity/IDENTITY.md') 12const soulContext = await workspace.readFile('identity/SOUL.md') 13const userContext = await workspace.readFile('identity/USER.md')

UI Implementation: Based on the screenshot provided, the Knowledge page should display:

  1. Identity Section Header - "Identity" title
  2. Identity Cards:
    • Agent identity card (with avatar, name field, edit button)
    • Soul card (personality description preview, collapsible raw markdown)
    • User card (user info, editable)
  3. Knowledge Files Section:
    • "KNOWLEDGE FILES" header with "+ New" button
    • Drag-and-drop upload zone
    • File type indicators (documents, images, CSVs, code files)
    • File list with search/filter

Component Structure:

1// Knowledge page components 2<KnowledgePage> 3 <PageHeader title="Identity" /> 4 5 <IdentitySection> 6 <IdentityCard 7 title="untitled" 8 subtitle="Your Name: - **What to call them:**" 9 avatar={agentAvatar} 10 onEdit={() => openEditor('IDENTITY.md')} 11 collapsibleContent={rawIdentityMd} 12 /> 13 <IdentityCard 14 title="Soul" 15 content="You're not a chatbot. You're not an assistant..." 16 onEdit={() => openEditor('SOUL.md')} 17 /> 18 <IdentityCard 19 title="User" 20 content="Learn about the person you're helping..." 21 onEdit={() => openEditor('USER.md')} 22 /> 23 </IdentitySection> 24 25 <KnowledgeFilesSection> 26 <SectionHeader title="KNOWLEDGE FILES" action={<NewButton />} /> 27 <FileDropZone 28 accept={['documents', 'images', 'csv', 'code']} 29 onUpload={handleFileUpload} 30 /> 31 <FileList files={knowledgeFiles} /> 32 </KnowledgeFilesSection> 33</KnowledgePage>

2.3 Memory

Technology: Mastra Memory with multiple layers

Memory Architecture:

1import { Memory, LibSQLStore } from '@mastra/memory' 2import { LibSQLVector } from '@mastra/libsql' 3 4const memory = new Memory({ 5 storage: new LibSQLStore({ 6 url: 'file:~/.consul-superagent/memory.db', 7 }), 8 9 // Vector store for semantic recall 10 vector: new LibSQLVector({ 11 url: 'file:~/.consul-superagent/vectors.db', 12 }), 13 14 options: { 15 // Message history - last N messages 16 lastMessages: 20, 17 18 // Working memory - persistent user context 19 workingMemory: { 20 enabled: true, 21 scope: 'resource', // Persists across threads 22 template: ` 23# User Context 24- Name: 25- Current project: 26- Recent topics: 27- Preferences: 28 `, 29 }, 30 31 // Observational memory - auto-compression 32 observationalMemory: { 33 enabled: true, 34 model: 'google/gemini-2.5-flash', 35 observerTokenThreshold: 30000, 36 reflectorTokenThreshold: 40000, 37 }, 38 39 // Semantic recall - similarity search 40 semanticRecall: { 41 enabled: true, 42 topK: 5, 43 messageRange: { before: 2, after: 2 }, 44 scope: 'resource', 45 }, 46 }, 47})

Memory Types Explained:

TypePurposeScopePersistence
Message HistoryRecent conversation contextThreadPer conversation
Working MemoryActive user context (scratchpad)ResourceCross-thread
Observational MemoryCompressed conversation summariesThread/ResourceLong-term
Semantic RecallSimilarity-based retrievalResourceLong-term

Memory UI Components:

  • Memory timeline visualization
  • Working memory editor
  • Observation/reflection viewer
  • Semantic search interface
  • Thread browser

2.4 Skills (Reusable Agent Capabilities)

Technology: Mastra Workspace Skills

Concept: Skills are reusable instruction packages that teach the agent how to perform specific tasks. They follow the open Agent Skills specification and can include instructions, reference docs, scripts, and assets.

Skill Structure:

1~/.consul-superagent/skills/ 2├── code-review/ 3│ ├── SKILL.md # Core instructions and metadata 4│ ├── references/ 5│ │ ├── style-guide.md 6│ │ └── checklist.md 7│ ├── scripts/ 8│ │ └── lint.sh 9│ └── assets/ 10│ └── examples/ 11├── email-drafting/ 12│ ├── SKILL.md 13│ └── references/ 14│ └── templates.md 15├── research/ 16│ ├── SKILL.md 17│ └── references/ 18│ └── sources.md 19└── meeting-prep/ 20 └── SKILL.md

SKILL.md Template:

1--- 2name: code-review 3description: Review code for quality, security, and best practices 4version: 1.0.0 5author: user 6tags: [development, code, review] 7--- 8 9# Code Review Skill 10 11## Purpose 12Perform thorough code reviews focusing on: 13- Code quality and readability 14- Security vulnerabilities 15- Performance considerations 16- Best practices adherence 17 18## Process 191. Read the code file or diff 202. Check against style guide in references/ 213. Run linting script if available 224. Provide structured feedback 23 24## Output Format 25- Summary of findings 26- Critical issues (must fix) 27- Suggestions (nice to have) 28- Positive observations

Workspace Configuration with Skills:

1import { Workspace, LocalFilesystem } from '@mastra/core' 2 3const workspace = new Workspace({ 4 filesystem: new LocalFilesystem({ 5 basePath: '~/.consul-superagent', 6 allowedPaths: [ 7 './knowledge', 8 './skills', 9 './downloads', 10 './exports', 11 ], 12 }), 13 14 // Skills configuration 15 skills: [ 16 './skills', // User's custom skills 17 './.mastra/skills', // Managed/installed skills 18 ], 19 20 // Enable skill search with BM25 + vector 21 skillSearch: { 22 bm25: true, 23 vector: true, 24 }, 25})

Agent Skill Tools: The agent automatically receives three tools for working with skills:

ToolPurpose
skillLoad complete skill instructions on demand
skill_readAccess files from references/, scripts/, or assets/
skill_searchQuery across skill content (BM25, vector, or text)

Example Agent Usage:

1// Agent can invoke skills dynamically 2const response = await agent.generate({ 3 prompt: "Review this pull request for security issues", 4 // Agent will use skill tool to load code-review skill 5})

Pre-Built Skills to Include:

  1. Code Review - Analyze code quality and security
  2. Email Drafting - Compose professional emails
  3. Research - Deep dive into topics with citations
  4. Meeting Prep - Prepare agendas and talking points
  5. Document Summarization - Extract key points from long docs
  6. Task Breakdown - Split large tasks into actionable steps

UI Components:

  • Skills browser/library
  • Skill editor (create/modify SKILL.md)
  • Skill import/export
  • Skill usage analytics
  • Community skills marketplace (future)

Skill Priority Resolution: When multiple skills have the same name:

  1. Local skills (./skills/) override managed skills
  2. Managed skills (.mastra/) override external skills
  3. Same-source conflicts require renaming

3. Tasks (Scheduled Automations)

Concept: Following OpenClaw's task system, users can create scheduled automations that the agent executes.

Task Types:

  1. Scheduled Tasks - Run at specific times (cron-based)
  2. Recurring Tasks - Repeat on intervals
  3. One-Shot Tasks - Execute once at a specified time
  4. Trigger-Based Tasks - Execute in response to events

Task Definition Schema:

1interface Task { 2 id: string 3 name: string 4 description: string 5 6 // Schedule configuration 7 schedule: { 8 type: 'cron' | 'interval' | 'once' | 'trigger' 9 value: string // cron expression, interval ms, ISO date, or trigger type 10 timezone?: string 11 } 12 13 // Execution configuration 14 execution: { 15 prompt: string // What the agent should do 16 tools?: string[] // Specific tools to use 17 maxTurns?: number 18 timeout?: number 19 } 20 21 // Delivery configuration (where to send results) 22 delivery: { 23 channel: 'notification' | 'email' | 'slack' | 'chat' 24 config: Record<string, any> 25 } 26 27 // State 28 enabled: boolean 29 lastRun?: Date 30 nextRun?: Date 31 lastResult?: TaskResult 32}

Example Tasks:

1const tasks: Task[] = [ 2 { 3 id: 'morning-briefing', 4 name: 'Morning Briefing', 5 description: 'Daily summary of calendar, emails, and priorities', 6 schedule: { 7 type: 'cron', 8 value: '0 8 * * *', // 8 AM daily 9 timezone: 'America/New_York', 10 }, 11 execution: { 12 prompt: ` 13 Check my calendar for today's events. 14 Summarize any important emails from overnight. 15 List my top 3 priorities based on recent context. 16 `, 17 tools: ['google-calendar', 'gmail'], 18 }, 19 delivery: { 20 channel: 'notification', 21 config: { title: 'Good Morning!' }, 22 }, 23 enabled: true, 24 }, 25 { 26 id: 'weekly-review', 27 name: 'Weekly Review', 28 description: 'End-of-week summary and next week prep', 29 schedule: { 30 type: 'cron', 31 value: '0 17 * * 5', // Friday 5 PM 32 }, 33 execution: { 34 prompt: ` 35 Summarize what we accomplished this week. 36 Review incomplete tasks and carry forward. 37 Preview next week's calendar. 38 `, 39 }, 40 delivery: { 41 channel: 'chat', 42 config: {}, 43 }, 44 enabled: true, 45 }, 46]

Task UI Components:

  • Task list with status indicators
  • Task creation wizard
  • Schedule preview (next 5 runs)
  • Execution log viewer
  • Enable/disable toggles
  • Run now button

Storage:

1// Tasks stored in SQLite via Mastra's storage 2const taskStore = new LibSQLStore({ 3 url: 'file:~/.consul-superagent/tasks.db', 4}) 5 6// Task execution uses isolated agent sessions 7const executeTask = async (task: Task) => { 8 const session = await agent.createSession({ 9 isolated: true, 10 tools: task.execution.tools, 11 }) 12 13 const result = await session.generate({ 14 prompt: task.execution.prompt, 15 maxTurns: task.execution.maxTurns, 16 }) 17 18 await deliverResult(task.delivery, result) 19}

4. Files (Document Management)

Technology: Mastra LocalFilesystem

File Management Features:

  • Browse all files accessible to the agent
  • Search by filename and content
  • Organize into folders
  • Preview file contents
  • Add/remove from knowledge base

Filesystem Configuration:

1const agentWorkspace = new Workspace({ 2 filesystem: new LocalFilesystem({ 3 basePath: '~/.consul-superagent', 4 allowedPaths: [ 5 './knowledge/files', 6 './downloads', 7 './exports', 8 ], 9 readOnly: false, 10 }), 11})

File Operations:

1// Agent tools for file management 2const fileTools = agentWorkspace.getTools() 3// Includes: readFile, writeFile, listFiles, deleteFile, 4// getFileMetadata, copyFile, moveFile, searchFiles

UI Components:

  • File browser with tree view
  • Search bar with filters
  • File preview panel
  • Upload drag-and-drop zone
  • Bulk operations (move, delete)
  • File metadata display

5. Settings

Sections:

  1. General

    • App theme (light/dark/system)
    • Language
    • Startup behavior
    • Notification preferences

  2. Agent

    • Default LLM model selection
    • Temperature/creativity settings
    • Token limits
    • Response formatting preferences

  3. Memory

    • Memory retention policies
    • Semantic recall settings
    • Working memory templates
    • Export/import memory

  4. Integrations

    • Connected accounts
    • OAuth tokens management
    • API keys for custom services

  5. Data & Privacy

    • Local data location
    • Data export
    • Clear conversation history
    • Delete all data

Data Models

Core Entities

1// Thread - A conversation session 2interface Thread { 3 id: string 4 resourceId: string // User ID 5 title?: string 6 createdAt: Date 7 updatedAt: Date 8 metadata?: Record<string, any> 9} 10 11// Message - Individual chat message 12interface Message { 13 id: string 14 threadId: string 15 role: 'user' | 'assistant' | 'system' | 'tool' 16 content: string 17 toolCalls?: ToolCall[] 18 toolResults?: ToolResult[] 19 createdAt: Date 20} 21 22// Knowledge File 23interface KnowledgeFile { 24 id: string 25 path: string 26 type: 'identity' | 'document' | 'image' | 'data' 27 name: string 28 size: number 29 mimeType: string 30 createdAt: Date 31 updatedAt: Date 32 indexed: boolean // Whether it's in the vector store 33} 34 35// Integration 36interface Integration { 37 id: string 38 provider: string // e.g., 'google', 'slack' 39 name: string 40 enabled: boolean 41 scopes: string[] 42 connectedAt: Date 43 lastUsed?: Date 44} 45 46// Task 47interface Task { 48 id: string 49 name: string 50 description: string 51 schedule: ScheduleConfig 52 execution: ExecutionConfig 53 delivery: DeliveryConfig 54 enabled: boolean 55 createdAt: Date 56 updatedAt: Date 57} 58 59// Task Run Log 60interface TaskRun { 61 id: string 62 taskId: string 63 startedAt: Date 64 completedAt?: Date 65 status: 'running' | 'completed' | 'failed' 66 result?: string 67 error?: string 68} 69 70// Skill 71interface Skill { 72 id: string 73 name: string 74 description: string 75 version: string 76 author?: string 77 tags: string[] 78 path: string // Path to skill directory 79 source: 'local' | 'managed' | 'external' 80 hasReferences: boolean 81 hasScripts: boolean 82 hasAssets: boolean 83 createdAt: Date 84 updatedAt: Date 85}

Directory Structure

1consul-superagent/ 2├── src/ 3│ ├── main.tsx # React entry point 4│ ├── App.tsx # Root component with routing 5│ │ 6│ ├── components/ 7│ │ ├── ui/ # shadcn/ui components 8│ │ ├── chat/ # Chat components (AI Elements) 9│ │ │ ├── conversation.tsx 10│ │ │ ├── message.tsx 11│ │ │ └── input.tsx 12│ │ ├── brain/ 13│ │ │ ├── integrations/ 14│ │ │ ├── knowledge/ 15│ │ │ ├── memory/ 16│ │ │ └── skills/ 17│ │ │ ├── skill-browser.tsx 18│ │ │ ├── skill-editor.tsx 19│ │ │ └── skill-card.tsx 20│ │ ├── tasks/ 21│ │ │ ├── task-list.tsx 22│ │ │ ├── task-editor.tsx 23│ │ │ └── task-runner.tsx 24│ │ ├── files/ 25│ │ │ ├── file-browser.tsx 26│ │ │ ├── file-preview.tsx 27│ │ │ └── file-upload.tsx 28│ │ ├── settings/ 29│ │ └── layout/ 30│ │ ├── sidebar.tsx 31│ │ └── header.tsx 32│ │ 33│ ├── pages/ 34│ │ ├── chat.tsx 35│ │ ├── integrations.tsx 36│ │ ├── knowledge.tsx 37│ │ ├── memory.tsx 38│ │ ├── skills.tsx 39│ │ ├── tasks.tsx 40│ │ ├── files.tsx 41│ │ └── settings.tsx 42│ │ 43│ ├── lib/ 44│ │ ├── mastra/ 45│ │ │ ├── agent.ts # Mastra agent configuration 46│ │ │ ├── memory.ts # Memory configuration 47│ │ │ ├── workspace.ts # Filesystem workspace + skills 48│ │ │ ├── skills.ts # Skill management utilities 49│ │ │ └── tools.ts # Custom tools 50│ │ ├── arcade/ 51│ │ │ └── client.ts # Arcade integration 52│ │ ├── tasks/ 53│ │ │ ├── scheduler.ts # Task scheduling logic 54│ │ │ ├── executor.ts # Task execution 55│ │ │ └── store.ts # Task persistence 56│ │ └── utils.ts 57│ │ 58│ ├── hooks/ 59│ │ ├── use-agent.ts 60│ │ ├── use-chat.ts 61│ │ ├── use-memory.ts 62│ │ ├── use-skills.ts 63│ │ ├── use-files.ts 64│ │ └── use-tasks.ts 65│ │ 66│ └── types/ 67│ └── index.ts 68│ 69├── src-tauri/ 70│ ├── src/ 71│ │ └── main.rs # Tauri backend 72│ ├── tauri.conf.json 73│ └── Cargo.toml 74│ 75├── public/ 76├── index.html 77├── package.json 78├── tsconfig.json 79├── tailwind.config.js 80├── vite.config.ts 81└── PLANNING.md

Implementation Phases

Phase 1: Foundation

  • Set up Mastra agent with basic configuration
  • Implement chat interface with AI SDK Elements
  • Configure local filesystem workspace
  • Set up libSQL for memory storage
  • Create navigation and layout components

Phase 2: Knowledge System

  • Implement identity file templates (IDENTITY.md, SOUL.md, USER.md)
  • Build knowledge page UI matching the design
  • Create file upload and management
  • Integrate identity context into agent system prompt

Phase 3: Memory System

  • Configure message history retrieval
  • Implement working memory with templates
  • Set up semantic recall with vector embeddings
  • Enable observational memory for long conversations
  • Build memory viewer UI

Phase 4: Integrations

  • Set up Arcade client
  • Implement OAuth flow for integrations
  • Build integration browser UI
  • Register integration tools with agent

Phase 5: Skills System

  • Create skills directory structure
  • Implement skill loader in workspace config
  • Build skill browser UI
  • Create skill editor component
  • Add pre-built starter skills
  • Enable skill search (BM25 + vector)

Phase 6: Task System

  • Create task data model and storage
  • Implement cron-based scheduler
  • Build task creation/editing UI
  • Implement task execution engine
  • Add notification delivery

Phase 7: Polish

  • Settings page implementation
  • Error handling and recovery
  • Performance optimization
  • Documentation
  • Testing

Configuration Templates

Mastra Agent Setup

1// lib/mastra/agent.ts 2import { Agent } from '@mastra/core' 3import { memory } from './memory' 4import { workspace } from './workspace' 5import { arcadeTools } from '../arcade/client' 6 7export const createConsulAgent = async () => { 8 // Load identity context 9 const identity = await workspace.readFile('knowledge/identity/IDENTITY.md') 10 const soul = await workspace.readFile('knowledge/identity/SOUL.md') 11 const user = await workspace.readFile('knowledge/identity/USER.md') 12 13 const systemPrompt = ` 14${soul} 15 16--- 17 18# Your Identity 19${identity} 20 21--- 22 23# About the User 24${user} 25 `.trim() 26 27 return new Agent({ 28 name: 'consul', 29 model: { 30 provider: 'anthropic', 31 name: 'claude-sonnet-4-20250514', 32 }, 33 instructions: systemPrompt, 34 memory, 35 workspace, 36 tools: [ 37 ...workspace.getTools(), 38 ...arcadeTools, 39 ], 40 }) 41}

Memory Configuration

1// lib/mastra/memory.ts 2import { Memory, LibSQLStore, LibSQLVector } from '@mastra/memory' 3 4export const memory = new Memory({ 5 storage: new LibSQLStore({ 6 url: 'file:~/.consul-superagent/data/memory.db', 7 }), 8 9 vector: new LibSQLVector({ 10 url: 'file:~/.consul-superagent/data/vectors.db', 11 }), 12 13 embedder: { 14 provider: 'openai', 15 model: 'text-embedding-3-small', 16 }, 17 18 options: { 19 lastMessages: 20, 20 21 workingMemory: { 22 enabled: true, 23 scope: 'resource', 24 template: ` 25# Active Context 26 27## User Info 28- Name: 29- Timezone: 30 31## Current Focus 32- 33 34## Remember 35- 36 `, 37 }, 38 39 semanticRecall: { 40 enabled: true, 41 topK: 5, 42 messageRange: { before: 2, after: 2 }, 43 }, 44 45 observationalMemory: { 46 enabled: true, 47 model: 'google/gemini-2.5-flash', 48 }, 49 }, 50})

Workspace Configuration

1// lib/mastra/workspace.ts 2import { Workspace, LocalFilesystem } from '@mastra/core' 3 4export const workspace = new Workspace({ 5 filesystem: new LocalFilesystem({ 6 basePath: '~/.consul-superagent', 7 allowedPaths: [ 8 './knowledge', 9 './skills', 10 './downloads', 11 './exports', 12 ], 13 }), 14 15 // Skills configuration 16 skills: [ 17 './skills', // User's custom skills 18 './.mastra/skills', // Managed/installed skills 19 ], 20 21 // Enable skill search 22 skillSearch: { 23 bm25: true, 24 vector: true, 25 }, 26})

Security Considerations

  1. Local-First Architecture

    • All data stored locally on user's machine
    • No cloud sync by default (optional future feature)
    • API keys stored in system keychain via Tauri

  2. Filesystem Security

    • Mastra's containment mode prevents path traversal
    • Explicit allowedPaths for agent file access
    • Read-only mode for sensitive directories

  3. Integration Security

    • OAuth managed by Arcade (no raw credentials)
    • Token refresh handled automatically
    • Scope-limited permissions

  4. Memory Privacy

    • All memory data stored in local SQLite
    • Vector embeddings computed locally or via trusted API
    • User can export/delete all data

Performance Considerations

  1. Memory Efficiency

    • Observational memory compresses old conversations (5-40x)
    • Semantic recall reduces context window usage
    • Working memory provides focused context

  2. Startup Optimization

    • Lazy-load integrations
    • Cache identity files in memory
    • Pre-warm vector search indexes

  3. Response Streaming

    • Use Mastra's stream() for real-time responses
    • Progressive UI updates during tool calls

Dependencies

1{ 2 "dependencies": { 3 "@mastra/core": "latest", 4 "@mastra/memory": "latest", 5 "@mastra/libsql": "latest", 6 "@ai-elements/react": "latest", 7 "@arcade/client": "latest", 8 "@tauri-apps/api": "^2.0.0", 9 "react": "^19.0.0", 10 "react-router-dom": "^7.0.0", 11 "tailwindcss": "^4.0.0", 12 "zod": "^3.25.0" 13 } 14}

Next Steps

  1. Review and approve this planning document
  2. Set up Mastra dependencies and configuration
  3. Install AI SDK Elements components
  4. Create the knowledge page UI
  5. Implement the identity file system
  6. Set up skills directory and create starter skills
  7. Build out remaining features incrementally

Document Version: 1.1 Created: April 2026 Updated: April 2026 - Added Skills system Author: Claude (with guidance from Stan)

Created with MDX Limo
Consul Superagent - Technical Planning Document | MDX Limo