Personal Agent Template

The repository is organized into four main layers:

• agent/: The Eve agent runtime. Contains agent.ts (config), channels/ (communication interfaces), tools/ (agent capabilities), skills/ (logic), and connections/ (external MCPs).
• app/: The Nuxt frontend. Contains pages, components (like MessageContentEve.vue), and composables (useMemory, useProfile).
• server/: The Nitro API backend. Contains API routes, Drizzle database schema/migrations, and utilities for auth and memory.
• shared/: Cross-layer TypeScript types and branding metadata used by both the agent and the app.

The agent uses a 'session memory injection' pattern to maintain context. When a session starts, the following flow occurs:

1. Eve triggers the session.started hook (defined in agent/instructions.ts).
2. The agent makes a GET request to /api/internal/memory?userId=... using the INTERNAL_API_SECRET.
3. The internal memory utility (agent/lib/memory-internal.ts) builds a prompt section from the retrieved data.
4. This section is appended to the agent's instructions for the duration of that session.

Note: To ensure changes to memory are picked up, you must start a new chat after importing or updating memory.

Memory categories determine how the agent organizes information. They are defined in shared/types/memory.ts via three key exports:

• MEMORY_CATEGORIES: The enum values used by the system.
• MEMORY_CATEGORY_LABELS: The human-readable labels shown in the UI.
• MEMORY_CATEGORY_HEADERS: Aliases used by the import parser.

Important: Each category stores exactly one prose block. Saving new memory replaces the entire existing block for that category rather than performing a partial update.

If you add or rename categories, you must also update:

1. shared/memory/export-prompt.ts (for ChatGPT export functionality).
2. agent/tools/save_memory.ts (to ensure the tool imports the new categories).

The Personal Agent Template operates as two cooperating services on Vercel, configured via vercel.json:

1. Web Surface (web): The Nuxt frontend accessible at /. It provides the UI and Nitro API.
2. Eve Agent Runtime (eve): The agent logic accessible at /_eve_internal/eve. This service handles channels (web, slack, sendblue), tools (weather, save_memory), and skills/connections (Linear MCP).

The Eve agent communicates with the Nuxt app via HTTP using a Bearer token (INTERNAL_API_SECRET).

The INTERNAL_API_SECRET is a shared bearer token used for communication between the Eve agent service and the Nuxt internal API (/api/internal/*).

It is required for:

• Memory read/write from the agent
• Slack account linking
• Sendblue / iMessage phone linking lookup

CRITICAL: This value must be identical on both Vercel services (web and eve). If they do not match, memory injection, Slack linking, and iMessage auth will fail silently or return 401 errors.

Memory is structured around the following principles:

• Categories: A fixed set of categories defined in shared/types/memory.ts.
• Atomic Updates: The system uses setMemoryForCategory, which replaces all existing rows for a specific category with the new data.
• Sources: Memory can originate from import, agent, or manual sources.
• Importing: Supports a Raycast-style paste parser via server/utils/memory-import.ts to ingest unstructured text.

Slack integration allows the agent to communicate via Slack channels.

Setup Steps:

1. Create a Slack connector in Vercel Connect.
2. Update the slug in agent/channels/slack.ts:

   credentials: connectSlackCredentials("slack/your-slug"),

3. Connect via Settings → Integrations.
4. Linking Accounts: Generate a code within the app, then send a Direct Message to the bot containing link <code_here>.

Requirement: INTERNAL_API_SECRET must be set in your environment for Slack linking to function.

// agent/channels/slack.ts
credentials: connectSlackCredentials("slack/your-slug"),

Skills are markdown-based instructions or workflows. To add one:

1. Create a new .md file in agent/skills/ (e.g., my-skill.md).
2. Reference the skill in the home quick actions by updating app/pages/index.vue.

The agent's core personality, system prompt, tone, tool usage rules, and memory behavior are defined in agent/lib/base-instructions.ts.

Note: After updating the persona, search the codebase for the original example name (e.g., V) to update any remaining UI copy in Vue components.

To customize the visual appearance of the application:

• Global Styles: Edit app/assets/css/main.css.
• Nuxt UI Configuration: Edit app/app.config.ts.
• Layout & Navigation: Modify app/layouts/default.vue and app/components/Navbar.vue.